Awesome

xprogress

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

DOCUMENTATION INCOMPLETE

Features

Stream management functionality

Installing

Via NPM:

npm install xprogress

Usage

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

import ProgressBar from 'xprogress';

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);

XProgress Example Result

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

<a id="progressbar"></a> 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]);

<a id="globopts"></a> `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.
<a id="globopts:template"></a> template: <string|string[]> The template to use for the progressbar view. This is parsed by stringd. with this.variables Default: ''.
<a id="globopts:variables"></a> 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.
writeStream: <WriteStream> The tty-ish writable stream we are writing to. Default: stdout.

The global options shared by both ProgressBar and ProgressStream.

<a id="variableopts"></a> `VariableOpts` <sub>extends `cStringd.raw`</sub>: `Object`

tag: <any> Floating mutable tag to be attached to the bar
*bar: <string> 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.

<a id="streamvariables"></a> `StreamVariables` <sub>extends `VariableOpts`</sub>: `Object`

eta: <string> Duration for the entire progress to end. Parsed by prettyMs
size: <ByteString> Human readable size for the number of total transferred bytes. Parsed by xbytes
speed: <string> Human readable speed for the number of bits transferred per second. Parsed by xbytes
progress: <ProgressStreamSlice> The Progress Object
eta:raw: <number> Duration estimate of how long it would take for the stream to end based on the number of bytes being steadily transmitted per second.
slot:bar: <string> The bar for the active chunk of the progressbar.
slot:blank: <string> The character with which to be used as the slot's blank character.
slot:eta: <string> Duration estimate for the active chunk to be completed. Parsed by prettyMs
slot:eta:raw: <number> Duration estimate for the active chunk to be completed.
slot:filler: <string|string[]> The character(s) with which to be used as the slot's filler character.
slot:header: <string> The character with which to be used as the slot's header character.
slot:size: <ByteString> Human readable size for the number of transferred bytes specific for the active chunk. Parsed by xbytes
slot:total: <ByteString> Human readable size for the total number of bytes that can be processed by the active chunk. Parsed by xbytes
slot:runtime: <string> Runtime for the active chunk. Parsed by prettyMs
slot:runtime:raw: <number> Runtime for the active chunk.
slot:percentage: <string> Integer defining the active slot completion percentage
slot:size:total: <ByteString> Human readable size for the total number of bytes transferred in a single instance

<a id='hybridinput'></a> `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. Pull requests are very much welcome.

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