Yapb NPM | npm.io

CLI-Progress

Progress bars, spinners and updating statistics for CLI processes!

Features

Progress bar that auto-sizes to the terminal width using window-size
Spinner support via cli-spinners
Proper support for clearing up after itself
Mustache templating support
Very simple syntax where any setting can be changed at any time - even the template
'Lazy' initialization of values, you can setup the progress bar before knowing any of the data you will be feeding into it (setting the 'maximum' is usually required by all other progress libraries)
Works fully without any 'raw' values - use it purely for spinners or other dynamic text
Works in a fully synchronous environment

var progress = require('cli-progress');

var myProgress = progress('{{spinner}} Loading widgets... [{{bar}}] {{percent}}%', {max: 300});

var current = 0;
var tick = function() {
	if (current == 300) { // Stop at 300 ticks
		myProgress.remove();
	} else {
		myProgress.update(++current);
		setTimeout(tick, 50);
	}
};
setTimeout(tick, 50);

See the examples folder for more.

Settings

Settings are simple keys stored in progressBar.settings. You can define your own properties, tokens and templates as needed at any time. See the Mustache documentation for more information.

Key	Type	Default	Description
`text`	string	`'{{current}} / {{max}} [{{bar}}] {{percent}}%'`	The template to use when rendering the object
`current`	number	0	The 'current' progress. This can be any number lower than `max`
`max`	number	100	The 'max' progress value. This should always be higher or equal to `current`
`stream`	Stream	`process.stderr`	What output stream to use
`render`	Function	see code	The render function used to output the object to the screen. The default version clears the active line and paints the output with the result of `format()`
`clear`	Function	see code	The function to invoke on any `remove()` call. The default version resets the current line
`width`	number	result of windowSize.width	The terminal width. This should be automatically calculated
`completeChar`	string	`=`	The character to use when rendering a progress bar. This character represents the left-most 'done' portion of the bar
`incompleteChar`	string	`=`	The character to use when rendering a progress bar. This character represents the right-most 'not done' portion of the bar
`percent`	Function	see code	Simple pre-prepared template function to return a number between 0 - 100 representing the process of `current / max * 100`
`throttle`	number	50	Restrict redrawing to this many milliseconds. Set this to any falsy value to disable throttling
`throttleSync`	boolean	false	Set this to true if the bar needs redrawing in a synchronous environment where tick'd redraws are unavailable
`spinner`	Function	see code	Spinner rendering function. This function is called on each draw phase to return the current spinner
`spinnerTheme`	string	`dots`	The spinner theme within cli-spinners to use when drawing the spinner
`spinnerFrame`	number	0	The current spinner animation frame. This is used by the `spinner` callback to store its current position
`startTime`	number	`Date.now()`	Timestamp in milliseconds when the object was created (used to calculate `eta`)
`eta`	Function	see code	The render function used to calculate and output the estimated completion time using `startTime` and `current` as a guide
`etaFormat`	string	`auto`	Formatting for the ETA display. This broadly follows the moment convention. Options: `auto`, `H:M:s.S`, `H:M:s`, `M:s.S`, `M:s`, `s`, `s.S`

API

update(settings|current value)

Main function to accept optional updated settings or a single new current value. This function will also redraw the object on the screen after update. If you wish to update settings without redrawing use set() instead.