fastevent 1.0.0 → 1.0.1

package/readme_cn.md

@@ -0,0 +1,282 @@
+# FastEvent
+
+FastEvent 是一个功能强大的`TypeScript`事件管理库，提供了灵活的事件订阅和发布机制，支持事件通配符、作用域、异步事件等特性。
+
+对比`EventEmitter2`，`FastEvent`具有以下优势：
+
+- 在含通配符发布与订阅时，`FastEvent`的性能比`EventEmitter2`高 `1+`倍左右。
+- `FastEvent`包大小为 `6.3xkb`，而`EventEmitter2`为 `43.4kb`。
+- `FastEvent`拥有更丰富的功能。
+
+# 安装
+
+使用 npm 安装:
+
+```bash
+npm install fastevent
+```
+
+或使用 yarn:
+
+```bash
+yarn add fastevent
+```
+
+# 快速入门
+
+## 基本使用
+
+```typescript
+import { FastEvent } from 'fastevent';
+
+// 创建事件实例
+const events = new FastEvent();
+
+// 订阅事件
+events.on('user/login', (user) => {
+  console.log('用户登录:', user);
+});
+
+// 发布事件
+events.emit('user/login', { id: 1, name: 'Alice' });
+```
+
+# 指南
+
+## 事件通配符
+
+FastEvent 支持两种通配符：
+- `*`: 匹配单层路径
+- `**`: 匹配多层路径
+
+```typescript
+const events = new FastEvent();
+
+// 匹配 user/*/login
+events.on('user/*/login', (data) => {
+  console.log('任何用户类型的登录:', data);
+});
+
+// 匹配 user 下的所有事件
+events.on('user/**', (data) => {
+  console.log('所有用户相关事件:', data);
+});
+
+// 触发事件
+events.emit('user/admin/login', { id: 1 });  // 两个处理器都会被调用
+events.emit('user/admin/profile/update', { name: 'New' });  // 只有 ** 处理器会被调用
+```
+
+## 事件作用域
+
+作用域允许你在特定的命名空间下处理事件：
+
+```typescript
+const events = new FastEvent();
+
+// 创建用户相关的作用域
+const userScope = events.scope('user');
+
+// 在作用域中订阅事件
+userScope.on('login', (data) => {
+  console.log('用户登录:', data);
+});
+
+// 等同于 events.emit('user/login', data)
+userScope.emit('login', { id: 1 });
+```
+
+## 一次性事件
+
+使用 `once` 订阅只触发一次的事件：
+
+```typescript
+const events = new FastEvent();
+
+events.once('startup', () => {
+  console.log('应用启动');
+});
+
+events.emit('startup');  // 输出: 应用启动
+events.emit('startup');  // 无输出，监听器已被移除
+```
+
+## 异步事件
+
+支持异步事件处理：
+
+```typescript
+const events = new FastEvent();
+
+events.on('data/fetch', async () => {
+  const response = await fetch('https://api.example.com/data');
+  return await response.json();
+});
+
+// 异步发布事件
+const results = await events.emitAsync('data/fetch');
+console.log('所有处理器的结果:', results);
+```
+
+## 事件等待
+
+使用 `waitFor` 等待特定事件发生：
+
+```typescript
+const events = new FastEvent();
+
+async function waitForLogin() {
+  try {
+    // 等待登录事件，超时时间 5 秒
+    const userData = await events.waitFor('user/login', 5000);
+    console.log('用户已登录:', userData);
+  } catch (error) {
+    console.log('登录等待超时');
+  }
+}
+
+waitForLogin();
+// 稍后触发登录事件
+events.emit('user/login', { id: 1, name: 'Alice' });
+```
+
+## 保留事件数据
+
+保留最后一次事件数据，新的订阅者会立即收到该数据：
+
+```typescript
+const events = new FastEvent();
+
+// 发布事件并保留
+events.emit('config/update', { theme: 'dark' }, true);
+
+// 之后的订阅者会立即收到保留的数据
+events.on('config/update', (config) => {
+  console.log('配置:', config);  // 立即输出: 配置: { theme: 'dark' }
+});
+```
+
+## 多级事件
+
+支持发布和订阅多级事件。
+
+默认使用 `/` 作为事件路径分隔符，你也可以使用自定义的分隔符：
+
+```typescript
+const events = new FastEvent({
+  delimiter: '.'
+});
+```
+
+## 全局事件监听
+
+使用 `onAny` 监听所有事件：
+
+```typescript
+const events = new FastEvent();
+
+events.onAny((data, meta) => {
+  console.log(`事件 ${meta.type} 被触发:`, data);
+});
+
+events.emit('user/login', { id: 1 });  // 输出: 事件 user/login 被触发: { id: 1 }
+events.emit('system/error', 'Connection failed');  // 输出: 事件 system/error 被触发: Connection failed
+```
+
+## 元数据(Meta)
+
+元数据是一种为事件提供额外上下文信息的机制。你可以在全局范围内设置元数据，也可以为单个事件添加特定的元数据。
+
+### 全局元数据
+
+在创建 FastEvent 实例时设置全局元数据：
+
+```typescript
+const events = new FastEvent({
+  meta: {
+    version: '1.0',
+    environment: 'production'
+  }
+});
+
+events.on('user/login', (data, meta) => {
+  console.log('事件数据:', data);
+  console.log('元数据:', meta);  // 包含 type、version 和 environment
+});
+```
+
+### 事件特定元数据
+
+在发布事件时可以传递额外的元数据，它会与全局元数据合并：
+
+```typescript
+const events = new FastEvent({
+  meta: { app: 'MyApp' }
+});
+
+// 在发布事件时添加特定的元数据
+events.emit('order/create', 
+  { orderId: '123' },  // 事件数据
+  false,  // 不保留
+  { timestamp: Date.now() }  // 事件特定的元数据
+);
+
+// 监听器接收合并后的元数据
+events.on('order/create', (data, meta) => {
+  console.log('订单:', data);  // { orderId: '123' }
+  console.log('元数据:', meta);  // { type: 'order/create', app: 'MyApp', timestamp: ... }
+});
+```
+
+## 错误处理
+
+FastEvent 提供了错误处理机制：
+
+```typescript
+const events = new FastEvent({
+  ignoreErrors: true,  // 默认为 true，不会抛出错误
+  onListenerError: (type, error) => {
+    console.error(`处理事件 ${type} 时发生错误:`, error);
+  }
+});
+
+events.on('process', () => {
+  throw new Error('处理失败');
+});
+
+// 不会抛出错误，而是触发 onListenerError
+events.emit('process');
+```
+
+## 自定义选项
+
+FastEvent 构造函数支持多个选项：
+
+```typescript
+const events = new FastEvent({
+  // 事件路径分隔符，默认为 '/'
+  delimiter: '.',  
+  // 事件处理器的上下文
+  context: null,  
+  // 元数据，会传递给所有事件处理器
+  meta: {  ... },
+  
+  // 错误处理
+  ignoreErrors: true,
+  onListenerError: (type, error) => {
+    console.error(`事件错误:`, type, error);
+  },
+  
+  // 监听器添加/移除的回调
+  onAddListener: (path, listener) => {
+    console.log('添加监听器:', path);
+  },
+  onRemoveListener: (path, listener) => {
+    console.log('移除监听器:', path);
+  }
+});
+```
+
+# 性能
+
+![](./bench.png)

package/src/__tests__/emit.test.ts

@@ -77,5 +77,18 @@ describe("简单发布与订阅",async ()=>{
         expect(err._trigger).toBe("x")
         
     })
+    test("添加侦听器时指定顺序",async ()=>{
+        const emitter = new FastEvent() 
+        const types:number[]=[]
+        emitter.on("x",()=>{
+            types.push(1)
+        })
+        
+        emitter.on("x",()=>{
+            types.push(2)
+        },{prepend:true})
+        emitter.emit("x")
+        expect(types).toEqual([2,1])
+    })      
 }) 
  

package/src/__tests__/many.test.ts

@@ -9,7 +9,7 @@ describe("指定次数事件的发布与订阅",async ()=>{
             expect(type).toBe("x")
             expect(payload).toBe(1)            
             events.push(type)
-        },2)
+        },{count:2})
         emitter.emit("x",1)
         emitter.emit("x",1)
         emitter.emit("x",1)

package/src/event.ts

@@ -7,7 +7,8 @@ import {
     FastListenerNode, 
     FastEventSubscriber, 
     ScopeEvents,
-    FastEventMeta
+    FastEventMeta,
+    FastEventListenOptions
 } from './types'; 
 import { isPathMatched } from './utils/isPathMatched';
 import { removeItem } from './utils/removeItem';
@@ -32,9 +33,15 @@ export class FastEvent<
         this._context = this._options.context || this
     }
     get options(){ return this._options  }
-    private _addListener(parts:string[],listener:FastEventListener<any,any>,count?:number):FastListenerNode | undefined{
+    private _addListener(parts:string[],listener:FastEventListener<any,any>,options:Required<FastEventListenOptions>):FastListenerNode | undefined{
+        const { count, prepend } = options
         return this._forEachNodes(parts,(node)=>{
-            node.__listeners.push(count && count >0 ? [listener,count]: listener)
+            const newListener =  count >0 ? [listener,count]: listener as any
+            if(prepend){
+                node.__listeners.splice(0,0,newListener)
+            }else{
+                node.__listeners.push(newListener)
+            }            
             if(typeof(this._options.onAddListener)==='function'){
                 this._options.onAddListener(parts,listener)
             }
@@ -88,13 +95,17 @@ export class FastEvent<
             return isRemove
         }) 
     }
-    public on<T extends string>(type: T, listener: FastEventListener<T,Events[T],Meta>, count?:number ): FastEventSubscriber
-    public on<T extends Types=Types>(type: T, listener: FastEventListener<Types,Events[T],Meta>, count?:number ): FastEventSubscriber
+    public on<T extends string>(type: T, listener: FastEventListener<T,Events[T],Meta>, options?:FastEventListenOptions ): FastEventSubscriber
+    public on<T extends Types=Types>(type: T, listener: FastEventListener<Types,Events[T],Meta>, options?:FastEventListenOptions): FastEventSubscriber
     public on<P=any>(type: '**', listener: FastEventListener<Types,P,Meta>): FastEventSubscriber
     public on(): FastEventSubscriber{
         const type = arguments[0] as string
         const listener = arguments[1] as FastEventListener 
-        const count = arguments[2] as number
+        const options = Object.assign({
+            count  : 0,
+            prepend: false
+        },arguments[2]) as Required<FastEventListenOptions>
+
         if(type.length===0) throw new Error('event type cannot be empty')
 
         if(type==='**'){
@@ -102,7 +113,7 @@ export class FastEvent<
         }
 
         const parts = type.split(this._delimiter);
-        const node = this._addListener(parts,listener,count)
+        const node = this._addListener(parts,listener,options)
         
         // Retain不支持通配符
         if(node && !type.includes('*')) this._emitForLastEvent(type) 
@@ -115,7 +126,7 @@ export class FastEvent<
     public once<T extends string>(type: T, listener: FastEventListener<T,Events[T],Meta> ): FastEventSubscriber
     public once<T extends Types=Types>(type: T, listener: FastEventListener<Types,Events[T],Meta> ): FastEventSubscriber
     public once(): FastEventSubscriber{
-        return this.on(arguments[0],arguments[1],1)
+        return this.on(arguments[0],arguments[1],{count:1})
     }
 
     /**
@@ -132,9 +143,13 @@ export class FastEvent<
      * subscriber.off();
      * ```
      */
-    onAny<P=any>(listener: FastEventListener<string,P,Meta>): FastEventSubscriber {
+    onAny<P=any>(listener: FastEventListener<string,P,Meta>, options?:Pick<FastEventListenOptions,'prepend'>): FastEventSubscriber {
         const listeners = this.listeners.__listeners
-        listeners.push(listener)
+        if(options && options.prepend){
+            listeners.splice(0,0,listener)
+        }else{
+            listeners.push(listener)
+        }        
         return {
             off:()=>this._removeListener(this.listeners,[],listener)
         }

package/src/scope.ts

@@ -1,5 +1,5 @@
 import { FastEvent } from "./event";
-import { FastEventListener, FastEvents, FastEventSubscriber } from "./types";
+import { FastEventListener, FastEventListenOptions, FastEvents, FastEventSubscriber } from "./types";
 
 export class FastEventScope<
     Events extends FastEvents  = FastEvents, 
@@ -29,8 +29,8 @@ export class FastEventScope<
         return type===undefined ? undefined : this.prefix + type
     }    
     
-    public on<T extends string>(type: T, listener: FastEventListener<T,Events[T],Meta>, count?:number ): FastEventSubscriber    
-    public on<T extends Types=Types>(type: T, listener: FastEventListener<T,Events[T],Meta>, count?:number ): FastEventSubscriber    
+    public on<T extends string>(type: T, listener: FastEventListener<T,Events[T],Meta>, options?:FastEventListenOptions ): FastEventSubscriber    
+    public on<T extends Types=Types>(type: T, listener: FastEventListener<T,Events[T],Meta>, options?:FastEventListenOptions): FastEventSubscriber    
     public on(type: '**', listener: FastEventListener<any,any,Meta>): FastEventSubscriber
     public on(): FastEventSubscriber{
         const args = [...arguments] as [any,any,any]
@@ -39,15 +39,15 @@ export class FastEventScope<
         return this.emitter.on(...args)
     }
 
-    public once<T extends string>(type: T, listener: FastEventListener<T,Events[T],Meta> ): FastEventSubscriber
-    public once<T extends Types = Types>(type: T, listener: FastEventListener<Types,Events[T],Meta> ): FastEventSubscriber    
+    public once<T extends string>(type: T, listener: FastEventListener<T,Events[T],Meta>, options?:FastEventListenOptions ): FastEventSubscriber
+    public once<T extends Types = Types>(type: T, listener: FastEventListener<Types,Events[T],Meta>, options?:FastEventListenOptions ): FastEventSubscriber    
     public once(): FastEventSubscriber{
-        return this.on(arguments[0],arguments[1],1)
+        return this.on(arguments[0],arguments[1],Object.assign(arguments[2],{},{count:1}))
     }
 
-    onAny<P=any>(listener: FastEventListener<Types,P,Meta>): FastEventSubscriber {
+    onAny<P=any>(listener: FastEventListener<Types,P,Meta>, options?:FastEventListenOptions): FastEventSubscriber {
         const type = this.prefix + '**'
-        return this.on(type as any,listener)
+        return this.on(type as any,listener,options)
     }   
     offAll(){
         this.emitter.offAll(this.prefix)

package/src/types.ts

@@ -48,3 +48,10 @@ export type ScopeEvents<T extends Record<string, any>, Prefix extends string> =
   };
 
  
+
+export type FastEventListenOptions={
+    // 侦听执行次数，当为1时为单次侦听，为0时为永久侦听，其他值为执行次数,每执行一次减一，减到0时移除侦听器
+    count?:number                   
+    // 将侦听器添加到侦听器列表的头部
+    prepend?:boolean
+}