Класс: 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 имеют "ссылку", поэтому обычно нет необходимости вызывать immediate.ref() , если ранее не был вызван immediate.unref().

immediate.unref()

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

При вызове активный объект Immediate не будет требовать сохранения активности цикла событий Node.js. Если нет других активностей, поддерживающих работу цикла событий, процесс может завершиться до вызова обратного вызова объекта 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 имеют "ссылку", поэтому обычно нет необходимости вызывать timeout.ref() , если ранее не был вызван timeout.unref().

timeout.refresh()

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

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

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

timeout.unref()

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

При вызове активный объект Timeout не будет требовать сохранения активности цикла событий Node.js. Если нет других активностей, поддерживающих работу цикла событий, процесс может завершиться до вызова обратного вызова объекта 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 <Функция> Функция, которая должна быть вызвана в конце текущего цикла 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 таймеров Promises

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, который может быть использован для отмены ожидания.
• Возвращает: <Промис>

Экспериментальный 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()

• Возвращает: <Промис>

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

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