Noções Básicas de EventEmitter

6 exemplos para você começar com EventEmitter - 4 básicos e 2 intermediários.

Pré-requisitos

• import { EventEmitter } from 'node:events'.
• Entenda Vazamentos de Memória de Listeners para serviços de produção.

Exemplos Básicos

1. Criar e Emitir

Registre listeners e emita eventos nomeados de forma síncrona.

import { EventEmitter } from 'node:events';
 
const bus = new EventEmitter();
 
bus.on('ping', (ms: number) => console.log('pong', ms));
bus.emit('ping', 42);

• emit chama os listeners de forma síncrona no mesmo tick, a menos que listeners async retornem Promises que você trate separadamente.
• Nomes de eventos são strings ou símbolos - prefira constantes para eventos de domínio.
• O valor de retorno de emit é true se os listeners existiam.

Relacionado: Domain Events vs EventEmitter - quando usar um barramento (bus)

2. once para Manipuladores de Uso Único

Remove automaticamente o listener após a primeira invocação.

import { EventEmitter } from 'node:events';
 
const emitter = new EventEmitter();
 
emitter.once('ready', () => console.log('startup complete'));
emitter.emit('ready');
emitter.emit('ready'); // a segunda emissão não faz nada

• Ideal para inicialização e espera por eventos 'open' em servidores.
• once envolve on com off automático - evita vazamento se o evento disparar exatamente uma vez.
• Para eventos repetidos, use on com off explícito na limpeza.

3. off / removeListener

Remova listeners quando o escopo terminar.

import { EventEmitter } from 'node:events';
 
const bus = new EventEmitter();
 
function handler(payload: string) {
  console.log(payload);
}
 
bus.on('job', handler);
bus.off('job', handler);

• Passe a mesma referência de função para off - funções anônimas não podem ser removidas sem removeAllListeners.
• Crítico para processos de longa duração e caminhos de recarga a quente (hot reload).
• Prefira o padrão AbortSignal para limpeza agrupada (veja a página de vazamentos de memória).

4. emitter.setMaxListeners

Aumente o limite quando muitos listeners forem intencionais.

import { EventEmitter } from 'node:events';
 
const emitter = new EventEmitter();
emitter.setMaxListeners(50);

• O padrão 10 dispara MaxListenersExceededWarning - sinaliza um possível vazamento.
• Aumentar o limite sem justificativa oculta vazamentos. Correção: remova listeners ou use um manipulador de fan-out.
• getMaxListeners() lê a configuração atual.

Relacionado: Vazamentos de Memória de Listeners - padrões de vazamento

Exemplos Intermediários

5. Armadilha de Listener Assíncrono

Listeners async retornam Promises que emit não aguarda.

import { EventEmitter } from 'node:events';
 
const bus = new EventEmitter();
 
bus.on('work', async () => {
  await Promise.resolve();
  console.log('done');
});
 
bus.emit('work');
console.log('emit returned');
// emit returned, then done

• Erros em listeners assíncronos se tornam rejeições não tratadas, a menos que você use try/catch internamente.
• Não presuma a ordem entre trabalhos assíncronos sem uma fila explícita.
• Para fan-out assíncrono, use uma fila de trabalhos (BullMQ) ou o iterador assíncrono events.on com cuidado.

6. Mapa de Eventos Tipado (Preview)

Eventos type-safe em TypeScript - padrões completos em uma página dedicada.

import { EventEmitter } from 'node:events';
 
type Events = {
  userCreated: [userId: string];
  error: [err: Error];
};
 
class TypedBus extends EventEmitter {
  emit<E extends keyof Events>(event: E, ...args: Events[E]): boolean {
    return super.emit(event, ...args);
  }
  on<E extends keyof Events>(event: E, listener: (...args: Events[E]) => void): this {
    return super.on(event, listener);
  }
}

• Previne erros de digitação em nomes de eventos em tempo de compilação.
• Veja Typed EventEmitter para utilitários prontos para produção.

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.