xprogress

Construct Dynamic, Flexible, extensible progressive CLI bar for the terminal built with NodeJS

Features

• Stream management functionality

Installing

Via NPM:

npm install xprogress

Usage

// Node CommonJS
const ProgressBar = require('xprogress');
// Or ES6
import ProgressBar from 'xprogress';

Example

Create a basic progress bar that updates itself with 10% twice every second until it's at maximum

const ProgressBar = require('xprogress');

const bar = new ProgressBar(100);

const interval = setInterval(() => {
  bar.tick(10).draw();
  if (bar.isComplete()) {
    bar.end(`The bar completed\n`);
    clearInterval(interval);
  }
}, 500);

How It Works

ProgressBar uses stringd to parse content within ProgressBar::template with variables in ProgressBar::variables and then displays them on the terminal. This sequence occurs for every time ProgressBar::draw() is called.

API

new ProgressBar(total[, slots][, opts])

• total: <number>
• slots: <HybridInput[]>
• opts: <BarOpts>

Create and return an xprogress instance slots define the percentage to each part of the progressbar. This is parsed by pad-ratio to a max of 100.

const bar = new ProgressBar(100, [20, 44]);

GlobOpts: Object

• bar: Object
  • blank: <string> Content to use for the blank portion of the progressbar. Default: '-'.
  • filler: <string> Content to use for the filled portion of the progressbar. Default: '#'.
  • header: <string> Content to use for the header(s) of progressbars. Default: ''.
  • colorize: <boolean> Whether or not to allow colors in the bar. Default: true.
  • separator: <string> Content to use when separating bars. Default: ''.
  • pulsateSkip: <number> Distance away at which to skip a pulsating bar. Default: 15.
  • pulsateLength: <number> The length of a pulsating progressbar. Default: 15.
• clean: <boolean> Whether or not to clear the progressbar buffer on the terminal after ProgressBar::end() has been called. Default: false.
• flipper: <string|string[]> Content(s) to use for the progressbar flipper. This would cycle through all indexes in this property for everywhere :{flipper} is speified. Default: ['|', '/', '-', '\'].
• pulsate: <boolean> Whether or not to use a pulsate view for the progressbar. Default: false.
• template: <string|string[]> The template to use for the progressbar view. This is parsed by stringd. with this.variables Default: ''.
• variables: <VariableOpts> Variables with which to parse this.template, extended with cStringd.raw.
• forceFirst: <boolean> Whether or not to force a multi-bar progressbar to a single bar (useful either when terminal width is too small or when filled with excess addons). Default: false.

The global options shared by both ProgressBar and ProgressStream.

VariableOpts _{extends cStringd.raw}: Object

• tag: <any> Floating mutable tag to be attached to the bar
• *bar: <any> The progress bar itself
• *label: <any> The label to be attached to the bar
• *total: <any> The maximum value for the entire duration of the bar
• flipper: <any> The flipper as defined in the definition for the progressbar. Default: ['|', '/', '-', '\'].
• *completed: <any> The value for the completion level of the entire bar activity. Generated from ProgressBar::average().completed
• *remaining: <any>
• *percentage: <any>

Variables with which to parse this.template, extended with cStringd.raw. variables prepended with * will be ignored anywhere else besides wherever's explicitly requesting a drawn bar.

StreamVariables _{extends VariableOpts}: Object

• eta: <string> Duration for the entire progress to end. Parsed by [moment.js]
• size: <ByteString>
• progress: <ProgressStreamSlice>
• eta:raw: <number>
• slot:bar: <any>
• slot:eta: <string>
• slot:eta:raw: <number>
• slot:size: <ByteString>
• slot:total: <ByteString>
• slot:runtime: <string>
• slot:runtime:raw: <number>
• slot:percentage: <string>
• slot:size:total: <ByteString>

HybridInput: string|number|number[]

This content here is parsed by pad-ratio in the construct of an HybridInput.

Development

Building

Feel free to clone, use in adherance to the license and perhaps send pull requests

git clone https://github.com/miraclx/xprogress.git
cd xprogress
npm install
# hack on code
npm run build

License

Apache 2.0 © Miraculous Owonubi (@miraclx) <omiraculous@gmail.com>