@porkchopsandwich/progress-tracker
v1.0.0
Published
Sequential or parallel progress tracking, and nested progress trackers.
Downloads
4
Readme
Progress Tracker
Sequential or parallel progress tracking, and nested progress trackers.
Requires support (native or polyfill) for Map/Set/WeakMap.
Installation
npm install --save @porkchopsandwich/progress-tracker
Use
Basics
Three Progress Trackers are available:
- Sequential Progress Tracker (
const progressTracker = sequentialProgressTracker(maxStates);
)- Used to represent a simple progress list whose 'steps' are progressed through sequentially.
- Indexed Progress Tracker (
const progressTracker = indexedProgressTracker(maxStates);
)- Used to represent a progress list whose 'steps' are identified by index and may be populated out of order, or whose values may change.
- Parent Progress Tracker (
const progressTracker = parentProgressTracker();
)- Used to contain child progress trackers (which can also be parents). Whenever a child progresses, the parent state is updated as well.
In TypeScript, use a string union to limit the valid progress states for a progress tracker:
type States = "success" | "failure";
const progressTracker = sequentialProgressTracker<States>(5);
Progressing
Sequential Progress Trackers are progressed by passing in the next progress value, or values:
// Single next value
progressTracker.progress("success");
// Multiple values
progressTracker.progress("success", "failure", "success");
Indexed Progress Trackers are progressed by indicating the (0-based) index to update, and the new value:
progressTracker.progress(2, "failure");
Tracking progress
Progress Trackers publish events when they are updated. These can be subscribed to with .subscribe()
. The current state can be read at any time with .getCurrentState()
.
const subscription = progressTracker.subscribe((state) => {
// Do something
});
// When finished, unsubscribe to stop receiving events
subscription.unsubscribe();
// Get the current state at any time:
const currentState = progressTracker.getCurrentState();
State object
The state object received by listeners, or returned by getCurrentState()
looks like:
- maxState: The maximum number of states (as defined upon creation or reset)
- progressedStates: The number of state progressions that have occured so far
- stateMap: An object whose keys are the State types ("success", "failure") and whose values are the number of times those States have been progressed.
- Types that have not yet been progressed at all will not be present in the object.
- stateList: An array of the progression states as they were added.
- For Sequential Progress Trackers this array will initially be zero-length, and will grow as entries are added.
- For Indexed Progress Trackers this array will be pre-populated with undefined, as the progress slots can are filled by index, potentially out of order.
In addition, Parent Progress Trackers have:
- childStates: A
WeakMap
whose keys are the child progress trackers, and whose values are those trackers' current states.
For example:
{
maxState: 5,
progressedState: 3,
stateMap: {
success: 2,
failure: 1,
},
stateList: ["success", "failure", "success"],
// If it is a parent tracker state
childStates: WeakMap<ProgressTracker, ProgressTrackerState>,
}