Temporizadores

[Estable: 2 - Estable]

Estable: 2 Estabilidad: 2 - Estable

Código Fuente: lib/timers.js

El módulo timer expone una API global para programar funciones que se llamarán en algún momento futuro. Dado que las funciones de temporizador son globales, no es necesario llamar a require('node:timers') para usar la API.

Las funciones de temporizador dentro de Node.js implementan una API similar a la API de temporizadores proporcionada por los navegadores web, pero utilizan una implementación interna diferente que se basa en el Bucle de Eventos de Node.js.

Clase: Immediate

Este objeto se crea internamente y se devuelve desde setImmediate(). Se puede pasar a clearImmediate() para cancelar las acciones programadas.

De forma predeterminada, cuando se programa un inmediato, el bucle de eventos de Node.js seguirá ejecutándose mientras el inmediato esté activo. El objeto Immediate devuelto por setImmediate() exporta las funciones immediate.ref() e immediate.unref() que se pueden usar para controlar este comportamiento predeterminado.

immediate.hasRef()

Agregado en: v11.0.0

• Devuelve: <boolean>

Si es verdadero, el objeto Immediate mantendrá activo el bucle de eventos de Node.js.

immediate.ref()

Agregado en: v9.7.0

• Devuelve: <Immediate> una referencia a immediate

Cuando se llama, solicita que el bucle de eventos de Node.js no se cierre mientras el Immediate esté activo. Llamar a immediate.ref() varias veces no tendrá efecto.

Por defecto, todos los objetos Immediate están "referenciados", por lo que normalmente no es necesario llamar a immediate.ref() a menos que se haya llamado previamente a immediate.unref().

immediate.unref()

Agregado en: v9.7.0

• Devuelve: <Immediate> una referencia a immediate

Cuando se llama, el objeto Immediate activo no requerirá que el bucle de eventos de Node.js permanezca activo. Si no hay otra actividad que mantenga el bucle de eventos en ejecución, el proceso puede cerrarse antes de que se invoque la retrollamada del objeto Immediate. Llamar a immediate.unref() varias veces no tendrá efecto.

immediate[Symbol.dispose]()

Agregado en: v20.5.0, v18.18.0

[Estable: 1 - Experimental]

Estable: 1 Estabilidad: 1 - Experimental

Cancela el inmediato. Esto es similar a llamar a clearImmediate().

Clase: Timeout

Este objeto se crea internamente y se devuelve desde setTimeout() y setInterval(). Se puede pasar a clearTimeout() o clearInterval() para cancelar las acciones programadas.

De forma predeterminada, cuando se programa un temporizador utilizando setTimeout() o setInterval(), el bucle de eventos de Node.js seguirá ejecutándose mientras el temporizador esté activo. Cada uno de los objetos Timeout devueltos por estas funciones exporta las funciones timeout.ref() y timeout.unref() que se pueden usar para controlar este comportamiento predeterminado.

timeout.close()

Añadido en: v0.9.1

[Estable: 3 - Legado]

Estable: 3 Estabilidad: 3 - Legado: Use clearTimeout() en su lugar.

• Devuelve: <Timeout> una referencia a timeout

Cancela el tiempo de espera.

timeout.hasRef()

Añadido en: v11.0.0

• Devuelve: <boolean>

Si es verdadero, el objeto Timeout mantendrá activo el bucle de eventos de Node.js.

timeout.ref()

Añadido en: v0.9.1

• Devuelve: <Timeout> una referencia a timeout

Cuando se llama, solicita que el bucle de eventos de Node.js no termine mientras el Timeout esté activo. Llamar a timeout.ref() varias veces no tendrá ningún efecto.

Por defecto, todos los objetos Timeout están "referenciados", por lo que normalmente no es necesario llamar a timeout.ref() a menos que se haya llamado previamente a timeout.unref().

timeout.refresh()

Agregado en: v10.2.0

• Devuelve: <Timeout> una referencia a timeout

Establece la hora de inicio del temporizador a la hora actual y reprograma el temporizador para que llame a su callback a la duración especificada previamente ajustada a la hora actual. Esto es útil para actualizar un temporizador sin asignar un nuevo objeto JavaScript.

Usar esto en un temporizador que ya ha llamado a su callback reactivará el temporizador.

timeout.unref()

Agregado en: v0.9.1

• Devuelve: <Timeout> una referencia a timeout

Cuando se llama, el objeto Timeout activo no requerirá que el bucle de eventos de Node.js permanezca activo. Si no hay otra actividad que mantenga el bucle de eventos en ejecución, el proceso puede salir antes de que se invoque el callback del objeto Timeout. Llamar a timeout.unref() varias veces no tendrá ningún efecto.

timeout[Symbol.toPrimitive]()

Agregado en: v14.9.0, v12.19.0

• Devuelve: <integer> un número que se puede usar para hacer referencia a este timeout

Coacciona un Timeout a un primitivo. El primitivo se puede usar para borrar el Timeout. El primitivo solo se puede usar en el mismo hilo donde se creó el timeout. Por lo tanto, para usarlo a través de worker_threads, primero debe pasarse al hilo correcto. Esto permite una compatibilidad mejorada con las implementaciones de setTimeout() y setInterval() del navegador.

timeout[Symbol.dispose]()

Añadido en: v20.5.0, v18.18.0

[Estable: 1 - Experimental]

Estable: 1 Estabilidad: 1 - Experimental

Cancela el tiempo de espera.

Programación de temporizadores

Un temporizador en Node.js es una construcción interna que llama a una función dada después de un cierto período de tiempo. Cuándo se llama a la función de un temporizador varía dependiendo de qué método se utilizó para crear el temporizador y qué otro trabajo está haciendo el bucle de eventos de Node.js.

setImmediate(callback[, ...args])

[Historial]

Versión	Cambios
v18.0.0	Pasar un callback inválido al argumento callback ahora lanza ERR_INVALID_ARG_TYPE en lugar de ERR_INVALID_CALLBACK.
v0.9.1	Añadido en: v0.9.1

• callback <Función> La función para llamar al final de este turno del Bucle de Eventos de Node.js
• ...args <any> Argumentos opcionales para pasar cuando se llama al callback.
• Devuelve: <Immediate> para usar con clearImmediate()

Programa la ejecución "inmediata" del callback después de los callbacks de eventos de E/S.

Cuando se hacen múltiples llamadas a setImmediate(), las funciones callback se ponen en cola para su ejecución en el orden en que se crean. Toda la cola de callbacks se procesa en cada iteración del bucle de eventos. Si un temporizador inmediato se pone en cola desde dentro de un callback en ejecución, ese temporizador no se activará hasta la siguiente iteración del bucle de eventos.

Si callback no es una función, se lanzará un TypeError.

Este método tiene una variante personalizada para promesas que está disponible utilizando timersPromises.setImmediate().

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

[Historial]

Versión	Cambios
v18.0.0	Pasar una función de callback inválida al argumento callback ahora lanza ERR_INVALID_ARG_TYPE en lugar de ERR_INVALID_CALLBACK.
v0.0.1	Añadido en: v0.0.1

• callback <Function> La función que se llamará cuando transcurra el temporizador.
• delay <number> El número de milisegundos que se esperará antes de llamar a callback. Por defecto: 1.
• ...args <any> Argumentos opcionales para pasar cuando se llama a callback.
• Devuelve: <Timeout> para usar con clearInterval()

Programa la ejecución repetida de callback cada delay milisegundos.

Cuando delay es mayor que 2147483647 o menor que 1 o NaN, delay se establecerá en 1. Los delays no enteros se truncan a un entero.

Si callback no es una función, se lanzará un TypeError.

Este método tiene una variante personalizada para promesas que está disponible usando timersPromises.setInterval().

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

[Historial]

Versión	Cambios
v18.0.0	Pasar una función de retorno no válida al argumento callback ahora arroja ERR_INVALID_ARG_TYPE en lugar de ERR_INVALID_CALLBACK.
v0.0.1	Añadido en: v0.0.1

• callback <Function> La función a llamar cuando transcurra el tiempo.
• delay <number> El número de milisegundos que esperar antes de llamar a callback. Predeterminado: 1.
• ...args <any> Argumentos opcionales para pasar cuando se llama a callback.
• Devuelve: <Timeout> para usar con clearTimeout()

Programa la ejecución de una callback única después de delay milisegundos.

Es probable que la callback no se invoque precisamente en delay milisegundos. Node.js no ofrece garantías sobre el tiempo exacto en el que se activarán las funciones de retorno, ni sobre su orden. La función de retorno se llamará lo más cerca posible del tiempo especificado.

Cuando delay es mayor que 2147483647 o menor que 1 o NaN, delay se establecerá en 1. Los retrasos no enteros se truncan a un entero.

Si callback no es una función, se generará un TypeError.

Este método tiene una variante personalizada para promesas que está disponible mediante timersPromises.setTimeout().

Cancelación de temporizadores

Los métodos setImmediate(), setInterval() y setTimeout() devuelven objetos que representan los temporizadores programados. Estos se pueden usar para cancelar el temporizador y evitar que se active.

Para las variantes promesificadas de setImmediate() y setTimeout(), se puede usar un AbortController para cancelar el temporizador. Cuando se cancela, las Promesas devueltas se rechazarán con un 'AbortError'.

Para setImmediate():

ESM

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

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

// No hacemos `await` a la promesa, por lo que `ac.abort()` se llama simultáneamente.
setImmediatePromise('foobar', { signal })
  .then(console.log)
  .catch(err => {
    if (err.name === 'AbortError') console.error('El inmediato fue 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('El inmediato fue abortado')
  })

ac.abort()

Para setTimeout():

ESM

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

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

// No hacemos `await` a la promesa, por lo que `ac.abort()` se llama simultáneamente.
setTimeoutPromise(1000, 'foobar', { signal })
  .then(console.log)
  .catch(err => {
    if (err.name === 'AbortError') console.error('El tiempo de espera fue 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('El tiempo de espera fue abortado')
  })

ac.abort()

clearImmediate(immediate)

Agregado en: v0.9.1

• immediate <Immediate> Un objeto Immediate como el que devuelve setImmediate().

Cancela un objeto Immediate creado por setImmediate().

clearInterval(timeout)

Agregado en: v0.0.1

• timeout <Timeout> | <string> | <number> Un objeto Timeout como el que devuelve setInterval() o el primitivo del objeto Timeout como una cadena o un número.

Cancela un objeto Timeout creado por setInterval().

clearTimeout(timeout)

Agregado en: v0.0.1

• timeout <Timeout> | <string> | <number> Un objeto Timeout como el que devuelve setTimeout() o el primitivo del objeto Timeout como una cadena o un número.

Cancela un objeto Timeout creado por setTimeout().

API de Promesas de Temporizadores

[Historial]

Versión	Cambios
v16.0.0	Graduado de experimental.
v15.0.0	Añadido en: v15.0.0

La API timers/promises proporciona un conjunto alternativo de funciones de temporizador que devuelven objetos Promise. Se puede acceder a la API a través de 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]]])

Añadido en: v15.0.0

• delay <number> El número de milisegundos a esperar antes de cumplir la promesa. Predeterminado: 1.
• value <any> Un valor con el que se cumple la promesa.
• options <Object>
  • ref <boolean> Establecer en false para indicar que el Timeout programado no debería requerir que el bucle de eventos de Node.js permanezca activo. Predeterminado: true.
  • signal <AbortSignal> Un AbortSignal opcional que se puede utilizar para cancelar el Timeout programado.

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

Agregado en: v15.0.0

• value <any> Un valor con el que se cumple la promesa.
• options <Objeto>
  • ref <boolean> Establecer en false para indicar que el Immediate programado no debería requerir que el bucle de eventos de Node.js permanezca activo. Predeterminado: true.
  • signal <AbortSignal> Un AbortSignal opcional que se puede usar para cancelar el Immediate programado.

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

Agregado en: v15.9.0

Devuelve un iterador asíncrono que genera valores en un intervalo de delay ms. Si ref es true, necesitas llamar a next() del iterador asíncrono explícita o implícitamente para mantener el bucle de eventos activo.

• delay <number> El número de milisegundos a esperar entre iteraciones. Predeterminado: 1.
• value <any> Un valor con el que el iterador devuelve.
• options <Object>
  • ref <boolean> Establecer en false para indicar que el Timeout programado entre iteraciones no debe requerir que el bucle de eventos de Node.js permanezca activo. Predeterminado: true.
  • signal <AbortSignal> Un AbortSignal opcional que puede usarse para cancelar el Timeout programado entre operaciones.

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

Agregado en: v17.3.0, v16.14.0

[Estable: 1 - Experimental]

Estable: 1 Estabilidad: 1 - Experimental

• delay <number> El número de milisegundos que se deben esperar antes de resolver la promesa.

• options <Object>

  • ref <boolean> Establecer en false para indicar que el Timeout programado no debe requerir que el bucle de eventos de Node.js permanezca activo. Predeterminado: true.
  • signal <AbortSignal> Un AbortSignal opcional que se puede usar para cancelar la espera.

• Devuelve: <Promise>

Una API experimental definida por el borrador de la especificación de APIs de Programación que se está desarrollando como una API estándar de la plataforma web.

Llamar a timersPromises.scheduler.wait(delay, options) es equivalente a llamar a timersPromises.setTimeout(delay, undefined, options).

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

await scheduler.wait(1000) // Esperar un segundo antes de continuar

timersPromises.scheduler.yield()

Agregado en: v17.3.0, v16.14.0

[Estable: 1 - Experimental]

Estable: 1 Estabilidad: 1 - Experimental

• Devuelve: <Promise>

Una API experimental definida por el borrador de especificación de Scheduling APIs que se está desarrollando como una API estándar de la plataforma web.

Llamar a timersPromises.scheduler.yield() es equivalente a llamar a timersPromises.setImmediate() sin argumentos.