nested-progress v1.0.0

Nested Progress

A simple progression tracking library, including nested progressers, written in TypeScript.

Common functionality

Progressers are created via unorderedProgresser(total), orderedProgresser(total) or parentProgresser().

All three types share the following functionality:

import {
    parentProgresser,
    unorderedProgresser,
    orderedProgresser
} from "nested-progress";

// If using TypeScript, use a string union type to define the possible states
// This permits type hinting of the progress state
type States = "success" | "failure";

// Create progresser instances
const ordered = orderedProgresser<States>(total);
// OR
const unordered = unorderedProgresser<States>(total);
// OR
const parent = parentProgresser<States>();

// A progress listener
const listener = (state) => {
    // State varies by progresser type, see below for detail
};

// Subscribe to updates. Returned unsubscriber is a function that when called unsubscribes the listener
const unsubscriber = anyProgresser.addProgressListener(listener);

// Unsubscribe from returned method
unsubscriber();

// Or unsubscribe directly
anyProgresser.removeProgressListener(listener);

// Get the current state directly
const currentState = anyProgresser.getState();

Specific details about the Progresser types follow.

Unordered Progress

Simply tracks progress through an unordered sequence, ideal for progress bars, etc.

const unordered = unorderedProgresser<States>(3);

// Add listeners to track the progress
unordered.addProgressListener((state) => {
    // state.total: total number of steps that can be progressed
    // state.progressedCount: total number of progressed steps so far
    // state.stateMap: A hash containing the progress states and how many times they have been progressed.
    
    // E.g. { total: 3, progressedCount: 1, stateMap: { success: 1 }}
});

// Add progress to trigger the event listeners
unordered.progress("success");
unordered.progress("failure");
unordered.progress("success");

// If adding more than the total, a RangeError is thrown
unordered.progress("success"); // throws RangeError

// Reset. Can pass a new initial total
const newTotal = 5;
unordered.reset(newTotal);

Ordered Progress

Tracks progress via discrete indexes, ideal for if the state of one element of the progress may change.

import { orderedProgresser } from "nested-progress";

const ordered = orderedProgresser<States>(3);

// Add listeners to track the progress
ordered.addProgressListener((state) => {
    // state.total: total number of steps that can be progressed
    // state.stateList: An array of <total> length containing the current state of each index. Undefined if no state has been set.
    // E.g. { total: 3, stateList: [undefined, "success", "failure"] }
});

// Update an index's state to trigger the event listeners
// Can be done in any order
ordered.progress(2, "failure");
ordered.progress(1, "success");

// If setting an index < 0 or >= total, throws a RangeError
ordered.progress(5, "success"); // Throws RangeError

// Reset. Can pass a new initial total
const newTotal = 5;
ordered.reset(newTotal);

Parent Progress

Tracks the progress of child progressers, even if those children are themselves parent progressers.

// Create a parent a two children.
// Child types can be mixed at will.
// If using TypeScript, the child States should match the parent States.
const parent = parentProgresser<States>();
const ordered = orderedProgresser<States>(2);
const unordered = unorderedProgresser<States>(2);

// Add event listener
parent.addProgressListener((state) => {
    // state.total: total of the totals of all child progressers
    // state.progressedCount: total of the progressed counts of all child progressers
    // state.stateMap: A hash containing the sum of the progress states and how many times they have been progressed of all child progressers
    // state.childStates: An array of the states of all child progressers, in the order they were added
});

// Add any number of child progressers
// Every time addChildProgressers() is invoked, listeners are invoked with the new state
parent.addChildProgressers(ordered, unordered);

// Update the children to trigger listeners on the parent
unordered.progress("success");
ordered.progress(0, "failure");

// Remove child progressers
// By name...
parent.removeChildProgressers(ordered, unordered);
// Or all at once...
parent.clearChildProgressers();