Класс: Immediate

Этот объект создается внутри системы и возвращается из setImmediate(). Его можно передать в clearImmediate(), чтобы отменить запланированные действия.

По умолчанию после планирования немедленного вызова цикл событий Node.js продолжает работу, пока этот вызов активен. Объект Immediate, возвращаемый из setImmediate(), экспортирует функции immediate.ref() и immediate.unref(), с помощью которых можно управлять этим поведением по умолчанию.

immediate.hasRef()

• Возвращает: <boolean>

Если значение равно true, объект Immediate будет поддерживать активность цикла событий Node.js.

immediate.ref()

• Возвращает: <Immediate> ссылку на immediate

При вызове запрашивает, чтобы цикл событий Node.js не завершался, пока активен Immediate. Повторные вызовы immediate.ref() не влияют на результат.

По умолчанию для всех объектов Immediate установлен флаг «ref», поэтому обычно вызывать immediate.ref() не требуется, если только ранее не был вызван immediate.unref().

immediate.unref()

• Возвращает: <Immediate> ссылку на immediate

При вызове активный объект Immediate не будет требовать, чтобы цикл событий Node.js оставался активным. Если никакая другая активность не поддерживает работу цикла событий, процесс может завершиться до вызова callback объекта Immediate. Повторные вызовы immediate.unref() не влияют на результат.

immediate[Symbol.dispose]()

Отменяет немедленный вызов. Это аналог вызова clearImmediate().

Класс: Timeout

Этот объект создается внутри системы и возвращается из setTimeout() и setInterval(). Его можно передать в clearTimeout() или clearInterval(), чтобы отменить запланированные действия.

По умолчанию при планировании таймера с помощью setTimeout() или setInterval() цикл событий Node.js продолжает работу, пока таймер активен. Каждый из объектов Timeout, возвращаемых этими функциями, экспортирует функции timeout.ref() и timeout.unref(), с помощью которых можно управлять этим поведением по умолчанию.

timeout.close()

• Возвращает: <Timeout> ссылку на timeout

Отменяет тайм-аут.

timeout.hasRef()

• Возвращает: <boolean>

Если значение равно true, объект Timeout будет поддерживать активность цикла событий Node.js.

timeout.ref()

• Возвращает: <Timeout> ссылку на timeout

При вызове запрашивает, чтобы цикл событий Node.js не завершался, пока активен Timeout. Повторные вызовы timeout.ref() не влияют на результат.

По умолчанию для всех объектов Timeout установлен флаг «ref», поэтому обычно вызывать timeout.ref() не требуется, если только ранее не был вызван timeout.unref().

timeout.refresh()

• Возвращает: <Timeout> ссылку на timeout

Устанавливает время начала таймера на текущее время и повторно планирует его вызов callback с ранее указанной задержкой, отсчитываемой от текущего времени. Это удобно для обновления таймера без создания нового объекта JavaScript.

Если использовать этот метод для таймера, callback которого уже был вызван, таймер будет активирован повторно.

timeout.unref()

• Возвращает: <Timeout> ссылку на timeout

При вызове активный объект Timeout не будет требовать, чтобы цикл событий Node.js оставался активным. Если никакая другая активность не поддерживает работу цикла событий, процесс может завершиться до вызова callback объекта Timeout. Повторные вызовы timeout.unref() не влияют на результат.

timeout[Symbol.toPrimitive]()

• Возвращает: <integer> число, которое можно использовать для ссылки на этот timeout

Преобразует Timeout в примитив. Этот примитив можно использовать для отмены Timeout. Примитив можно использовать только в том же потоке, в котором был создан тайм-аут. Поэтому, чтобы использовать его в разных worker_threads, сначала необходимо передать его в нужный поток. Это обеспечивает повышенную совместимость с реализациями setTimeout() и setInterval() в браузерах.

timeout[Symbol.dispose]()

Отменяет тайм-аут.

Планирование таймеров

Таймер в Node.js — это внутренняя конструкция, которая вызывает заданную функцию через определенный промежуток времени. Момент вызова функции таймера зависит от метода, использованного для его создания, и от других задач, выполняемых циклом событий Node.js.

setImmediate(callback[, ...args])

• callback <Function> Функция, которую нужно вызвать в конце текущего цикла цикла событий Node.js
• ...args <any> Необязательные аргументы, передаваемые при вызове callback.
• Возвращает: <Immediate> для использования с clearImmediate()

Планирует «немедленный» вызов callback после callback событий ввода-вывода.

При нескольких вызовах setImmediate() функции callback помещаются в очередь на выполнение в порядке создания. Вся очередь callback обрабатывается на каждой итерации цикла событий. Если таймер немедленного вызова помещен в очередь из выполняемого callback, он сработает только на следующей итерации цикла событий.

Если callback не является функцией, будет выброшено исключение TypeError.

Для этого метода доступен специальный вариант для промисов — timersPromises.setImmediate().

setInterval(callback[, delay[, ...args]])

• callback <Function> Функция, которую нужно вызвать по истечении таймера.
• delay <number> Количество миллисекунд ожидания перед вызовом callback. По умолчанию: 1.
• ...args <any> Необязательные аргументы, передаваемые при вызове callback.
• Возвращает: <Timeout> для использования с clearInterval()

Планирует повторное выполнение callback каждые delay миллисекунд.

Если delay больше 2147483647 или меньше 1, значение delay будет установлено в 1. Нецелочисленные задержки округляются вниз до целого числа.

Если callback не является функцией, будет выброшено исключение TypeError.

Для этого метода доступен специальный вариант для промисов — timersPromises.setInterval().

setTimeout(callback[, delay[, ...args]])

• callback <Function> Функция, которую нужно вызвать по истечении таймера.
• delay <number> Количество миллисекунд ожидания перед вызовом callback. По умолчанию: 1.
• ...args <any> Необязательные аргументы, передаваемые при вызове callback.
• Возвращает: <Timeout> для использования с clearTimeout()

Планирует однократное выполнение callback через delay миллисекунд.

Вероятно, callback не будет вызван точно через delay миллисекунд. Node.js не гарантирует точное время вызова callback или порядок их вызова. Callback будет вызван как можно ближе к указанному времени.

Если delay больше 2147483647 или меньше 1, значение delay будет установлено в 1. Нецелочисленные задержки округляются вниз до целого числа.

Если callback не является функцией, будет выброшено исключение TypeError.

Для этого метода доступен специальный вариант для промисов — timersPromises.setTimeout().

Отмена таймеров

Методы setImmediate(), setInterval() и setTimeout() возвращают объекты, представляющие запланированные таймеры. Их можно использовать для отмены таймера и предотвращения его срабатывания.

Для вариантов setImmediate() и setTimeout(), возвращающих промисы, для отмены таймера можно использовать AbortController. При отмене возвращенные промисы будут отклонены с ошибкой 'AbortError'.

Для setImmediate():

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

const ac = new AbortController();
const signal = ac.signal;

// We do not `await` the promise so `ac.abort()` is called concurrently.
setImmediatePromise('foobar', { signal })
  .then(console.log)
  .catch((err) => {
    if (err.name === 'AbortError')
      console.error('The immediate was aborted');
  });

ac.abort();

const { setImmediate: setImmediatePromise } = require('node:timers/promises');

const ac = new AbortController();
const signal = ac.signal;

setImmediatePromise('foobar', { signal })
  .then(console.log)
  .catch((err) => {
    if (err.name === 'AbortError')
      console.error('The immediate was aborted');
  });

ac.abort();

Для setTimeout():

import { setTimeout as setTimeoutPromise } from 'node:timers/promises';

const ac = new AbortController();
const signal = ac.signal;

// We do not `await` the promise so `ac.abort()` is called concurrently.
setTimeoutPromise(1000, 'foobar', { signal })
  .then(console.log)
  .catch((err) => {
    if (err.name === 'AbortError')
      console.error('The timeout was aborted');
  });

ac.abort();

const { setTimeout: setTimeoutPromise } = require('node:timers/promises');

const ac = new AbortController();
const signal = ac.signal;

setTimeoutPromise(1000, 'foobar', { signal })
  .then(console.log)
  .catch((err) => {
    if (err.name === 'AbortError')
      console.error('The timeout was aborted');
  });

ac.abort();

clearImmediate(immediate)

• immediate <Immediate> Объект Immediate, возвращаемый методом setImmediate().

Отменяет объект Immediate, созданный методом setImmediate().

clearInterval(timeout)

• timeout <Timeout> | <string> | <number> Объект Timeout, возвращаемый методом setInterval(), или примитивное значение примитива объекта Timeout в виде строки или числа.

Отменяет объект Timeout, созданный методом setInterval().

clearTimeout(timeout)

• timeout <Timeout> | <string> | <number> Объект Timeout, возвращаемый методом setTimeout(), или примитивное значение примитива объекта Timeout в виде строки или числа.

Отменяет объект Timeout, созданный методом setTimeout().

API таймеров на основе промисов

API timers/promises предоставляет альтернативный набор функций таймеров, возвращающих объекты Promise. Доступ к API осуществляется через require('node:timers/promises').

import {
  setTimeout,
  setImmediate,
  setInterval,
} from 'node:timers/promises';

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

timersPromises.setTimeout([delay[, value[, options]]])

• delay <number> Количество миллисекунд ожидания до выполнения промиса. По умолчанию: 1.
• value <any> Значение, которым будет выполнен промис.
• options <Object>
  • ref <boolean> Установите значение false, чтобы указать, что запланированный Timeout не должен требовать, чтобы цикл событий Node.js оставался активным. По умолчанию: true.
  • signal <AbortSignal> Необязательный AbortSignal, который можно использовать для отмены запланированного Timeout.

import {
  setTimeout,
} from 'node:timers/promises';

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

console.log(res);  // Prints 'result'

const {
  setTimeout,
} = require('node:timers/promises');

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

timersPromises.setImmediate([value[, options]])

• value <any> Значение, которым будет выполнен промис.
• options <Object>
  • ref <boolean> Установите значение false, чтобы указать, что запланированный Immediate не должен требовать, чтобы цикл событий Node.js оставался активным. По умолчанию: true.
  • signal <AbortSignal> Необязательный AbortSignal, который можно использовать для отмены запланированного Immediate.

import {
  setImmediate,
} from 'node:timers/promises';

const res = await setImmediate('result');

console.log(res);  // Prints 'result'

const {
  setImmediate,
} = require('node:timers/promises');

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

timersPromises.setInterval([delay[, value[, options]]])

Возвращает асинхронный итератор, генерирующий значения с интервалом delay мс. Если ref имеет значение true, необходимо явно или неявно вызвать next() асинхронного итератора, чтобы цикл событий оставался активным.

• delay <number> Количество миллисекунд ожидания между итерациями. По умолчанию: 1.
• value <any> Значение, возвращаемое итератором.
• options <Object>
  • ref <boolean> Установите значение false, чтобы указать, что запланированный Timeout между итерациями не должен требовать, чтобы цикл событий Node.js оставался активным. По умолчанию: true.
  • signal <AbortSignal> Необязательный AbortSignal, который можно использовать для отмены запланированного Timeout между операциями.

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());

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());
})();

timersPromises.scheduler.wait(delay[, options])

• delay <number> Количество миллисекунд ожидания до выполнения промиса.
• options <Object>
  • ref <boolean> Установите значение false, чтобы указать, что запланированный Timeout не должен требовать, чтобы цикл событий Node.js оставался активным. По умолчанию: true.
  • signal <AbortSignal> Необязательный AbortSignal, который можно использовать для отмены ожидания.
• Возвращает: <Promise>

Экспериментальный API, определенный в проекте спецификации Scheduling APIs, разрабатываемом как стандартный API веб-платформы.

Вызов timersPromises.scheduler.wait(delay, options) эквивалентен вызову timersPromises.setTimeout(delay, undefined, options).

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

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

timersPromises.scheduler.yield()

• Возвращает: <Promise>

Экспериментальный API, определенный в проекте спецификации Scheduling APIs, разрабатываемом как стандартный API веб-платформы.

Вызов timersPromises.scheduler.yield() эквивалентен вызову timersPromises.setImmediate() без аргументов.