Single Baro | Multi Baro | Options | Examples | Layouts | Events
baro
easy to use progress-bar for command-line/terminal applications
Install
$ yarn add baro
$ npm install baro --save
Features
- Simple, Robust and Easy to use
- Full customizable output format (constious placeholders are available)
- Single progressbar mode
- Multi progessbar mode
- Custom Baro Characters
- FPS limiter
- ETA calculation based on elapsed time
- Custom Tokens to display additional data (payload) within the bar
- TTY and NOTTY mode
- No callbacks required - designed as pure, external controlled UI widget
- Works in Asynchronous and Synchronous tasks
- Layout/Theme support
- Custom bar formatters (via callback)
Usage
Multiple examples are available e.g. example.js - just try it $ node example.js
const cliProgress = require('baro');
// create a new progress bar instance and use shades_classic theme
const bar1 = new cliProgress.SingleBar({}, cliProgress.Layouts.shades_classic);
// start the progress bar with a total value of 200 and start value of 0
bar1.init(200, 0);
// update the current value in your application..
bar1.update(100);
// stop the progress bar
bar1.stop();
Single Baro Mode
Example
const cliProgress = require('baro');
// create new progress bar
const b1 = new cliProgress.SingleBar({
format: 'CLI Progress |' + _colors.cyan('{bar}') + '| {progress}% || {value}/{total} Chunks || Speed: {speed}',
proChar: '\u2588',
negChar: '\u2591',
hideCursor: true
});
// initialize the bar - defining payload token "speed" with the default value "N/A"
b1.init(200, 0, {
speed: "N/A"
});
// update values
b1.increment();
b1.update(20);
// stop the bar
b1.stop();
Constructor
Initialize a new Progress bar. An instance can be used multiple times! it's not required to re-create it!
const cliProgress = require('baro');
const <instance> = new cliProgress.SingleBar(config:object [, preset:object]);
Options
::initialize()
Starts the progress bar and set the total and initial value
<instance>.initialize(totalValue:int, startValue:int [, payload:object = {}]);
::update()
Sets the current progress value and optionally the payload with values of custom tokens as a second parameter. To update payload only, set currentValue to null
.
<instance>.update([currentValue:int [, payload:object = {}]]);
// update progress without altering value
<instance>.update([payload:object = {}]);
::increment()
Increases the current progress value by a specified amount (default +1). Update payload optionally
<instance>.increment([delta:int [, payload:object = {}]]);
// delta=1 assumed
<instance>.increment(payload:object = {}]);
::setTotal()
Sets the total progress value while progressbar is active. Especially useful handling dynamic tasks.
<instance>.setTotal(totalValue:int);
::stop()
Stops the progress bar and go to next line
<instance>.stop();
::updateETA()
Force eta calculation update (long running processes) without altering the progress values.
Note: you may want to increase etaCapacity
size - otherwise it can cause INF
eta values in case the value didn't updated within the time series.
<instance>.updateETA();
Multi Baro Mode
Example
const cliProgress = require('baro');
// create new container
const multibar = new cliProgress.MultiBar({
autoClear: false,
hideCursor: true
}, cliProgress.Layouts.shades_grey);
// add bars
const b1 = multibar.create(200, 0);
const b2 = multibar.create(1000, 0);
// control bars
b1.increment();
b2.update(20, {filename: "helloworld.txt"});
// stop all bars
multibar.stop();
Constructor
Initialize a new multiprogress container. Bars need to be added. The config/presets are used for each single bar!
const cliProgress = require('baro');
const <instance> = new cliProgress.MultiBar(config:object [, preset:object]);
::create()
Adds a new progress bar to the container and starts the bar. Returns regular SingleBar
object which can be individually controlled.
const <barInstance> = <instance>.create(totalValue:int, startValue:int [, payload:object = {}]);
::remove()
Removes an existing bar from the multi progress container.
<instance>.remove(<barInstance>:object);
::stop()
Stops the all progress bars
<instance>.stop();
Options
The following config can be updated
-
format
(type:string|function) - progress bar output format @see format section -
fps
(type:float) - the maximum update rate (default: 10) -
stream
(type:stream) - output stream to use (default:process.stderr
) -
autoStop
(type:boolean) - automatically callstop()
when the value reaches the total (default: false) -
autoClear
(type:boolean) - clear the progress bar on complete /stop()
call (default: false) -
barSize
(type:int) - the length of the progress bar in chars (default: 40) -
align
(type:char) - position of the progress bar - 'left' (default), 'right' or 'center' -
proChar
(type:char) - character to use as "complete" indicator in the bar (default: "=") -
negChar
(type:char) - character to use as "incomplete" indicator in the bar (default: "-") -
hideCursor
(type:boolean) - hide the cursor during progress operation; restored on complete (default: false) - passnull
to keep terminal settings -
linewrap
(type:boolean) - disable line wrapping (default: false) - passnull
to keep terminal settings; passtrue
to add linebreaks automatically (not recommended) -
etaCapacity
(type:int) - number of updates with which to calculate the eta; higher numbers give a more stable eta (default: 10) -
etaAutoUpdate
(type:boolean) - trigger an eta calculation update during asynchronous rendering trigger using the current value - should only be used for long running processes in conjunction with loffps
values and largeetaCapacity
(default: false) -
syncUpdate
(type:boolean) - trigger redraw duringupdate()
in case threshold time x2 is exceeded (default: true) - limited to single bar usage -
noTTYOutput
(type:boolean) - enable scheduled output to noTTY streams - e.g. redirect to files (default: false) -
notTTYSchedule
(type:int) - set the output schedule/interval for noTTY output inms
(default: 2000ms) -
autoZero
(type:boolean) - display progress bars with 'total' of zero(0) as empty, not full (default: false) -
forceRedraw
(type:boolean) - trigger redraw on every frame even if progress remains the same; can be useful if progress bar gets overwritten by other concurrent writes to the terminal (default: false) -
barGlue
(type:string) - a "glue" string between the complete and incomplete bar elements used to insert ascii control sequences for colorization (default: empty) - Note: in case you add visible "glue" characters the barSize will be increased by the length of the glue! -
autoPadding
(type: boolean) - add padding chars to formatted time and progress to force fixed width (default: false) - Note: handled standard format functions! -
padChar
(type: string) - the character sequence used for autoPadding (default: " ") - Note: due to performance optimizations this value requires a length of 3 identical chars -
barChars
(type: function) - a custom bar format function which renders the bar-element (default: format-bar.js) -
formatTime
(type: function) - a custom timer format function which renders the formatted time elements likeeta_formatted
andduration-formatted
(default: format-time.js) -
formatValue
(type: function) - a custom value format function which renders all other values (default: format-value.js)
Events
The classes extends EventEmitter which allows you to hook into different events.
See event docs for detailed information + examples.
Baro Formatting
The progressbar can be customized by using the following build-in placeholders. They can be combined in any order.
-
{bar}
- the progress bar, customizable by the config barSize, proChars and negChars -
{progress}
- the current progress in percent (0-100) -
{total}
- the end value -
{value}
- the current value set by lastupdate()
call -
{eta}
- expected time of accomplishment in seconds (limited to 115days, otherwise INF is displayed) -
{duration}
- elapsed time in seconds -
{eta_formatted}
- expected time of accomplishment formatted into appropriate units -
{duration_formatted}
- elapsed time formatted into appropriate units
Example
const opt = {
format: 'progress [{bar}] {progress}% | ETA: {eta}s | {value}/{total}'
}
is rendered as
progress [========================================] 100% | ETA: 0s | 200/200
Custom formatters
Instead of a "static" format string it is also possible to pass a custom callback function as format.
For a full example (including params) take a look on lib/format.js
Example 1
function format(config, params, payload){
// bar grows dynamically by current progress - no whitespaces are added
const bar = config.barCompleteString.substr(0, Math.round(params.progress*config.barSize));
// end value reached ?
// change color to green when finished
if (params.value >= params.total){
return '# ' + _colors.grey(payload.task) + ' ' + _colors.green(params.value + '/' + params.total) + ' --[' + bar + ']-- ';
}else{
return '# ' + payload.task + ' ' + _colors.yellow(params.value + '/' + params.total) + ' --[' + bar + ']-- ';
}
}
const opt = {
format: format
}
is rendered as
# Task 1 0/200 --[]--
# Task 1 98/200 --[████████████████████]--
# Task 1 200/200 --[████████████████████████████████████████]--
Example 2
You can also access the default format functions to use them within your format:
const {TimeFormat, ValueFormat, BarFormat, Formatter} = require('cli-progess').Format;
...
Examples
Example 1 - Set Options
// change the progress characters
// set fps limit to 5
// change the output stream and barSize
const bar = new _progress.Baro({
proChar: '#',
negChar: '.',
fps: 5,
stream: process.stdout,
barSize: 65,
position: 'center'
});
Example 2 - Change Styles defined by Layout
// uee shades preset
// change the barSize
const bar = new _progress.Baro({
barSize: 65,
position: 'right'
}, _progress.Layouts.shades_grey);
Example 3 - Custom Payload
The payload object keys should only contain keys matching standard \w+
regex!
// create new progress bar with custom token "speed"
const bar = new _progress.Baro({
format: 'progress [{bar}] {progress}% | ETA: {eta}s | {value}/{total} | Speed: {speed} kbit'
});
// initialize the bar - set payload token "speed" with the default value "N/A"
bar.init(200, 0, {
speed: "N/A"
});
// some code/update loop
// ...
// update bar value. set custom token "speed" to 125
bar.update(5, {
speed: '125'
});
// process finished
bar.stop();
Example 4 - Custom Layouts
File myPreset.js
const _colors = require('colors');
module.exports = {
format: _colors.red(' {bar}') + ' {progress}% | ETA: {eta}s | {value}/{total} | Speed: {speed} kbit',
proChar: '\u2588',
negChar: '\u2591'
};
Application
const myPreset = require('./myPreset.js');
const bar = new _progress.Baro({
barSize: 65
}, myPreset);
Layouts/Themes
Need a more modern appearance ? baro supports predefined themes via presets. You are welcome to add your custom one :)
But keep in mind that a lot of the "special-chars" rely on Unicode - it might not work as expected on legacy systems.
Default Layouts
The following presets are included by default
- legacy - Styles as of baro v1.3.0
- shades-classic - Unicode background shades are used for the bar
- shades-grey - Unicode background shades with grey bar
- rect - Unicode Rectangles
Compatibility
baro is designed for linux/macOS/container applications which mostly providing standard compliant tty terminals/shells. In non-tty mode it is suitable to be used with logging daemons (cyclic output).
It also works with PowerShell on Windows 10 - the legacy command prompt on outdated Windows versions won't work as expected and is not supported!
Any Questions ? Report a Bug ? Enhancements ?
Please open a new issue on GitHub
License
baro is OpenSource and licensed under the Terms of The MIT License (X11). You're welcome to contribute!