On this page

Timers Promises API

History

The timers/promises API provides an alternative set of timer functions that return Promise objects. The API is accessible via require('node:timers/promises').

import {
  setTimeout,
  setImmediate,
  setInterval,
} from 'node:timers/promises';
JavaScript
const {
  setTimeout,
  setImmediate,
  setInterval,
} = require('node:timers/promises');
JavaScript
M

timersPromises.setTimeout

History
timersPromises.setTimeout(delay?, value?, options?): void
Attributes
delay?:number
The number of milliseconds to wait before fulfilling the promise. Default: 1.
value:any
A value with which the promise is fulfilled.
options:Object
ref?:boolean
Set to false to indicate that the scheduled Timeout should not require the Node.js event loop to remain active. Default: true.
signal:AbortSignal
An optional AbortSignal that can be used to cancel the scheduled Timeout.
import {
  setTimeout,
} from 'node:timers/promises';

const res = await setTimeout(100, 'result');

console.log(res);  // Prints 'result'
JavaScript
const {
  setTimeout,
} = require('node:timers/promises');

setTimeout(100, 'result').then((res) => {
  console.log(res);  // Prints 'result'
});
JavaScript
M

timersPromises.setImmediate

History
timersPromises.setImmediate(value?, options?): void
Attributes
value:any
A value with which the promise is fulfilled.
options:Object
ref?:boolean
Set to false to indicate that the scheduled Immediate should not require the Node.js event loop to remain active. Default: true.
signal:AbortSignal
An optional AbortSignal that can be used to cancel the scheduled Immediate.
import {
  setImmediate,
} from 'node:timers/promises';

const res = await setImmediate('result');

console.log(res);  // Prints 'result'
JavaScript
const {
  setImmediate,
} = require('node:timers/promises');

setImmediate('result').then((res) => {
  console.log(res);  // Prints 'result'
});
JavaScript
M

timersPromises.setInterval

History
timersPromises.setInterval(delay?, value?, options?): void

Returns an async iterator that generates values in an interval of delay ms. If ref is true, you need to call next() of async iterator explicitly or implicitly to keep the event loop alive.

Attributes
delay?:number
The number of milliseconds to wait between iterations. Default: 1.
value:any
A value with which the iterator returns.
options:Object
ref?:boolean
Set to false to indicate that the scheduled Timeout between iterations should not require the Node.js event loop to remain active. Default: true.
signal:AbortSignal
An optional AbortSignal that can be used to cancel the scheduled Timeout between operations.
import {
  setInterval,
} from 'node:timers/promises';

const interval = 100;
for await (const startTime of setInterval(interval, Date.now())) {
  const now = Date.now();
  console.log(now);
  if ((now - startTime) > 1000)
    break;
}
console.log(Date.now());
JavaScript
const {
  setInterval,
} = require('node:timers/promises');
const interval = 100;

(async function() {
  for await (const startTime of setInterval(interval, Date.now())) {
    const now = Date.now();
    console.log(now);
    if ((now - startTime) > 1000)
      break;
  }
  console.log(Date.now());
})();
JavaScript
M

timersPromises.scheduler.wait

History
timersPromises.scheduler.wait(delay, options?): Promise
Stability: 1Experimental
Attributes
delay:number
The number of milliseconds to wait before resolving the promise.
options:Object
ref?:boolean
Set to false to indicate that the scheduled Timeout should not require the Node.js event loop to remain active. Default: true.
signal:AbortSignal
An optional AbortSignal that can be used to cancel waiting.
Returns:Promise

An experimental API defined by the Scheduling APIs draft specification being developed as a standard Web Platform API.

Calling timersPromises.scheduler.wait(delay, options) is equivalent to calling timersPromises.setTimeout(delay, undefined, options).

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

await scheduler.wait(1000); // Wait one second before continuing
JavaScript
M

timersPromises.scheduler.yield

History
timersPromises.scheduler.yield(): Promise
Stability: 1Experimental
Returns:Promise

An experimental API defined by the Scheduling APIs draft specification being developed as a standard Web Platform API.

Calling timersPromises.scheduler.yield() is equivalent to calling timersPromises.setImmediate() with no arguments.

PreviousCancelling timers