TypeScript实现类型安全的EventEmitter

作者：寒星时间：2026-10-26 11:25:44浏览：365

本文介绍如何利用TypeScript的高级类型特性，构建一个类型安全的EventEmitter。通过泛型约束和条件类型，确保事件名与回调函数参数严格匹配，避免运行时错误。文章详细解析了on、emit、off方法的类型定义，并提供了交叉类型扩展临时事件的技巧，帮助开发者在复杂项目中提升代码健壮性。

正文

近期个人项目中频繁使用 EventEmitter 模块，但由于其类型定义不够严谨，编写时需谨慎处理。为此，计划对其进行改良，打造一个支持 TypeScript 类型安全的 EventEmitter，以解决事件名称与函数参数类型无法自动校验的问题。

Node.js 中的 EventEmitter 是一个用于发布-订阅模式的模块。

借助该类，可以实现事件的监听机制。被监听对象会在适当时机触发事件，并调用监听者提供的方法，这是实现模块间解耦的常见手段。

随着 TypeScript 的普及，通过安装 @types/node 可以获得更完善的类型支持，从而减少低级错误。然而，现有的 EventEmitter 类型实现并不完善，难以称为真正的类型安全。

通常情况下，不同事件对应的响应函数类型各不相同，但 @types/node 的 EventEmitter 类型并未提供高级类型支持，而是允许一个异常宽松的值。

class EventEmitter {
  constructor(options?: EventEmitterOptions);
  // 类型过于宽泛
  on(eventName: string | symbol, listener: (...args: any[]) => void): this;
  emit(eventName: string | symbol, ...args: any[]): boolean;
  // ...其他
}

可以看到，on 方法传入的事件名类型是 string | symbol，而 listener 则是任意类型的函数。emit 传入的参数也是 any[]。

由于类型定义过于宽松，如果事件名拼写错误，TypeScript 并不会报错。当事件类型变得非常多时，这种实现与裸写 JavaScript 无异。

自己动手，丰衣足食，我们不妨自己实现一个类型安全的 EventEmitter。

EventEmitter 实现

由于我主要在前端环境中使用 EventEmitter，因此编写了一个简易的 JavaScript 实现版本。

class EventEmitter {
  eventMap = {};

  // 添加对应事件的监听函数
  on(eventName, listener) {
    if (!this.eventMap[eventName]) {
      this.eventMap[eventName] = [];
    }
    this.eventMap[eventName].push(listener);
    return this;
  }

  // 触发事件
  emit(eventName, ...args) {
    const listeners = this.eventMap[eventName];
    if (!listeners || listeners.length === 0) return false;
    listeners.forEach((listener) => {
      listener(...args);
    });
    return true;
  }

  // 取消对应事件的监听
  off(eventName, listener) {
    const listeners = this.eventMap[eventName];
    if (listeners && listeners.length > 0) {
      const index = listeners.indexOf(listener);
      if (index > -1) {
        listeners.splice(index, 1);
      }
    }
    return this;
  }
}

如果你在使用 Node.js，继承现有的 EventEmitter 并修改其类型可能是更好的做法，或者采用“基于组合而非继承”的方式来实现。

类型安全的 EventEmitter

接下来将上述代码转换为 TypeScript 版本。

我们希望达到的效果是：

const ee = new EventEmitter<{
  update(newVal: string, prevVal: string): void;
  destroy(): void;
}>();


const handler = (newVal: string, prevVal: string) => {
  console.log(newVal, prevVal)
}
ee.on("update", handler);
ee.emit('update', '前端西瓜哥上班前的精神状态', '前端西瓜哥上班后的精神状态')
ee.off("update", handler);

// 以下报错
// 'number' is not assignable to parameter of type 'string'
ee.emit('update', 1, 2)
// (val: number) => void' is not assignable to parameter of type '() => void
ee.on('destroy', (val: number) => {})

EventEmitter 支持接收一个对象结构的 interface 作为类型参数，指定不同的 key 对应的函数类型。

随后在调用 on、emit、off 时，如果事件名或函数参数不匹配，编译阶段即可报错。

代码实现：

class EventEmitter<T extends Record<string | symbol, any>> {
  private eventMap: Record<keyof T, Array<(...args: any[]) => void>> =
    {} as any;

  // 添加对应事件的监听函数
  on<K extends keyof T>(eventName: K, listener: T[K]) {
    if (!this.eventMap[eventName]) {
      this.eventMap[eventName] = [];
    }
    this.eventMap[eventName].push(listener);
    return this;
  }

  // 触发事件
  emit<K extends keyof T>(eventName: K, ...args: Parameters<T[K]>) {
    const listeners = this.eventMap[eventName];
    if (!listeners || listeners.length === 0) return false;
    listeners.forEach((listener) => {
      listener(...args);
    });
    return true;
  }

  // 取消对应事件的监听
  off<K extends keyof T>(eventName: K, listener: T[K]) {
    const listeners = this.eventMap[eventName];
    if (listeners && listeners.length > 0) {
      const index = listeners.indexOf(listener);
      if (index > -1) {
        listeners.splice(index, 1);
      }
    }
    return this;
  }
}

读者可自行拷贝上述两段代码到 TypeScript Playground 进行测试。

简单讲解一下实现细节。

首先是开头的类型参数定义。

class EventEmitter<T extends Record<string | symbol, any>> {
  //
}

这里的 extends 用于限定类型范围，防止传入不符合规则的类型参数。

Record 是 TypeScript 内置的高级类型，根据传入的 key 和 value 创建一个对象结构（后续提到的 T 即为此结构）。

Record<string | symbol, any>
// 等价于
{
  [key: string | symbol]: any
}

value 原本的类型应为 (...args: any[]) => void，以限制为函数。但在非字面量类型直接传入的情况下无法通过类型检查，因此改为 any。（这是 Index signature for type 'string' is missing 导致的报错）

然后是 eventMap，其实际内容如下：

eventMap = {
  event1: [ handler1, handler2 ],
  event2: [ handler3, handler4 ]
}

因此 key 需要为传入对象类型参数的 key。

函数无需指定特定类型，因为它是私有的，类外部无法访问，且未做过多的类型推断，故设为任意函数类型。

private eventMap: Record<keyof T, Array<(...args: any[]) => void>> =
  {} as any;

这里使用了对象字面量，读者也可以考虑使用 Map 数据结构。

接着是 on 方法，首先 eventName 必须为 T 的 key 之一。为了推断 K 这个内部类型变量，需要在 on 后添加 <K extends keyof T>，listener 则对应 T[K]。

on<K extends keyof T>(eventName: K, listener: T[K]): this

off 方法同理，此处不再展开。

然后是 emit，第一个 eventName 使用 keyof T 没问题，后续需要取出 handler 的参数作为剩余参数。

emit<K extends keyof T>(eventName: K, ...args: Parameters<T[K]>): boolean

这里使用了 TS 内置的 Parameters 高级类型，用于取出函数参数并返回数组类型。

临时扩展自定义事件

如果要给一个已经固定了类型的实例临时添加一个事件，可以使用 & 交叉类型进行扩展。

interface Events {
  update(newVal: string, prevVal: string): void;
  destroy(): void;
}
const ee = new EventEmitter<Events>();

// 用 & 扩展
const ee2 = ee as EventEmitter<
  Events & {
    customA(a: boolean): void;
  }
>;
// 不报错
ee2.emit('customA', true)

// 或者
(ee as EventEmitter<
  Events & {
    customA(a: boolean): void;
  }
>).emit('customA', true)