Node.js Reference ยท Events and Timers
Node.js timers/promises setImmediate() function
Reference for setImmediate() from node:timers/promises: await the next check phase of the event loop, return a value, cancel with a signal and yield to I/O.
setImmediate(value, options) from node:timers/promises returns a promise that fulfills with value in the check phase of the event loop, right after the current poll phase has handled I/O. It is the awaitable form of the global setImmediate().
Its main use is yielding: inside a long async loop, await setImmediate() lets pending I/O callbacks, timers that are due and other work run before your loop continues, so one busy task cannot starve the rest of the process. A plain await of an already resolved promise does not do that, because it only yields to other microtasks.
import { setImmediate as nextTurn } from 'node:timers/promises'; await nextTurn();
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 { setImmediate } from 'node:timers/promises'; setImmediate([value[, options]]): Promise<any>
| Name | Description |
|---|---|
value |
Anything. The promise fulfills with it. Default undefined. |
options.signal |
An AbortSignal. Aborting rejects with AbortError. |
options.ref |
Boolean, default true. false lets the process exit before the immediate runs. |
Returns: a Promise fulfilling with value.
Errors: AbortError if the signal aborts before the immediate runs. Wrong argument types throw ERR_INVALID_ARG_TYPE.
Usage notes
- Note the argument order differs from the timer version: there is no
delay, sovalueis the first argument. - Order of the main queues: synchronous code first, then the microtask and
process.nextTick()queues, then (later in the loop) timers and immediates. In CommonJSnextTickcallbacks run before promise microtasks, but ES module top-level code already runs inside a microtask, so there the promise callback comes first (as the first example prints). - Use it to chunk CPU work: process a slice of items,
await setImmediate(), continue. Chunk sizes of a few milliseconds keep servers responsive. - A promise that
awaits a resolved value only yields to microtasks; the event loop itself does not advance. OnlysetImmediate(), timers and real I/O let the loop turn. - Between a
setTimeout(0)and an immediate scheduled from the main module the order is not guaranteed; inside an I/O callback the immediate is always first. - Added in Node.js 15.0.