derrickpelletier / node-status

Nodejs stdout status and progress bar. Multi-item, various display types.

node-status

Makes a little stdout status bar. As simple or complex as you need.

npm install node-status

• Config
• Item Options
• Item Methods
• Patterns
• Tokens

Example of custom patterns

Example of steps

Quickstart

var status = require('node-status')
var pizzas = status.addItem('pizza')

status.start()

pizzas.inc()
pizzas.inc(3)

Config

Status accepts the following config options on start():

• invert: defaults to false. Inverts the colors of the bar.
• interval: defaults to 250. Number of milliseconds per re-draw interval.
• pattern: optional manual definition for status bar layout. See Patterns

status.start({
	invert: true,
	interval: 200,
	pattern: 'Doing work: {uptime}  |  {spinner.cyan}  |  {pizza.bar}'
})

Item Options

All item options are optional.

option	type	default	notes
count	number	0	Can specify a starting count if needed.
max	number	null	Will cause 'count' type to display as count/max. Required for some display types. Can be a number or a function that returns a number.
custom	function	null	a function run when the pattern {<item>.custom} is used. Access this.count and this.max for values if needed. Must return a string.
precision	number	2	The precision used in percentages.
steps	Array	false	An array of strings that identify steps for the item. The count of the item identifies the current step.

Item Methods

method	notes
inc( Number )	Increases the count on the item by the desired amount. If no amount is specified, will increase by 1.
dec( Number )	Decreases the count on the item by the desired amount. If no amount is specified, will decrease by 1.
doneStep( success:Boolean, message:String )	A helper method for when using steps on an item. Will stamp the step to the screen with a ✔ when success is true, ✖ when false. An optional message can be added which will be appended to the display. See the gif above, or the examples/steps.js

Patterns

The pattern setting in status config can be used to layout your bar as you see fit, if the default doesn't suit you. Simply a string of tokens.

The pattern:

'Doing work: {uptime}  |  {spinner.cyan}  |  {pizza.bar}'

Would render as:

Doing work: 10s  |  ⠼  |  [▒▒▒▒▒▒----]

Tokens are specified as: {<token>[.color][.modifier]}.

All tokens support colorization with marak/colors.

Non-item tokens

token	modifiers	notes
uptime		renders the current uptime of the process.
spinner	spinner types	renders a spinner. Any type available in cli-spinners can be used. Ex: {spinner.bouncingBall.cyan}

Item tokens

All items use their name as tokens. If you add an item named pizza, you can render it in the pattern with {pizza}. Simple.

Item type modifiers

The items have a number of types available to render.

type	example
default	5 or 5/10	With no type specified, item is rendered as the count, or the count/max if max was specified.
percentage	15.23%	Renders a simple percentage, requires max to be set. Uses the precision setting to round the value.
custom	anything	Renders whatever is returned by the specified custom function.
bar	[▒▒▒▒▒-----]	Renders as a progress bar. Requires max to be set.
time	15s	Uses the count as milliseconds and renders the value as a nicely formatted time.

Using Console.log alongside status

Right now, if you have to use console.log after the status bar has started, it can be a bit janky because the stdout line isn't cleared when a console.log is run.

You can utilize an extended console.log by adding this after requiring status.

console = status.console()

node-status's Issues

Bottom setting

Would like a setting for whether the bar should be at the bottom of the window or just at the current cursor.

Add ability to remove items from bar

It would be useful to be able to remove items programmatically to change the representation on the fly.
#16 has a similar request, wanted to wipe out a whole bar. That might come as a byproduct of this, but I'd like to be able to remove individual items first.

Clear and start another?

Hello!

Could you please give an example of how one progress bar could be stopped and another one started?

Right now, I'm calling:

status.clear();
status.removeAll();

between two progress bar executions, but it didn't reset the time counter for some reason.

Include get val

please include:

Item.prototype = {
inc: function(amount){
this.val += (amount !== undefined) ? amount : 1;
},

dec: function(amount){
this.val -= (amount !== undefined) ? amount : 1;
},

val: function(){
return this.val;
},
}

tests for 1.0 changes

not compatible with console.debug and 2>error.log

Dears,

Thanks a lot for this very module !

Nevertheless, it's not working very well when I'm calling it that way :

node ftp_to_s3.js 3754 2>error.log.2

(using console.debug() which does not cause the display problem)

How could we do ?

Does not work in Windows terminal

It only renders after the task is complete. I ran your example and it does not render the increments.
It's a great looking UI tool, I'd love to be able to use it in a Windows environment if possible.

Thanks :)

Adding spinner support

Adding support for quickly adding a spinner to the status bar.

Move docs into subdir so readme isn't so messy.

Setting the 'label' property has no effect

Does not handle console.error properly

The console replacement doesn't handle messages printed to console.error gracefully.

Add support for ETA

Hello!

Thank you for this great library!

However, it would be really cool, if it will display ETA of the process, automatically calculated based on the overall performance.

Thanks!

Write TTY tests

A number of portions of the code rely on being written to tty for testing.
Need to look into maybe using tty.js for testing.
That or maybe I make the output stream configurable?

Pattern support

This is a big-ish issue because it means removing a lot of old functionality and accommodating differences.

• Adding in pattern support, which allows designing the status bar manually.
• Removing type option on items as it will be supported through the pattern itself.
• default pattern will be generated as items are added.
• removing uptime setting as it can be specified through pattern.
• removing label setting as it can be specified through pattern.
• accommodating loss of custom function type. Not sure what to do here yet.
• remove color option from items, can be specified in pattern.

Time format show decimal time (instead of hh:mm:ss)

We're running tasks here that can take almost an hour. Time elapsed currently shows as decimal once we're past the 2-minute mark. Currently it reads '33.867m'. Is there a way to change the timeformatting here to something more straight forward like '33:52'?

Does not work with node apps launched using Foreman

No too sure who's to blame, but just so you all know, node-status does not seem to work if the node app is started using Foreman. Might be a problem for all modules making use of Charm... (?)

Add status methods to docs

Get rid of the blinking cursor inside the status bar

It sits on the far left and blinks. I think it should only be removed when bottom === false, as the bar is rendered on the current line. But when Bottom is true, the bar is rendered at the bottom of the tty and the cursor remains in place where it should be.

Allow one 'count' to be the sum of several other counts

If status consists of counts for e.g. 'new items', 'updated items', and 'failed items' then it would be good if it was possible to have a 'total items' that was the sum of the parts. E.g. by allowing assignment of a function to the count property. Something like:
count: function() { return status.new.count + status.updated.count + status.failed.count }
Thus avoiding having to call inc() on more than one counter.