@concorde2k/progressor v1.0.0

Progressor

The Progressor and associated ProgressStream classes simplify and standardize how progress is tracked when dealing with time-based events. Progressor provides the core functionality. ProgressStream uses Progressor to create a transform stream that has Progressor features.

Progressor Class

The class is an EventEmitter and communicates exclusively through its events.

Constructor

new Progressor(options) Where available options are

• threshold:number - How many frames will pass between progress reports. So, if you pass a value of 100, then it will report progress every 100 frames. Required
• expected:number - How many records overall. You may not know this advance and so it is optional. If your provide it, the progress event will return percentage complete and some other neat stuff.

Events

As stated above, this is how you will interact with the object. You can raise events on the object and respond to some events.

Talk to Progressor

progressor:sample - This tells the object that something happened. What happened is not salient for our Progressor hero, just that something did. We call what was measured a "frame" so that it is generic and carries no semantic baggage. You can pass in an optional parameter which will tell the object how many frames passed. It defaults to 1.

const counter = new Progressor({threshold: 1000});
for (i = 0; i <= 20000; i++){
    counter.emit("progressor:sample");
}

progressor:startMetering - This tells the object to start looking for frames. If progressor:sample is called and this event has not yet been called, it will raise this event automatically.

progressor:endMetering - This tell the object that it will not expect any further frames

Progressor talks to you

progressor:started - this is raised when the object is told to start or when the first sample comes in - whichever is first.

progressor:ended - The last frame came in and the process is complete

progressor:progress - This is actually the most import event here. This tells you that the threshold was met and it will return you a fairly detailed object with information about the stream.

Metrics

This is what is returned to you on the progress event

• time - When the event was raised. Milliseconds since UTC epoch
• start - When the progressor received the start event. Milliseconds since UTC epoch
• end - When the progressor received the end event. This may not be null. Milliseconds since UTC epoch
• expected - How many records were expected. May be null if it was not provided on creation
• count - How many frames were counted
• elapsed - How many milliseconds have passed since it received the start event
• rate - Frames per second.
• threshold - The configured value for the threshold passed in when the object was created
• events - A diagnostic value for streams. Some streams raise null "chunks", but this will only count chunks with values. This counter includes null chunks.
• formatted - If you are wondering how to display all this info, this field has a pre-formatted string suitable for logging.

ProgressStream

The ProgressStream is a Transform Stream that simply passes through to the next end of the pipe. But before it does, it records the passage of data on an internal instance of Progressor. When the threshold is met, it automatically logs the formatted string from the progress event. You can pass any option that is valid for the transform stream and that will be passed directly through. We add three new options:

• threshold:number - How many frames will pass between progress reports. So, if you pass a value of 100, then it will report progress every 100 frames. Required
• expected:number - How many records overall. You may not know this advance and so it is optional. If your provide it, the progress event will return percentage complete and some other neat stuff.
• name:string - The logger name that will be used.