npm package: @hcstar/emitter
Description: 事件触发器
Author: hcstar
Latest version: 0.0.3

# @hcstar/emitter

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

## 安装

```bash
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<L>, signArray?: ListenerSignType[]): CallListenerResult<L>[]**
  - 同步将事件分发给监听器
  - 参数：
    - `args` - 触发监听器的参数
    - `signArray` - 可选，要触发的监听器标识
  - 返回：每个监听器的执行结果数组

- **dispatchAsync(args: Parameters<L>, signArray?: ListenerSignType[]): Promise<void>**
  - 异步分发事件（在微任务队列执行）
  - 参数：同 `dispatch`
  - 返回：Promise

- **dispatchAllResolve(args: Parameters<L>, signArray?: ListenerSignType[]): Promise<void>**
  - 类似 `Promise.all()` 的逻辑，等待所有监听器完成
  - 参数：同 `dispatch`
  - 返回：Promise

- **dispatchAllSettled(args: Parameters<L>, signArray?: ListenerSignType[]): Promise<void>**
  - 类似 `Promise.allSettled()` 的逻辑，等待所有监听器完成（包括错误）
  - 参数：同 `dispatch`
  - 返回：Promise

- **dispatchEvery(args: Parameters<L>, predicate?: (returnValue: ReturnType<L>) => boolean | Promise<boolean>, signArray?: ListenerSignType[]): Promise<boolean>**
  - 类似 `Array.every()` 的逻辑，检查所有监听器的返回值
  - 参数：
    - `args` - 触发监听器的参数
    - `predicate` - 可选，返回值检查函数
    - `signArray` - 可选，要触发的监听器标识
  - 返回：布尔值，表示是否所有监听器都满足条件

- **dispatchSome(args: Parameters<L>, predicate?: (returnValue: ReturnType<L>) => boolean | Promise<boolean>, signArray?: ListenerSignType[]): Promise<boolean>**
  - 类似 `Array.some()` 的逻辑，检查是否有监听器满足条件
  - 参数：同 `dispatchEvery`
  - 返回：布尔值，表示是否有监听器满足条件

- **merge(...array: EventHandler<L>[])**
  - 合并多个其他 EventHandler 实例
  - 参数：`array` - 要合并的 EventHandler 实例数组

### EventEmitter 类

#### 公开方法

- **clear(): void**
  - 清空当前 Emitter 中的所有事件和监听器

- **clearHandler<T extends keyof ELM>(type: T, ...signArray: ListenerSignType[]): void**
  - 清空指定事件类型的监听器
  - 参数：
    - `type` - 要清空的事件类型
    - `signArray` - 可选，指定要清除的监听器标识范围

- **setEventHandler<T extends keyof ELM>(type: T, newHandler: EventHandler<ELM[T]>): void**
  - 手动设置外部的 EventHandler 实例，实现事件共享
  - 参数：
    - `type` - 事件类型
    - `newHandler` - 要设置的 EventHandler 实例

- **getEventHandler<T extends keyof ELM>(type: T, autoCreate?: boolean): EventHandler<ELM[T]> | undefined**
  - 获取指定事件类型的 EventHandler 实例
  - 参数：
    - `type` - 事件类型
    - `autoCreate` - 如果不存在，是否自动创建
  - 返回：EventHandler 实例或 undefined

- **addListener<T extends keyof ELM>(type: T, handler: ELM[T], config: ListenerConfig = {}): () => void**
  - 添加事件监听器
  - 参数：
    - `type` - 事件类型
    - `handler` - 监听函数
    - `config` - 监听器配置，可选
  - 返回：用于移除监听器的函数

- **removeListener<T extends keyof ELM>(type: T, handler: ELM[T]): boolean**
  - 移除指定的事件监听器
  - 参数：
    - `type` - 事件类型
    - `handler` - 要移除的监听函数
  - 返回：布尔值，表示是否成功移除

- **dispatch<T extends keyof ELM>(type: T, args: Parameters<ELM[T]>, signArray?: ListenerSignType[]): CallListenerResult<ELM[T]>[]**
  - 同步触发指定事件
  - 参数：
    - `type` - 事件类型
    - `args` - 触发事件的参数
    - `signArray` - 可选，要触发的监听器标识
  - 返回：每个监听器的执行结果数组

- **dispatchAsync<T extends keyof ELM>(type: T, args: Parameters<ELM[T]>, signArray?: ListenerSignType[]): Promise<void>**
  - 异步触发指定事件
  - 参数：同 `dispatch`
  - 返回：Promise

- **dispatchAllResolve<T extends keyof ELM>(type: T, args: Parameters<ELM[T]>, signArray?: ListenerSignType[]): Promise<void>**
  - 类似 `Promise.all()` 的逻辑触发事件
  - 参数：同 `dispatch`
  - 返回：Promise

- **dispatchAllSettled<T extends keyof ELM>(type: T, args: Parameters<ELM[T]>, signArray?: ListenerSignType[]): Promise<void>**
  - 类似 `Promise.allSettled()` 的逻辑触发事件
  - 参数：同 `dispatch`
  - 返回：Promise

- **dispatchEvery<T extends keyof ELM>(type: T, args: Parameters<ELM[T]>, predicate?: (returnValue: ReturnType<ELM[T]>) => boolean | Promise<boolean>, signArray?: ListenerSignType[]): Promise<boolean>**
  - 类似 `Array.every()` 的逻辑触发事件
  - 参数：
    - `type` - 事件类型
    - `args` - 触发事件的参数
    - `predicate` - 可选，返回值检查函数
    - `signArray` - 可选，要触发的监听器标识
  - 返回：布尔值，表示是否所有监听器都满足条件

- **dispatchSome<T extends keyof ELM>(type: T, args: Parameters<ELM[T]>, predicate?: (returnValue: ReturnType<ELM[T]>) => boolean | Promise<boolean>, signArray?: ListenerSignType[]): Promise<boolean>**
  - 类似 `Array.some()` 的逻辑触发事件
  - 参数：同 `dispatchEvery`
  - 返回：布尔值，表示是否有监听器满足条件

### 配置选项

监听器配置 (`ListenerConfig`) 包括：

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

## 使用示例

### 基础使用

```typescript
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();
```

### 使用标识符控制监听器

```typescript
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']);
```

### 一次性监听器

```typescript
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', []);
```

### 异步事件处理

```typescript
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