事件发射器在Node.js、浏览器扩展和多数前端状态管理工具中都承担着解耦通信的职责。一个对象负责广播事件，另一个对象订阅并处理，调用方只需要知道事件名字符串。但正是这种字符串约定让类型检查经常失效：事件名拼错不会在编译期报错，回调参数与发布参数不一致也要等到运行时才暴露。TypeScript的类型级编程可以把这些约定从注释和口头协议提升为编译器可验证的约束。本文不依赖装饰器或第三方框架，而是从映射类型、泛型约束、逆变位置和条件类型出发，逐步构建一个端到端类型安全的事件发射器。

一、用事件映射接口锁定事件名与载荷

典型的EventEmitter会把所有事件处理函数放在一个以string为键的字典里，回调参数通常被声明为any或unknown。这么做的确灵活，但灵活到让错误可以轻松穿透编译检查。例如某个模块发布userLogin事件时带的是{ id, name }，另一个模块却按{ userId, nickname }去读取，类型系统完全不知道这两件事有任何关联。只有当真实运行到那一行，才会得到undefined或直接抛异常。

要改变这一点，第一步是定义一个事件映射接口。事件名作为字面量键，每个键对应的类型就是该事件触发时应当携带的载荷。这个接口既是数据结构的描述，也是整个事件发射器的合同。下面是一个简单示例：

interface AppEvents {
  userLogin: { id: number; name: string };
  message: string;
  ready: undefined;
}

接口中ready事件载荷为undefined，表示它不需要参数。AppEvents这个映射一旦确定，后续on、emit、once等所有方法都能从它推导出合法的事件名和回调签名，不再需要手动维护联合类型。

接着创建TypedEmitter类。关键在于让类接受一个泛型E，并对E使用extends object约束。E可以是接口、类型别名，只要它具有字面量键即可。on方法使用<K extends keyof E>捕获当前事件名K，handler参数写成(payload: E[K]) => void。emit方法的payload同样使用E[K]。这里的keyof E和索引访问是类型级编程的基础操作，它们让事件名和载荷类型之间建立起了等号关系。

class TypedEmitter<E extends object> {
  protected listeners = new Map<keyof E, Array<(payload: any) => void>>();
  on<K extends keyof E>(type: K, handler: (payload: E[K]) => void): this {
    const existing = this.listeners.get(type) ?? [];
    existing.push(handler as (payload: any) => void);
    this.listeners.set(type, existing);
    return this;
  }
  emit<K extends keyof E>(type: K, payload: E[K]): void {
    const handlers = this.listeners.get(type);
    if (!handlers) {
      return;
    }
    for (const handler of handlers) {
      (handler as (payload: E[K]) => void)(payload);
    }
  }
  off<K extends keyof E>(type: K, handler: (payload: E[K]) => void): void {
    const handlers = this.listeners.get(type);
    if (!handlers) {
      return;
    }
    const index = handlers.indexOf(handler as (payload: any) => void);
    if (index !== -1) {
      handlers.splice(index, 1);
    }
  }
}

二、逆变推导让回调参数自动获得精确类型

当调用bus.on('message', (text) => ...)时，text并不需要显式声明，它被自动推断成string。这个体验的底层来自函数参数位置的兼容性规则。在TypeScript中，函数类型之间做赋值或参数传递，参数通常按逆变方式检查。虽然class方法参数历史上存在双变例外，但当我们把监听器声明为对象字面量或独立函数类型时，编译器仍然会按目标签名约束实际回调。换句话说，on方法的签名已经声明了handler必须接收E[K]，那么传入的箭头函数参数就会根据目标类型获得上下文类型。

逆变还意味着回调不能随意收窄参数类型。比如userLogin载荷是{ id: number; name: string }，如果监听器写成(user: string) => ...，编译会直接报错。因为对于所有会发布userLogin的调用点来说，载荷一定是那个对象，不可能被安全地当作string处理。反过来，回调参数写得更宽，比如(user: unknown) => ...，通常可以通过逆变检查，因为unknown能接收任何值。这为某些只关心事件发生时机、不关心具体内容的监听器提供了出口。

实际使用中，emit也会接受同样严格的检查。发布方必须提供完整且类型正确的载荷。下面的代码展示了正常调用和几类会被拦截的错误：

const bus = new TypedEmitter<AppEvents>();
bus.on('userLogin', (user) => {
  console.log(user.name.toUpperCase());
});
bus.emit('userLogin', { id: 1, name: 'Ada' });
// 错误：缺少 name 属性
// bus.emit('userLogin', { id: 1 });
bus.on('message', (text) => {
  console.log(text);
});
bus.emit('message', 'hello');

这种检查让事件发射器从一个字符串转发器变成一个强类型API。尤其是在多个模块协作的项目里，接口一旦变化，所有不匹配的发布和订阅位置都会立刻变红，不用再靠测试用例去覆盖每一条事件链。

三、once、off与无载荷事件的类型设计

基础的on和emit足以覆盖多数同步通知场景，但真实项目往往还需要一次性监听、移除监听器、无参数事件、通配符监听等能力。这些功能不是简单套一个any就能收场的，类型级编程同样有发挥空间。

一次性监听如果以回调方式实现，会在回调执行后自动移除监听器。但如果把它设计成返回Promise的once方法，调用方可以await下一次事件发生，代码会更接近异步流程。类型签名可以写成once<K extends keyof E>(type: K): Promise<E[K]>，它保证await得到的值就是事件载荷类型。实现时内部创建临时handler，在回调被触发后调用off并resolve。off方法也必须复用on的签名，否则可能出现删除不存在的监听器这类问题。

class AdvancedEmitter<E extends object> extends TypedEmitter<E> {
  once<K extends keyof E>(type: K): Promise<E[K]> {
    return new Promise((resolve) => {
      const handler = (payload: E[K]) => {
        this.off(type, handler);
        resolve(payload);
      };
      this.on(type, handler);
    });
  }
}

无载荷事件是个容易忽略的细节。如果E中某个事件的载荷是undefined，emit仍然强制要求传递undefined，调用起来很别扭。可以利用条件类型和元组参数，让这种事件直接变成零参数调用。示例：

type EventArgs<E, K extends keyof E> = E[K] extends undefined ? [] : [payload: E[K]];
class StrictEmitter<E extends object> extends TypedEmitter<E> {
  emitStrict<K extends keyof E>(type: K, ...args: EventArgs<E, K>): void {
    const payload = args[0] as E[K];
    super.emit(type, payload);
  }
}
const strictBus = new StrictEmitter<AppEvents>();
strictBus.emitStrict('ready');
strictBus.emitStrict('message', 'hello');
// 错误：message 需要第二个参数
// strictBus.emitStrict('message');

这里的EventArgs<E, K>判断E[K]是否可赋值给undefined，若是则生成空元组，否则生成带payload的单元素元组。配合emitStrict的剩余参数签名，编译器就能自动决定是否需要传参。

通配符监听是另一个进阶需求。某些日志、埋点或调试工具希望监听所有事件，但又不丢失类型信息。可以先用映射类型生成事件条目联合，让回调收到的参数是一个可辨识元组，第一项是事件名，第二项是对应载荷。这样在onAny回调内部通过判断第一项，仍能收窄出精确的载荷类型。

type EventEntries<E> = {
  [K in keyof E]: [K, E[K]];
}[keyof E];
class WildcardEmitter<E extends object> extends TypedEmitter<E> {
  onAny(handler: (entry: EventEntries<E>) => void): this {
    (Object.keys(this.listeners) as (keyof E)[]).forEach((key) => {
      this.on(key, (payload) => {
        handler([key, payload] as EventEntries<E>);
      });
    });
    return this;
  }
}

这个简化实现基于已知监听器键做遍历，真正要覆盖后续动态注册的事件，还要把通配符handler存在单独列表并在emit中同时触发。核心价值在类型层面：即便监听全部事件，回调也不会退化成any。

四、错误排查、类型边界与辅助工具

类型级编程并非没有代价。最常见的问题是动态事件名会导致字面量类型被拓宽成string。假设事件名来自用户输入或接口配置，编译器无法把它约束到keyof E，此时需要显式使用as const、泛型函数或类型守卫来保留字面量。例如把const event = 'message'改为const event = 'message' as const，或者直接写一个泛型辅助函数publish<K extends keyof AppEvents>(type: K, payload: AppEvents[K])，让TypeScript在调用处推导K。

另一个容易踩坑的地方是索引签名。如果事件映射接口包含[key: string]: any，那么keyof E会被拓宽成string | number，所有围绕字面量键的推导都会明显变弱。如果确实需要开放扩展，最好把已知事件定义在一个严格接口中，再通过交叉类型或联合类型接入开放部分，避免直接污染主事件映射。

当类型报错信息过于庞大时，可以使用辅助类型展开映射结果。比如Prettify<T>能把交叉类型展开成直观的对象形状：

type Prettify<T> = {
  [K in keyof T]: T[K];
} & {};
type VisibleEvents = Prettify<AppEvents>;

类型级编程不是要把所有运行时逻辑都塞进类型里。事件发射器的类型安全核心是让事件名、载荷和监听器签名保持一致。具体实现仍然要处理异常、监听器顺序、错误隔离等运行时问题。类型系统负责的是编译期契约，运行逻辑还是要保持简单清晰。把两者结合起来，事件发射器才能在大型项目中既保持灵活性，又不牺牲可维护性。

回看整个设计，类型级编程带来的最大收益不是少写几个判断，而是让事件通信链路可以被编译器持续验证。任何一次事件契约调整，都会立即映射到所有发布和订阅位置。对于长期维护的TypeScript项目，这种反馈速度往往比运行时兜底更有价值。