@souct/ticker v1.5.4

TM-Ticker

An interval ticker class (no GUI).

Installation

$ npm install tm-ticker

import Ticker from 'tm-ticker';
// or
const Ticker = require('tm-ticker');

TL;DR

Jump to API

Create:

// construct & config
const t = new Ticker(interval, callback, tickOnStart = true)

// or just construct (and config later)
const t = new Ticker()

Config:

t.tickOnStart = bool // deafult: true
t.setInterval(number)
t.setCallback(fn)
t.set(interval, callback)

Use:

now is optional

 t.start(now)

 t.getTimeLeft(now)

 t.stop(now)

 t.reset(now)

 t.destroy()

API

Constructor

new Ticker(interval, callback, tickOnStart);

• interval number, optional
  Milliseconds between ticks. Must be greater than 50.

• callback function, optional
  Tick handler function. Gets called on every tick.

• tickOnStart boolean, optional, default: true
  By default, the first tick happens on start, synchronously, before any timeout. Set to false if you want the first tick to happen only after the first interval.

Configuration

A Ticker instance won't tick unless it has an interval and a tick callback.
You can do it on construction or later with the following methods which are very self explanatory:

const myTicker = new Ticker();

myTicker.setInterval(1000)
myTicker.setCallback(myFunc)
myTicker.set(1000, myFunc)

// default is true.
myTicker.tickOnStart = false

You can also set the interval & callback directly as props but this way bypasses type validation for both and min number validation for interval (should be greater than 50ms).

myTicker.interval = 1000
myTicker.callback = myFunc

Methods

All methods can get called with a timestamp argument. Pass in a current timestamp when you need to sync time with other modules.

• timestamp (ms, number, optional) - The timestamp to be considered as the method's execution time.

.start()

Start ticking.

If tickOnStart is set to true (default behavior), your callback will get called on start (as opposed to only after the first interval)

When called after a .stop() it acts as a "resume" function. There will be no start-tick in this case. The next tick is calculated based on the timeLeft record.

// optional
const timestamp = Date.now()

myTicker.start(timestamp)

.getTimeLeft()

Returns how many milliseconds left to next tick.

const myTicker = new Ticker(1000, callback)

myTicker.start()

// after about two ticks and a half (2480ms)
myTicker.getTimeLeft() // --> 520

.stop()

Stop/Pause ticking.

When called, the Ticker instance calculates the time left to next tick and stores it on a timeLeft prop in case you'll want to resume ticking from exact same point.
Run .start() to resume.

const myTicker = new Ticker(1000, sayTick)

myTicker.start() // TICK!

// Time passes by.. TICK!.. TICK!..
myTicker.stop()

console.log(myTicker.timeLeft) // 680 (ms left to next tick)

// resume
myTicker.start() // next tick in 680ms.

.reset()

Reset the ticker.

Reseting a ticker doesn't change its initial interval.

Can be called whether the ticker is running or not:

• When running: Restart as if you have just started. Doesn't stop the ticker.
• When stopped: Reset the recorded timeLeft.

const myTicker = new Ticker(1000, sayTick)

myTicker.start() // new start point
myTicker.reset() // new start point. still running...
myTicker.stop() // save `timeLeft`

myTicker.start() // resume from the same point
myTicker.stop()  // save `timeLeft`
myTicker.reset() // reset `timeLeft`

myTicker.start() // new start point

.destroy()

Destroy the ticker.

Calls .stop() and .reset() and set the .isOk prop to false.

To use the same Ticker instance again, isOk should be set to true.

const myTicker = new Ticker(1000, sayTick)

myTicker.start()
myTicker.destroy()

// Resurrection
myTicker.isOk = true;

myTicker.start()

Playground / benchmark

Compares Ticker with using vanilla setTimeout & setInterval

$ npm run playground