Skip to main content

ProgressTracker

The ProgressTracker class is a tool for tracking progress in an operation that is divided into multiple stages. It allows you to create sub-trackers for each stage, with individual weights and captions. The main tracker automatically calculates the progress based on the weighted sum of each sub-tracker’s progress. This makes it easy to keep track of a complex, multi-stage process and report progress in a user-friendly way.

After creating the sub-trackers, you can call the set() method to update the progress of the current stage. You can also call the finish() method to mark the current stage as complete and move on to the next one. Alternatively, you can call the fillSlowly() method to simulate progress filling up slowly to 100% before calling finish().

@example
const tracker = new ProgressTracker();
tracker.addEventListener('progress', (e) => {
        console.log(
                e.detail.progress,
                e.detail.caption
        );
});

const stage1 = tracker.stage(0.5, 'Calculating pi digits');
const stage2 = tracker.stage(0.5, 'Downloading data');

stage1.fillSlowly();
await calc100DigitsOfPi();
stage1.finish();

await fetchWithProgress(function onProgress(loaded, total) {
        stage2.set( loaded / total * 100);
});
stage2.finish();

Hierarchy

  • EventTarget
    • ProgressTracker

Index

Constructors

Accessors

Methods

Constructors

constructor

Accessors

caption

  • get caption(): string

  • Returns string

done

  • get done(): boolean

  • Returns boolean

loadingListener

observer

  • get observer(): ProgressObserver

  • Returns ProgressObserver

progress

  • get progress(): number

  • Returns number

weight

  • get weight(): number

  • Returns number

Methods

addEventListener

fillSlowly

  • fillSlowly(options?: { stopBeforeFinishing: undefined | boolean }): void

  • Fills the progress bar slowly over time, simulating progress.

    The progress bar is filled in a 100 steps, and each step, the progress is increased by 1. If stopBeforeFinishing is true, the progress bar will stop filling when it reaches 99% so that you can call finish() explicitly.

    If the progress bar is filling or already filled, this method does nothing.

    @example
    const progress = new ProgressTracker({ caption: 'Processing...' });
    progress.fillSlowly();

    Parameters

    • options: { stopBeforeFinishing: undefined | boolean } = {}

      Optional options.

    Returns void

finish

  • finish(): void

  • Returns void

pipe

removeEventListener

set

  • set(value: number): void

  • Parameters

    • value: number

    Returns void

setCaption

  • setCaption(caption: string): void

  • Parameters

    • caption: string

    Returns void

stage

  • Creates a new sub-tracker with a specific weight.

    The weight determines what percentage of the overall progress the sub-tracker represents. For example, if the main tracker is monitoring a process that has two stages, and the first stage is expected to take twice as long as the second stage, you could create the first sub-tracker with a weight of 0.67 and the second sub-tracker with a weight of 0.33.

    The caption is an optional string that describes the current stage of the operation. If provided, it will be used as the progress caption for the sub-tracker. If not provided, the main tracker will look for the next sub-tracker with a non-empty caption and use that as the progress caption instead.

    Returns the newly-created sub-tracker.

    @throws

    If the weight of the new stage would cause the total weight of all stages to exceed 1.

    @example
    const tracker = new ProgressTracker();
    const subTracker1 = tracker.stage(0.67, 'Slow stage');
    const subTracker2 = tracker.stage(0.33, 'Fast stage');

    subTracker2.set(50);
    subTracker1.set(75);
    subTracker2.set(100);
    subTracker1.set(100);

    Parameters

    • optionalweight: number

      The weight of the new stage, as a decimal value between 0 and 1.

    • caption: string = ''

      The caption for the new stage, which will be used as the progress caption for the sub-tracker.

    Returns ProgressTracker