Interval

A glorified setInterval. Interval provides a more intuitive developer experience to creating intervals, adding scheduled actions and event emission to increase their utility.

Installation

npm i @jacoblockett/interval

Basic Usage

import Interval from "@jacoblockett/interval"

// creates an Interval that will execute actions every 2 seconds
const interval = new Interval(2000)

// adds an action to the action stack, to be executed on every interval
const actionOne = interval.addAction(() => {
	console.log("I'm action number one!")
}, "actionOne") // this action's ID will be "actionOne"

// initializes a listener on "updated" which emits whenever all actions on the current interval have been completed
let actionTwo
interval.on("updated", state => {
	// Dynamically add an action after two intervals have completed
	if (state.intervalsCompleted === 2) {
		actionTwo = interval.addAction(() => {
			console.log("I'm action number two!")
		}) // this action's ID will be a random 8-length string generated by nanoid (https://www.npmjs.com/package/nanoid)
	}

	// Dynamically remove an action after four intervals have completed
	if (state.intervalsCompleted === 4) {
		interval.removeAction(actionOne)
	}

	// Stop the Interval after six intervals have completed
	if (state.intervalsCompleted === 6) {
		interval.stop()
	}
})

interval.start()

API

Interval: Class

Signature:

new Interval(interval?: Number | undefined): Interval

// interval default = 1000
// interval value is in milliseconds, just like a normal setInterval/setTimeout

Description:

Creates a new Interval object.

Interval.isRunning: Getter

Signature:

Interval.isRunning: Boolean

Description:

Checks if the Interval is currently running.

Interval.prototype.setInterval: Function

Signature:

Interval.setInterval(interval: Number): void

Description:

Sets the interval on the Interval object. Can be set at any time to change the interval.

Interval.prototype.start: Function

Signature:

Interval.start(): void

Description:

Starts the Interval.

Interval.prototype.addAction: Function

Signature:

Interval.addAction(action: () => any, actionID?: String | undefined): String

// actionID default = nanoid(8)
// returns the actionID to be used with Interval.prototype.removeAction

Description:

Adds an action to the Interval's action stack. This action will be executed on every subsequent interval after it was added.

Interval.prototype.removeAction: Function

Signature:

Interval.removeAction(actionID: String): void

Description:

Removes the action from the Interval's action stack.

Interval.prototype.stop: Function

Signature:

Interval.stop(): {
    intervalsCompleted: Number,
    timeStarted: BigInt,
    timeStopped: BigInt,
    timeElapsed: BigInt,
}

// returns the final state of the Interval

Description:

Stops the Interval.

Interval.on("start"): Event

Signature:

Interval.on("start", callback?: () => void | undefined): void

Description:

Emits when the Interval starts.

Interval.on("actionAdded"): Event

Signature:

Interval.on("actionAdded", callback?: () => void | undefined): void

Description:

Emits after a new action was added to the action stack.

Interval.on("actionRemoved"): Event

Signature:

Interval.on("actionRemoved", callback?: () => void | undefined): void

Description:

Emits after an action was removed from the action stack.

Interval.on("updating"): Event

Signature:

Interval.on("updating", callback?: (state?: {
    intervalsCompleted: Number,
    startTime: BigInt,
} | undefined) => void | undefined): void

Description:

Emits when the Interval begins running all of the actions on the action stack.

Interval.on("updated"): Event

Signature:

Interval.on("updated", callback?: (state?: {
    intervalsCompleted: Number,
    startTime: BigInt,
} | undefined) => void | undefined): void

Description:

Emits after all of the actions on the action stack have been completed.

Interval.on("stopping"): Event

Signature:

Interval.on("stopping", callback?: (state?: {
    intervalsCompleted: Number,
    startTime: BigInt,
} | undefined) => void | undefined): void

Description:

Emits when the Interval begins to stop and performs cleanup.

Interval.on("stopped"): Event

Signature:

Interval.on("stopped", callback?: (state?: {
    intervalsCompleted: Number,
    timeStarted: BigInt,
    timeStopped: BigInt,
    timeElapsed: BigInt,
} | undefined) => void | undefined): void

Description:

Emits when the Interval finalizes cleanup and stops running.

Maintainers

• Jacob Lockett (author)

License

© 2023 Jacob Lockett

ISC License - the "do almost whatever the f*** you want with it" one.