Skip to content
Tutorials Center
My learning

Topics

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.

NODE
import { setImmediate as nextTurn } from 'node:timers/promises';

await nextTurn();

Try it

Node.js Value and ordering

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 Yielding lets a timer run

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 { 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, so value is 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 CommonJS nextTick callbacks 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. Only setImmediate(), 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.