Conceptos básicos de EventEmitter

6 ejemplos para empezar con EventEmitter: 4 básicos y 2 intermedios.

Requisitos previos

• import { EventEmitter } from 'node:events'.
• Comprende las fugas de memoria de los listeners para servicios de producción.

Ejemplos básicos

1. Crear y emitir

Registra listeners y emite eventos con nombre 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 llama a los listeners de forma síncrona en el mismo tick, a menos que los listeners async devuelvan Promesas que manejes por separado.
• Los nombres de los eventos son cadenas o símbolos; prefiere las constantes para los eventos de dominio.
• El valor de retorno de emit es true si existían listeners.

Relacionado: Eventos de dominio vs EventEmitter - cuándo usar un bus

2. once para manejadores de un solo uso

Elimina automáticamente el listener después de la primera invocación.

import { EventEmitter } from 'node:events';
 
const emitter = new EventEmitter();
 
emitter.once('ready', () => console.log('startup complete'));
emitter.emit('ready');
emitter.emit('ready'); // la segunda emisión no hace nada

• Ideal para el arranque y la espera de eventos 'open' en servidores.
• once envuelve on con off automático, evita fugas si el evento se dispara exactamente una vez.
• Para eventos repetidos, usa on con off explícito en la limpieza.

3. off / removeListener

Elimina listeners cuando el ámbito termina.

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

• Pasa la misma referencia de función a off; las funciones anónimas no se pueden eliminar sin removeAllListeners.
• Crítico para procesos de larga duración y rutas de recarga en caliente.
• Prefiere el patrón AbortSignal para la limpieza agrupada (ver la página de fugas de memoria).

4. emitter.setMaxListeners

Aumenta el límite cuando muchos listeners son intencionales.

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

• El valor predeterminado de 10 dispara MaxListenersExceededWarning, lo que indica una posible fuga.
• Aumentar el límite sin justificación oculta las fugas. Solución: elimina listeners o usa un manejador de abanico.
• getMaxListeners() lee la configuración actual.

Relacionado: Fugas de memoria de los listeners - patrones de fuga

Ejemplos intermedios

5. Trampa del listener asíncrono

Los listeners async devuelven Promesas que emit no espera.

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

• Los errores en los listeners asíncronos se convierten en rechazos no manejados a menos que uses try/catch dentro.
• No asumas el orden en el trabajo asíncrono sin una cola explícita.
• Para la distribución asíncrona, usa una cola de trabajos (BullMQ) o el iterador asíncrono events.on con cuidado.

6. Mapa de eventos tipado (Vista previa)

Eventos con tipo seguro en TypeScript: patrones completos en una 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);
  }
}

• Evita errores tipográficos en los nombres de los eventos en tiempo de compilación.
• Consulta Typed EventEmitter para utilidades listas para producción.

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.