Skip to content
Tutorials Center
My learning

Topics

Node.js Reference ยท Globals and Console

Node.js setTimeout() function

Reference for setTimeout() in Node.js: delay rules and clamping, extra arguments, the Timeout object it returns, the promise version and common mistakes.

setTimeout(callback, delay, ...args) schedules callback to run once, no sooner than delay milliseconds from now. It returns a Timeout object that you can pass to clearTimeout() to cancel the call before it fires.

The delay is a minimum, not a promise. The callback runs when the event loop reaches its timers phase and the time has elapsed, so a busy thread makes it late. Node keeps the process alive while a normal timer is pending.

NODE
const timer = setTimeout((name) => console.log('hi', name), 100, 'Maya');

Try it

Node.js Arguments, this and the return 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 The promise-based version

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
setTimeout(callback[, delay[, ...args]]): Timeout

// node:timers/promises
setTimeout([delay[, value[, options]]]): Promise
Name Description
callback Function to call. A string is not accepted (unlike the old browser form).
delay Milliseconds to wait. Defaults to 1. Converted to a number.
...args Extra arguments passed to callback.
value (promise version) The value the promise resolves with.
options.signal (promise version) An AbortSignal that rejects the promise with AbortError.
options.ref (promise version) Set to false to let the process exit while waiting.

Returns: a Timeout object. Its numeric id can be obtained with +timer.

Errors: ERR_INVALID_ARG_TYPE if callback is not a function.

Usage notes

  • Delay clamping: values below 1, NaN and negative values become 1. Values above 2147483647 (about 24.8 days) also become 1 and print a TimeoutOverflowWarning. For longer waits, store a deadline and check it on a shorter timer.
  • 0 and 1 are the same, so setTimeout(fn, 0) does not mean "immediately". Use queueMicrotask() for "after this code" or setImmediate() for "after the poll phase".
  • Ordering: timers fire in due-time order; equal delays fire in creation order.
  • this: in a regular function callback, this is the Timeout object; arrow functions keep their own this.
  • Keep or release the process: call timer.unref() for a timer that must not keep Node alive (a cache sweeper, for example). See Timeout object.
  • Not a number: unlike browsers, the return value is an object. Code that stores it in a number field or compares it with 0 is a browser habit that breaks here.
  • Errors in the callback are uncaught exceptions. Handle them inside the callback.
  • Awaiting a delay: await setTimeout(ms) from node:timers/promises is the cleanest form; util.promisify(setTimeout) gives the same result.