Neo's Playing Morpheus

    tm-ticker
    TypeScript icon, indicating that this package has built-in type declarations

    2.0.2 • Public • Published

    TM-Ticker

    License: MIT Build Status

    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

    Install

    npm i tm-ticker

    DownloadsWeekly Downloads

    6

    Version

    2.0.2

    License

    MIT

    Unpacked Size

    32.2 kB

    Total Files

    28

    Last publish

    Collaborators

    • taitulism