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.
import { scheduler } from 'node:timers/promises'; await scheduler.wait(100); await scheduler.yield();
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 { 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 liketimers/promisessetTimeout(n)with no value; pick whichever reads better.wait()has norefoption.scheduler.yield()is the same as awaitingsetImmediate(): 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.