bare-timers
Native timers for Javascript
v3.2.4bare-timers — Native timers for Javascript. It is a native addon and requires Bare >=1.7.0.
Mirrors the Node.js timers module.
npm i bare-timersUsage
const { setTimeout, clearTimeout } = require('bare-timers')API
TimerError
TimerError.code: string
TimerError.name: 'TimerError'
TimerError.INVALID_CALLBACK(msg?: string): TimerError
Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
msg? | string | — | — |
Functions
setTimeout
setTimeout<T extends unknown[]>(callback: (...args: T) => unknown, delay: number, ...args: T): TimeoutSchedule execution once after delay milliseconds, clamped to a minimum of 1ms.
Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
callback | (...args: T) => unknown | — | The function to run after the delay. |
delay | number | — | Milliseconds to wait before running; clamped to a minimum of 1. |
args | T | — | Additional arguments passed to callback. |
clearTimeout(timer: Timeout): void
Cancel a pending timeout, preventing it from firing.
Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
timer | Timeout | — | The timeout handle to cancel. |
setInterval
setInterval<T extends unknown[]>(callback: (...args: T) => unknown, delay: number, ...args: T): TimeoutSchedule repeated execution every delay milliseconds, clamped to a minimum of 1ms.
Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
callback | (...args: T) => unknown | — | The function to run on each interval. |
delay | number | — | Milliseconds between runs; clamped to a minimum of 1. |
args | T | — | Additional arguments passed to callback. |
clearInterval(timer: Timeout): void
Cancel a pending interval, preventing further firings.
Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
timer | Timeout | — | The interval handle to cancel. |
setImmediate<T extends unknown[]>(callback: (...args: T) => unknown, ...args: T): Immediate
Schedule execution once at the end of the current event loop iteration.
Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
callback | (...args: T) => unknown | — | The function to run at the end of the current event loop iteration. |
args | T | — | Additional arguments passed to callback. |
clearImmediate(immediate: Immediate): void
Cancel a pending immediate, preventing it from firing.
Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
immediate | Immediate | — | The immediate handle to cancel. |
Types
Timeout
interface Timeout {
refresh(): this
ref(): this
unref(): this
hasRef(): boolean
}The handle returned by setTimeout and setInterval.
refresh() resets the delay so that it counts from now, and returns the timeout. It also works on a timeout that has already fired, which then fires again after its delay. Before v3.2.4, refreshing a fired timeout did not re-arm the native timer, so the callback did not run on time. It ran only when the native timer next woke for another timer, or not at all when no other timer was pending and the process exited first.
Immediate
interface Immediate {
ref(): this
unref(): this
hasRef(): boolean
}The handle returned by setImmediate.
bare-timers/promises
Functions
setTimeout<T>(delay?: number, value?: T, options?: TimeoutOptions): Promise<T>
Schedule execution once after delay milliseconds, clamped to a minimum of 1ms.
Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
delay? | number | — | Milliseconds to wait before running; clamped to a minimum of 1. |
value? | T | — | The value the returned promise resolves with. |
options? | TimeoutOptions | — | Options; ref defaults to true (set false to unref), and signal may be an AbortSignal that cancels the timer. |
setInterval<T>(delay?: number, value?: T, options?: TimeoutOptions): AsyncGenerator<T>
Schedule repeated execution every delay milliseconds, clamped to a minimum of 1ms.
Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
delay? | number | — | Milliseconds between runs; clamped to a minimum of 1. |
value? | T | — | The value yielded on each iteration. |
options? | TimeoutOptions | — | Options; ref defaults to true (set false to unref), and signal may be an AbortSignal that cancels the timer. |
setImmediate<T>(value?: T, options?: ImmediateOptions): Promsie<T>
Schedule execution once at the end of the current event loop iteration.
Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
value? | T | — | The value the returned promise resolves with. |
options? | ImmediateOptions | — | Options; ref defaults to true (set false to unref), and signal may be an AbortSignal that cancels the timer. |
Types
TaskOptions
interface TaskOptions {
ref?: boolean
signal?: AbortSignal
}Shared options for the bare-timers/promises scheduling functions.
TimeoutOptions
interface TimeoutOptions {
ref?: boolean
signal?: AbortSignal
}Options for bare-timers/promises' setTimeout and setInterval.
ImmediateOptions
interface ImmediateOptions {
ref?: boolean
signal?: AbortSignal
}Options for bare-timers/promises' setImmediate.
bare-timers/errors
TimerError
errors.TimerError.code: string
errors.TimerError.name: 'TimerError'
errors.TimerError.INVALID_CALLBACK(msg?: string): TimerError
Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
msg? | string | — | — |
Threat model
bare-timers is one of the addons Bare compiles into its binary, so every Bare process has it, sealed or not, and it inherits Bare's threat model. The module's own threat model, added in v3.2.4, says where it sits in that one. It provides the timers on the event loop, so sealed code can keep the loop alive or starve it, and neither is a bug. The risks it names are precision and lifetime. Fast timers plus SharedArrayBuffer give side channels against anything in the same address space, and the answer is an OS sandbox rather than a coarser timer. A timer is a C structure that JavaScript starts and stops, and stopping a timer from inside its own callback, stopping one twice, and tearing down a thread with timers still armed are the shapes to watch. A use after free or a double free of a timer handle, and any other memory bug in the timer bookkeeping that JavaScript can reach, is reportable.
See also
- Inside Bare these functions are installed as globals, so most code calls them directly without importing anything.
delayis floored to an integer. Adelaythat is less than1,NaN, non-numeric, or greater thanNumber.MAX_SAFE_INTEGERis clamped to1ms. (Node caps the maximum at2147483647; Bare's ceiling isNumber.MAX_SAFE_INTEGER.)- Passing
null,undefined, or a non-object toclearTimeout/clearInterval/clearImmediateis a no-op, as is clearing a handle that has already fired or been cleared. All three delegate to the same routine, so any one can cancel any handle—but use the matching name for clarity. - Every handle also implements
[Symbol.dispose](), so ausing timer = setTimeout(…)declaration cancels the timer when the scope exits. - The usual suspension pattern is to clear timers outright on
suspend;unref()is the alternative for a timer that must keep running across the cycle—the same patternbare-ipcuses for its channel. - Hooks into the Bare runtime's lifecycle events (
idle,resume,wakeup) to pause and restart the underlying native timer. The promise-based API integrates withbare-abort-controller—an optional peer dependency—forsignal-based cancellation. require('bare-timers').promisesis also reachable as the standalonerequire('bare-timers/promises').- Bare modules — the full
bare-*catalog. - Bare runtime API — the runtime these modules extend.
Last updated on