Dynamic-interval NPM

dynamic-interval

:clock1: The dynamic setInterval

setInterval with the ability to specify a new interval duration on each tick.

Also referred to as a "dynterval".

Sections

Install

npm install dynamic-interval

Usage

import setDynterval from 'dynamic-interval'

const dynterval = setDynterval(ctx => console.log('tick!', ctx), 100)

Examples

Basic

This script doubles the duration of the interval on each iteration, starting with 50ms:

import setDynterval from 'dynamic-interval'

// you can attach arbitrary properties to this object (in this case, `rate`), but
// `wait` is what's used to determine the duration between each interval
const config = { wait: 50, rate: 2 }

const dynterval = setDynterval(context => {
  console.log('interval', context)

  const next = context.wait * context.rate

  return { ...context, wait: next }
}, config)

// interval { wait: 50,  rate: 2 }
// interval { wait: 100, rate: 2 }
// interval { wait: 200, rate: 2 }
// ...

// clear out the interval after 2 seconds
// NOTE: `window.clearInterval` is not compatible! use the `clear` method instead
setTimeout(() => {
  dynterval.clear()
}, 2000)

Advanced

This script calculates the amount of drift on each step and corrects for it during the subsequent step.

It uses a custom interval api. In this case, we're using worker-timers.

import setDynterval from 'dynamic-interval'
import * as workerTimers from 'worker-timers'

const setAccurateInterval = (func, wait) => {
  let expected = Date.now() + wait

  return setDynterval(context => {
    const drift = Date.now() - expected

    if (drift > wait)
      throw Error(`that drift be crazy: ${drift}`)

    expected += wait

    const next = Math.max(0, wait - drift)

    func(context)

    return { ...context, drift, wait: next }
  }, wait, workerTimers)
}

setAccurateInterval(context => console.log('tick', context), 1000)

Interface

`setDynterval(<action>, <wait|config>, <api>)`

`action`

The callback to invoke on each interval tick

Type: Function
Required

`wait`

Specifies the duration of each interval (i.e. the amount of time to wait between each tick)

Type: Number

`config`

Specifies the configuration of the interval. Passed into the action function as context.

Type: Object
Properties:
- wait
  Specifies the duration of each interval
  - Type: Number
- immediate
  Determines if the interval should start immediately or wait one interval before starting
  - Type: Boolean
  - Default: false

`api`

A custom interval api may be provided. It must define functions for both setInterval and clearInterval.

Type: Object
Properties:
- setTimeout
  Defines how to create a new timeout
  - Type: Function
  - Signature: setTimeout(func: Function, delay: Number)
  - Returns: TimeoutID
  - Default: WindowOrWorkerGlobalScope.setTimeout
- clearTimeout
  Defines how to clear or cancel a timeout
  - Type: Function
  - Signature: clearTimeout(id: TimeoutID)
  - Returns: void
  - Default: WindowOrWorkerGlobalScope.clearTimeout
- setInterval
  Defines how to create a new interval
  - Type: Function
  - Signature: setInterval(func: Function, delay: Number)
  - Returns: IntervalID
  - Default: WindowOrWorkerGlobalScope.setInterval
- clearInterval
  Defines how to clear or cancel an interval
  - Type: Function
  - Signature: clearInterval(id: IntervalID)
  - Returns: void
  - Default: WindowOrWorkerGlobalScope.clearInterval

stateful-dynamic-interval adds pause, resume and grouping functionality to dynamic-interval.
accurate-interval an interval that automatically corrects for local drift on each tick. May be provided as an api.
audio-context-timers an interval that uses the Web Audio API clock. May be provided as an api.
worker-timers an interval that uses Service Workers as a backend. May be provided as an api.