bare-timers

Reference for bare-timers: native setTimeout, setInterval, setImmediate, and their clear functions for Bare, plus ref/unref control over event-loop references.

stable

bare-timers provides the timer functions for Bare—setTimeout, setInterval, setImmediate, and their clear* counterparts. The shape mirrors the Node.js timers API. Inside Bare these functions are installed as globals, so most code calls them directly without importing anything. It's a native addon and requires Bare >=1.7.0.

Require the module explicitly only to be version-specific or to reach the promise-based API:

npm i bare-timers

Usage

// Globals — no import needed inside Bare
const timer = setInterval(() => console.log('tick'), 1000)

setTimeout(() => clearInterval(timer), 5000)

// Or require the module explicitly
const timers = require('bare-timers')

timers.setTimeout(() => console.log('hello world'), 100)

API

The signatures match Node.js. The Bare-specific points are called out below: a timer handle is an object rather than a numeric id, every handle is referenced by default, and the maximum delay is much larger than Node's.

Timers

`setTimeout(callback, delay[, ...args])`

Schedule callback to run once after delay milliseconds. Any extra args are forwarded to callback. Returns a Timeout handle.

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.)

`setInterval(callback, delay[, ...args])`

Like setTimeout, but re-runs callback every delay milliseconds until cleared. Returns a Timeout handle. The same delay clamping applies.

`setImmediate(callback[, ...args])`

Schedule callback to run after the current operation completes, ahead of any pending timeouts. There is no delay argument. Extra args are forwarded to callback. Returns an Immediate handle.

`clearTimeout(timer)` · `clearInterval(timer)` · `clearImmediate(immediate)`

Cancel a pending handle. Passing null, undefined, or a non-object 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.

Timer handles

setTimeout and setInterval return a Timeout; setImmediate returns an Immediate. Unlike browsers—where the timer functions return a numeric id—Bare returns an object handle, as Node.js does. Keep the handle to clear, re-reference, or refresh the timer. Every handle also implements [Symbol.dispose](), so a using timer = setTimeout(…) declaration cancels the timer when the scope exits.

A handle is referenced when created. While it is active and referenced it keeps the event loop alive—which is exactly what prevents a backgrounded app from going idle. See Handle app suspension for why this matters on mobile.

`timer.ref()`

Mark the handle as keeping the event loop alive. Handles start referenced, so this only matters after a previous unref(). Returns the handle. No-op if the handle is already referenced or no longer active.

`timer.unref()`

Remove the handle from the loop's reference count without canceling it. The callback still fires if something else keeps the loop alive, but the timer alone will no longer prevent the loop from going idle. Returns the handle. No-op if the handle is already unreferenced or no longer active.

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.

`timer.hasRef()`

Return true if the handle currently holds a reference on the event loop.

`timer.refresh()`

Reschedule a Timeout to fire delay milliseconds from now, reusing the same handle, callback, and args; reactivates the handle if it had been cleared. Returns the handle. Available on setTimeout and setInterval handles only—Immediate has no refresh().

Promise-based timers

require('bare-timers').promises (also reachable as require('bare-timers/promises')) exposes promise-returning variants. Each accepts an options object with ref (set to false to unref() the underlying timer) and signal (an AbortSignal that cancels the timer when aborted).

const { setTimeout } = require('bare-timers').promises

await setTimeout(1000) // sleep for one second

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. See Bare modules.