Progress

The Progress component creates animated progress bars in the terminal with spinner indicators, buffered progress support, rainbow animation, configurable symbols and colors, and multi-bar rendering. It extends EventEmitter for type-safe event handling and supports completion, cancellation, and error states. External console.log calls are automatically printed above the progress block without disrupting the display.

Constructor

new Progress(
title: string,
total?: number,
options?: ProgressOptions,
)

Parameters

• title: The title displayed alongside the progress bar.
• total: The total value representing 100% completion. Defaults to 100.
• options: An optional ProgressOptions object to configure labels and bar appearance (length, symbols, animation, and colors).

Methods

• init(): Initializes the progress bar, registers it for multi-bar rendering, and starts the spinner.
• update(current, buffer?, options?): Updates the progress value and optional buffer. You can also pass ProgressUpdateOptions to change the bar's message, labels, symbols, or colors mid-flight. Automatically completes when current reaches total.
• cancel(): Cancels the progress bar and emits the "cancel" event.
• error(...args: any[]): Sets the error state and emits the "error" event with the provided arguments.
• getIsExited(): Returns true if the progress bar has been cancelled or errored.

Events

• "update": Emitted on each update. Passes (current: number, percentage: number).
• "complete": Emitted when progress reaches total. Passes (total: number).
• "cancel": Emitted when progress is cancelled.
• "error": Emitted on error with the error arguments.

Features

• Multi-bar rendering: Multiple progress bars render together and finish as a group.
• Rainbow animation: Set bar.animation to { type: "rainbow" } for a scrolling parallax rainbow effect, or { type: "rainbow-smooth" } for a full-spectrum 8-bit gradient. Control speed and wave size with the optional speed and size fields.
• Custom symbols: Configure loadedSymbol, bufferedSymbol, and emptySymbol to change the bar characters.
• State colors: Customize colors for loaded, buffered, empty, completed, cancelled, and errored states via bar.color.
• Full-width mode: Set bar.length to "full-width" to fill the terminal width.
• Safe stdout interception: External console.log calls are printed above the progress block without duplication.

Usage

import { Progress } from "ts-better-console";

const bar = new Progress("Downloading", 100);
bar.init();

let i = 0;
const timer = setInterval(() => {
i += 10;
bar.update(i);
if (i >= 100) clearInterval(timer);
}, 200);