tiny-progress

tiny-progress

Ultra-minimal progress indicators for Node.js CLI tools

tiny-progress is a lightweight, zero-dependency NPM package providing simple progress indicators for console-based scripts and CLI tools. It features automatic TTY detection with graceful fallback for non-interactive environments.

✨ Features

• 🪶 Ultra-lightweight: <5kb total package size
• 🚫 Zero dependencies: Uses only Node.js built-ins
• 🔄 Auto TTY detection: Graceful fallback for pipes/redirects
• 🎯 Three indicator types: Dots, progress bars, and spinners
• 🌐 Cross-platform: Works on Windows, macOS, and Linux
• ⚡ Easy to use: Simple, intuitive API

📦 Installation

npm install tiny-progress

🚀 Quick Start

const { dots, bar, spinner } = require('tiny-progress');

// Dots indicator
const d = dots({ char: '•', interval: 200 });
d.start();
setTimeout(() => d.stop('✅ Done!'), 3000);

// Progress bar
const b = bar({ total: 100, width: 40 });
for (let i = 0; i <= 100; i++) {
  setTimeout(() => {
    b.update(i);
    if (i === 100) b.finish('Complete!');
  }, i * 50);
}

// Spinner
const s = spinner({ message: 'Loading...' });
s.start();
setTimeout(() => s.stop('✅ Loaded!'), 2000);

📖 API Reference

dots(options)

Creates a heartbeat-style progress indicator that prints characters at fixed intervals.

Options

Option	Type	Default	Description
interval	number	250	Time between prints (milliseconds)
char	string	'.'	Character to print
message	string	undefined	Optional prefix message

Methods

• start() - Begins the dots animation
• stop(message) - Stops animation and prints final message

Example

const { dots } = require('tiny-progress');

const d = dots({
  char: '•',
  interval: 200,
  message: 'Processing files'
});

d.start();

// Simulate work
setTimeout(() => {
  d.stop('✅ Files processed successfully!');
}, 5000);

bar(options)

Creates a traditional progress bar with percentage display and visual fill indicator.

Options

Option	Type	Default	Description
total	number	100	Total progress value
width	number	40	Bar width in characters
char	string	'█'	Fill character
incomplete	string	'░'	Empty character
format	string	'{bar} {percentage}%'	Display format

Methods

• update(current) - Updates progress to current value
• finish(message) - Completes progress and shows final message

Format Tokens

• {bar} - The progress bar visual
• {percentage} - Percentage complete (0-100)
• {current} - Current progress value
• {total} - Total progress value

Example

const { bar } = require('tiny-progress');

const b = bar({
  total: 50,
  width: 30,
  format: '{bar} {current}/{total} ({percentage}%)'
});

// Simulate incremental progress
for (let i = 0; i <= 50; i++) {
  setTimeout(() => {
    b.update(i);
    if (i === 50) {
      b.finish('🎉 Upload complete!');
    }
  }, i * 100);
}

spinner(options)

Creates a rotating spinner animation for indeterminate progress.

Options

Option	Type	Default	Description
frames	Array	Unicode spinner	Animation frames
interval	number	80	Frame change interval (ms)
message	string	undefined	Text to display alongside spinner

Methods

• start() - Begins spinner animation
• stop(message) - Stops spinner and shows final message
• updateMessage(message) - Updates display message while spinning

Custom Spinner Frames

const customFrames = ['◐', '◓', '◑', '◒'];
const s = spinner({ frames: customFrames, interval: 100 });

Example

const { spinner } = require('tiny-progress');

const s = spinner({ message: 'Connecting to server' });
s.start();

setTimeout(() => {
  s.updateMessage('Authenticating user');
}, 2000);

setTimeout(() => {
  s.updateMessage('Loading dashboard');
}, 4000);

setTimeout(() => {
  s.stop('✅ Connected successfully!');
}, 6000);

🖥️ TTY Detection

tiny-progress automatically detects whether it's running in a TTY (interactive terminal) environment:

TTY Mode (Interactive)

• Full animations with ANSI escape sequences
• Cursor manipulation for smooth updates
• Real-time visual feedback

Non-TTY Mode (Pipes/Redirects)

• Plain text output without animations
• Periodic updates to avoid spam
• Compatible with log files and CI/CD

Example: Redirected Output

# Interactive mode (full animation)
node your-script.js

# Non-interactive mode (plain text)
node your-script.js > output.log
node your-script.js | grep "Done"

🎨 Practical Examples

File Processing Script

const fs = require('fs');
const { bar, spinner } = require('tiny-progress');

async function processFiles(files) {
  const progress = bar({
    total: files.length,
    format: 'Processing: {bar} {current}/{total} files ({percentage}%)'
  });

  for (let i = 0; i < files.length; i++) {
    // Simulate file processing
    await new Promise(resolve => setTimeout(resolve, 200));
    progress.update(i + 1);
  }

  progress.finish('✅ All files processed!');
}

// Usage
processFiles(['file1.txt', 'file2.txt', 'file3.txt']);

HTTP Download with Progress

const https = require('https');
const { bar } = require('tiny-progress');

function downloadFile(url, filename) {
  const progress = bar({
    total: 0, // Will be set when we know file size
    format: 'Downloading: {bar} {percentage}%'
  });

  https.get(url, (response) => {
    const totalSize = parseInt(response.headers['content-length']);
    progress.total = totalSize;
    
    let downloaded = 0;
    response.on('data', (chunk) => {
      downloaded += chunk.length;
      progress.update(downloaded);
    });
    
    response.on('end', () => {
      progress.finish(`✅ Downloaded ${filename}`);
    });
  });
}

CLI Tool with Multiple Steps

const { spinner, dots, bar } = require('tiny-progress');

async function deployApp() {
  // Step 1: Build
  const buildSpinner = spinner({ message: 'Building application' });
  buildSpinner.start();
  await simulateWork(3000);
  buildSpinner.stop('✅ Build complete');

  // Step 2: Upload
  const uploadProgress = bar({
    total: 100,
    format: 'Uploading: {bar} {percentage}%'
  });
  
  for (let i = 0; i <= 100; i++) {
    await new Promise(resolve => setTimeout(resolve, 50));
    uploadProgress.update(i);
  }
  uploadProgress.finish('✅ Upload complete');

  // Step 3: Deploy
  const deployDots = dots({
    char: '.',
    message: 'Deploying'
  });
  deployDots.start();
  await simulateWork(2000);
  deployDots.stop('🚀 Deployment successful!');
}

function simulateWork(ms) {
  return new Promise(resolve => setTimeout(resolve, ms));
}

deployApp();

🧪 Testing

Run the included tests to verify functionality:

# Run all tests
npm test

# Test specific scenarios
node test/test.js
node test/non-tty-test.js

# Test non-TTY behavior
node test/test.js > output.log

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📄 License

MIT © tiny-progress contributors

🔗 Related

• cli-progress - More feature-rich but heavier
• progress - Classic progress bar library
• ora - Feature-rich spinner (larger dependency)

Why tiny-progress?

When you need simple progress indicators without the overhead of larger libraries. Perfect for CLI tools, build scripts, and any Node.js application where you want to show progress without bloating your dependency tree. Ultra-minimal NPM package that provides progress indicators for console based scripts and CLI tools