Timers e Scheduler

Timers do Node agendam macrotarefas no event loop - callbacks de node:timers e sleeps assíncronos de node:timers/promises alimentam retentativas, debouncing e polling sem dependências extras.

Receita

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

Quando usar isso:

• Backoff de retentativa em clientes HTTP de saída
• Gatilhos de atualização de cache com debounce
• Verificação de status de job até estado terminal
• Atrasos com jitter em testes de integração

Exemplo Funcional

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;

O que isso demonstra:

• Backoff exponencial com sleep de timers/promises
• AbortSignal cancela timer pendente com AbortError
• Iterador setInterval (API de promessas de timer do Node) para loops assíncronos periódicos
• Prefira schedulers de fila para cron distribuído

Análise Detalhada

Como Funciona

• Timers de callback vivem em node:timers - fila de macrotarefas na fase de timers do libuv.
• timers/promises os envolve como Promises e iteráveis assíncronos.
• ref/unref em handles de Timeout - unref permite que o processo saia se apenas timers permanecerem.
• Módulo scheduler (orientado a navegador) tem casos de uso limitados em servidores Node.

Escolha 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 });
  }
}

Armadilhas

• setInterval com callback assíncrono lento - execuções sobrepostas. Correção: encadeie setTimeout após a conclusão do await.
• Não limpar timers no desligamento - atrasa a saída do SIGTERM. Correção: clearTimeout no handler de desligamento.
• Deriva sob carga - não preciso em relação ao relógio de parede. Correção: cron externo para jobs de meia-noite.
• Milhares de timers ativos - custo de heap e fase de timers. Correção: batch ou timer coordenador único.
• Esquecer unref em heartbeat de background - bloqueia a saída do deploy. Correção: timeout.unref() quando apropriado.

Alternativas

FAQs

Relacionado

• Timers & Scheduling - deriva e fases
• Noções Básicas de APIs Embutidas - visão geral
• BullMQ ioredis - agendamento distribuído
• Melhores Práticas do Event Loop - evite abuso de timers

Versões da Stack: Esta página foi escrita para Node.js 24.18.0 (Active LTS), npm 10+, TypeScript 5.6+, Express 5, Fastify 5 e NestJS 11.