interval-plus
v1.0.2
Published
Truly pauseable, time-extendable, functionally dynamic intervals and timeouts in a lightweight package
Downloads
23
Maintainers
Readme
Interval Plus
Truly pauseable, time-extendable, functionally dynamic intervals and timeouts in a lightweight package
Features
- Pause and Resume
- Variable time interval
- Immediate function invocation
- Function updating
- Interval progress and status tracking
- Invocation skipping
- 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
func: function, required
- a function to be invoked. Pass an
async
function to ensure asynchronous execution
- a function to be invoked. Pass an
ms: number, required
- how many milliseconds to observe before re-invoking
func
- how many milliseconds to observe before re-invoking
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
- Whether or not to immediately invoke
- name: String (optional), default
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
- 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.