tessl/npm-cli-progress

Terminal progress bar library with single/multi bar support

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

CLI Progress

Name: tessl/npm-cli-progress
Author: tessl

CLI Progress is a comprehensive terminal progress bar library that enables developers to create visual progress indicators for command-line and terminal applications. It supports both single and multi-progress bar modes with extensive customization options including custom bar characters, formatting, themes/presets, and real-time progress tracking.

Package Information

Package Name: cli-progress
Package Type: npm
Language: JavaScript (Node.js)
Installation: npm install cli-progress

Core Imports

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

For ES modules:

import * as cliProgress from 'cli-progress';

Basic Usage

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

// Create a single progress bar with preset
const bar = new cliProgress.SingleBar({}, cliProgress.Presets.shades_classic);

// Start the progress bar with total value of 100
bar.start(100, 0);

// Update progress
bar.update(50);

// Stop the progress bar
bar.stop();

Architecture

CLI Progress is built around several key components:

SingleBar: Individual progress bar with automatic rendering and terminal management
MultiBar: Container for coordinating multiple progress bars with event-driven updates
Presets: Built-in themes and styling configurations for common visual patterns
Formatters: Customizable rendering system with token-based templating and format utilities
Terminal Management: Low-level cursor control, TTY detection, and graceful cleanup

Capabilities

Single Progress Bar

Individual progress bar implementation with automatic rendering, ETA calculation, and comprehensive customization options.

class SingleBar extends GenericBar {
  constructor(options?: ProgressBarOptions, preset?: PresetConfiguration);
  start(total: number, startValue?: number, payload?: object): void;
  update(current?: number, payload?: object): void;
  increment(delta?: number, payload?: object): void;
  stop(): void;
  setTotal(total: number): void;
  updateETA(): void;
}

// Bar is an alias for SingleBar for convenience
const Bar = SingleBar;

Single Progress Bar

Multi Progress Bar

Container for managing multiple progress bars simultaneously with coordinated rendering and logging capabilities.

class MultiBar extends EventEmitter {
  constructor(options?: ProgressBarOptions, preset?: PresetConfiguration);
  create(total: number, startValue?: number, payload?: object, barOptions?: object): SingleBar;
  remove(bar: SingleBar): boolean;
  stop(): void;
  log(message: string): void;
}

Multi Progress Bar

Presets and Formatting

Built-in themes and advanced formatting system for creating custom progress bar appearances.

interface Presets {
  legacy: PresetConfiguration;
  shades_classic: PresetConfiguration;
  shades_grey: PresetConfiguration;
  rect: PresetConfiguration;
}

interface Format {
  Formatter: (options: ProgressBarOptions, params: FormatParams, payload: object) => string;
  BarFormat: (progress: number, options: ProgressBarOptions) => string;
  ValueFormat: (value: any, options: ProgressBarOptions, type: string) => any;
  TimeFormat: (seconds: number, options: ProgressBarOptions, roundTo?: number) => string;
}

Presets and Formatting

Types

interface ProgressBarOptions {
  // Visual options
  format?: string | function;
  barsize?: number;
  align?: 'left' | 'right' | 'center';
  barCompleteChar?: string;
  barIncompleteChar?: string;
  barGlue?: string;
  hideCursor?: boolean;
  linewrap?: boolean;
  
  // Behavior options
  fps?: number;
  stream?: NodeJS.WriteStream;
  stopOnComplete?: boolean;
  clearOnComplete?: boolean;
  gracefulExit?: boolean;
  synchronousUpdate?: boolean;
  noTTYOutput?: boolean;
  notTTYSchedule?: number;
  emptyOnZero?: boolean;
  forceRedraw?: boolean;
  
  // ETA and calculation options
  etaBuffer?: number;
  etaAsynchronousUpdate?: boolean;
  progressCalculationRelative?: boolean;
  
  // Formatting options
  autopadding?: boolean;
  autopaddingChar?: string;
  formatBar?: (progress: number, options: ProgressBarOptions) => string;
  formatTime?: (seconds: number, options: ProgressBarOptions, roundTo?: number) => string;
  formatValue?: (value: any, options: ProgressBarOptions, type: string) => any;
  terminal?: object;
}

interface PresetConfiguration {
  format?: string;
  barCompleteChar?: string;
  barIncompleteChar?: string;
  [key: string]: any;
}

interface FormatParams {
  progress: number;
  eta: number;
  startTime: number;
  stopTime?: number;
  total: number;
  value: number;
  maxWidth: number;
}