Elapsed

An overview:

Core.elapsedSince - time from a start point
Core.elapsedInterval - time from start point, and between each subsequent call
Core.elapsedOnce - one-time measurement from a start point

Since

Core.elapsedSince yields how much time (in milliseconds) has passed since first invoked. This is the fixed reference point all later invocations are compared to.


import { elapsedSince } from "https://unpkg.com/@ixfx/core/bundle"

// A. Start monitoring elapsed time
const s = elapsedSince();

// ...some time later ...
s(); // B. Elapsed time since (A)

// ...some time later ...
s(); // C. Elapsed time since (A)

Interval

Core.elapsedInterval reports the time from the first initialisation and each subsequent call. Unlike since, there is a not a fixed reference point. It is always comparing to either the initial time or when the callback was last run.

import { elapsedInterval } from "https://unpkg.com/@ixfx/core/bundle"

// A. Start monitoring elapsed time
const i = elapsedInterval();

// ...some time later ...
i(); // B. Elapsed time since (A)

// ...some time later ...
i(); // C. Elapsed time since (B)

Once

Core.elapsedOnce fixes both the start point and a second reference time. After initialisation, it records the time at which the first call happens. This is then given as the value for all future calls.

import { elapsedOnce } from "https://unpkg.com/@ixfx/core/bundle"

// A. Start monitoring elapsed time
const o = elapsedOnce();

// ...some time later...
o(); // B. Time since (A). Since it is the first call, we now fix the second reference.

// ...some time later...
o(); // C. Will be same value as earlier (B-A)

// ... some time later...
o(); // D. As above, forever

Time completion

If you have a sense of how long something should take, you can track progression.

Flow.ofTotal takes an Interval and returns a function that reports back a 0..1 percentage of completion.

import { ofTotal } from "https://unpkg.com/ixfx/dist/flow.js"
const timer = ofTotal({ mins: 1});

// Every time we call timer() we get the progression
// towards the total duration
timer();

Since we could call the function after the duration has elapsed, it may well return a number over 1. To avoid this, clamp the value:

const timer = ofTotal({ mins: 1}, { clampValue: true });

It’s also possible to wrap the value. When the total duration is exceeded, the progression wraps around back to zero. Therefore, an elapsed time of 150% is reported as 0.5, not 1.5.

const timer = ofTotal({ mins: 1}, { wrapValue: true });