fastevent 1.1.0 → 1.1.2

package/src/event.ts

@@ -13,26 +13,65 @@ import {
 import { isPathMatched } from './utils/isPathMatched';
 import { removeItem } from './utils/removeItem';
 
+/**
+ * FastEvent 事件发射器类
+ * 
+ * @template Events - 事件类型定义，继承自FastEvents接口
+ * @template Meta - 事件元数据类型，默认为任意键值对对象
+ * @template Types - 事件类型的键名类型，默认为Events的键名类型
+ */
 export class FastEvent<
     Events extends FastEvents = FastEvents,
     Meta extends Record<string, any> = Record<string, any>,
+    Context = any,
     Types extends keyof Events = keyof Events
 > {
+    /** 事件监听器树结构，存储所有注册的事件监听器 */
     public listeners: FastListeners = { __listeners: [] } as unknown as FastListeners
+
+    /** 事件发射器的配置选项 */
     private _options: FastEventOptions
+
+    /** 事件名称的分隔符，默认为'/' */
     private _delimiter: string = '/'
-    private _context: any
-    private _retainedEvents: Map<string, any> = new Map<string, any>()
+
+    /** 事件监听器执行时的上下文对象 */
+    private _context: Context
+
+    /** 保留的事件消息映射，用于新订阅者 */
+    retainedMessages: Map<string, any> = new Map<string, any>()
+
+    /** 当前注册的监听器总数 */
+    listenerCount: number = 0
+    /**
+     * 创建FastEvent实例
+     * @param options - 事件发射器的配置选项
+     * 
+     * 默认配置：
+     * - debug: false - 是否启用调试模式
+     * - id: 随机字符串 - 实例唯一标识符
+     * - delimiter: '/' - 事件名称分隔符
+     * - context: null - 监听器执行上下文
+     * - ignoreErrors: true - 是否忽略监听器执行错误
+     */
     constructor(options?: FastEventOptions<Meta>) {
         this._options = Object.assign({
+            debug: false,
+            id: Math.random().toString(36).substring(2),
             delimiter: '/',
             context: null,
             ignoreErrors: true
         }, options)
         this._delimiter = this._options.delimiter!
         this._context = this._options.context || this
+        this._enableDevTools()
     }
+
+    /** 获取事件发射器的配置选项 */
     get options() { return this._options }
+
+    /** 获取事件发射器的唯一标识符 */
+    get id() { return this._options.id! }
     private _addListener(parts: string[], listener: FastEventListener<any, any>, options: Required<FastEventListenOptions>): FastListenerNode | undefined {
         const { count, prepend } = options
         return this._forEachNodes(parts, (node) => {
@@ -43,10 +82,17 @@ export class FastEvent<
                 node.__listeners.push(newListener)
             }
             if (typeof (this._options.onAddListener) === 'function') {
+                this.listenerCount++
                 this._options.onAddListener(parts, listener)
             }
         })
     }
+    private _enableDevTools() {
+        if (this.options.debug) {
+            // @ts-ignore
+            globalThis.__FLEXEVENT_DEVTOOLS__.add(this)
+        }
+    }
     /**
      * 
      * 根据parts路径遍历侦听器树，并在最后的节点上执行回调函数
@@ -90,14 +136,39 @@ export class FastEvent<
             item = Array.isArray(item) ? item[0] : item
             const isRemove = item === listener
             if (isRemove && typeof (this._options.onRemoveListener) === 'function') {
+                this.listenerCount--
                 this._options.onRemoveListener(path, listener)
             }
             return isRemove
         })
     }
-    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
+    /**
+     * 注册事件监听器
+     * @param type - 事件类型，支持以下格式：
+     *   - 普通字符串：'user/login'
+     *   - 通配符：'user/*'（匹配单层）或'user/**'（匹配多层）
+     *   - 全局监听：'**'（监听所有事件）
+     * @param listener - 事件监听器函数
+     * @param options - 监听器配置选项：
+     *   - count: 触发次数限制，0表示无限制
+     *   - prepend: 是否将监听器添加到监听器队列开头
+     * @returns 返回订阅者对象，包含off方法用于取消监听
+     * 
+     * @example
+     * ```ts
+     * // 监听特定事件
+     * emitter.on('user/login', (data) => console.log(data));
+     * 
+     * // 使用通配符
+     * emitter.on('user/*', (data) => console.log(data));
+     * 
+     * // 限制触发次数
+     * emitter.on('event', handler, { count: 3 });
+     * ```
+     */
+    public on<T extends string>(type: T, listener: FastEventListener<T, Events[T], Meta, Context>, options?: FastEventListenOptions): FastEventSubscriber
+    public on<T extends Types = Types>(type: T, listener: FastEventListener<Types, Events[T], Meta, Context>, options?: FastEventListenOptions): FastEventSubscriber
+    public on<P = any>(type: '**', listener: FastEventListener<Types, P, Meta, Context>): FastEventSubscriber
     public on(): FastEventSubscriber {
         const type = arguments[0] as string
         const listener = arguments[1] as FastEventListener
@@ -123,8 +194,30 @@ 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
+
+    /**
+     * 注册一次性事件监听器
+     * @param type - 事件类型，支持与on方法相同的格式：
+     *   - 普通字符串：'user/login'
+     *   - 通配符：'user/*'（匹配单层）或'user/**'（匹配多层）
+     * @param listener - 事件监听器函数
+     * @returns 返回订阅者对象，包含off方法用于取消监听
+     * 
+     * @description
+     * 监听器只会在事件首次触发时被调用一次，之后会自动解除注册。
+     * 这是on方法的特例，相当于设置options.count = 1。
+     * 如果事件有保留消息，新注册的监听器会立即收到最近一次的保留消息并解除注册。
+     * 
+     * @example
+     * ```ts
+     * // 只监听一次登录事件
+     * emitter.once('user/login', (data) => {
+     *   console.log('用户登录:', data);
+     * });
+     * ```
+     */
+    public once<T extends Types = Types>(type: T, listener: FastEventListener<T, Events[T], Meta, Context>): FastEventSubscriber
+    public once<T extends string>(type: T, listener: FastEventListener<T, Events[T], Meta, Context>): FastEventSubscriber
     public once(): FastEventSubscriber {
         return this.on(arguments[0], arguments[1], { count: 1 })
     }
@@ -143,7 +236,7 @@ export class FastEvent<
      * subscriber.off();
      * ```
      */
-    onAny<P = any>(listener: FastEventListener<string, P, Meta>, options?: Pick<FastEventListenOptions, 'prepend'>): FastEventSubscriber {
+    onAny<P = any>(listener: FastEventListener<string, P, Meta, Context>, options?: Pick<FastEventListenOptions, 'prepend'>): FastEventSubscriber {
         const listeners = this.listeners.__listeners
         if (options && options.prepend) {
             listeners.splice(0, 0, listener)
@@ -210,9 +303,10 @@ export class FastEvent<
             if (entryNode) entryNode.__listeners = []
             this._removeRetainedEvents(entry)
         } else {
-            this._retainedEvents.clear()
+            this.retainedMessages.clear()
             this.listeners = { __listeners: [] } as unknown as FastListeners
         }
+        if (typeof (this._options.onClearListeners) === 'function') this._options.onClearListeners.call(this)
     }
 
     private _getListenerNode(parts: string[]): FastListenerNode | undefined {
@@ -230,14 +324,14 @@ export class FastEvent<
      * @private
      */
     private _removeRetainedEvents(prefix?: string) {
-        if (!prefix) this._retainedEvents.clear()
+        if (!prefix) this.retainedMessages.clear()
         if (prefix?.endsWith(this._delimiter)) {
             prefix += this._delimiter
         }
-        this._retainedEvents.delete(prefix!)
-        for (let key of this._retainedEvents.keys()) {
+        this.retainedMessages.delete(prefix!)
+        for (let key of this.retainedMessages.keys()) {
             if (key.startsWith(prefix!)) {
-                this._retainedEvents.delete(key)
+                this.retainedMessages.delete(key)
             }
         }
     }
@@ -252,8 +346,8 @@ export class FastEvent<
 
 
     private _emitForLastEvent(type: string) {
-        if (this._retainedEvents.has(type)) {
-            const message = this._retainedEvents.get(type)
+        if (this.retainedMessages.has(type)) {
+            const message = this.retainedMessages.get(type)
             const parts = type.split(this._delimiter);
             this._traverseToPath(this.listeners, parts, (node) => {
                 this._executeListeners(node, message)
@@ -324,6 +418,23 @@ export class FastEvent<
         traverseNodes(entryNode, callback, []);
     }
 
+    /**
+     * 执行单个监听器函数
+     * @param listener - 要执行的监听器函数或包装过的监听器对象
+     * @param message - 事件消息对象，包含type、payload和meta
+     * @returns 监听器的执行结果或错误对象（如果配置了ignoreErrors）
+     * @private
+     * 
+     * @description
+     * 执行单个监听器函数，处理以下情况：
+     * - 如果监听器是包装过的（有__wrappedListener属性），调用包装的函数
+     * - 否则直接调用监听器函数
+     * - 使用配置的上下文（_context）作为this
+     * - 捕获并处理执行过程中的错误：
+     *   - 如果有onListenerError回调，调用它
+     *   - 如果配置了ignoreErrors，返回错误对象
+     *   - 否则抛出错误
+     */
     private _executeListener(listener: any, message: FastEventMessage): any {
         try {
             if (typeof (listener.__wrappedListener) === 'function') {
@@ -395,11 +506,48 @@ export class FastEvent<
      * // 方式2: 对象形式
      * emit({ type: 'user.login', payload: { id: 1 } ,meta:{...}}}, true)
      */
+    /**
+     * 同步触发事件
+     * @param type - 事件类型，可以是字符串或预定义的事件类型
+     * @param payload - 事件数据负载
+     * @param retain - 是否保留该事件，用于后续新的订阅者
+     * @param meta - 事件元数据
+     * @returns 所有监听器的执行结果数组
+     * 
+     * @description
+     * 同步触发指定类型的事件，支持两种调用方式：
+     * 1. 参数形式：emit(type, payload, retain, meta)
+     * 2. 对象形式：emit({ type, payload, meta }, retain)
+     * 
+     * 特性：
+     * - 支持通配符匹配，一个事件可能触发多个监听器
+     * - 如果设置了retain为true，会保存最后一次的事件数据
+     * - 按照注册顺序同步调用所有匹配的监听器
+     * - 如果配置了ignoreErrors，监听器抛出的错误会被捕获并返回
+     * 
+     * @example
+     * ```ts
+     * // 简单事件触发
+     * emitter.emit('user/login', { userId: 123 });
+     * 
+     * // 带保留的事件触发
+     * emitter.emit('status/change', { online: true }, true);
+     * 
+     * // 带元数据的事件触发
+     * emitter.emit('data/update', newData, false, { timestamp: Date.now() });
+     * 
+     * // 使用对象形式触发
+     * emitter.emit({
+     *   type: 'user/login',
+     *   payload: { userId: 123 },
+     *   meta: { time: Date.now() }
+     * }, true);
+     * ```
+     */
     public emit<R = any>(type: string, payload?: any, retain?: boolean, meta?: Meta): R[]
     public emit<R = any>(type: Types, payload?: Events[Types], retain?: boolean, meta?: Meta): R[]
     public emit<R = any>(message: FastEventMessage<Types, Events[Types], Meta>, retain?: boolean): R[]
     public emit<R = any>(message: FastEventMessage<string, any, Meta>, retain?: boolean): R[]
-
     public emit<R = any>(): R[] {
         let type: string, payload: any, retain: boolean, meta: any
         if (typeof (arguments[0]) === 'object') {
@@ -420,17 +568,61 @@ export class FastEvent<
         }
         const parts = type.split(this._delimiter);
         if (retain) {
-            this._retainedEvents.set(type, message)
+            this.retainedMessages.set(type, message)
         }
         const results: any[] = []
         // onAny侦听器保存在根节点中，所以需要执行 
         results.push(...this._executeListeners(this.listeners, message))
         this._traverseToPath(this.listeners, parts, (node) => {
             results.push(...this._executeListeners(node, message))
+            // 用于调试时使用
+            if (this._options.debug && typeof (this._options.onExecuteListener) === 'function') {
+                if (retain) {
+                    if (!message.meta) message.meta = { retain: true }
+                }
+                this._options.onExecuteListener.call(this, message, results, [...this.listeners.__listeners, ...node.__listeners])
+            }
         })
+
         return results
     }
 
+    /**
+     * 异步触发事件
+     * @param type - 事件类型，可以是字符串或预定义的事件类型
+     * @param payload - 事件数据负载
+     * @param retain - 是否保留该事件，用于后续新的订阅者
+     * @param meta - 事件元数据
+     * @returns Promise，解析为所有监听器的执行结果数组
+     * 
+     * @description
+     * 异步触发指定类型的事件，与emit方法类似，但有以下区别：
+     * - 返回Promise，等待所有异步监听器执行完成
+     * - 使用Promise.allSettled处理监听器的执行结果
+     * - 即使某些监听器失败，也会等待所有监听器执行完成
+     * - 返回结果包含成功值或错误信息
+     * 
+     * @example
+     * ```ts
+     * // 异步事件处理
+     * const results = await emitter.emitAsync('data/process', rawData);
+     * 
+     * // 处理结果包含成功和失败的情况
+     * results.forEach(result => {
+     *   if (result instanceof Error) {
+     *     console.error('处理失败:', result);
+     *   } else {
+     *     console.log('处理成功:', result);
+     *   }
+     * });
+     * 
+     * // 带元数据的异步事件
+     * await emitter.emitAsync('batch/process', items, false, {
+     *   batchId: 'batch-001',
+     *   timestamp: Date.now()
+     * });
+     * ```
+     */
     public async emitAsync<R = any>(type: string, payload?: any, retain?: boolean, meta?: Meta): Promise<[R | Error][]>
     public async emitAsync<R = any>(type: Types, payload?: Events[Types], retain?: boolean, meta?: Meta): Promise<[R | Error][]>
     public async emitAsync<P = any>(): Promise<[P | Error][]> {
@@ -454,20 +646,41 @@ export class FastEvent<
     }
 
     /**
-     * 等待指定事件发生 
+     * 等待指定事件发生，返回一个Promise
+     * @param type - 要等待的事件类型
+     * @param timeout - 超时时间（毫秒），默认为0表示永不超时
+     * @returns Promise，解析为事件消息对象，包含type、payload和meta
+     * 
+     * @description
+     * 创建一个Promise，在指定事件发生时解析。
+     * - 当事件触发时，Promise会解析为事件消息对象
+     * - 如果设置了timeout且超时，Promise会被拒绝
+     * - 一旦事件发生或超时，会自动取消事件监听
+     * 
+     * @example
+     * ```ts
+     * try {
+     *   // 等待登录事件，最多等待5秒
+     *   const event = await emitter.waitFor('user/login', 5000);
+     *   console.log('用户登录成功:', event.payload);
+     * } catch (error) {
+     *   console.error('等待登录超时');
+     * }
      * 
-     * @param type 
-     * @param timeout  超时时间，单位毫秒，默认为 0，表示无限等待
+     * // 无限等待事件
+     * const event = await emitter.waitFor('server/ready');
+     * console.log('服务器就绪');
+     * ```
      */
-    public waitFor<R = any>(type: string, timeout?: number): Promise<R>
-    public waitFor<R = any>(type: Types, timeout?: number): Promise<R>
-    public waitFor<R = any>(): Promise<R> {
-        const type = arguments[0] as string
+    public waitFor<T extends Types, P = Events[T], M = Meta>(type: T, timeout?: number): Promise<FastEventMessage<T, P, M>>
+    public waitFor<T extends string, P = Events[T], M = Meta>(type: string, timeout?: number): Promise<FastEventMessage<T, P, M>>
+    public waitFor<T extends string, P = Events[T], M = Meta>(): Promise<FastEventMessage<T, P, M>> {
+        const type = arguments[0] as any
         const timeout = arguments[1] as number
-        return new Promise<R>((resolve, reject) => {
+        return new Promise<FastEventMessage<T, P, M>>((resolve, reject) => {
             let tid: any
             let subscriber: FastEventSubscriber
-            const listener = (message: any) => {
+            const listener = (message: FastEventMessage<T, P, M>) => {
                 clearTimeout(tid)
                 subscriber.off()
                 resolve(message)
@@ -478,30 +691,51 @@ export class FastEvent<
                     reject(new Error('wait for event<' + type + '> is timeout'))
                 }, timeout)
             }
-            subscriber = this.on(type, listener)
+            subscriber = this.on(type, listener as any)
         })
     }
 
     /**
-     * 创建事件域
+     * 创建一个新的事件作用域
+     * @param prefix - 作用域前缀，将自动添加到该作用域下所有事件名称前
+     * @returns 新的FastEventScope实例
+     * 
+     * @description
+     * 创建一个新的事件作用域，用于在特定命名空间下管理事件。
+     * 
+     * 重要特性：
+     * - 作用域与父事件发射器共享同一个监听器表
+     * - 作用域中的事件会自动添加前缀
+     * - 作用域的所有操作都会映射到父事件发射器上
+     * - 作用域不是完全隔离的，只是提供了事件名称的命名空间
      * 
-     * 注意：
+     * @example
+     * ```ts
+     * const emitter = new FastEvent();
      * 
-     *  事件域与当前事件对象共享相同的侦听器表
-     *  也就是说，如果在事件域中触发事件，当前事件对象也会触发该事件
-     *  两者工不是完全隔离的,仅是事件侦听和触发时的事件类型不同而已
+     * // 创建用户相关事件的作用域
+     * const userEvents = emitter.scope('user');
      * 
-     * const emitter = new FastEvent()
+     * // 在作用域中监听事件
+     * userEvents.on('login', (data) => {
+     *   // 实际监听的是 'user/login'
+     *   console.log('用户登录:', data);
+     * });
      * 
-     * const scope= emitter.scope("a/b")
+     * // 在作用域中触发事件
+     * userEvents.emit('login', { userId: 123 });
+     * // 等同于 emitter.emit('user/login', { userId: 123 })
      * 
-     * scope.on("x",()=>{})   == emitter.on("a/b/x",()=>{})
-     * scope.emit("x",1)      == emitter.emit("a/b/x",1) 
-     * scope.offAll()         == emitter.offAll("a/b")
+     * // 创建嵌套作用域
+     * const profileEvents = userEvents.scope('profile');
+     * profileEvents.emit('update', { name: 'John' });
+     * // 等同于 emitter.emit('user/profile/update', { name: 'John' })
      * 
+     * // 清理作用域
+     * userEvents.offAll();  // 清理 'user' 前缀下的所有事件
+     * ```
      */
     scope<T extends string>(prefix: T) {
         return new FastEventScope<ScopeEvents<Events, T>>(this as unknown as FastEvent<ScopeEvents<Events, T>>, prefix)
     }
-
 } 

package/src/scope.ts

@@ -4,6 +4,7 @@ import { FastEventListener, FastEventListenOptions, FastEventMessage, FastEvents
 export class FastEventScope<
     Events extends FastEvents = FastEvents,
     Meta extends Record<string, any> = Record<string, any>,
+    Context = any,
     Types extends keyof Events = keyof Events
 > {
     constructor(public emitter: FastEvent<Events, Meta, Types>, public prefix: string) {
@@ -29,10 +30,13 @@ export class FastEventScope<
     private _getScopeType(type: string) {
         return type === undefined ? undefined : this.prefix + type
     }
+    private _fixScopeType(type: string) {
+        return type.startsWith(this.prefix) ? type.substring(this.prefix.length) : type
+    }
 
-    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<T extends Types = Types>(type: T, listener: FastEventListener<T, Events[T], Meta, Context>, options?: FastEventListenOptions): FastEventSubscriber
+    public on<T extends string>(type: T, listener: FastEventListener<T, Events[T], Meta, Context>, options?: FastEventListenOptions): FastEventSubscriber
+    public on(type: '**', listener: FastEventListener<any, any, Meta, Context>): FastEventSubscriber
     public on(): FastEventSubscriber {
         const args = [...arguments] as [any, any, any]
         args[0] = this._getScopeType(args[0])
@@ -40,13 +44,13 @@ export class FastEventScope<
         return this.emitter.on(...args)
     }
 
-    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<T extends string>(type: T, listener: FastEventListener<T, Events[T], Meta, Context>, options?: FastEventListenOptions): FastEventSubscriber
+    public once<T extends Types = Types>(type: T, listener: FastEventListener<Types, Events[T], Meta, Context>, options?: FastEventListenOptions): FastEventSubscriber
     public once(): FastEventSubscriber {
         return this.on(arguments[0], arguments[1], Object.assign({}, arguments[2], { count: 1 }))
     }
 
-    onAny<P = any>(listener: FastEventListener<Types, P, Meta>, options?: FastEventListenOptions): FastEventSubscriber {
+    onAny<P = any>(listener: FastEventListener<Types, P, Meta, Context>, options?: FastEventListenOptions): FastEventSubscriber {
         const type = this.prefix + '**'
         return this.on(type as any, listener, options)
     }
@@ -68,21 +72,58 @@ export class FastEventScope<
     clear() {
         this.offAll()
     }
-    public emit<R = any>(type: string, payload?: any, retain?: boolean): R[]
+
     public emit<R = any>(type: Types, payload?: Events[Types], retain?: boolean): R[]
+    public emit<R = any>(type: string, payload?: any, retain?: boolean): R[]
     public emit<R = any>(): R[] {
         const type = arguments[0] as string
         const payload = arguments[1]
         const retain = arguments[2] as boolean
         return this.emitter.emit(this._getScopeType(type)!, payload, retain)
     }
-    public waitFor<R = any>(type: string, timeout?: number): Promise<R>
-    public waitFor<R = any>(type: Types, timeout?: number): Promise<R>
-    public waitFor<R = any>(): Promise<R> {
+    public async waitFor<T extends Types, P = Events[T], M = Meta>(type: T, timeout?: number): Promise<FastEventMessage<T, P, M>>
+    public async waitFor<T extends string, P = Events[T], M = Meta>(type: string, timeout?: number): Promise<FastEventMessage<T, P, M>>
+    public async waitFor<T extends string, P = Events[T], M = Meta>(): Promise<FastEventMessage<T, P, M>> {
         const type = arguments[0] as string
         const timeout = arguments[1] as number
-        return this.emitter.waitFor(this._getScopeType(type)!, timeout)
+        const message = await this.emitter.waitFor(this._getScopeType(type)!, timeout)
+        const scopeMessage = Object.assign({}, message, {
+            type: this._fixScopeType(message.type)
+        })
+        return scopeMessage as unknown as FastEventMessage<T, P, M>
     }
+    /**
+     * 创建一个新的作用域实例
+     * @param prefix - 作用域前缀
+     * @returns 新的FastEventScope实例
+     * 
+     * @description
+     * 基于当前作用域创建一个新的子作用域。新作用域会继承当前作用域的所有特性，
+     * 并在事件类型前添加额外的前缀。这允许创建层级化的事件命名空间。
+     * 
+     * 作用域的特性：
+     * - 自动为所有事件类型添加前缀
+     * - 在触发事件时自动添加前缀
+     * - 在接收事件时自动移除前缀
+     * - 支持多层级的作用域嵌套
+     * 
+     * @example
+     * ```ts
+     * const emitter = new FastEvent();
+     * const userScope = emitter.scope('user');
+     * const profileScope = userScope.scope('profile');
+     * 
+     * // 在profileScope中监听'update'事件
+     * // 实际监听的是'user/profile/update'
+     * profileScope.on('update', (data) => {
+     *   console.log('Profile updated:', data);
+     * });
+     * 
+     * // 在profileScope中触发'update'事件
+     * // 实际触发的是'user/profile/update'
+     * profileScope.emit('update', { name: 'John' });
+     * ```
+     */
     public scope(prefix: string) {
         return this.emitter.scope(this._getScopeType(prefix)!)
     }

package/src/types.ts

@@ -11,8 +11,9 @@ export type FastEventMessage<T = string, P = any, M = unknown> = {
 export type FastEventListener<
     T = string,
     P = any,
-    M = unknown
-> = (message: FastEventMessage<T, P, M>) => any | Promise<any>
+    M = unknown,
+    C = any
+> = (this: C, message: FastEventMessage<T, P, M>) => any | Promise<any>
 
 export type FastListenerNode = {
     __listeners: (FastEventListener<any, any, any> | [FastEventListener<any, any>, number])[];
@@ -30,7 +31,9 @@ export interface FastEventListenerMeta {
 
 export type FastListeners = FastListenerNode
 
-export type FastEventOptions<M = unknown> = {
+export type FastEventOptions<M = Record<string, any>> = {
+    id?: string
+    debug?: boolean
     // 事件分隔符
     delimiter?: string
     // 侦听器函数执行上下文
@@ -45,10 +48,14 @@ export type FastEventOptions<M = unknown> = {
     onAddListener?: (type: string[], listener: FastEventListener) => void
     // 当移除侦听器时回调
     onRemoveListener?: (type: string[], listener: FastEventListener) => void
+    // 当清空侦听器时回调
+    onClearListeners?: () => void
+    // 当执行侦听器后时回调
+    onExecuteListener?: (message: FastEventMessage, returns: any[], listeners: (FastEventListener<any, any, any> | [FastEventListener<any, any>, number])[]) => void
 }
 
-export type FastEvents = Record<string, any>
 
+export type FastEvents = Record<string, any>
 
 export type ScopeEvents<T extends Record<string, any>, Prefix extends string> = {
     [K in keyof T as K extends `${Prefix}/${infer Rest}` ? Rest : never]: T[K];

package/src/utils/WeakObjectMap.ts

@@ -0,0 +1,64 @@
+/**
+ * 一个基于弱引用（WeakRef）的键值映射集合
+ * 
+ * @template T - 值的类型，必须是对象类型（继承自 `object`）
+ * 
+ * @example
+ * const map = new WeakObjectMap<MyObject>();
+ * map.set('key1', obj1);
+ * const retrieved = map.get('key1'); // 返回 obj1 或 undefined（如果已被垃圾回收）
+ */
+export class WeakObjectMap<T extends object> {
+    private map: Map<string, WeakRef<T>>;
+    private finalizationRegistry: FinalizationRegistry<string>;
+  
+    /**
+     * 构造一个新的 WeakObjectMap 实例
+     */
+    constructor() {
+      this.map = new Map();
+      this.finalizationRegistry = new FinalizationRegistry((key) => {
+        this.map.delete(key);
+      });
+    }
+  
+    /**
+     * 设置键值对
+     * @param key - 字符串键名
+     * @param value - 要存储的对象值（会被自动包装为弱引用）
+     */
+    set(key: string, value: T): void {
+      const weakRef = new WeakRef(value);
+      this.map.set(key, weakRef);
+      this.finalizationRegistry.register(value, key);
+    }
+  
+    /**
+     * 获取指定键对应的值
+     * @param key - 要查找的键名
+     * @returns 如果值存在且未被垃圾回收则返回值，否则返回 undefined
+     */
+    get(key: string): T | undefined {
+      const weakRef = this.map.get(key);
+      return weakRef ? weakRef.deref() : undefined;
+    }
+  
+    /**
+     * 删除指定键的映射
+     * @param key - 要删除的键名
+     * @returns 如果键存在并已删除则返回 true，否则返回 false
+     */
+    delete(key: string): boolean {
+      return this.map.delete(key);
+    }
+  
+    /**
+     * 检查是否存在指定键的映射（且值未被垃圾回收）
+     * @param key - 要检查的键名
+     * @returns 如果键存在且值未被回收则返回 true，否则返回 false
+     */
+    has(key: string): boolean {
+      const weakRef = this.map.get(key);
+      return weakRef ? weakRef.deref() !== undefined : false;
+    }
+}