Padrões EventEmitter

Use EventEmitter do Node.js para padrões publish-subscribe, com eventos tipados e manipuladores assíncronos.

Receita

Cartão de receita de referência rápida - pronto para copiar e colar.

import { EventEmitter } from "node:events";
 
const emitter = new EventEmitter();
 
// Assinar
emitter.on("message", (text: string) => {
  console.log("recebido:", text);
});
 
// Assinar uma vez
emitter.once("ready", () => {
  console.log("ready disparado uma vez");
});
 
// Cancelar assinatura
const handler = (n: number) => console.log(n);
emitter.on("tick", handler);
emitter.off("tick", handler);
 
// Publicar
emitter.emit("message", "olá");
emitter.emit("ready");
 
// Sempre trate erros - 'error' não tratado derruba o processo
emitter.on("error", (err) => {
  console.error("erro do emitter:", err);
});
emitter.emit("error", new Error("boom"));

Quando usar isso: Desacoplar produtores de consumidores dentro de um único processo Node - filas de jobs, pipelines de log, ciclo de vida de streams, hooks de plugins.

Exemplo de Trabalho

Uma classe wrapper EventEmitter tipada para uma fila de jobs.

import { EventEmitter } from "node:events";
 
// Mapeamento de tipos: nome do evento para tupla de argumentos
interface JobEvents {
  "job:start": [id: string];
  "job:progress": [id: string, percent: number];
  "job:complete": [id: string, result: unknown];
  "job:error": [id: string, err: Error];
}
 
class JobQueue extends EventEmitter {
  override on<K extends keyof JobEvents>(
    event: K,
    listener: (...args: JobEvents[K]) => void
  ): this {
    return super.on(event, listener as (...args: unknown[]) => void);
  }
 
  override emit<K extends keyof JobEvents>(
    event: K,
    ...args: JobEvents[K]
  ): boolean {
    return super.emit(event, ...args);
  }
 
  async run(id: string, task: (report: (p: number) => void) => Promise<unknown>) {
    this.emit("job:start", id);
    try {
      const result = await task((percent) => {
        this.emit("job:progress", id, percent);
      });
      this.emit("job:complete", id, result);
    } catch (err) {
      this.emit("job:error", id, err as Error);
    }
  }
}
 
const queue = new JobQueue();
 
queue.on("job:start", (id) => console.log(`[${id}] iniciando`));
queue.on("job:progress", (id, pct) => console.log(`[${id}] ${pct}%`));
queue.on("job:complete", (id, result) => console.log(`[${id}] concluído`, result));
queue.on("job:error", (id, err) => console.error(`[${id}] falhou`, err));
 
await queue.run("job-1", async (report) => {
  for (let i = 0; i <= 100; i += 25) {
    report(i);
    await new Promise((r) => setTimeout(r, 50));
  }
  return { ok: true };
});

O que isso demonstra:

• Sobrescritas tipadas para on e emit fornecem autocompletar completo e segurança de payload.
• Eventos de erro são explícitos - sem falhas silenciosas.
• O produtor (run) e os consumidores (os manipuladores on) são totalmente desacoplados.

Mergulho Profundo

Como Funciona

EventEmitter mantém um mapa interno do nome do evento para um array de funções de listener. emit itera esse array de forma síncrona, chamando cada listener na ordem em que foi registrado. Não há fila embutida nem backpressure - listeners rodam no tick atual, a menos que eles mesmos agendem trabalho assíncrono.

on anexa, once anexa um wrapper que se remove após a primeira chamada, off (alias removeListener) remove por referência, e removeAllListeners(event?) limpa tudo.

O evento 'error' é especial: se nada estiver ouvindo quando você emit('error', err), o Node lança o erro e, se não for capturado, termina o processo.

Variações

EventEmitter Tipado com genéricos. O padrão JobQueue acima é a abordagem idiomática em Node + TypeScript moderno. Bibliotecas como tsee ou typed-emitter empacotam a mesma ideia.

Iteração assíncrona com events.on(). Consuma eventos como um stream:

import { on, EventEmitter } from "node:events";
 
const emitter = new EventEmitter();
 
setTimeout(() => emitter.emit("data", 1), 10);
setTimeout(() => emitter.emit("data", 2), 20);
 
for await (const [value] of on(emitter, "data")) {
  console.log("valor:", value);
  if (value === 2) break;
}

once como uma Promise. Ótimo para esperar por um único evento de ciclo de vida:

import { once, EventEmitter } from "node:events";
 
const emitter = new EventEmitter();
setTimeout(() => emitter.emit("ready", "ok"), 50);
 
const [value] = await once(emitter, "ready");
console.log(value); // "ok"

Estendendo EventEmitter. Crie uma subclasse quando o emitter for a identidade principal do seu objeto (o exemplo JobQueue). Componha (tenha um #emitter interno) quando os eventos forem uma preocupação secundária.

Removendo todos os listeners. emitter.removeAllListeners() sem argumento destrói todos os eventos; com um argumento, apenas aquele evento. Útil no teardown, mas perigoso se você não for o dono do emitter.

Aviso de max listeners. Node imprime MaxListenersExceededWarning em 11 listeners por evento. Aumente com emitter.setMaxListeners(50) ou globalmente via EventEmitter.defaultMaxListeners. O aviso é uma dica de vazamento, não um erro.

Notas TypeScript

Defina um mapa de tipos de evento como uma interface onde cada chave é o nome do evento e cada valor é uma tupla dos argumentos do listener - por exemplo interface Events \{ start: [id: string]; progress: [percent: number] \}. Use este mapa com uma classe base genérica como TypedEmitter<Events> (de typed-emitter), ou escreva suas próprias sobrescritas de on, once, off e emit que restrinjam o nome do evento com K extends keyof Events e os args com Events[K]. Isso lhe dará autocompletar nos nomes de eventos e verificação em tempo de compilação das formas dos payloads.

Armadilhas

1. Esquecer manipuladores de error derruba o processo. Emitir 'error' sem listener lança uma exceção. Sempre anexe um listener de error antes de qualquer caminho de código que possa emitir um.
2. Aviso de max listeners em 10. Adicionar o mesmo manipulador em um loop, ou assinar dentro de um efeito React sem limpeza, rapidamente excede o padrão. O aviso é impresso uma vez por emitter por evento - fácil de perder.
3. emit é síncrono. Listeners rodam na ordem de registro no mesmo tick. Um listener síncrono lento bloqueia todos os outros listeners e o event loop.
4. once não impede outras inscrições. Ele apenas envolve aquele manipulador. Outros listeners on continuam disparando para sempre.
5. Listeners anônimos não podem ser removidos. emitter.off("x", () => {}) passa uma referência de função totalmente nova e não remove nada. Armazene o manipulador em uma variável se você precisar removê-lo.
6. Lançar exceção dentro de um listener. Um throw síncrono se propaga para fora de emit e pode derrubar listeners não relacionados. Envolva trabalho arriscado em try/catch ou use manipuladores assíncronos que rejeitem para um evento error.
7. Listeners assíncronos são "dispare e esqueça". emit não espera por nada. Promises rejeitadas em listeners se tornam rejeições não tratadas, a menos que você anexe .catch dentro do listener.

Alternativas

FAQs

Relacionados

• docs/nodejs-scripts/http-server.md - Servidores HTTP, que são eles mesmos instâncias de EventEmitter.
• docs/browser-apis/postmessage-basics.md - mensagens entre janelas, um padrão pub-sub do lado do navegador.
• docs/react-hooks/use-effect.md - assinando e limpando listeners de eventos do React.