SampleEventBus

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

特性

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

安装

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

快速开始

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');

调试模式

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

// 通过构造函数开启
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 实例（支持链式调用）

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> - 等待所有处理函数执行完成

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

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

off(type, handler?)

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

参数：

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

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

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 实例（支持链式调用）

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

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

has(type)

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

参数：

• type: string - 事件类型

返回： boolean

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

listenerCount(type)

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

参数：

• type: string - 事件类型

返回： number

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

clear()

清除所有事件监听。

bus.clear();

enableDebug(prefix?)

开启调试模式。

参数：

• prefix?: string - 可选的日志前缀

返回： SampleEventBus 实例

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

disableDebug()

关闭调试模式。

返回： SampleEventBus 实例

bus.disableDebug();

isDebugEnabled()

检查是否处于调试模式。

返回： boolean

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

使用示例

基础用法

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!');

多个监听者

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

异步处理函数

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');

单次监听

const bus = new SampleEventBus();

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

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

错误处理

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

链式调用

const bus = new SampleEventBus();

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

调试模式

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 类型支持：

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);

测试

# 运行测试
npm test

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

测试覆盖率：

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

构建

# 构建生产版本
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