proggy
Progress bar updates at a distance
A decoupled progress bar connector component that lets you emit events on
the process object to provide progress updates from various parts of a
program.
USAGE
Somewhere in your program, you have a thing that is performing actions that
take a while.
In there, you will emit progress
events on the global process
object
using Proggy.
const proggy = require('proggy')
const doSomething = async (listOfItems) => {
const tracker = proggy.createTracker('doing something')
let i = 0
for (const item of listOfItems) {
tracker.update(i++, listOfItems.length)
const result = await doSomething(item)
if (result.more)
listOfItems.push(result.more)
}
tracker.end()
}
Proggy is not a UI component. It is a way to decouple the UI of a progress
bar from the thing that is making the actual progress.
In another part of your program, where you are handling showing stuff to
the user, you can display this information using any of the wonderful
progress bar UI modules available on npm.
const proggy = require('proggy')
const client = proggy.createClient()
If you set the normalize: true
flag, then the client will normalize how
far it thinks the progress should have gone, in order to prevent backwards
motion if the length increases along the way. If using this, then the
total
value will always be set to 100, and the increment
value will
always be some number smaller than 100. Use the actualValue
and
actualTotal
fields to identify how many things have actually been done.
For example, using
cli-progress
:
const cliProgress = require('cli-progress')
const multibar = new cliProgress.MultiBar({
clearOnComplete: true,
hideCursor: true,
format: '[{bar}] {percentage}% | {name} {actualValue}/{actualTotal} {duration_formatted}',
barCompleteChar: '\u2588',
barIncompleteChar: '\u2591',
}, cliProgress.Presets.shades_grey)
const client = proggy.createClient({
normalize: true,
})
const bars = {}
client.on('bar', (key, data) => {
bars[key] = multibar.create(data.total)
})
client.on('progress', (key, data) => {
bars[key].update(data.value, data)
bars[key].setTotal(data.total)
})
client.on('barDone', (key, data) => {
bars[key].stop()
})
client.on('done', () => {
multibar.stop()
})
API
proggy.createTracker(name, [key], [total])
Create a new Tracker
.
key
will default to name
if not set. It must be unique.
new proggy.Tracker(name, [key], [total])
The Tracker class, for emitting progress information.
total
will default to 100
if not set, but will be updated whenever
progress is tracked.
Fields
name
, key
- The name and identifer values set in the constructordone
- true
if the tracker is completed.total
value
- The most recent values updated.
tracker.update(value, total, [metadata])
Update the tracker and emit a 'progress'
event on the process
object.
tracker.finish([metadata])
Alias for tracker.update(tracker.total, tracker.total, metadata)
proggy.createClient(options)
Create a new Client
.
new proggy.Client({ normalize = false, stopOnDone = false })
The Client class, for consuming progress information.
Set normalize: true
in the options object to prevent backward motion and
fix the total
value at 100
.
Set stopOnDone: true
in the options object to tell the client to
automatically stop when it emits its 'done'
event.
Fields
normalize
- whether this Client is in normalizing modesize
- the number of active trackers this Client is aware of
Events
client.on('bar', (key, data) => {})
- Emitted when a new progress bar
is encountered.client.on('progress', (key, data) => {})
- Emitted when an update is
available for a given progress bar.client.on('barDone', (key, data) => {})
- Emitted when a progress bar
is completed.client.on('done', () => {})
- Emitted when all progress bars are
completed.
client.start()
Begin listening for 'progress'
events on the process
object.
Called implicitly if client.on('progress', fn)
is called.
client.stop()
Stop listening for 'progress'
events on the process
object.
Called implicitly when the 'done'
event is emitted, if
client.stopOnDone
is true.
Progress Data
All client events receive data objects containing the following fields, in
addition to whatever else was sent by the tracker
.
key
- The unique key for this progress bar.name
- The name for this progress bar.value
- The current value of the progress. If client.normalize
is
true, then this will always be a number less than 100
, and never reduce
from one update to the next.total
- The expected final value of the progress. If
client.normalize
is true, then this number will always be 100
.actualValue
- The value originally sent by the tracker. If
client.normalize
is not true, then this is always equal to value
.actualTotal
- The total originally sent by the tracker. If
client.normalize
is not true, then this is always equal to total
.done
- True if the tracker explicitly sent done: true
in the data, or
if value
is greater than or equal to total
.- Whatever other fields were set on the
metadata
sent by the tracker.