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

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.
• writeStream: <WriteStream> The tty-ish writable stream we are writing to. Default: stdout.

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: <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.

StreamVariables extends VariableOpts: 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

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

License

Apache 2.0 © Miraculous Owonubi (@miraclx) <[email protected]>