Emissores de Eventos Type-Safe em TypeScript

Você já passou por isso: um erro de digitação no nome de um evento, um payload incompatível e, de repente, um listener que nunca dispara silenciosamente. O bug leva 30 minutos para rastrear, e a correção é de um único caractere. Emissores de eventos tipados em TypeScript eliminam toda essa categoria de problema ao mover o erro do tempo de execução para o tempo de compilação.

Este artigo mostra como funciona o padrão de mapa de eventos do TypeScript, quando construir sua própria abstração versus usar o que já existe, e alguns padrões práticos que vale a pena conhecer.

Por Que Emissores de Eventos Type-Safe São Importantes

A abordagem não tipada se parece com isso:

import { EventEmitter } from 'events'

const emitter = new EventEmitter()

emitter.on('userLoggedIn', (user) => {
  console.log(user.name) // user é `any`
})

emitter.emit('userLoggedin', { name: 'Alice' }) // erro de digitação — sem erro

Neste uso não tipado, o TypeScript não capturará a diferença de capitalização entre userLoggedIn e userLoggedin. O listener nunca dispara, e nada lhe diz o porquê.

O Padrão de Mapa de Eventos do TypeScript

A correção começa com uma interface simples — um mapa de eventos — onde cada chave é um nome de evento e cada valor é seu tipo de payload:

interface UserEvents {
  userLoggedIn: { userId: string, timestamp: Date }
  userLoggedOut: { userId: string }
  profileUpdated: { userId: string, changes: Record<string, unknown> }
}

Esta interface se torna a única fonte de verdade para tudo que seu emissor pode fazer.

Construindo um Emissor Personalizado Fortemente Tipado

Aqui está uma classe emissora tipada mínima mas completa:

type EventCallback<T> = (payload: T) => void

class TypedEventEmitter<TEvents extends Record<string, unknown>> {
  private listeners: {
    [K in keyof TEvents]?: EventCallback<TEvents[K]>[]
  } = {}

  on<K extends keyof TEvents>(event: K, callback: EventCallback<TEvents[K]>): void {
    (this.listeners[event] ??= []).push(callback)
  }

  off<K extends keyof TEvents>(event: K, callback: EventCallback<TEvents[K]>): void {
    const cbs = this.listeners[event]
    if (cbs) this.listeners[event] = cbs.filter(cb => cb !== callback)
  }

  emit<K extends keyof TEvents>(event: K, payload: TEvents[K]): void {
    this.listeners[event]?.forEach(cb => cb(payload))
  }

  once<K extends keyof TEvents>(event: K, callback: EventCallback<TEvents[K]>): void {
    const wrapper: EventCallback<TEvents[K]> = (payload) => {
      this.off(event, wrapper)
      callback(payload)
    }
    this.on(event, wrapper)
  }
}

O mecanismo chave é K extends keyof TEvents. Quando você chama emit('userLoggedIn', ...), o TypeScript restringe K para exatamente 'userLoggedIn' e verifica se o payload corresponde a { userId: string, timestamp: Date }. Um erro de digitação ou estrutura errada se torna um erro de compilação.

const emitter = new TypedEventEmitter<UserEvents>()

emitter.on('userLoggedIn', ({ userId, timestamp }) => {
  console.log(userId, timestamp) // totalmente tipado
})

emitter.emit('userLoggedin', { userId: '1', timestamp: new Date() }) // ❌ erro de compilação
emitter.emit('userLoggedIn', { userId: '1' }) // ❌ timestamp ausente

Usando EventEmitter do Node.js com Type Safety

O @types/node moderno expõe EventEmitter como uma classe genérica, então você pode frequentemente obter eventos tipados diretamente sem escrever um wrapper.

import { EventEmitter } from 'events'

interface AppEvents {
  'user:login': [userId: string, email: string]
  'data:sync': [recordCount: number]
}

const emitter = new EventEmitter<AppEvents>()

emitter.on('user:login', (userId, email) => {
  console.log(userId, email)
})

emitter.emit('data:sync', 42)

Uma ressalva importante: o sistema de eventos do Node é síncrono por padrão — os listeners executam na ordem de registro antes que emit retorne. Além disso, o evento 'error' tem comportamento especial em tempo de execução: se emitido sem nenhum listener anexado, o Node lança uma exceção não capturada. Utilitários auxiliares como events.once() podem não preservar totalmente os tipos do seu mapa de eventos, então a segurança de tipos pode degradar nesses casos.

Alternativas e Bibliotecas

Em contextos de navegador, EventTarget com CustomEvent é a opção nativa, mas tipar subclasses personalizadas de EventTarget em TypeScript é desajeitado — as restrições genéricas não se alinham de forma limpa com CustomEvent<T>.

Bibliotecas como mitt e eventemitter3 oferecem emissores tipados prontos para uso e valem a pena considerar se você quiser uma implementação testada em batalha em vez de criar a sua própria. Elas são opcionais, não obrigatórias — o padrão em si é direto o suficiente para ser implementado diretamente.

Limpeza Prática: Evitando Vazamentos de Memória

Sempre remova listeners quando eles não forem mais necessários. Listeners esquecidos são uma das fontes mais comuns de vazamentos de memória em código orientado a eventos:

const handler = ({ userId }: { userId: string }) => console.log(userId)

emitter.on('userLoggedOut', handler)

// Mais tarde, na limpeza:
emitter.off('userLoggedOut', handler)

No React, combine isso com a limpeza do useEffect. Em qualquer serviço de longa duração, documente qual componente é responsável pela remoção dos listeners.

Conclusão

O padrão de mapa de eventos do TypeScript custa uma definição de interface antecipadamente. O que você recebe em troca é a aplicação em tempo de compilação de nomes de eventos e estruturas de payload em toda a sua base de código — sem mais incompatibilidades silenciosas, sem mais callbacks tipados como any, e IntelliSense completo em cada listener. Para qualquer sistema onde eventos cruzam fronteiras de módulos, essa troca vale a pena fazer imediatamente.

Perguntas Frequentes

Complete picture for complete understanding

Capture every clue your frontend is leaving so you can instantly get to the root cause of any issue with OpenReplay — the open-source session replay tool for developers. Self-host it in minutes, and have complete control over your customer data.

Check our GitHub repo and join the thousands of developers in our community.