Skip to content
Tutorials Center
My learning

Topics

Node.js Reference ยท Events and Timers

Node.js scheduler.wait() and scheduler.yield()

Reference for timersPromises.scheduler in Node.js: scheduler.wait() delays like setTimeout, scheduler.yield() gives other work a turn, with signals and edge cases.

scheduler from node:timers/promises is an object with two methods modeled on the web platform's scheduler API. scheduler.wait(delay, options) is setTimeout() without a value: it resolves after a delay. scheduler.yield() resolves on the next turn of the event loop, equivalent to setImmediate() without arguments.

They exist to make intent readable. await scheduler.wait(500) reads as "pause here", and await scheduler.yield() reads as "let others run" inside long loops. Both work in Node.js 24 without a flag.

NODE
import { scheduler } from 'node:timers/promises';

await scheduler.wait(100);
await scheduler.yield();

Try it

Node.js wait and yield

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 Cancelling a wait

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 { scheduler } from 'node:timers/promises';

scheduler.wait(delay[, options]): Promise<void>
scheduler.yield(): Promise<void>
Name Description
delay Milliseconds to wait. Always pass it.
options.signal An AbortSignal. Aborting rejects wait() with AbortError.

Returns: a promise fulfilling with undefined. Neither method takes a value.

Errors: wait() rejects with AbortError when the signal aborts. yield() has no failure mode.

Usage notes

  • scheduler.wait(n) behaves like timers/promises setTimeout(n) with no value; pick whichever reads better. wait() has no ref option.
  • scheduler.yield() is the same as awaiting setImmediate(): pending I/O callbacks and due timers can run before you continue, microtasks alone cannot do that.
  • Long CPU loops should yield every few milliseconds, not on every iteration; each yield costs a trip around the event loop.
  • Yielding does not make code parallel. It only breaks one task into slices so latency for other work stays low. For real parallelism use worker threads.
  • The object is also reachable as timers.promises.scheduler.
  • Added in Node.js 17.3 and 16.14.