TM-Ticker

An accurate interval ticker class.

TL;DR

const interval = 1000;
const tickHandler = () => console.log('Tick.');

// create a simple ticker
const myTicker = Ticker.create(interval, tickHandler);

// or construct with more options
const myTicker = new Ticker({
	interval,
    tickHandler,
	tickOnStart: false,
	timeoutObj: {setTimeoutAlternative, clearTimeoutAlternative}
});

// use
myTicker.start();
myTicker.stop();
myTicker.reset();

myTicker.isTicking // boolean
myTicker.isPaused  // boolean
myTicker.timeToNextTick // ms

Installation

$ npm install tm-ticker

import {Ticker} from 'tm-ticker';

Creation

Using the creator function:

const myTicker = Ticker.create(interval?, tickHndler?);

Using the constructor:

const myTicker = new Ticker(options?);

options

Type: TickerOptions

The constructor accepts an optional object with the following properties:

• interval: number (optional)
  Milliseconds between ticks. Must be greater than 50.

• tickHandler: function (optional)
  The ticking callback function. Gets called on every tick.

• tickOnStart: boolean (default = true)
  By default, the first tick happens right on start, synchronously, before any timeout is set. Set tickOnStart to false if you want the first tick only after the first interval.

• timeoutObj: {setTimeout, clearTimeout} (default = globalThis)
  An object that implements both setTimeout and clearTimeout methods. Utilize this option when you want to base your ticker on alternative timeout methods (read more).

interval and tickHandler can also be set after construction using the instance methods:

• .setInterval(interval)
• .onTick(tickHandler)

const myTicker = new Ticker();

myTicker.setInterval(interval)

myTicker.onTick(tickHandler)

There can be only one tickHandler. Setting a new tick handler will override the previous one.

Using the ticker

This part is very straight forward.

You have three main methods:

• .start()
• .stop()
• .reset()

and three readOnly properties:

• isTicking
• isPaused
• timeToNextTick

For the following examples we'll use the same ticker that logs the word "tick" every second.

const myTicker = new Ticker({
    interval: 1000,
    tickHandler: sayTick,
})

.start()

Start ticking. The tickHandler function will get called every <interval> milliseconds. If tickOnStart flag is set to true (default), start will also runs the first tick, before setting the first interval.
When called after .stop() it functions as "resume", completing what's left of the interval that was stopped. There will be no start-tick in this case, regardless of tickOnStart state.

NOTE: .start() will throw an error if called before setting an interval.

myTicker.start()

/*
... 1000 ms
tick
... 1000 ms
tick
... 1000 ms
tick
...
*/

.stop()

Stop ticking (pause). Saves the interval remainder so the next call to .start() will continue from where it stopped.

myTicker.start()
// ... 3800 ms
myTicker.stop() // remainder = 200
// ...
myTicker.start() // resume

/*
... 200 ms
tick
... 1000 ms
tick
... 1000 ms
tick
...
*/

.reset()

Resets the ticker. Calling .reset() while ticking does not stop the ticker. It resets the ticking starting point.
If tickOnStart flag is set to true (default), your tickHandler function will get called.

Calling .reset() after a .stop() resets the timeToNextTick value to zero.

myTicker.start()
// ... 3800 ms
myTicker.stop() // remainder = 200

myTicker.reset() // remainder = 0

myTicker.start()

/*
... 1000 ms
tick
... 1000 ms
tick
... 1000 ms
tick
...
*/

You can also do:

myTicker.stop().reset();

.isTicking

ReadOnly boolean.
Toggled by .start() and .stop() methods:

console.log(myTicker.isTicking) // false

myTicker.start()

console.log(myTicker.isTicking) // true

myTicker.stop()

console.log(myTicker.isTicking) // false

.isPaused

ReadOnly boolean.
"Paused" means the ticker is stopped but hasn't been reset.

console.log(myTicker.isPaused) // false

myTicker.start()

console.log(myTicker.isPaused) // false

myTicker.stop()

console.log(myTicker.isPaused) // true

myTicker.reset()

console.log(myTicker.isPaused) // false

.timeToNextTick

ReadOnly number.
The number of milliseconds left to next tick. Resets to zero when .reset() is called.

myTicker.start()
// ... 5800 ms
myTicker.stop()

console.log(myTicker.timeToNextTick); // 200
myTicker.reset()
console.log(myTicker.timeToNextTick); // 0

Synchronizing

The main methods, start, stop and reset, accepts an optional timestamp argument.

• timestamp - number, optional

That is the timestamp to be considered as the method's execution time. You can pass in a timestamp when you need to syncronize the ticker with other modules.

For example, let's say we're building a stopwatch module that is based on Ticker. Its startCounting method could be something like:

FancyStopWatch.startCounting = () => {
    const startedAt = Date.now();

    // doing stuff that takes 50 milliseconds to complete...

    myTicker.start(startedAt);
}

Without passing the startedAt timestamp we would loose those 50ms and the first tick would happen 1000 + 50 ms after the user clicked that imaginery START button. If, for whatever reason, we don't want to loose those precious milliseconds we can utilize the timestamp argument.

timeoutObj

By default, Ticker internally uses the global object's setTimeout and clearTimeout methods but sometimes we might want to use alternative methods.

You can provide an object that implements those two methods (with the same argument signatures) to be used by the ticker.

For example, let's say we want to use some kind of a setTimeout-logger that logs every timeout that the ticker sets. It looks like this:

const myTimeoutLogger = {
    setTimeout (callback, ms, ...callbackArgs) {
        const ref = window.setTimeout(callback, ms, ...callbackArgs);

        console.log('Timeout is set');

        return ref;
    },

    clearTimeout: window.clearTimeout
}

To create a Ticker that uses our made up timeout-logger object we use the constructor's timeoutObj option:

const myTicker = new Ticker({
    timeoutObj: myTimeoutLogger
});

Check out "timeout-worker". This npm module utilizes a dedicated web-worker for setting timeouts on a separate process. This makes timeouts more accurate and steady:

import { timeoutWorker } from 'timeout-worker';

timeoutWorker.start();

const myTicker = new Ticker({
    timeoutObj: timeoutWorker
});

Benchmark

Compare TM-Ticker against vanilla setTimeout / setInterval

Run "npm run dev" first.

$ npm run benchmark