API 参考

EventBus 是默认导出类；eventBus 是具名导出的全局单例。

类：EventBus

import EventBus from "@ai-zen/event-bus";

new EventBus()

创建事件总线实例，内部维护 subscribers。

const bus = new EventBus();

bus.subscribers

• 类型：Map<string, Map<EventHandler, ErrorHandler>>
• 说明：公开属性，存储事件订阅者。键为事件名，值为「handler -> errorHandler」的映射。一般无需直接访问。

bus.subscribers.has("greet"); // false

bus.on(name, handler, error?)

• 类型：on(name: string, handler: EventHandler, error?: ErrorHandler): Disposable
• 说明：订阅事件。返回一个 Disposable，调用其 dispose() 可退订。
• 参数：
  • name：事件名。
  • handler：事件处理函数。
  • error（可选）：错误处理函数。
• 返回：Disposable。
• 示例：

const disposable = bus.on("greet", (name) => {
  console.log(name);
});
disposable.dispose();

bus.off(name, handler)

• 类型：off(name: string, handler: EventHandler): boolean
• 说明：退订指定事件的指定 handler。成功退订返回 true，否则返回 false。
• 示例：

const ok = bus.off("greet", handler);

bus.offAll(name)

• 类型：offAll(name: string): void
• 说明：清空指定事件的所有 handler 与错误处理器。
• 示例：

bus.offAll("greet");

bus.destroy()

• 类型：destroy(): void
• 说明：清空全部订阅，销毁事件总线。
• 示例：

bus.destroy();

bus.emit(name, ...args)

• 类型：emit(name: string, ...args: any[]): void
• 说明：触发事件，将 args 原样传给所有已订阅的 handler。只调用 handler，不会调用错误处理器。
• 示例：

bus.emit("greet", "AI-Zen");

bus.error(name, reason)

• 类型：error(name: string, reason: any): void
• 说明：向指定事件的错误处理器派发错误，只调用订阅时传入的 error 处理器。
• 示例：

bus.error("load", new Error("boom"));

bus.gather<T>(name, ...args)

• 类型：gather<T>(name: string, ...args: any[]): T[]
• 说明：调用指定事件的所有 handler，返回它们的返回结果数组。
• 示例：

const results = bus.gather<number>("calc");

bus.gatherMap<T>(name, ...args)

• 类型：gatherMap<T>(name: string, ...args: any[]): Map<EventHandler, T>
• 说明：调用指定事件的所有 handler，返回以 handler 为键、返回结果为值的 Map。
• 示例：

const m = bus.gatherMap<number>("calc");

bus.once(name, handler, error?)

• 类型：once(name: string, handler: EventHandler, error?: ErrorHandler): Disposable
• 说明：订阅事件，事件第一次触发后自动退订。返回 Disposable。
• 示例：

bus.once("reply", (value) => console.log(value));
bus.emit("reply", "done"); // 仅触发一次

bus.promise(name)

• 类型：promise(name: string): Promise<any>
• 说明：返回一个 Promise，事件触发时 resolve；若对该事件调用 error，则该 Promise reject。
• 示例：

const result = await bus.promise("reply");
bus.emit("reply", "done");

bus.subscribe / bus.unsubscribe / bus.publish

• 说明：三者均为 getter 属性，分别返回 on / off / emit 方法的引用，作为别名使用。

bus.subscribe("greet", handler);   // 等价于 bus.on
bus.unsubscribe("greet", handler); // 等价于 bus.off
bus.publish("greet", "AI-Zen");    // 等价于 bus.emit

具名导出

eventBus

全局单例 EventBus 实例，可在多处共享同一总线。

import { eventBus } from "@ai-zen/event-bus";
eventBus.on("greet", handler);

类型定义

type EventHandler = (...args: any[]) => any; // 事件处理函数
type ErrorHandler = (reason?: any) => void;  // 错误处理函数
type Disposable = { dispose: () => void };   // 可退订对象

• EventHandler：事件处理函数，接收任意参数并返回任意结果。
• ErrorHandler：错误处理函数，接收可选的 reason。
• Disposable：具有 dispose() 方法的对象，用于退订。

说明

• 类型定义位于构建产物 dist/EventBus.d.ts。
• 源码见仓库内 src/EventBus.ts。
• 若对某些行为（如 once 的自动退订、promise 的 reject 触发条件、subscribe/unsubscribe/publish 为 getter 别名）有疑问，请以 src/EventBus.ts 实现为准。