Skip to content
Tutorials Center
My learning

Topics

Node.js Reference ยท Events and Timers

Node.js timers/promises setTimeout() function

Reference for setTimeout() from node:timers/promises: await a delay, resolve with a value, cancel with an AbortSignal and control ref behavior.

setTimeout(delay, value, options) from node:timers/promises returns a promise that fulfills with value after at least delay milliseconds. It is the awaitable version of the global setTimeout(): no callback, no Timeout object, just await sleep(100) style code.

Cancellation is done with an AbortSignal in the options. When the signal aborts, the timer is cleared and the promise rejects with an AbortError, so no stray timer keeps the process alive.

NODE
import { setTimeout as sleep } from 'node:timers/promises';

const value = await sleep(50, 'done');

Try it

Node.js Sleeping with a value

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Node.js Cancelling with AbortSignal

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Syntax

NODE
import { setTimeout } from 'node:timers/promises';

setTimeout([delay[, value[, options]]]): Promise<any>
Name Description
delay Milliseconds to wait. Default 1. Values that are not a number between 1 and 2147483647 are treated as 1.
value Anything. The promise fulfills with it. Default undefined.
options.signal An AbortSignal. Aborting rejects the promise with AbortError (err.code === 'ABORT_ERR').
options.ref Boolean, default true. With false, the pending timer does not keep the event loop alive.

Returns: a Promise that fulfills with value.

Errors: AbortError when the signal aborts, whether before or during the wait. ERR_INVALID_ARG_TYPE for options of the wrong type.

Usage notes

  • Import it with an alias (import { setTimeout as sleep }) so it does not shadow the global setTimeout().
  • The promise resolves at least delay ms later. Heavy synchronous work or a busy event loop makes it later still.
  • With ref: false, a program whose only remaining work is that timer exits silently; the promise never settles. This is useful for background housekeeping, harmful if you await it at top level.
  • There is no way to cancel without a signal. Reuse one AbortController to cancel many timers at once.
  • Combine with AbortSignal.timeout() or Promise.race() to build timeouts around other promises, but remember the loser of a race still runs unless it has its own signal.
  • The same function is available as timersPromises.setTimeout, and from the node:timers module as timers.promises.setTimeout.
  • Added in Node.js 15.0.