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.
import { setTimeout as sleep } from 'node:timers/promises'; const value = await sleep(50, 'done');
Try it
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.
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
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 globalsetTimeout(). - The promise resolves at least
delayms 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 youawaitit at top level. - There is no way to cancel without a signal. Reuse one
AbortControllerto cancel many timers at once. - Combine with
AbortSignal.timeout()orPromise.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 thenode:timersmodule astimers.promises.setTimeout. - Added in Node.js 15.0.