Skip to content
Tutorials Center
My learning

Topics

Node.js Reference ยท Globals and Console

Node.js setImmediate() function

Reference for setImmediate() in Node.js: when it runs in the event loop, how it differs from setTimeout(0) and nextTick, and how to split long work into chunks.

setImmediate(callback, ...args) schedules a callback to run in the "check" phase of the event loop, which comes right after the poll phase where I/O callbacks are handled. It returns an Immediate object that you can cancel with clearImmediate().

The name is misleading: the callback is not run immediately, but on the next pass of the loop after pending I/O has been processed. It is the right tool for "let I/O and other callbacks run first, then continue", for example when splitting a long computation into small pieces.

NODE
setImmediate(() => console.log('after I/O'));

Try it

Node.js setImmediate versus setTimeout inside I/O

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 Chunking long work without blocking

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
setImmediate(callback[, ...args]): Immediate

// node:timers/promises
setImmediate([value[, options]]): Promise
Name Description
callback Function to run in the check phase.
...args Extra arguments passed to callback.
value (promise version) The value the promise resolves with.
options (promise version) signal to cancel and ref to control whether the process is kept alive.

Returns: an Immediate object with ref(), unref() and hasRef() methods.

Errors: ERR_INVALID_ARG_TYPE if callback is not a function.

Usage notes

  • Versus setTimeout(fn, 0): from the main module the order of the two is not guaranteed because it depends on how fast the loop starts. Inside an I/O callback, setImmediate always runs first.
  • Versus process.nextTick() and microtasks: those run before the loop continues at all. Only setImmediate gives I/O and timers a turn.
  • Callbacks queued during the check phase run on the next loop iteration, not in the same pass, so a self-rescheduling immediate cannot starve I/O the way a recursive nextTick can.
  • Order: immediates run in the order they were created.
  • Cancellation: use clearImmediate(); an already-run immediate is ignored.
  • unref(): an unref'd immediate does not keep the process alive on its own.
  • Not in browsers. It is a Node.js (and legacy IE) API; browsers use setTimeout, MessageChannel or scheduler.postTask().
  • Promise form: await setImmediate() from node:timers/promises yields to the event loop, a handy "let others run" call inside long loops.