Timers

[Stable: 2 - Stable]

Stable: 2 Estabilidade: 2 - Estável

Código Fonte: lib/timers.js

O módulo timer expõe uma API global para agendar funções a serem chamadas em algum período de tempo futuro. Como as funções de timer são globais, não há necessidade de chamar require('node:timers') para usar a API.

As funções de timer dentro do Node.js implementam uma API semelhante à API de timers fornecida pelos navegadores da Web, mas usam uma implementação interna diferente, construída em torno do Loop de Eventos do Node.js.

Classe: Immediate

Este objeto é criado internamente e é retornado de setImmediate(). Ele pode ser passado para clearImmediate() para cancelar as ações agendadas.

Por padrão, quando um immediate é agendado, o loop de eventos do Node.js continuará sendo executado enquanto o immediate estiver ativo. O objeto Immediate retornado por setImmediate() exporta as funções immediate.ref() e immediate.unref() que podem ser usadas para controlar este comportamento padrão.

immediate.hasRef()

Adicionado em: v11.0.0

• Retorna: <boolean>

Se verdadeiro, o objeto Immediate manterá o loop de eventos do Node.js ativo.

immediate.ref()

Adicionado em: v9.7.0

• Retorna: <Immediate> uma referência para immediate

Quando chamado, solicita que o loop de eventos do Node.js não saia enquanto o Immediate estiver ativo. Chamar immediate.ref() várias vezes não terá efeito.

Por padrão, todos os objetos Immediate são "ref'ed", tornando normalmente desnecessário chamar immediate.ref() a menos que immediate.unref() tenha sido chamado anteriormente.

immediate.unref()

Adicionado em: v9.7.0

• Retorna: <Immediate> uma referência para immediate

Quando chamado, o objeto Immediate ativo não exigirá que o loop de eventos do Node.js permaneça ativo. Se não houver outra atividade mantendo o loop de eventos em execução, o processo poderá ser encerrado antes que o callback do objeto Immediate seja invocado. Chamar immediate.unref() várias vezes não terá efeito.

immediate[Symbol.dispose]()

Adicionado em: v20.5.0, v18.18.0

[Estável: 1 - Experimental]

Estável: 1 Estabilidade: 1 - Experimental

Cancela o immediate. Isso é semelhante a chamar clearImmediate().

Classe: Timeout

Este objeto é criado internamente e é retornado de setTimeout() e setInterval(). Ele pode ser passado para clearTimeout() ou clearInterval() para cancelar as ações agendadas.

Por padrão, quando um temporizador é agendado usando setTimeout() ou setInterval(), o loop de eventos do Node.js continuará em execução enquanto o temporizador estiver ativo. Cada um dos objetos Timeout retornados por essas funções exporta as funções timeout.ref() e timeout.unref() que podem ser usadas para controlar esse comportamento padrão.

timeout.close()

Adicionado em: v0.9.1

[Estável: 3 - Legado]

Estável: 3 Estabilidade: 3 - Legado: Use clearTimeout() em vez disso.

• Retorna: <Timeout> uma referência para timeout

Cancela o timeout.

timeout.hasRef()

Adicionado em: v11.0.0

• Retorna: <boolean>

Se verdadeiro, o objeto Timeout manterá o loop de eventos do Node.js ativo.

timeout.ref()

Adicionado em: v0.9.1

• Retorna: <Timeout> uma referência para timeout

Quando chamado, solicita que o loop de eventos do Node.js não saia enquanto o Timeout estiver ativo. Chamar timeout.ref() várias vezes não terá efeito.

Por padrão, todos os objetos Timeout são "referenciados", tornando normalmente desnecessário chamar timeout.ref() a menos que timeout.unref() tenha sido chamado anteriormente.

timeout.refresh()

Adicionado em: v10.2.0

• Retorna: <Timeout> uma referência para timeout

Define a hora de início do temporizador para a hora atual e reprograma o temporizador para chamar seu retorno de chamada na duração especificada anteriormente, ajustada para a hora atual. Isso é útil para atualizar um temporizador sem alocar um novo objeto JavaScript.

Usar isso em um temporizador que já chamou seu retorno de chamada irá reativar o temporizador.

timeout.unref()

Adicionado em: v0.9.1

• Retorna: <Timeout> uma referência para timeout

Quando chamado, o objeto Timeout ativo não exigirá que o loop de eventos do Node.js permaneça ativo. Se não houver outra atividade mantendo o loop de eventos em execução, o processo pode sair antes que o retorno de chamada do objeto Timeout seja invocado. Chamar timeout.unref() várias vezes não terá efeito.

timeout[Symbol.toPrimitive]()

Adicionado em: v14.9.0, v12.19.0

• Retorna: <integer> um número que pode ser usado para referenciar este timeout

Coage um Timeout para um primitivo. O primitivo pode ser usado para limpar o Timeout. O primitivo só pode ser usado no mesmo thread onde o timeout foi criado. Portanto, para usá-lo entre worker_threads ele deve primeiro ser passado para o thread correto. Isso permite compatibilidade aprimorada com as implementações de setTimeout() e setInterval() do navegador.

timeout[Symbol.dispose]()

Adicionado em: v20.5.0, v18.18.0

[Estável: 1 - Experimental]

Estável: 1 Estabilidade: 1 - Experimental

Cancela o timeout.

Agendando temporizadores

Um temporizador no Node.js é uma construção interna que chama uma função fornecida após um certo período de tempo. O momento em que a função de um temporizador é chamada varia dependendo de qual método foi usado para criar o temporizador e qual outro trabalho o loop de eventos do Node.js está fazendo.

setImmediate(callback[, ...args])

[Histórico]

Versão	Alterações
v18.0.0	Passar um callback inválido para o argumento callback agora lança ERR_INVALID_ARG_TYPE em vez de ERR_INVALID_CALLBACK.
v0.9.1	Adicionado em: v0.9.1

• callback <Function> A função a ser chamada no final desta rodada do Loop de Eventos do Node.js
• ...args <any> Argumentos opcionais para passar quando o callback é chamado.
• Retorna: <Immediate> para uso com clearImmediate()

Agenda a execução "imediata" do callback após os callbacks de eventos de E/S.

Quando várias chamadas para setImmediate() são feitas, as funções callback são enfileiradas para execução na ordem em que são criadas. Toda a fila de callbacks é processada a cada iteração do loop de eventos. Se um temporizador imediato for enfileirado de dentro de um callback em execução, esse temporizador não será acionado até a próxima iteração do loop de eventos.

Se callback não for uma função, um TypeError será lançado.

Este método tem uma variante personalizada para promises que está disponível usando timersPromises.setImmediate().

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

[Histórico]

Versão	Alterações
v18.0.0	Passar um callback inválido para o argumento callback agora lança ERR_INVALID_ARG_TYPE em vez de ERR_INVALID_CALLBACK.
v0.0.1	Adicionado em: v0.0.1

• callback <Function> A função a ser chamada quando o temporizador expirar.
• delay <number> O número de milissegundos a esperar antes de chamar o callback. Padrão: 1.
• ...args <any> Argumentos opcionais para passar quando o callback é chamado.
• Retorna: <Timeout> para uso com clearInterval()

Agenda a execução repetida de callback a cada delay milissegundos.

Quando delay for maior que 2147483647 ou menor que 1 ou NaN, o delay será definido como 1. Atrasos não inteiros são truncados para um inteiro.

Se callback não for uma função, um TypeError será lançado.

Este método tem uma variante personalizada para promises que está disponível usando timersPromises.setInterval().

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

[Histórico]

Versão	Alterações
v18.0.0	Passar um callback inválido para o argumento callback agora lança ERR_INVALID_ARG_TYPE em vez de ERR_INVALID_CALLBACK.
v0.0.1	Adicionado em: v0.0.1

• callback <Function> A função a ser chamada quando o temporizador expirar.
• delay <number> O número de milissegundos para esperar antes de chamar o callback. Padrão: 1.
• ...args <any> Argumentos opcionais a serem passados quando o callback for chamado.
• Retorna: <Timeout> para uso com clearTimeout()

Agenda a execução de um callback único após delay milissegundos.

O callback provavelmente não será invocado precisamente em delay milissegundos. O Node.js não oferece garantias sobre o tempo exato em que os callbacks serão disparados, nem sobre sua ordem. O callback será chamado o mais próximo possível do tempo especificado.

Quando delay for maior que 2147483647 ou menor que 1 ou NaN, o delay será definido como 1. Atrasos não inteiros são truncados para um inteiro.

Se callback não for uma função, um TypeError será lançado.

Este método tem uma variante personalizada para promessas que está disponível usando timersPromises.setTimeout().

Cancelando temporizadores

Os métodos setImmediate(), setInterval() e setTimeout() retornam cada um objetos que representam os temporizadores agendados. Estes podem ser usados para cancelar o temporizador e evitar que ele seja disparado.

Para as variantes promissificadas de setImmediate() e setTimeout(), um AbortController pode ser usado para cancelar o temporizador. Quando canceladas, as Promises retornadas serão rejeitadas com um 'AbortError'.

Para setImmediate():

ESM

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

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

// Não fazemos `await` na promise para que `ac.abort()` seja chamado concorrentemente.
setImmediatePromise('foobar', { signal })
  .then(console.log)
  .catch((err) => {
    if (err.name === 'AbortError')
      console.error('O immediate foi abortado');
  });

ac.abort();

CJS

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('O immediate foi abortado');
  });

ac.abort();

Para setTimeout():

ESM

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

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

// Não fazemos `await` na promise para que `ac.abort()` seja chamado concorrentemente.
setTimeoutPromise(1000, 'foobar', { signal })
  .then(console.log)
  .catch((err) => {
    if (err.name === 'AbortError')
      console.error('O timeout foi abortado');
  });

ac.abort();

CJS

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('O timeout foi abortado');
  });

ac.abort();

clearImmediate(immediate)

Adicionado em: v0.9.1

• immediate <Immediate> Um objeto Immediate como retornado por setImmediate().

Cancela um objeto Immediate criado por setImmediate().

clearInterval(timeout)

Adicionado em: v0.0.1

• timeout <Timeout> | <string> | <number> Um objeto Timeout como retornado por setInterval() ou o primitivo do objeto Timeout como uma string ou um número.

Cancela um objeto Timeout criado por setInterval().

clearTimeout(timeout)

Adicionado em: v0.0.1

• timeout <Timeout> | <string> | <number> Um objeto Timeout como retornado por setTimeout() ou o primitivo do objeto Timeout como uma string ou um número.

Cancela um objeto Timeout criado por setTimeout().

API de Promessas de Timers

[Histórico]

Versão	Alterações
v16.0.0	Graduado de experimental.
v15.0.0	Adicionado em: v15.0.0

A API timers/promises fornece um conjunto alternativo de funções de timer que retornam objetos Promise. A API é acessível via require('node:timers/promises').

ESM

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

CJS

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

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

Adicionado em: v15.0.0

• delay <number> O número de milissegundos para esperar antes de cumprir a promessa. Padrão: 1.
• value <any> Um valor com o qual a promessa é cumprida.
• options <Object>
  • ref <boolean> Definido como false para indicar que o Timeout agendado não deve exigir que o loop de eventos do Node.js permaneça ativo. Padrão: true.
  • signal <AbortSignal> Um AbortSignal opcional que pode ser usado para cancelar o Timeout agendado.

ESM

import {
  setTimeout,
} from 'node: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]])

Adicionado em: v15.0.0

• value <any> Um valor com o qual a promessa é cumprida.
• options <Object>
  • ref <boolean> Definido como false para indicar que o Immediate agendado não deve exigir que o loop de eventos do Node.js permaneça ativo. Padrão: true.
  • signal <AbortSignal> Um AbortSignal opcional que pode ser usado para cancelar o Immediate agendado.

ESM

import {
  setImmediate,
} from 'node: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]]])

Adicionado em: v15.9.0

Retorna um iterador assíncrono que gera valores em um intervalo de delay ms. Se ref for true, você precisa chamar next() do iterador assíncrono explicitamente ou implicitamente para manter o loop de eventos ativo.

• delay <number> O número de milissegundos para esperar entre as iterações. Padrão: 1.
• value <any> Um valor com o qual o iterador retorna.
• options <Object>
  • ref <boolean> Defina como false para indicar que o Timeout agendado entre as iterações não deve exigir que o loop de eventos do Node.js permaneça ativo. Padrão: true.
  • signal <AbortSignal> Um AbortSignal opcional que pode ser usado para cancelar o Timeout agendado entre as operações.

ESM

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

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])

Adicionado em: v17.3.0, v16.14.0

[Estável: 1 - Experimental]

Estável: 1 Estabilidade: 1 - Experimental

• delay <number> O número de milissegundos para esperar antes de resolver a promise.

• options <Object>

  • ref <boolean> Defina como false para indicar que o Timeout agendado não deve exigir que o loop de eventos do Node.js permaneça ativo. Padrão: true.
  • signal <AbortSignal> Um AbortSignal opcional que pode ser usado para cancelar a espera.

• Retorna: <Promise>

Uma API experimental definida pela especificação de rascunho das APIs de Agendamento sendo desenvolvida como uma API de Plataforma Web padrão.

Chamar timersPromises.scheduler.wait(delay, options) é equivalente a chamar timersPromises.setTimeout(delay, undefined, options).

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

await scheduler.wait(1000); // Espere um segundo antes de continuar

timersPromises.scheduler.yield()

Adicionado em: v17.3.0, v16.14.0

[Estável: 1 - Experimental]

Estável: 1 Estabilidade: 1 - Experimental

• Retorna: <Promise>

Uma API experimental definida pela especificação preliminar das APIs de Agendamento que está sendo desenvolvida como uma API padrão da Plataforma Web.

Chamar timersPromises.scheduler.yield() é equivalente a chamar timersPromises.setImmediate() sem argumentos.