@hcstar/emitter

一个功能强大的事件发射器工具库，提供了灵活的事件管理机制。

安装

npm install @hcstar/emitter

功能特性

• 🔄 支持同步和异步事件处理
• 🔧 灵活的事件监听器配置（一次性监听、标记过滤等）
• 📦 提供 EventEmitter 和 EventHandler 两个核心类
• 🌐 支持 TypeScript 类型定义
• 🛠️ 支持基于标识符(sign)的精确事件控制

核心概念

EventEmitter

EventEmitter 是主要的事件管理器，用于管理多种类型的事件，支持类型化事件定义。

EventHandler

EventHandler 管理单一类型事件的所有监听器，是 EventEmitter 内部用于处理具体事件的控制器。

API 文档

EventHandler 类

公开属性

• size: number - 当前注册的监听器数量

公开方法

• has(listener: L): boolean

  • 检查是否存在指定的事件监听函数
  • 参数：listener - 要判断的目标 listener 函数
  • 返回：布尔值，表示是否存在

• clear(...signArray: ListenerSignType[]): void

  • 清空当前注册的所有事件监听函数
  • 参数：signArray - 可选，指定要清除的监听器标识范围

• addListener(handler: L, config: ListenerConfig = {}): () => boolean

  • 添加监听器（重复添加会先移除前一个）
  • 参数：
    • handler - 要添加的 listener 函数
    • config - 监听器配置，可选
  • 返回：用于移除监听器的函数

• removeListener(handler: L): boolean

  • 移除指定的监听器
  • 参数：handler - 要移除的 listener 函数
  • 返回：布尔值，表示是否成功移除

• [Symbol.iterator](signArray: ListenerSignType[] = []): MapIterator<[L, ListenerConfig]>

  • 监听器及其配置的迭代器
  • 参数：signArray - 可选，用于过滤监听器的标识
  • 返回：包含监听器和配置的迭代器

• dispatch(args: Parameters, signArray?: ListenerSignType[]): CallListenerResult[]

  • 同步将事件分发给监听器
  • 参数：
    • args - 触发监听器的参数
    • signArray - 可选，要触发的监听器标识
  • 返回：每个监听器的执行结果数组

• dispatchAsync(args: Parameters, signArray?: ListenerSignType[]): Promise

  • 异步分发事件（在微任务队列执行）
  • 参数：同 dispatch
  • 返回：Promise

• dispatchAllResolve(args: Parameters, signArray?: ListenerSignType[]): Promise

  • 类似 Promise.all() 的逻辑，等待所有监听器完成
  • 参数：同 dispatch
  • 返回：Promise

• dispatchAllSettled(args: Parameters, signArray?: ListenerSignType[]): Promise

  • 类似 Promise.allSettled() 的逻辑，等待所有监听器完成（包括错误）
  • 参数：同 dispatch
  • 返回：Promise

• dispatchEvery(args: Parameters, predicate?: (returnValue: ReturnType) => boolean | Promise, signArray?: ListenerSignType[]): Promise

  • 类似 Array.every() 的逻辑，检查所有监听器的返回值
  • 参数：
    • args - 触发监听器的参数
    • predicate - 可选，返回值检查函数
    • signArray - 可选，要触发的监听器标识
  • 返回：布尔值，表示是否所有监听器都满足条件

• dispatchSome(args: Parameters, predicate?: (returnValue: ReturnType) => boolean | Promise, signArray?: ListenerSignType[]): Promise

  • 类似 Array.some() 的逻辑，检查是否有监听器满足条件
  • 参数：同 dispatchEvery
  • 返回：布尔值，表示是否有监听器满足条件

• merge(...array: EventHandler[])

  • 合并多个其他 EventHandler 实例
  • 参数：array - 要合并的 EventHandler 实例数组

EventEmitter 类

公开方法

• clear(): void

  • 清空当前 Emitter 中的所有事件和监听器

• clearHandler(type: T, ...signArray: ListenerSignType[]): void

  • 清空指定事件类型的监听器
  • 参数：
    • type - 要清空的事件类型
    • signArray - 可选，指定要清除的监听器标识范围

• setEventHandler(type: T, newHandler: EventHandler<ELM[T]>): void

  • 手动设置外部的 EventHandler 实例，实现事件共享
  • 参数：
    • type - 事件类型
    • newHandler - 要设置的 EventHandler 实例

• getEventHandler(type: T, autoCreate?: boolean): EventHandler<ELM[T]> | undefined

  • 获取指定事件类型的 EventHandler 实例
  • 参数：
    • type - 事件类型
    • autoCreate - 如果不存在，是否自动创建
  • 返回：EventHandler 实例或 undefined

• addListener(type: T, handler: ELM[T], config: ListenerConfig = {}): () => void

  • 添加事件监听器
  • 参数：
    • type - 事件类型
    • handler - 监听函数
    • config - 监听器配置，可选
  • 返回：用于移除监听器的函数

• removeListener(type: T, handler: ELM[T]): boolean

  • 移除指定的事件监听器
  • 参数：
    • type - 事件类型
    • handler - 要移除的监听函数
  • 返回：布尔值，表示是否成功移除

• dispatch(type: T, args: Parameters<ELM[T]>, signArray?: ListenerSignType[]): CallListenerResult<ELM[T]>[]

  • 同步触发指定事件
  • 参数：
    • type - 事件类型
    • args - 触发事件的参数
    • signArray - 可选，要触发的监听器标识
  • 返回：每个监听器的执行结果数组

• dispatchAsync(type: T, args: Parameters<ELM[T]>, signArray?: ListenerSignType[]): Promise

  • 异步触发指定事件
  • 参数：同 dispatch
  • 返回：Promise

• dispatchAllResolve(type: T, args: Parameters<ELM[T]>, signArray?: ListenerSignType[]): Promise

  • 类似 Promise.all() 的逻辑触发事件
  • 参数：同 dispatch
  • 返回：Promise

• dispatchAllSettled(type: T, args: Parameters<ELM[T]>, signArray?: ListenerSignType[]): Promise

  • 类似 Promise.allSettled() 的逻辑触发事件
  • 参数：同 dispatch
  • 返回：Promise

• dispatchEvery(type: T, args: Parameters<ELM[T]>, predicate?: (returnValue: ReturnType<ELM[T]>) => boolean | Promise, signArray?: ListenerSignType[]): Promise

  • 类似 Array.every() 的逻辑触发事件
  • 参数：
    • type - 事件类型
    • args - 触发事件的参数
    • predicate - 可选，返回值检查函数
    • signArray - 可选，要触发的监听器标识
  • 返回：布尔值，表示是否所有监听器都满足条件

• dispatchSome(type: T, args: Parameters<ELM[T]>, predicate?: (returnValue: ReturnType<ELM[T]>) => boolean | Promise, signArray?: ListenerSignType[]): Promise

  • 类似 Array.some() 的逻辑触发事件
  • 参数：同 dispatchEvery
  • 返回：布尔值，表示是否有监听器满足条件

配置选项

监听器配置 (ListenerConfig) 包括：

• once: boolean - 是否只触发一次
• sign: ListenerSignType[] - 监听器标识符数组，用于精确控制事件触发

使用示例

基础使用

import { EventEmitter } from '@hcstar/emitter';

interface AppEvents {
  'page-view': (path: string) => void;
  'user-action': (action: string, data: any) => void;
}

const appEvents = new EventEmitter<AppEvents>();

// 添加监听器
const unsubscribe = appEvents.addListener('page-view', (path) => {
  console.log(`Viewing page: ${path}`);
});

// 触发事件
appEvents.dispatch('page-view', ['/home']);

// 移除监听器
unsubscribe();

使用标识符控制监听器

import { EventEmitter } from '@hcstar/emitter';

interface DataEvents {
  'data-update': (data: any) => void;
}

const dataEmitter = new EventEmitter<DataEvents>();

// 添加带标识符的监听器
dataEmitter.addListener('data-update', (data) => {
  console.log('Module A received:', data);
}, { sign: ['moduleA'] });

dataEmitter.addListener('data-update', (data) => {
  console.log('Module B received:', data);
}, { sign: ['moduleB'] });

// 只触发带有特定标识符的监听器
dataEmitter.dispatch('data-update', [{ id: 1, value: 'test' }], ['moduleA']);

一次性监听器

import { EventEmitter } from '@hcstar/emitter';

interface InitEvents {
  'init-complete': () => void;
}

const initEmitter = new EventEmitter<InitEvents>();

// 添加一次性监听器
initEmitter.addListener('init-complete', () => {
  console.log('Initialization complete (will only run once)');
}, { once: true });

// 第一次触发会执行
initEmitter.dispatch('init-complete', []);

// 第二次触发不会执行
initEmitter.dispatch('init-complete', []);

异步事件处理

import { EventEmitter } from '@hcstar/emitter';

interface AsyncEvents {
  'data-fetch': (url: string) => Promise<any>;
}

const asyncEmitter = new EventEmitter<AsyncEvents>();

// 添加异步监听器
asyncEmitter.addListener('data-fetch', async (url) => {
  const response = await fetch(url);
  return response.json();
});

// 使用 dispatchAllResolve 等待所有异步操作完成
async function fetchData() {
  await asyncEmitter.dispatchAllResolve('data-fetch', ['https://api.example.com/data']);
  console.log('All data fetched');
}

fetchData();

License

MIT