Single Progress Bar

/**
 * Creates a new progress bar instance
 * @param options - Configuration options for the progress bar
 * @param preset - Preset configuration to merge with options
 */
class SingleBar extends GenericBar {
  constructor(options?: ProgressBarOptions, preset?: PresetConfiguration);
}

const cliProgress = require('cli-progress');

// Basic progress bar with default options
const bar1 = new cliProgress.SingleBar({});

// Progress bar with preset theme
const bar2 = new cliProgress.SingleBar({}, cliProgress.Presets.shades_classic);

// Customized progress bar
const bar3 = new cliProgress.SingleBar({
  format: 'CLI Progress |{bar}| {percentage}% | {value}/{total} | ETA: {eta}s',
  barCompleteChar: '█',
  barIncompleteChar: '░',
  hideCursor: true,
  clearOnComplete: true
});

/**
 * Starts the progress bar and sets total and initial values
 * @param total - Maximum value for the progress bar
 * @param startValue - Initial progress value (default: 0)
 * @param payload - Custom data for token replacement in format string
 */
start(total: number, startValue?: number, payload?: object): void;

// Start with total of 100, starting at 0
bar.start(100, 0);

// Start with total of 50, starting at 10
bar.start(50, 10);

// Start with custom payload data
bar.start(200, 0, {
  filename: 'processing.txt',
  speed: 'N/A'
});

/**
 * Updates progress value and/or payload data
 * @param current - New progress value (optional if updating payload only)
 * @param payload - Custom data for token replacement
 */
update(current?: number, payload?: object): void;

/**
 * Updates payload data only without changing progress value
 * @param payload - Custom data for token replacement
 */
update(payload: object): void;

// Update progress value only
bar.update(75);

// Update progress value and payload
bar.update(75, { filename: 'data.csv', speed: '2.3 MB/s' });

// Update payload only (progress value unchanged)
bar.update({ speed: '1.8 MB/s', eta: '30s' });

// Update to null (keeps current progress, updates payload)
bar.update(null, { status: 'finalizing' });

/**
 * Increments progress by specified delta value
 * @param delta - Amount to increment (default: 1)
 * @param payload - Custom data for token replacement
 */
increment(delta?: number, payload?: object): void;

/**
 * Increments progress by 1 and updates payload
 * @param payload - Custom data for token replacement
 */
increment(payload: object): void;

// Increment by 1 (default)
bar.increment();

// Increment by specific amount
bar.increment(5);

// Increment by 1 with payload update
bar.increment({ filename: 'next-file.txt' });

// Increment by specific amount with payload
bar.increment(3, { processed: 'batch-complete' });

/**
 * Sets new total value while progress bar is active
 * @param total - New maximum value
 */
setTotal(total: number): void;

// Start with estimated total
bar.start(100, 0);

// Discover actual total and update
bar.setTotal(150);
bar.update(75); // Now shows 75/150 instead of 75/100

/**
 * Stops the progress bar and performs cleanup
 */
stop(): void;

// Complete the progress and stop
bar.update(100);
bar.stop();

// Stop early (incomplete progress)
bar.update(45);
bar.stop();

/**
 * Forces ETA calculation update without altering progress
 * Note: Increase etaBuffer size to avoid INF values if value unchanged
 */
updateETA(): void;

// For long-running processes, periodically update ETA
setInterval(() => {
  if (bar.isActive) {
    bar.updateETA();
  }
}, 5000);

/**
 * Gets the normalized progress value (0.0 to 1.0)
 * @returns Current progress as decimal (0.0 = 0%, 1.0 = 100%)
 */
getProgress(): number;

/**
 * Gets the current total/maximum value
 * @returns Current total value
 */
getTotal(): number;

/**
 * Forces manual rendering of the progress bar
 * Note: This method is primarily for internal use
 */
render(): void;

// Event: 'start' - Emitted when progress bar starts
bar.on('start', (total: number, startValue: number) => {
  console.log(`Progress started: ${startValue}/${total}`);
});

// Event: 'update' - Emitted on progress value changes
bar.on('update', (total: number, value: number) => {
  console.log(`Progress: ${value}/${total}`);
});

// Event: 'stop' - Emitted when progress bar stops
bar.on('stop', (total: number, value: number) => {
  console.log(`Progress completed: ${value}/${total}`);
});

// Event: 'redraw-pre' - Emitted before bar redraw
bar.on('redraw-pre', () => {
  // Prepare for redraw
});

// Event: 'redraw-post' - Emitted after bar redraw
bar.on('redraw-post', () => {
  // Post-redraw operations
});

interface SingleBarProperties {
  readonly value: number;        // Current progress value
  readonly total: number;        // Maximum progress value
  readonly startValue: number;   // Starting value for relative calculations
  readonly payload: object;      // Custom payload data
  readonly isActive: boolean;    // Whether bar is currently active
  readonly options: ProgressBarOptions; // Configuration options
}

const bar = new cliProgress.SingleBar({
  format: 'Progress |{bar}| {percentage}% | {value}/{total} | Speed: {speed}',
  stopOnComplete: true,
  clearOnComplete: false
});

bar.start(100, 0, { speed: 'N/A' });

for (let i = 0; i <= 100; i++) {
  // Simulate variable processing speed
  const speed = Math.random() * 10;
  
  bar.update(i, { 
    speed: speed.toFixed(1) + ' ops/s' 
  });
  
  // Simulate processing time
  await new Promise(resolve => setTimeout(resolve, 50));
}

const bar = new cliProgress.SingleBar({
  gracefulExit: true // Handle SIGINT/SIGTERM
});

try {
  bar.start(totalItems, 0);
  
  for (let i = 0; i < totalItems; i++) {
    await processItem(i);
    bar.increment();
  }
} catch (error) {
  // Ensure cleanup on error
  if (bar.isActive) {
    bar.stop();
  }
  throw error;
}