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 afterProgressBar::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. withthis.variables
Default:''
. -
variables
: <VariableOpts> Variables with which to parsethis.template
, extended withcStringd.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 fromProgressBar::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) <omiraculous@gmail.com>