Patrones de EventEmitter

Usa Node.js EventEmitter para patrones de publicación-suscripción, con eventos tipados y manejadores asincronos.

Receta

Tarjeta de receta de referencia rápida — lista para copiar y pegar.

import { EventEmitter } from "node:events";
 
const emitter = new EventEmitter();
 
// Suscribirse
emitter.on("message", (text: string) => {
  console.log("got:", text);
});
 
// Suscribirse una única vez
emitter.once("ready", () => {
  console.log("ready fired once");
});
 
// Desuscribirse
const handler = (n: number) => console.log(n);
emitter.on("tick", handler);
emitter.off("tick", handler);
 
// Publicar
emitter.emit("message", "hello");
emitter.emit("ready");
 
// Siempre maneja errores — unhandled 'error' bloquea el proceso
emitter.on("error", (err) => {
  console.error("emitter error:", err);
});
emitter.emit("error", new Error("boom"));

Cuándo usarlo: Desacoplamiento de productores de consumidores dentro de un único proceso de Node — colas de trabajo, tuberías de registro, ciclo de vida de stream, hooks de plugin.

Ejemplo Práctico

Una clase envolvente de EventEmitter tipada para una cola de trabajo.

import { EventEmitter } from "node:events";
 
// Mapa de tipos: nombre de evento a 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}] start`));
queue.on("job:progress", (id, pct) => console.log(`[${id}] ${pct}%`));
queue.on("job:complete", (id, result) => console.log(`[${id}] done`, result));
queue.on("job:error", (id, err) => console.error(`[${id}] failed`, 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 };
});

Lo que esto demuestra:

• Las anulaciones tipadas para on y emit proporcionan autocompletado total y seguridad de carga útil.
• Los eventos de error son explícitos — sin fallos silenciosos.
• El productor (run) y los consumidores (los manejadores on) están completamente desacoplados.

Análisis Profundo

Cómo funciona

EventEmitter mantiene un mapa interno de nombre de evento a un array de funciones listener. emit itera ese array sincrónic amente, llamando a cada listener en el orden en que fue registrado. No hay cola incorporada ni contrapresión — los listeners se ejecutan en el tick actual a menos que ellos mismos programen trabajo asincrónico.

on añade, once añade un envolvente que se elimina a sí mismo después de la primera llamada, off (alias removeListener) elimina por referencia, y removeAllListeners(event?) borra todo.

El evento 'error' es especial: si nada está escuchando cuando haces emit('error', err), Node lanza el error y, si no se atrapa, termina el proceso.

Variaciones

EventEmitter tipado con generics. El patrón JobQueue anterior es el enfoque idiomático en Node + TypeScript modernos. Las bibliotecas como tsee o typed-emitter empaquetan la misma idea.

Iteración asincrónica con events.on(). Consume eventos como un 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("value:", value);
  if (value === 2) break;
}

once como una Promise. Excelente para esperar un único evento del 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"

Extendiendo EventEmitter. Subclas ifica cuando el emitter es la identidad principal de tu objeto (el ejemplo JobQueue). Compón (ten un #emitter interno) cuando los eventos son una preocupación secundaria.

Eliminando todos los listeners. emitter.removeAllListeners() sin argumento elimina todos los eventos; con un argumento, solo ese evento. Útil en desmontaje pero peligroso si no posees el emitter.

Advertencia de máximo de listeners. Node imprime MaxListenersExceededWarning con 11 listeners por evento. Elévalo con emitter.setMaxListeners(50) o globalmente a través de EventEmitter.defaultMaxListeners. La advertencia es una pista de fuga, no un error.

Notas de TypeScript

Define un mapa de tipo de evento como una interfaz donde cada clave es el nombre del evento y cada valor es una tupla de los argumentos del listener — por ejemplo interface Events \{ start: [id: string]; progress: [percent: number] \}. Usa este mapa con una clase base genérica como TypedEmitter<Events> (de typed-emitter), o escribe tus propias anulaciones de on, once, off, y emit que restrinjan el nombre del evento con K extends keyof Events y los argumentos con Events[K]. Esto te da autocompletado en nombres de eventos y verificación de compilación de formas de carga útil.

Trampas

1. Olvidar manejadores de error bloquea el proceso. Emitir 'error' sin listener lanza. Siempre adjunta un listener de error antes de cualquier ruta de código que pueda emitir uno.
2. Advertencia de MaxListeners en 10. Agregar el mismo manejador en un bucle, o suscribirse dentro de un efecto de React sin limpieza, rápidamente excede el predeterminado. La advertencia se imprime una vez por emitter por evento — fácil de perder.
3. emit es sincrónico. Los listeners se ejecutan en orden de registro en el mismo tick. Un listener sincrónico lento bloquea todos los demás listeners y el event loop.
4. once no previene otras registraciones. Solo envuelve ese único manejador. Otros listeners on siguen disparándose para siempre.
5. Los listeners anónimos no se pueden eliminar. emitter.off("x", () => {}) pasa una referencia de función nueva y no elimina nada. Almacena el manejador en una variable si alguna vez necesitas eliminarlo.
6. Lanzar dentro de un listener. Un lanzamiento sincrónico se propaga desde emit y puede derribar listeners no relacionados. Envuelve trabajo riesgoso en try/catch o usa manejadores asincronos que rechacen en un evento de error.
7. Los listeners asincronos son dispara y olvida. emit no espera nada. Las promesas rechazadas en listeners se convierten en rechazos no manejados a menos que adjuntes .catch dentro del listener.

Alternativas

Preguntas Frecuentes

Relacionado

• docs/nodejs-scripts/http-server.md — Servidores HTTP, que son instancias de EventEmitter.
• docs/browser-apis/postmessage-basics.md — mensajería entre ventanas, un patrón pub-sub del lado del navegador.
• docs/react-hooks/use-effect.md — suscripción y limpieza de listeners de eventos desde React.