Класс: Immediate

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

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

immediate.hasRef()

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

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

immediate.ref()

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

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

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

immediate.unref()

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

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

immediate[Symbol.dispose]()

Отменяет immediate. Это аналогично вызову 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 «ссылаются», что обычно делает вызов timeout.ref() ненужным, если ранее не был вызван timeout.unref().

timeout.refresh()

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

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

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

timeout.unref()

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

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

timeout[Symbol.toPrimitive]()

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

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

timeout[Symbol.dispose]()

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

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

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

setImmediate(callback[, ...args])

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

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

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

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

У этого метода есть специальная версия для промисов, доступная с помощью timersPromises.setImmediate().

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

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

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

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

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

У этого метода есть специальная версия для промисов, доступная с помощью timersPromises.setInterval().

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

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

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

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

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

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

У этого метода есть специальная версия для промисов, доступная с помощью timersPromises.setTimeout().

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

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

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

Для setImmediate():

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

Для setTimeout():

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

clearImmediate(immediate)

• immediate <Объект немедленного выполнения> Объект Immediate возвращённый методом setImmediate().

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

clearInterval(timeout)

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

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

clearTimeout(timeout)

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

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

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

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

Модули MJS

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

Модули CJS

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

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

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

Модули MJS

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

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

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

Модули CJS

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

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

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

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

Модули MJS

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

const res = await setImmediate('result');

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

Модули CJS

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

Модули MJS

import {
  setInterval,
} from '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());

Модули CJS

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 <число> Количество миллисекунд, которое нужно подождать перед разрешением промиса.
• options <объект>
  • signal <AbortSignal> Необязательный AbortSignal, который можно использовать для отмены ожидания.
• Возвращает: <Promise>

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

Вызов timersPromises.scheduler.wait(delay, options) примерно эквивалентен вызову timersPromises.setTimeout(delay, undefined, options), за исключением того, что опция ref не поддерживается.

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() без аргументов.