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.
const timer = setTimeout((name) => console.log('hi', name), 100, 'Maya');
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
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,NaNand negative values become1. Values above2147483647(about 24.8 days) also become1and print aTimeoutOverflowWarning. For longer waits, store a deadline and check it on a shorter timer. 0and1are the same, sosetTimeout(fn, 0)does not mean "immediately". UsequeueMicrotask()for "after this code" orsetImmediate()for "after the poll phase".- Ordering: timers fire in due-time order; equal delays fire in creation order.
this: in a regular function callback,thisis theTimeoutobject; arrow functions keep their ownthis.- 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
0is a browser habit that breaks here. - Errors in the callback are uncaught exceptions. Handle them inside the callback.
- Awaiting a delay:
await setTimeout(ms)fromnode:timers/promisesis the cleanest form;util.promisify(setTimeout)gives the same result.