npm package: @iss-ai/sample-event-bus
Description: 一个简单、轻量级的事件总线实现
Latest version: 0.0.2

# SampleEventBus

一个简单、轻量级的事件总线实现，支持 TypeScript，提供完整的类型安全和调试功能。

## 特性

- 🚀 **轻量级** - 零依赖，体积小巧
- 🔒 **类型安全** - 完整的 TypeScript 类型支持
- 🔧 **调试模式** - 可选的调试日志，方便开发调试
- ⛓ **错误处理** - 自动捕获处理函数中的错误，不影响其他监听者
- 🔗 **链式调用** - 所有方法支持链式调用
- ⚡ **异步支持** - 完美支持同步和异步处理函数

## 安装

```bash
npm install @iss-ai/sample-event-bus
# 或
pnpm add @iss-ai/sample-event-bus
# 或
yarn add @iss-ai/sample-event-bus
```

## 快速开始

```typescript
import SampleEventBus from '@iss-ai/sample-event-bus';

// 创建事件总线实例
const bus = new SampleEventBus();

// 监听事件
bus.on('user:login', (user) => {
  console.log('User logged in:', user);
});

// 触发事件
bus.emit('user:login', { id: 1, name: 'John' });

// 移除监听
bus.off('user:login');
```

## 调试模式

开启调试模式可以查看详细的事件操作日志：

```typescript
// 通过构造函数开启
const bus = new SampleEventBus({ debug: true });

// 自定义日志前缀
const bus = new SampleEventBus({ 
  debug: true, 
  debugPrefix: '[MyApp]' 
});

// 运行时动态开启
bus.enableDebug();
bus.enableDebug('[CustomPrefix]');

// 关闭调试
bus.disableDebug();

// 检查调试状态
if (bus.isDebugEnabled()) {
  console.log('Debug is enabled');
}
```

调试输出示例：
```
[SampleEventBus] Registered first listener for "user:login"
[SampleEventBus] Emitting "user:login" to 1 listener(s) { id: 1, name: 'John' }
[SampleEventBus] Calling listener #1 for "user:login"
[SampleEventBus] Listener #1 for "user:login" completed
[SampleEventBus] All listeners for "user:login" finished
```

## API 文档

### on(type, handler)

监听指定类型的事件。

**参数：**
- `type: string` - 事件类型
- `handler: Function` - 事件处理函数

**返回：** `SampleEventBus` 实例（支持链式调用）

```typescript
bus.on('event', (data) => {
  console.log(data);
});

// 链式调用
bus.on('event1', handler1)
   .on('event2', handler2)
   .on('event3', handler3);
```

### emit(type, ...args)

触发指定类型的事件，传递参数给所有监听者。

**参数：**
- `type: string` - 事件类型
- `...args: any[]` - 传递给处理函数的参数

**返回：** `Promise<void>` - 等待所有处理函数执行完成

```typescript
// 同步时等待
await bus.emit('event', 'data');

// 不等待
bus.emit('event', 'data');
```

### off(type, handler?)

移除事件监听。如果不指定 handler，则移除该事件的所有监听。

**参数：**
- `type: string` - 事件类型
- `handler?: Function` - 要移除的处理函数（可选）

**返回：** `SampleEventBus` 实例（支持链式调用）

```typescript
const handler = (data) => console.log(data);
bus.on('event', handler);

// 移除指定监听
bus.off('event', handler);

// 移除所有监听
bus.off('event');
```

### once(type, handler)

注册单次监听，触发后自动移除。

**参数：**
- `type: string` - 事件类型
- `handler: Function` - 事件处理函数

**返回：** `SampleEventBus` 实例（支持链式调用）

```typescript
bus.once('init', () => {
  console.log('This will only run once');
});

// 触发后自动移除
await bus.emit('init');
await bus.emit('init'); // 不会再次触发
```

### has(type)

检查是否存在指定事件的监听。

**参数：**
- `type: string` - 事件类型

**返回：** `boolean`

```typescript
if (bus.has('event')) {
  console.log('Event has listeners');
}
```

### listenerCount(type)

获取指定事件的监听数量。

**参数：**
- `type: string` - 事件类型

**返回：** `number`

```typescript
const count = bus.listenerCount('event');
console.log(`Event has ${count} listener(s)`);
```

### clear()

清除所有事件监听。

```typescript
bus.clear();
```

### enableDebug(prefix?)

开启调试模式。

**参数：**
- `prefix?: string` - 可选的日志前缀

**返回：** `SampleEventBus` 实例

```typescript
bus.enableDebug();
bus.enableDebug('[MyApp]');
```

### disableDebug()

关闭调试模式。

**返回：** `SampleEventBus` 实例

```typescript
bus.disableDebug();
```

### isDebugEnabled()

检查是否处于调试模式。

**返回：** `boolean`

```typescript
if (bus.isDebugEnabled()) {
  console.log('Debug mode is on');
}
```

## 使用示例

### 基础用法

```typescript
import SampleEventBus from '@iss-ai/sample-event-bus';

const bus = new SampleEventBus();

// 监听事件
bus.on('message', (text) => {
  console.log('Received:', text);
});

// 触发事件
bus.emit('message', 'Hello World!');
```

### 多个监听者

```typescript
const bus = new SampleEventBus();

bus.on('click', () => console.log('Handler 1'));
bus.on('click', () => console.log('Handler 2'));
bus.on('click', () => console.log('Handler 3'));

bus.emit('click');
// 输出:
// Handler 1
// Handler 2
// Handler 3
```

### 异步处理函数

```typescript
const bus = new SampleEventBus();

bus.on('fetch', async (url) => {
  const response = await fetch(url);
  const data = await response.json();
  console.log('Fetched:', data);
});

await bus.emit('fetch', 'https://api.example.com/data');
```

### 单次监听

```typescript
const bus = new SampleEventBus();

bus.once('init', () => {
  console.log('Initializing...');
});

await bus.emit('init'); // 输出: Initializing...
await bus.emit('init'); // 无输出
```

### 错误处理

```typescript
const bus = new SampleEventBus();

bus.on('event', () => {
  throw new Error('Something went wrong');
});

bus.on('event', () => {
  console.log('This will still run');
});

await bus.emit('event');
// 输出:
// This will still run
// [SampleEventBus] Error in listener #1 for "event": Error: Something went wrong
```

### 链式调用

```typescript
const bus = new SampleEventBus();

bus.on('event1', handler1)
   .on('event2', handler2)
   .on('event3', handler3)
   .emit('event1')
   .emit('event2')
   .emit('event3');
```

### 调试模式

```typescript
const bus = new SampleEventBus({ 
  debug: true,
  debugPrefix: '[MyApp]'
});

bus.on('user:login', (user) => {
  console.log('User logged in:', user);
});

await bus.emit('user:login', { id: 1, name: 'John' });

// 控制台输出:
// [MyApp] Registered first listener for "user:login"
// [MyApp] Emitting "user:login" to 1 listener(s) { id: 1, name: 'John' }
// [MyApp] Calling listener #1 for "user:login"
// [MyApp] Listener #1 for "user:login" completed
// [MyApp] All listeners for "user:login" finished
```

## TypeScript 支持

SampleEventBus 提供完整的 TypeScript 类型支持：

```typescript
import SampleEventBus, { EventHandler } from 'sample-event-bus';

// 自定义事件类型
type UserEvent = [user: { id: number; name: string }];
type MessageEvent = [text: string];

// 类型安全的处理函数
const userHandler: EventHandler<UserEvent> = (user) => {
  console.log(user.id, user.name);
};

const messageHandler: EventHandler<MessageEvent> = (text) => {
  console.log(text);
};

const bus = new SampleEventBus();
bus.on('user:login', userHandler);
bus.on('message', messageHandler);
```

## 测试

```bash
# 运行测试
npm test

# 运行测试并生成覆盖率报告
npm run coveralls
```

测试覆盖率：
- 语句覆盖率：94.23%
- 分支覆盖率：87.17%
- 函数覆盖率：94.11%
- 行覆盖率：93.87%

## 构建

```bash
# 构建生产版本
npm run build
```

构建产物：
- `lib/index.cjs.js` - CommonJS 格式
- `lib/index.esm.js` - ES Module 格式
- `lib/index.umd.js` - UMD 格式
- `lib/index.min.js` - IIFE 格式
- `lib/index.d.ts` - TypeScript 类型定义

## License

MIT

## Author

iss-tools <https://github.com/iss-tools>