interval-plus v1.0.2

Interval Plus

Truly pauseable, time-extendable, functionally dynamic intervals and timeouts in a lightweight package

• Interval Plus
  • Features
  • Motivation
  • Getting Started
    • Install and Import
      • Node.js
      • Browser
  • Usage
    • Instantiation
      • Constructor Parameters
    • Instantiation Examples
  • Operations
    • pause()
    • resume()
    • stop()
    • changeInterval(ms)
      • Function Parameters
    • nextInvocationTime()
    • nextInvocationActiveMs()
    • prevInvocationStartTime()
    • prevInvocationEndTime()
    • prevInvocationStartActiveMs()
    • prevInvocationEndActiveMs()
    • skipToNextInvocation()
    • hasFutureInvocations()

Features

1. Pause and Resume
2. Variable time interval
3. Immediate function invocation
4. Function updating
5. Interval progress and status tracking
6. Invocation skipping
7. Asynchronous execution (async/await)

Motivation

JavaScript's setInterval and setTimeout offerings are fundamentally weak due to their inflexibility. To achieve their desired interval behavior, developers often have to re-instantiate intervals, manage or track interval instances, or implement other workaround solutions. I first developed this package to support the features above necessary in my personal projects, then decided to open source the package.

Getting Started

Install and Import

Node.js

npm i interval-plus

const { IntervalPlus, TimeoutPlus } = require("interval-plus")

// or

import {IntervalPlus, TimeoutPlus} from "interval-plus"

Browser

<script src="https://cdn.jsdelivr.net/npm/interval-plus@latest/src/index.js"></script>

Usage

Instantiation

const interval = new IntervalPlus(func, ms, options)
const timeout = new TimeoutPlus(func, ms, options)

Constructor Parameters

1. func: function, required
   • a function to be invoked. Pass an async function to ensure asynchronous execution

2. ms: number, required

   • how many milliseconds to observe before re-invoking func

3. options: Object (optional)

   • name: String (optional), default "IntervalPlus"
     • An identifier to represent the IntervalPlus or TimeoutPlus object logs.
   • verbose: boolean (optional), default false
     • Whether or not to output logs to the console during key interval events
   • immediate: boolean (optional), default `false
     • Whether or not to immediately invoke func once instantiated

Instantiation Examples

const interval = new IntervalPlus(() => {
    console.log("it's been 1 second!")
}), 1000)

const timeout = new TimeoutPlus(() => {
    console.log("Execute once after 2 seconds")
}), 2000, {
    name: "myFirstTimeout",
    verbose: true
})

const immediateInterval = new IntervalPlus(() => {
    console.log("Execute now, then every 3 seconds")
}), 3000, {
    immediate: true
})

Operations

pause()

await interval.pause()

Allow the interval to sleep, freezing the amount of active time to elapse before next invocation.

This operation is idempotent - calling it multiple times sequentially is a the same as a single call.

If called during invocation, this operation will apply as soon as invocation terminates.

resume()

interval.resume()

Wake the interval from its sleep, counting down the remaining active time until next invocation.

This operation is idempotent - calling it multiple times sequentially is a the same as a single call.

stop()

await interval.stop()

Terminate the interval and its future invocation schedule.

Under the hood, this method calls clearInterval to ensure no ongoing asynchronous processes remain.

This operation is idempotent - calling it multiple times sequentially is a the same as a single call.

If called during invocation, this operation will apply as soon as invocation terminates.

changeInterval(ms)

await interval.changeInterval(2500)

Function Parameters

1. ms: number, required

Adjust the interval's millisecond wait between invocations to equal ms.

If called during invocation, this operation will apply as soon as invocation terminates.

nextInvocationTime()

const nextDateObj = interval.nextInvocationTime()

Obtain a Date object corresponding to the next invocation, assuming no pausing.

Returns "now" if currently executing. Returns "paused" if paused.

nextInvocationActiveMs()

const nextMs = interval.nextInvocationActiveMs()

Get the number of active milliseconds until next invocation. Active means time passing while in a non-paused state.

Returns "now" if currently executing. Returns "paused" if paused.

prevInvocationStartTime()

const prevStart = interval.prevInvocationStartTime()

Obtain a Date object corresponding to the start of the previous invocation.

Returns undefined if no previous invocation.

prevInvocationEndTime()

const prevEnd = interval.prevInvocationEndTime()

Obtain a Date object corresponding to the end of the previous invocation.

Returns undefined if no previous invocation end.

prevInvocationStartActiveMs()

const prevStartMs = interval.prevInvocationStartActiveMs()

Get the number of active milliseconds since the previous invocation start. Active means time passed while in a non-paused state.

Returns undefined if no previous invocation.

prevInvocationEndActiveMs()

const prevEndMs = interval.prevInvocationeEndActiveMs()

Get the number of active milliseconds since the previous invocation end. Active means time passed while in a non-paused state.

Returns undefined if no previous invocation end.

skipToNextInvocation()

await interval.skipToNextInvocation()

Immediately skip forward to the next invocation, respecting a constant time interval afterwards.

If called during invocation, this operation will apply as soon as invocation terminates.

hasFutureInvocations()

const isAlive = interval.hasFutureInvocations()

Returns a boolean describing whether or not future invocations will be made. For instance, this function returns false once stop() has been called.