progress

progress is a minimal Node.js library for rendering ASCII progress bars in terminal applications. It exposes a single ProgressBar class that tracks ticks toward a total and renders a customizable bar using template tokens like :bar, :percent, :eta, and :rate.

Widely used across the Node.js CLI ecosystem for over a decade, it favors a small, stable API over configurability creep: a format string for layout, an options object for behavior (width, characters, render throttle), and a tick-based programming model that matches how most long-running command-line operations report progress.

What You Get

• ProgressBar class - a single constructor that takes a format string and an options object or a bare total.
• Template tokens - :bar, :current, :total, :elapsed, :percent, :eta, :rate, plus arbitrary custom tokens passed to tick().
• Configurable rendering - control over bar width, complete/incomplete/head characters, render throttle, and whether the bar clears on completion.
• Zero runtime dependencies - a single ~230-line file with nothing to install beyond the package itself.

Common Use Cases

• Showing download/upload progress in CLI tools
• Displaying installer or build-step progress in Node scripts
• Reporting iteration progress in data-processing or migration scripts
• Building custom terminal dashboards that combine multiple progress indicators

Under The Hood

Architecture The library is a single, flat module (lib/node-progress.js, re-exported by index.js) exporting one constructor, ProgressBar, with no internal layering. The constructor initializes state (curr, total, width, chars, renderThrottle); tick() mutates that state and calls render(); render() computes ratio/percent/eta/rate and writes the formatted string directly to the output stream; update() computes a delta from a target ratio and delegates to tick(); interrupt() and terminate() handle side-message printing and cleanup. There is no separation between the progress “model” (curr/total) and the “view” (string templating happens inside the same method that performs the terminal writes), so the entire rendering behavior is a single point of risk if it needs to change.

Tech Stack Plain, dependency-free JavaScript written in an ES5 style (var, prototype methods, no classes or TypeScript), targeting Node.js >=0.4.0 per package.json. There is no build tooling, bundler, or transpiler — a Makefile simply runs each file under examples/ through plain node as a manual smoke test. The only external surface touched is Node’s built-in stream/TTY APIs (stream.isTTY, cursorTo, clearLine, columns), and the package is distributed as CommonJS via npm.

Code Quality No test files exist in the repository (a test directory is referenced in .npmignore but is not present in the current tree). The closest thing to verification is the Makefile’s test target, which executes each examples/*.js file and echoes success rather than asserting behavior. Error handling is explicit only at construction time (throw new Error('format required'), throw new Error('total required')); elsewhere, edge cases like division by zero or NaN/Infinity results for eta/elapsed are silently coerced to safe defaults rather than surfaced. Naming is short and consistent, and comments follow a lightweight JSDoc-style convention, but there is no type safety, no linter/formatter configuration, and no CI configuration in the repo.

API Design The public surface is deliberately tiny — one constructor plus four public methods (tick, render, update, interrupt) — and getting started takes two lines: construct with a format string and a total, then call tick() repeatedly. The constructor accepts either a bare number as a total shorthand or a full options object, reducing boilerplate for the common case, and the format-string-plus-token model (:bar, :percent, :eta, custom tokens) is intuitive for anyone familiar with printf-style templates. Documentation is thorough for the project’s size — the README documents every option and token, backed by ten runnable example scripts — though the source’s JSDoc-style comments aren’t surfaced as TypeScript types, so editors can’t autocomplete option names.