Temporizadores

[Estável: 2 - Estável]

Estável: 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 temporizador são globais, não há necessidade de chamar require('node:timers') para usar a API.

As funções de temporizador em Node.js implementam uma API semelhante à API de temporizadores 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 imediato é agendado, o loop de eventos do Node.js continuará em execução enquanto o imediato estiver ativo. O objeto Immediate retornado por setImmediate() exporta as funções immediate.ref() e immediate.unref(), que podem ser usadas para controlar esse 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 a 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 "referenciados", 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 a 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á sair antes que o callback do objeto Immediate seja invocado. Chamar immediate.unref() múltiplas 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 imediato. Isso é similar a chamar clearImmediate().

Classe: Timeout

Este objeto é criado internamente e retornado por 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 expõem 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 a 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 a timeout

Quando chamado, solicita que o loop de eventos do Node.js não saia enquanto o Timeout estiver ativo. Chamar timeout.ref() múltiplas 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 a timeout

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

Usar isso em um temporizador que já chamou seu callback reativará o temporizador.

timeout.unref()

Adicionado em: v0.9.1

• Retorna: <Timeout> uma referência a 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 poderá sair antes que o callback do objeto Timeout seja invocado. Chamar timeout.unref() múltiplas vezes não terá efeito.

timeout[Symbol.toPrimitive]()

Adicionado em: v14.9.0, v12.19.0

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

Coerce um Timeout para um primitivo. O primitivo pode ser usado para limpar o Timeout. O primitivo só pode ser usado na mesma thread em que o timeout foi criado. Portanto, para usá-lo em várias worker_threads, ele deve primeiro ser passado para a thread correta. Isso permite compatibilidade aprimorada com as implementações 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.

Agendamento de temporizadores

Um temporizador no Node.js é uma construção interna que chama uma função determinada após um certo período de tempo. Quando a função de um temporizador é chamada varia dependendo de qual método foi usado para criar o temporizador e de 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 iteração do loop de eventos do Node.js Event Loop
• ...args <any> Argumentos opcionais a serem passados quando o callback for 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 a setImmediate() são feitas, as funções callback são colocadas em fila 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 colocado em fila 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 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 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. Delays 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 <Função> A função a ser chamada quando o temporizador expirar.
• delay <número> O número de milissegundos para esperar antes de chamar o callback. Padrão: 1.
• ...args <qualquer> 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 em exatamente delay milissegundos. O Node.js não garante o tempo exato de quando os callbacks serão disparados, nem sua ordenação. 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. Delays 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.setTimeout().

Cancelando temporizadores

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

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 esperamos a promise, então `ac.abort()` é chamado concorrentemente.
setImmediatePromise('foobar', { signal })
  .then(console.log)
  .catch(err => {
    if (err.name === 'AbortError') console.error('O imediato 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 imediato 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 esperamos a promise, então `ac.abort()` é 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().

Timers Promises API

[Histórico]

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

A API timers/promises fornece um conjunto alternativo de funções de temporizador 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) // Imprime 'result'

CJS

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

setTimeout(100, 'result').then(res => {
  console.log(res) // Imprime '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) // Imprime 'result'

CJS

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

setImmediate('result').then(res => {
  console.log(res) // Imprime '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 iterações. Padrão: 1.
• value <any> Um valor com o qual o iterador retorna.
• options <Object>
  • ref <boolean> Definido como false para indicar que o Timeout agendado entre 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 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 promessa.

• 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 a espera.

• Retorna: <Promise>

Uma API experimental definida pela especificação de rascunho Scheduling APIs em desenvolvimento como uma API padrão da plataforma Web.

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

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

await scheduler.wait(1000) // Aguardar 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 de rascunho Scheduling APIs em desenvolvimento como uma API padrão da Plataforma Web.

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