Temporizadores y Planificador

Los temporizadores de Node programan macrotareas en el bucle de eventos: las devoluciones de llamada de node:timers y los sleeps asíncronos de node:timers/promises impulsan reintentos, debouncing y sondeos sin dependencias adicionales.

Receta

import { setTimeout, setInterval } from 'node:timers/promises';
 
await setTimeout(500, undefined, { signal: abortController.signal });
 
for await (const start of setInterval(1000, Date.now())) {
  console.log('tick', Date.now() - start);
}

Cuándo usarlo:

• Retroceso exponencial en clientes HTTP salientes
• Debouncing de disparadores de actualización de caché
• Sondeo del estado del trabajo hasta el estado terminal
• Retrasos con jitter en pruebas de integración

Ejemplo de trabajo

import { setTimeout as sleep } from 'node:timers/promises';
 
async function retry<T>(fn: () => Promise<T>, attempts = 3): Promise<T> {
  let lastErr: unknown;
  for (let i = 0; i < attempts; i++) {
    try {
      return await fn();
    } catch (err) {
      lastErr = err;
      if (i < attempts - 1) {
        await sleep(100 * 2 ** i);
      }
    }
  }
  throw lastErr;
}
 
const controller = new AbortController();
const cancellable = sleep(10_000, undefined, { signal: controller.signal })
  .catch((err) => console.log('cancelled', err.name));
 
controller.abort();
await cancellable;

Lo que esto demuestra:

• Retroceso exponencial con sleep de timers/promises
• AbortSignal cancela el temporizador pendiente con AbortError
• Iterador asíncrono setInterval (API de promesas de temporizador de Node) para bucles asíncronos periódicos
• Preferir planificadores de cola para cron distribuido

Inmersión Profunda

Cómo funciona

• Los temporizadores de devolución de llamada viven en node:timers - cola de macrotareas en la fase de temporizadores de libuv.
• timers/promises los envuelve como Promesas e iterables asíncronos.
• ref/unref en los manejadores de Timeout - unref permite la salida del proceso si solo quedan temporizadores.
• El módulo scheduler (orientado al navegador) tiene casos de uso limitados en servidores Node.

Selección de API

Notas de TypeScript

import { setTimeout } from 'node:timers/promises';
 
export async function pollUntil(
  check: () => boolean | Promise<boolean>,
  { intervalMs = 200, timeoutMs = 5_000, signal }: {
    intervalMs?: number;
    timeoutMs?: number;
    signal?: AbortSignal;
  } = {},
): Promise<void> {
  const deadline = Date.now() + timeoutMs;
  while (!(await check())) {
    if (Date.now() > deadline) throw new Error('timeout');
    await setTimeout(intervalMs, undefined, { signal });
  }
}

Errores comunes

• setInterval con devolución de llamada asíncrona lenta - ejecuciones superpuestas. Solución: encadenar setTimeout después de que await se complete.
• No limpiar los temporizadores al apagar - retrasa la salida de SIGTERM. Solución: clearTimeout en el manejador de apagado.
• Desfase bajo carga - no es preciso con el reloj de pared. Solución: cron externo para trabajos de medianoche.
• Miles de temporizadores activos - costo de heap y fase de temporizador. Solución: procesamiento por lotes o un único temporizador coordinador.
• Olvidar unref en el latido de fondo - bloquea la salida del despliegue. Solución: timeout.unref() cuando sea apropiado.

Alternativas

Preguntas frecuentes

Relacionado

• Temporizadores y Planificación - desfase y fases
• Conceptos básicos de APIs integradas - resumen
• BullMQ ioredis - planificación distribuida
• Mejores prácticas del bucle de eventos - evitar el abuso de temporizadores

Versiones de la pila: Esta página fue escrita para Node.js 24.18.0 (LTS activa), npm 10+, TypeScript 5.6+, Express 5, Fastify 5 y NestJS 11.