Bare Docs

bare-timers

Native timers for Javascript

Documented against v3.2.4
stable

bare-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-timers

Usage

const { setTimeout, clearTimeout } = require('bare-timers')

API

TimerError

TimerError.code: string

TimerError.name: 'TimerError'

TimerError.INVALID_CALLBACK(msg?: string): TimerError

Parameters

ParameterTypeDefaultDescription
msg?string——

Functions

setTimeout

setTimeout<T extends unknown[]>(callback: (...args: T) => unknown, delay: number, ...args: T): Timeout

Schedule execution once after delay milliseconds, clamped to a minimum of 1ms.

Parameters

ParameterTypeDefaultDescription
callback(...args: T) => unknown—The function to run after the delay.
delaynumber—Milliseconds to wait before running; clamped to a minimum of 1.
argsT—Additional arguments passed to callback.

clearTimeout(timer: Timeout): void

Cancel a pending timeout, preventing it from firing.

Parameters

ParameterTypeDefaultDescription
timerTimeout—The timeout handle to cancel.

setInterval

setInterval<T extends unknown[]>(callback: (...args: T) => unknown, delay: number, ...args: T): Timeout

Schedule repeated execution every delay milliseconds, clamped to a minimum of 1ms.

Parameters

ParameterTypeDefaultDescription
callback(...args: T) => unknown—The function to run on each interval.
delaynumber—Milliseconds between runs; clamped to a minimum of 1.
argsT—Additional arguments passed to callback.

clearInterval(timer: Timeout): void

Cancel a pending interval, preventing further firings.

Parameters

ParameterTypeDefaultDescription
timerTimeout—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

ParameterTypeDefaultDescription
callback(...args: T) => unknown—The function to run at the end of the current event loop iteration.
argsT—Additional arguments passed to callback.

clearImmediate(immediate: Immediate): void

Cancel a pending immediate, preventing it from firing.

Parameters

ParameterTypeDefaultDescription
immediateImmediate—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

ParameterTypeDefaultDescription
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

ParameterTypeDefaultDescription
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

ParameterTypeDefaultDescription
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

ParameterTypeDefaultDescription
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.
  • delay is floored to an integer. A delay that is less than 1, NaN, non-numeric, or greater than Number.MAX_SAFE_INTEGER is clamped to 1 ms. (Node caps the maximum at 2147483647; Bare's ceiling is Number.MAX_SAFE_INTEGER.)
  • Passing null, undefined, or a non-object to clearTimeout/clearInterval/clearImmediate is 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 a using 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 pattern bare-ipc uses 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 with bare-abort-controller—an optional peer dependency—for signal-based cancellation.
  • require('bare-timers').promises is also reachable as the standalone require('bare-timers/promises').
  • Bare modules — the full bare-* catalog.
  • Bare runtime API — the runtime these modules extend.

Last updated on

Was this helpful?

On this page