fastevent 1.1.2 → 2.0.0

package/dist/index.d.mts

@@ -1,67 +1,188 @@
-type FastEventMessage<T = string, P = any, M = unknown> = {
-    type: T;
-    payload: P;
-    meta: M;
-};
-type FastEventListener<T = string, P = any, M = unknown, C = any> = (this: C, message: FastEventMessage<T, P, M>) => any | Promise<any>;
+type FastListenerPipe = (listener: FastEventListener) => FastEventListener;
+
+interface FaseEventMessageExtends {
+}
+interface FastEventMeta {
+    priority?: number;
+}
+type FastEventMessage<Events extends Record<string, any> = Record<string, any>, M = any> = ({
+    [K in keyof Events]: {
+        type: Exclude<K, number | symbol>;
+        payload: Events[K];
+        meta: FastEventMeta & M & Record<string, any>;
+    };
+}[Exclude<keyof Events, number | symbol>]) & FaseEventMessageExtends;
+type FastEventEmitMessage<Events extends Record<string, any> = Record<string, any>, M = any> = ({
+    [K in keyof Events]: {
+        type: Exclude<K, number | symbol>;
+        payload?: Events[K];
+        meta?: FastEventMeta & M & Record<string, any>;
+    };
+}[Exclude<keyof Events, number | symbol>]) & FaseEventMessageExtends;
+type FastEventListener<T extends string = string, P = any, M = any, C = any> = (this: C, message: FastEventMessage<{
+    [K in T]: P;
+}, M>, args: FastEventListenerArgs<M>) => any | Promise<any>;
+type FastEventAnyListener<Events extends Record<string, any> = Record<string, any>, Meta = never, Context = any> = (this: Context, message: FastEventMessage<Events, Meta>, args: FastEventListenerArgs<Meta>) => any | Promise<any>;
+/**
+ * [监听器函数引用，需要执行多少次，实际执行的次数(用于负载均衡时记录)]
+ */
+type FastListenerMeta = [FastEventListener<any, any>, number, number];
 type FastListenerNode = {
-    __listeners: (FastEventListener<any, any, any> | [FastEventListener<any, any>, number])[];
+    __listeners: FastListenerMeta[];
 } & {
     [key: string]: FastListenerNode;
 };
 type FastEventSubscriber = {
     off: () => void;
+    /**
+     * 为什么要有一个listener引用? 主要用于移除侦听器时使用
+     *
+     *  - 正常情况下
+     *  const subscriber = emitter.on('event', listener)
+     *
+     *  subscriber.off()
+     *  emitter.off('event', listener)
+     *  emitter.off(listener)
+     *
+     *  - 在使用scope时
+     *  const scope = emitter.scope("xxx")
+     *  const subscriber = scope.on('event', listener)
+     *
+     *  subscriber.off()        可以正常生效
+     *  scope.off('event', listener)    // 无法生效
+     *  scope.off(listener) // 无法生效
+     *  因为在scope中，为了让侦听器可以处理scope的逻辑，对listener进行了包装，
+     *  因此在事件注册表中登记的不是listener，而是经过包装的侦听器
+     *  subscriber.off()        可以正常生效
+     *  如果要使用scope.off或emitter.off
+     *  需要使用subscriber.listener， subscriber.listener记录了原始的侦听器引用
+     *   subscriber.listener===listener
+     *
+     *  scope.off('event', subscriber.listener)    // 生效
+     *  scope.off(subscriber.listener) // 生效
+     *
+     */
+    listener: FastEventListener<any, any, any>;
 };
-interface FastEventListenerMeta {
-    emitter?: string;
-}
 type FastListeners = FastListenerNode;
-type FastEventOptions<M = Record<string, any>> = {
+type FastEventOptions<Meta = Record<string, any>, Context = any> = {
     id?: string;
     debug?: boolean;
     delimiter?: string;
-    context?: any;
+    context?: Context;
     ignoreErrors?: boolean;
-    onListenerError?: ((type: string, error: Error) => void);
-    meta?: M;
+    meta?: Meta;
     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;
+    onListenerError?: ((listener: FastEventListener, error: Error, message: FastEventMessage<any, Meta>, args: FastEventListenerArgs<Meta> | undefined) => void);
+    onBeforeExecuteListener?: (message: FastEventMessage<any, Meta>, args: FastEventListenerArgs<Meta>) => boolean | void;
+    onAfterExecuteListener?: (message: FastEventMessage<any, Meta>, returns: any[], listeners: FastListenerNode[]) => void;
+    /**
+     * 全局执行器
+     * allSettled: 使用Promise.allSettled()执行所有监听器
+     * race: 使用Promise.race()执行所有监听器，只有第一个执行完成就返回,其他监听器执行结果会被忽略
+     * balance: 尽可能平均执行各个侦听器
+     * sequence: 按照侦听器添加顺序依次执行
+     */
+    executor?: FastListenerExecutorArgs;
 };
-type FastEvents = Record<string, any>;
-type ScopeEvents<T extends Record<string, any>, Prefix extends string> = {
+interface FastEvents {
+}
+type PickScopeEvents<T extends Record<string, any>, Prefix extends string> = {
     [K in keyof T as K extends `${Prefix}/${infer Rest}` ? Rest : never]: T[K];
 };
-type FastEventListenOptions = {
+type ScopeEvents<T extends Record<string, any>, Prefix extends string> = PickScopeEvents<T, Prefix>;
+type FastEventListenOptions<Events extends Record<string, any> = Record<string, any>, Meta = any> = {
     count?: number;
     prepend?: boolean;
+    filter?: (message: FastEventMessage<Events, Meta>, args: FastEventListenerArgs<Meta>) => boolean;
+    off?: (message: FastEventMessage<Events, Meta>, args: FastEventListenerArgs<Meta>) => boolean;
+    pipes?: FastListenerPipe[];
+};
+type FastListenerExecutorArgs = 'default' | 'allSettled' | 'race' | 'balance' | 'first' | 'last' | 'random' | IFastListenerExecutor;
+type FastEventListenerArgs<M = Record<string, any>> = {
+    retain?: boolean;
+    meta?: Partial<M> & Record<string, any>;
+    abortSignal?: AbortSignal;
+    /**
+     *
+     * allSettled: 使用Promise.allSettled()执行所有监听器
+     * race: 使用Promise.race()执行所有监听器，只有第一个执行完成就返回,其他监听器执行结果会被忽略
+     * balance: 尽可能平均执行各个侦听器
+     * sequence: 按照侦听器添加顺序依次执行
+     */
+    executor?: FastListenerExecutorArgs;
+};
+type Merge<T extends object, U extends object> = {
+    [K in keyof T | keyof U]: K extends keyof U ? U[K] : K extends keyof T ? T[K] : never;
 };
+type RequiredItems<T extends object, Items extends string[]> = Omit<T, Items[number]> & {
+    [K in Items[number] & keyof T]-?: Exclude<T[K], undefined>;
+};
+type Fallback<T, F> = [
+    T
+] extends [never] ? F : T extends undefined ? F : T;
+type IFastListenerExecutor = (listeners: FastListenerMeta[], message: FastEventMessage, args: FastEventListenerArgs | undefined, execute: (listener: FastEventListener, message: FastEventMessage, args?: FastEventListenerArgs) => Promise<any> | any) => Promise<any[]> | any[];
 
-declare class FastEventScope<Events extends FastEvents = FastEvents, Meta extends Record<string, any> = Record<string, any>, Context = any, Types extends keyof Events = keyof Events> {
-    emitter: FastEvent<Events, Meta, Types>;
+type FastEventScopeOptions<Meta, Context> = {
+    meta?: FastEventMeta & Meta;
+    context?: Context;
+    executor?: FastListenerExecutorArgs;
+};
+type FastEventScopeMeta = {
+    scope: string;
+};
+declare class FastEventScope<Events extends Record<string, any> = Record<string, any>, Meta extends Record<string, any> = Record<string, any>, Context = any, Types extends keyof Events = keyof Events, FinalMeta extends Record<string, any> = Meta & FastEventScopeMeta> {
+    emitter: FastEvent<Events>;
     prefix: string;
-    constructor(emitter: FastEvent<Events, Meta, Types>, prefix: string);
+    options: Required<FastEventScopeOptions<FinalMeta, Context>>;
+    events: Events;
+    constructor(emitter: FastEvent<Events>, prefix: string, options?: FastEventScopeOptions<Meta, Context>);
+    get context(): Context;
+    /**
+     * 获取作用域监听器
+     * 当启用作用域时,对原始监听器进行包装,添加作用域前缀处理逻辑
+     * @param listener 原始事件监听器
+     * @returns 包装后的作用域监听器
+     * @private
+     */
     private _getScopeListener;
     private _getScopeType;
     private _fixScopeType;
-    on<T extends Types = Types>(type: T, listener: FastEventListener<T, Events[T], Meta, Context>, options?: FastEventListenOptions): FastEventSubscriber;
-    on<T extends string>(type: T, listener: FastEventListener<T, Events[T], Meta, Context>, options?: FastEventListenOptions): FastEventSubscriber;
-    on(type: '**', listener: FastEventListener<any, any, Meta, Context>): FastEventSubscriber;
-    once<T extends string>(type: T, listener: FastEventListener<T, Events[T], Meta, Context>, options?: FastEventListenOptions): FastEventSubscriber;
-    once<T extends Types = Types>(type: T, listener: FastEventListener<Types, Events[T], Meta, Context>, options?: FastEventListenOptions): FastEventSubscriber;
-    onAny<P = any>(listener: FastEventListener<Types, P, Meta, Context>, options?: FastEventListenOptions): FastEventSubscriber;
-    offAll(): void;
+    on<T extends Types = Types>(type: T, listener: FastEventListener<Exclude<T, number | symbol>, Events[T], FinalMeta, Context>, options?: FastEventListenOptions): FastEventSubscriber;
+    on<T extends string>(type: T, listener: FastEventListener<string, any, FinalMeta, Context>, options?: FastEventListenOptions): FastEventSubscriber;
+    on(type: '**', listener: FastEventAnyListener<Events, FinalMeta, Context>, options?: FastEventListenOptions): FastEventSubscriber;
+    once<T extends Types = Types>(type: T, listener: FastEventListener<Exclude<T, number | symbol>, Events[T], FinalMeta, Context>, options?: FastEventListenOptions): FastEventSubscriber;
+    once<T extends string>(type: T, listener: FastEventListener<string, any, FinalMeta, Context>, options?: FastEventListenOptions): FastEventSubscriber;
+    onAny<P = any>(listener: FastEventAnyListener<{
+        [K: string]: P;
+    }, FinalMeta, Context>, options?: Pick<FastEventListenOptions, 'prepend'>): FastEventSubscriber;
     off(listener: FastEventListener<any, any, any>): void;
     off(type: string, listener: FastEventListener<any, any, any>): void;
     off(type: Types, listener: FastEventListener<any, any, any>): void;
     off(type: string): void;
     off(type: Types): void;
+    offAll(): void;
     clear(): void;
-    emit<R = any>(type: Types, payload?: Events[Types], retain?: boolean): R[];
-    emit<R = any>(type: string, payload?: any, retain?: boolean): R[];
-    waitFor<T extends Types, P = Events[T], M = Meta>(type: T, timeout?: number): Promise<FastEventMessage<T, P, M>>;
-    waitFor<T extends string, P = Events[T], M = Meta>(type: string, timeout?: number): Promise<FastEventMessage<T, P, M>>;
+    emit<R = any>(type: Types, payload?: Events[Types], options?: FastEventListenerArgs<FinalMeta>): R[];
+    emit<R = any, T extends string = string>(type: T, payload?: T extends Types ? Events[Types] : any, options?: FastEventListenerArgs<FinalMeta>): R[];
+    emit<R = any>(message: FastEventEmitMessage<Events, FinalMeta>, options?: FastEventListenerArgs<FinalMeta>): R[];
+    emit<R = any, T extends string = string>(message: FastEventEmitMessage<{
+        [K in T]: K extends Types ? Events[K] : any;
+    }, FinalMeta>, options?: FastEventListenerArgs<FinalMeta>): R[];
+    emitAsync<R = any>(type: string, payload?: any, options?: FastEventListenerArgs<FinalMeta>): Promise<[R | Error][]>;
+    emitAsync<R = any>(type: Types, payload?: Events[Types], options?: FastEventListenerArgs<FinalMeta>): Promise<[R | Error][]>;
+    emitAsync<R = any>(message: FastEventMessage<Events, FinalMeta>, options?: FastEventListenerArgs<FinalMeta>): Promise<[R | Error][]>;
+    waitFor<T extends Types>(type: T, timeout?: number): Promise<FastEventMessage<{
+        [key in T]: Events[T];
+    }, FinalMeta>>;
+    waitFor(type: string, timeout?: number): Promise<FastEventMessage<{
+        [key: string]: any;
+    }, FinalMeta>>;
+    waitFor<P = any>(type: string, timeout?: number): Promise<FastEventMessage<{
+        [key: string]: P;
+    }, FinalMeta>>;
     /**
      * 创建一个新的作用域实例
      * @param prefix - 作用域前缀
@@ -94,7 +215,7 @@ declare class FastEventScope<Events extends FastEvents = FastEvents, Meta extend
      * profileScope.emit('update', { name: 'John' });
      * ```
      */
-    scope(prefix: string): FastEventScope<ScopeEvents<Events, string>, Record<string, any>, any, keyof ScopeEvents<Events, string>>;
+    scope<E extends Record<string, any> = Record<string, any>, P extends string = string, M extends Record<string, any> = Record<string, any>, C = Context>(prefix: P, options?: FastEventScopeOptions<Partial<FinalMeta> & M, C>): FastEventScope<PickScopeEvents<Events, P> & E, FinalMeta & M, C, keyof PickScopeEvents<Events, P> | keyof E, FinalMeta & M & FastEventScopeMeta>;
 }
 
 /**
@@ -104,7 +225,7 @@ declare class FastEventScope<Events extends FastEvents = FastEvents, Meta extend
  * @template Meta - 事件元数据类型，默认为任意键值对对象
  * @template Types - 事件类型的键名类型，默认为Events的键名类型
  */
-declare class FastEvent<Events extends FastEvents = FastEvents, Meta extends Record<string, any> = Record<string, any>, Context = any, Types extends keyof Events = keyof Events> {
+declare class FastEvent<Events extends Record<string, any> = Record<string, any>, Meta extends Record<string, any> = Record<string, any>, Context = never, AllEvents extends Record<string, any> = Events & FastEvents, Types extends keyof AllEvents = Exclude<keyof (AllEvents), number | symbol>> {
     /** 事件监听器树结构，存储所有注册的事件监听器 */
     listeners: FastListeners;
     /** 事件发射器的配置选项 */
@@ -117,6 +238,7 @@ declare class FastEvent<Events extends FastEvents = FastEvents, Meta extends Rec
     retainedMessages: Map<string, any>;
     /** 当前注册的监听器总数 */
     listenerCount: number;
+    events: Events;
     /**
      * 创建FastEvent实例
      * @param options - 事件发射器的配置选项
@@ -128,9 +250,10 @@ declare class FastEvent<Events extends FastEvents = FastEvents, Meta extends Rec
      * - context: null - 监听器执行上下文
      * - ignoreErrors: true - 是否忽略监听器执行错误
      */
-    constructor(options?: FastEventOptions<Meta>);
+    constructor(options?: FastEventOptions<Meta, Context>);
     /** 获取事件发射器的配置选项 */
-    get options(): FastEventOptions;
+    get options(): RequiredItems<FastEventOptions<Meta, Context>, ["meta", "context"]>;
+    get context(): Context;
     /** 获取事件发射器的唯一标识符 */
     get id(): string;
     private _addListener;
@@ -152,6 +275,7 @@ declare class FastEvent<Events extends FastEvents = FastEvents, Meta extends Rec
      * @description 遍历节点的监听器列表,移除所有匹配的监听器。支持移除普通函数和数组形式的监听器
      */
     private _removeListener;
+    private _pipeListener;
     /**
      * 注册事件监听器
      * @param type - 事件类型，支持以下格式：
@@ -176,9 +300,12 @@ declare class FastEvent<Events extends FastEvents = FastEvents, Meta extends Rec
      * emitter.on('event', handler, { count: 3 });
      * ```
      */
-    on<T extends string>(type: T, listener: FastEventListener<T, Events[T], Meta, Context>, options?: FastEventListenOptions): FastEventSubscriber;
-    on<T extends Types = Types>(type: T, listener: FastEventListener<Types, Events[T], Meta, Context>, options?: FastEventListenOptions): FastEventSubscriber;
-    on<P = any>(type: '**', listener: FastEventListener<Types, P, Meta, Context>): FastEventSubscriber;
+    on<T extends Types = Types>(type: T, options?: FastEventListenOptions<AllEvents, Meta>): FastEventSubscriber;
+    on<T extends string>(type: T, options?: FastEventListenOptions<AllEvents, Meta>): FastEventSubscriber;
+    on(type: '**', options?: FastEventListenOptions<AllEvents, Meta>): FastEventSubscriber;
+    on<T extends Types = Types>(type: T, listener: FastEventListener<Exclude<T, number | symbol>, AllEvents[T], Meta, Fallback<Context, typeof this>>, options?: FastEventListenOptions<AllEvents, Meta>): FastEventSubscriber;
+    on<T extends string>(type: T, listener: FastEventAnyListener<AllEvents, Meta, Fallback<Context, typeof this>>, options?: FastEventListenOptions<AllEvents, Meta>): FastEventSubscriber;
+    on(type: '**', listener: FastEventAnyListener<Record<string, any>, Meta, Fallback<Context, typeof this>>, options?: FastEventListenOptions<AllEvents, Meta>): FastEventSubscriber;
     /**
      * 注册一次性事件监听器
      * @param type - 事件类型，支持与on方法相同的格式：
@@ -200,8 +327,10 @@ declare class FastEvent<Events extends FastEvents = FastEvents, Meta extends Rec
      * });
      * ```
      */
-    once<T extends Types = Types>(type: T, listener: FastEventListener<T, Events[T], Meta, Context>): FastEventSubscriber;
-    once<T extends string>(type: T, listener: FastEventListener<T, Events[T], Meta, Context>): FastEventSubscriber;
+    once<T extends Types = Types>(type: T, options?: FastEventListenOptions<AllEvents, Meta>): FastEventSubscriber;
+    once<T extends string>(type: T, options?: FastEventListenOptions<AllEvents, Meta>): FastEventSubscriber;
+    once<T extends Types = Types>(type: T, listener: FastEventListener<Exclude<T, number | symbol>, AllEvents[T], Meta, Fallback<Context, typeof this>>, options?: FastEventListenOptions<AllEvents, Meta>): FastEventSubscriber;
+    once<T extends string>(type: T, listener: FastEventAnyListener<AllEvents, Meta, Fallback<Context, typeof this>>, options?: FastEventListenOptions<AllEvents, Meta>): FastEventSubscriber;
     /**
      * 注册一个监听器，用于监听所有事件
      * @param listener 事件监听器函数，可以接收任意类型的事件数据
@@ -214,9 +343,18 @@ declare class FastEvent<Events extends FastEvents = FastEvents, Meta extends Rec
      *
      * // 取消监听
      * subscriber.off();
-     * ```
+     * ```listener: FastEventAnyListener<AllEvents, Meta, Fallback<Context, typeof this>>): FastEventSubscriber
+     */
+    onAny(options?: Omit<FastEventListenOptions<AllEvents, Meta>, 'count'>): FastEventSubscriber;
+    onAny<P = any>(listener: FastEventAnyListener<Record<string, P>, Meta, Fallback<Context, typeof this>>, options?: Omit<FastEventListenOptions<AllEvents, Meta>, 'count'>): FastEventSubscriber;
+    /**
+     *
+     * 当调用on/once/onAny时如果没有指定监听器，则调用此方法
+     *
+     * 此方法供子类继承
+     *
      */
-    onAny<P = any>(listener: FastEventListener<string, P, Meta, Context>, options?: Pick<FastEventListenOptions, 'prepend'>): FastEventSubscriber;
+    onMessage(message: FastEventMessage): void;
     off(listener: FastEventListener<any, any, any>): void;
     off(type: string, listener: FastEventListener<any, any, any>): void;
     off(type: Types, listener: FastEventListener<any, any, any>): void;
@@ -230,7 +368,7 @@ declare class FastEvent<Events extends FastEvents = FastEvents, Meta extends Rec
      * - 如果没有提供prefix,则清除所有监听器
      * - 同时会清空保留的事件(_retainedEvents)
      * - 重置监听器对象为空
-
+ 
     * @example
      *
      * ```ts
@@ -239,7 +377,6 @@ declare class FastEvent<Events extends FastEvents = FastEvents, Meta extends Rec
      *
      */
     offAll(entry?: string): void;
-    private _getListenerNode;
     /**
      * 移除保留的事件
      * @param prefix - 事件前缀。如果不提供，将清除所有保留的事件。
@@ -248,8 +385,7 @@ declare class FastEvent<Events extends FastEvents = FastEvents, Meta extends Rec
      * @private
      */
     private _removeRetainedEvents;
-    clear(): void;
-    private _createMeta;
+    clear(prefix?: string): void;
     private _emitForLastEvent;
     /**
      * 遍历监听器节点树
@@ -267,6 +403,7 @@ declare class FastEvent<Events extends FastEvents = FastEvents, Meta extends Rec
      */
     private _traverseToPath;
     private _traverseListeners;
+    private _onListenerError;
     /**
      * 执行单个监听器函数
      * @param listener - 要执行的监听器函数或包装过的监听器对象
@@ -285,6 +422,13 @@ declare class FastEvent<Events extends FastEvents = FastEvents, Meta extends Rec
      *   - 否则抛出错误
      */
     private _executeListener;
+    private _getListenerExecutor;
+    /**
+     * 触发事件并执行对应的监听器
+     * @param type - 事件类型字符串或包含事件信息的对象
+     * @param payload - 事件携带的数据负载
+        return
+    }
     /**
      * 执行监听器节点中的所有监听函数
      * @param node - FastListenerNode类型的监听器节点
@@ -353,10 +497,18 @@ declare class FastEvent<Events extends FastEvents = FastEvents, Meta extends Rec
      * }, true);
      * ```
      */
-    emit<R = any>(type: string, payload?: any, retain?: boolean, meta?: Meta): R[];
-    emit<R = any>(type: Types, payload?: Events[Types], retain?: boolean, meta?: Meta): R[];
-    emit<R = any>(message: FastEventMessage<Types, Events[Types], Meta>, retain?: boolean): R[];
-    emit<R = any>(message: FastEventMessage<string, any, Meta>, retain?: boolean): R[];
+    emit<R = any, T extends Types = Types>(type: T, payload?: AllEvents[T], retain?: boolean): R[];
+    emit<R = any, T extends string = string>(type: T, payload?: T extends Types ? AllEvents[Types] : any, retain?: boolean): R[];
+    emit<R = any, T extends string = string>(message: FastEventEmitMessage<{
+        [K in T]: K extends Types ? AllEvents[K] : any;
+    }, Meta>, retain?: boolean): R[];
+    emit<R = any>(message: FastEventEmitMessage<AllEvents, Meta>, retain?: boolean): R[];
+    emit<R = any, T extends Types = Types>(type: T, payload?: AllEvents[T], options?: FastEventListenerArgs<Meta>): R[];
+    emit<R = any, T extends string = string>(type: T, payload?: T extends Types ? AllEvents[Types] : any, options?: FastEventListenerArgs<Meta>): R[];
+    emit<R = any, T extends string = string>(message: FastEventEmitMessage<{
+        [K in T]: K extends Types ? AllEvents[K] : any;
+    }, Meta>, options?: FastEventListenerArgs<Meta>): R[];
+    emit<R = any>(message: FastEventEmitMessage<AllEvents, Meta>, options?: FastEventListenerArgs<Meta>): R[];
     /**
      * 异步触发事件
      * @param type - 事件类型，可以是字符串或预定义的事件类型
@@ -393,8 +545,18 @@ declare class FastEvent<Events extends FastEvents = FastEvents, Meta extends Rec
      * });
      * ```
      */
-    emitAsync<R = any>(type: string, payload?: any, retain?: boolean, meta?: Meta): Promise<[R | Error][]>;
-    emitAsync<R = any>(type: Types, payload?: Events[Types], retain?: boolean, meta?: Meta): Promise<[R | Error][]>;
+    emitAsync<R = any>(type: string, payload?: any, retain?: boolean): Promise<[R | Error][]>;
+    emitAsync<R = any>(type: Types, payload?: AllEvents[Types], retain?: boolean): Promise<[R | Error][]>;
+    emitAsync<R = any, T extends string = string>(message: FastEventEmitMessage<{
+        [K in T]: K extends Types ? AllEvents[K] : any;
+    }, Meta>, retain?: boolean): Promise<[R | Error][]>;
+    emitAsync<R = any>(message: FastEventEmitMessage<AllEvents, Meta>, retain?: boolean): Promise<[R | Error][]>;
+    emitAsync<R = any>(type: string, payload?: any, options?: FastEventListenerArgs<Meta>): Promise<[R | Error][]>;
+    emitAsync<R = any>(type: Types, payload?: AllEvents[Types], options?: FastEventListenerArgs<Meta>): Promise<[R | Error][]>;
+    emitAsync<R = any, T extends string = string>(message: FastEventEmitMessage<{
+        [K in T]: K extends Types ? AllEvents[K] : any;
+    }, Meta>, options?: FastEventListenerArgs<Meta>): Promise<[R | Error][]>;
+    emitAsync<R = any>(message: FastEventEmitMessage<AllEvents, Meta>, options?: FastEventListenerArgs<Meta>): Promise<[R | Error][]>;
     /**
      * 等待指定事件发生，返回一个Promise
      * @param type - 要等待的事件类型
@@ -422,8 +584,13 @@ declare class FastEvent<Events extends FastEvents = FastEvents, Meta extends Rec
      * console.log('服务器就绪');
      * ```
      */
-    waitFor<T extends Types, P = Events[T], M = Meta>(type: T, timeout?: number): Promise<FastEventMessage<T, P, M>>;
-    waitFor<T extends string, P = Events[T], M = Meta>(type: string, timeout?: number): Promise<FastEventMessage<T, P, M>>;
+    waitFor<T extends Types>(type: T, timeout?: number): Promise<FastEventMessage<{
+        [key in T]: AllEvents[T];
+    }, Meta>>;
+    waitFor(type: string, timeout?: number): Promise<FastEventMessage<AllEvents, Meta>>;
+    waitFor<P = any>(type: string, timeout?: number): Promise<FastEventMessage<{
+        [key: string]: P;
+    }, Meta>>;
     /**
      * 创建一个新的事件作用域
      * @param prefix - 作用域前缀，将自动添加到该作用域下所有事件名称前
@@ -464,7 +631,69 @@ declare class FastEvent<Events extends FastEvents = FastEvents, Meta extends Rec
      * userEvents.offAll();  // 清理 'user' 前缀下的所有事件
      * ```
      */
-    scope<T extends string>(prefix: T): FastEventScope<ScopeEvents<Events, T>, Record<string, any>, any, keyof ScopeEvents<Events, T>>;
+    scope<E extends Record<string, any> = Record<string, any>, P extends string = string, M extends Record<string, any> = Record<string, any>, C = Context>(prefix: P, options?: FastEventScopeOptions<M, C>): FastEventScope<PickScopeEvents<AllEvents, P> & E, Meta & M, C, keyof PickScopeEvents<AllEvents, P> | keyof E, Meta & M & FastEventScopeMeta>;
+}
+
+interface FastEventListenerDecorators {
+    queue: string;
+}
+type FastQueuePriority = 'none';
+type FastQueueOverflows = "drop" | "expand" | 'slide' | 'throw';
+type QueueListenerPipeOptions = {
+    size?: number;
+    maxExpandSize?: number;
+    expandOverflow?: Omit<FastQueueOverflows, 'expand'>;
+    overflow?: FastQueueOverflows;
+    onNew?: (newMessage: FastEventMessage, messages: FastEventMessage[]) => void;
+};
+declare const queue: (options?: QueueListenerPipeOptions) => FastListenerPipe;
+declare const dropping: (size?: number) => FastListenerPipe;
+declare const sliding: (size?: number) => FastListenerPipe;
+declare const expanding: (options?: Omit<QueueListenerPipeOptions, "overflow">) => FastListenerPipe;
+
+/**
+ * 创建一个超时装饰器，限制监听器函数的执行时间
+ * @param ms 超时时间（毫秒）
+ * @param defaultValue 可选的默认返回值，如果提供则超时时返回此值，否则抛出TimeoutError
+ * @returns 装饰器函数
+ */
+declare const timeout: <T = any>(ms: number, defaultValue?: T) => FastListenerPipe;
+
+interface DebounceOptions {
+    /**
+     * 当消息被丢弃时的回调函数
+     */
+    drop?: (message: FastEventMessage) => void;
+}
+/**
+ * 创建一个防抖动装饰器，限制监听器函数的执行频率
+ * @param ms 防抖动时间（毫秒）
+ * @param options 可选的配置项
+ * @returns 装饰器函数
+ */
+declare const debounce: (ms: number, options?: DebounceOptions) => FastListenerPipe;
+
+interface ThrottleOptions {
+    /**
+     * 当消息被丢弃时的回调函数
+     */
+    drop?: (message: FastEventMessage) => void;
+}
+/**
+ * 创建一个节流装饰器，限制监听器函数的执行频率
+ * @param interval 节流时间间隔（毫秒）
+ * @param options 可选的配置项
+ * @returns 装饰器函数
+ */
+declare const throttle: (interval: number, options?: ThrottleOptions) => FastListenerPipe;
+
+declare class FastEventError extends Error {
+}
+declare class TimeoutError extends FastEventError {
+}
+declare class AbortError extends FastEventError {
+}
+declare class QueueOverflowError extends FastEventError {
 }
 
-export { FastEvent, type FastEventListenOptions, type FastEventListener, type FastEventListenerMeta, type FastEventMessage, type FastEventOptions, FastEventScope, type FastEventSubscriber, type FastEvents, type FastListenerNode, type FastListeners, type ScopeEvents };
+export { AbortError, type DebounceOptions, type Fallback, type FaseEventMessageExtends, FastEvent, type FastEventAnyListener, type FastEventEmitMessage, FastEventError, type FastEventListenOptions, type FastEventListener, type FastEventListenerArgs, type FastEventListenerDecorators, type FastEventMessage, type FastEventMeta, type FastEventOptions, FastEventScope, type FastEventScopeMeta, type FastEventScopeOptions, type FastEventSubscriber, type FastEvents, type FastListenerExecutorArgs, type FastListenerMeta, type FastListenerNode, type FastListenerPipe, type FastListeners, type FastQueueOverflows, type FastQueuePriority, type IFastListenerExecutor, type Merge, type PickScopeEvents, type QueueListenerPipeOptions, QueueOverflowError, type RequiredItems, type ScopeEvents, type ThrottleOptions, TimeoutError, debounce, dropping, expanding, queue, sliding, throttle, timeout };