fastevent 2.0.2 → 2.1.0

package/dist/eventbus/index.d.mts

@@ -0,0 +1,1005 @@
+type FastListenerExecutor = (listeners: FastListenerMeta[], message: FastEventMessage, args: FastEventListenerArgs, execute: (listener: FastEventListener, message: FastEventMessage, args: FastEventListenerArgs, catchErrors?: boolean) => Promise<any> | any) => Promise<any[]> | any[];
+
+type FastListenerPipe = (listener: FastEventListener) => FastEventListener;
+
+interface FaseEventMessageExtends {
+}
+interface FastEventMeta {
+}
+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?: Partial<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: 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>;
+};
+type FastListeners = FastListenerNode;
+type FastEventOptions<Meta = Record<string, any>, Context = any> = {
+    id: string;
+    debug: boolean;
+    delimiter: string;
+    context: Context;
+    ignoreErrors: boolean;
+    meta: Meta;
+    onAddListener?: (type: string, listener: FastEventListener, options: FastEventListenOptions<Record<string, any>, Meta>) => boolean | FastEventSubscriber | void;
+    onRemoveListener?: (type: string, listener: FastEventListener) => void;
+    onClearListeners?: () => void;
+    onListenerError?: ((error: Error, listener: FastEventListener, message: FastEventMessage<any, Meta>, args: FastEventListenerArgs<Meta> | undefined) => void);
+    onBeforeExecuteListener?: (message: FastEventMessage<any, Meta>, args: FastEventListenerArgs<Meta>) => boolean | void | any[];
+    onAfterExecuteListener?: (message: FastEventMessage<any, Meta>, returns: any[], listeners: FastListenerNode[]) => void;
+    /**
+     * 全局执行器
+     */
+    executor?: FastListenerExecutor;
+    onMessage?: FastEventListener;
+    expandEmitResults?: boolean;
+};
+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 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 FastEventListenerArgs<M = Record<string, any>> = {
+    retain?: boolean;
+    meta?: Partial<M> & Record<string, any>;
+    abortSignal?: AbortSignal;
+    /**
+     *
+     * allSettled: 使用Promise.allSettled()执行所有监听器
+     * race: 使用Promise.race()执行所有监听器，只有第一个执行完成就返回,其他监听器执行结果会被忽略
+     * balance: 尽可能平均执行各个监听器
+     * sequence: 按照监听器添加顺序依次执行
+     */
+    executor?: FastListenerExecutor;
+    /**
+     * 当emit参数解析完成后的回调，用于修改emit参数
+     */
+    parseArgs?: (message: FastEventMessage, args: FastEventListenerArgs) => void;
+};
+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 Expand<T> = T extends infer O ? {
+    [K in keyof O]: O[K];
+} : never;
+type OptionalItems<T, K extends keyof T> = Expand<Omit<T, K> & {
+    [P in K]?: T[P];
+}>;
+type DeepPartial<T> = {
+    [P in keyof T]?: T[P] extends object ? DeepPartial<T[P]> : T[P];
+};
+type Fallback<T, F> = [
+    T
+] extends [never] ? F : T extends undefined ? F : T;
+type ChangeFieldType<Record, Name extends string, Type = any> = Expand<Omit<Record, Name> & {
+    [K in Name]: Type;
+}>;
+type OverrideOptions<T> = ChangeFieldType<Required<T>, 'context', never>;
+type ObjectKeys<T, I = string> = {
+    [P in keyof T]: P extends I ? P : never;
+}[keyof T];
+/**
+ * 从类型数组中移除重复项，返回保留唯一类型的元组
+ * @template T - 输入的任意类型数组（元组）
+ * @template Result - 内部使用的累积结果数组（默认空数组）
+ * @returns {any[]} 去重后的类型元组，保留首次出现的顺序
+ *
+ * @example
+ * type T1 = Unique<[number, string, number]>;  // [number, string]
+ * type T2 = Unique<[1, 2, 2, 3]>;              // [1, 2, 3]
+ * type T3 = Unique<['a', 'b', 'a']>;           // ['a', 'b']
+ */
+type Unique<T extends any[], Result extends any[] = []> = T extends [infer First, ...infer Rest] ? First extends Result[number] ? Unique<Rest, Result> : Unique<Rest, [...Result, First]> : Result;
+type Overloads<T> = Unique<T extends {
+    (...args: infer A1): infer R1;
+    (...args: infer A2): infer R2;
+    (...args: infer A3): infer R3;
+    (...args: infer A4): infer R4;
+    (...args: infer A5): infer R5;
+    (...args: infer A6): infer R6;
+    (...args: infer A7): infer R7;
+    (...args: infer A8): infer R8;
+} ? [
+    (...args: A1) => R1,
+    ((...args: A2) => R2),
+    ((...args: A3) => R3),
+    ((...args: A4) => R4),
+    ((...args: A5) => R5),
+    ((...args: A6) => R6),
+    ((...args: A7) => R7),
+    ((...args: A8) => R8)
+] : T extends {
+    (...args: infer A1): infer R1;
+    (...args: infer A2): infer R2;
+    (...args: infer A3): infer R3;
+    (...args: infer A4): infer R4;
+    (...args: infer A5): infer R5;
+    (...args: infer A6): infer R6;
+    (...args: infer A7): infer R7;
+} ? [
+    (...args: A1) => R1,
+    ((...args: A2) => R2),
+    ((...args: A3) => R3),
+    ((...args: A4) => R4),
+    ((...args: A5) => R5),
+    ((...args: A6) => R6),
+    ((...args: A7) => R7)
+] : T extends {
+    (...args: infer A1): infer R1;
+    (...args: infer A2): infer R2;
+    (...args: infer A3): infer R3;
+    (...args: infer A4): infer R4;
+    (...args: infer A5): infer R5;
+    (...args: infer A6): infer R6;
+} ? [
+    (...args: A1) => R1,
+    ((...args: A2) => R2),
+    ((...args: A3) => R3),
+    ((...args: A4) => R4),
+    ((...args: A5) => R5),
+    ((...args: A6) => R6)
+] : T extends {
+    (...args: infer A1): infer R1;
+    (...args: infer A2): infer R2;
+    (...args: infer A3): infer R3;
+    (...args: infer A4): infer R4;
+    (...args: infer A5): infer R5;
+} ? [
+    (...args: A1) => R1,
+    ((...args: A2) => R2),
+    ((...args: A3) => R3),
+    ((...args: A4) => R4),
+    ((...args: A5) => R5)
+] : T extends {
+    (...args: infer A1): infer R1;
+    (...args: infer A2): infer R2;
+    (...args: infer A3): infer R3;
+    (...args: infer A4): infer R4;
+} ? [
+    (...args: A1) => R1,
+    ((...args: A2) => R2),
+    ((...args: A3) => R3),
+    ((...args: A4) => R4)
+] : T extends {
+    (...args: infer A1): infer R1;
+    (...args: infer A2): infer R2;
+    (...args: infer A3): infer R3;
+} ? [
+    ((...args: A1) => R1),
+    ((...args: A2) => R2),
+    ((...args: A3) => R3)
+] : T extends {
+    (...args: infer A1): infer R1;
+    (...args: infer A2): infer R2;
+} ? [
+    ((...args: A1) => R1),
+    ((...args: A2) => R2)
+] : T extends {
+    (...args: infer A1): infer R1;
+} ? [
+    (...args: A1) => R1
+] : [
+    T
+]>;
+type Dict<V = any> = Record<Exclude<string, number | symbol>, V>;
+
+type FastEventBusMessage<Events extends Record<string, any> = Record<string, any>, M = any> = FastEventEmitMessage<Events, M> & {
+    from?: string;
+    to?: string;
+};
+type FastEventBusOptions<Meta = Record<string, any>, Context = any> = FastEventOptions<Meta, Context>;
+interface FastEventBusEvents {
+    '$connect': string;
+    '$disconnect': string;
+    'data': any;
+}
+type FastEventBusEventTypes = keyof FastEventBusEvents;
+interface FastEventBusNodes {
+}
+type FastEventBusNodeIds = keyof FastEventBusNodes;
+
+type FastEventScopeOptions<Meta = Record<string, any>, Context = any> = {
+    meta: FastEventScopeMeta & FastEventMeta & Meta;
+    context: Context;
+    executor?: FastListenerExecutor;
+    onMessage?: FastEventListener;
+};
+type FastEventScopeMeta = {
+    scope: string;
+};
+declare class FastEventScope<Events extends Record<string, any> = Record<string, any>, Meta extends Record<string, any> = Record<string, any>, Context = never, Types extends keyof Events = keyof Events, FinalMeta extends Record<string, any> = FastEventMeta & FastEventScopeMeta & Meta> {
+    __FastEventScope__: boolean;
+    private _options;
+    types: {
+        events: Events;
+        meta: FinalMeta;
+        context: Fallback<Context, typeof this>;
+    };
+    prefix: string;
+    emitter: FastEvent<Events>;
+    constructor(options?: DeepPartial<FastEventScopeOptions<FinalMeta, Context>>);
+    get context(): Fallback<Context, typeof this>;
+    get options(): FastEventScopeOptions<FinalMeta, Context>;
+    bind(emitter: FastEvent<any>, prefix: string, options?: DeepPartial<FastEventScopeOptions<FinalMeta, Context>>): void;
+    /**
+     * 获取作用域监听器
+     * 当启用作用域时,对原始监听器进行包装,添加作用域前缀处理逻辑
+     * @param listener 原始事件监听器
+     * @returns 包装后的作用域监听器
+     * @private
+     */
+    private _getScopeListener;
+    private _getScopeType;
+    private _fixScopeType;
+    on<T extends Types = Types>(type: T, options?: FastEventListenOptions<Events, FinalMeta>): FastEventSubscriber;
+    on<T extends string>(type: T, options?: FastEventListenOptions<Events, FinalMeta>): FastEventSubscriber;
+    on(type: '**', options?: FastEventListenOptions<Events, FinalMeta>): FastEventSubscriber;
+    on<T extends Types = Types>(type: T, listener: FastEventListener<Exclude<T, number | symbol>, Events[T], FinalMeta, Fallback<Context, typeof this>>, options?: FastEventListenOptions): FastEventSubscriber;
+    on<T extends string>(type: T, listener: FastEventListener<string, any, FinalMeta, Fallback<Context, typeof this>>, options?: FastEventListenOptions): FastEventSubscriber;
+    on(type: '**', listener: FastEventAnyListener<Events, FinalMeta, Fallback<Context, typeof this>>, options?: FastEventListenOptions): FastEventSubscriber;
+    once<T extends Types = Types>(type: T, options?: FastEventListenOptions<Events, FinalMeta>): FastEventSubscriber;
+    once<T extends string>(type: T, options?: FastEventListenOptions<Events, FinalMeta>): FastEventSubscriber;
+    once<T extends Types = Types>(type: T, listener: FastEventListener<Exclude<T, number | symbol>, Events[T], FinalMeta, Fallback<Context, typeof this>>, options?: FastEventListenOptions): FastEventSubscriber;
+    once<T extends string>(type: T, listener: FastEventListener<string, any, FinalMeta, Fallback<Context, typeof this>>, options?: FastEventListenOptions): FastEventSubscriber;
+    onAny(options?: Pick<FastEventListenOptions, 'prepend'>): FastEventSubscriber;
+    onAny<P = any>(listener: FastEventAnyListener<{
+        [K: string]: P;
+    }, FinalMeta, Fallback<Context, typeof this>>, 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(type: Types, directive: symbol): void;
+    emit(type: string, directive: symbol): void;
+    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 - 作用域前缀
+     * @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' });
+     * ```
+     */
+    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?: DeepPartial<FastEventScopeOptions<Partial<FinalMeta> & M, C>>): FastEventScope<ScopeEvents<Events, P> & E, FinalMeta & M, C>;
+    scope<E extends Record<string, any> = Record<string, any>, P extends string = string, M extends Record<string, any> = Record<string, any>, C = Context, ScopeInstance extends FastEventScope<any, any, any> = FastEventScope<ScopeEvents<ScopeEvents<Events, P> & E, P> & E, FinalMeta & M, C>>(prefix: P, scopeObj: ScopeInstance, options?: DeepPartial<FastEventScopeOptions<Partial<FinalMeta> & M, C>>): ScopeInstance;
+    /**
+     * 当on/once/onAny未指定监听器时,此为默认监听器
+     * @param message
+     */
+    onMessage(message: FastEventMessage<Events, FinalMeta>, args: FastEventListenerArgs<FinalMeta>): void;
+}
+
+/**
+ * FastEvent 事件发射器类
+ *
+ * @template Events - 事件类型定义，继承自FastEvents接口
+ * @template Meta - 事件元数据类型，默认为任意键值对对象
+ * @template Types - 事件类型的键名类型，默认为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 = Expand<Exclude<keyof (AllEvents), number | symbol>>> {
+    __FastEvent__: boolean;
+    /** 事件监听器树结构，存储所有注册的事件监听器 */
+    listeners: FastListeners;
+    /** 事件发射器的配置选项 */
+    private _options;
+    /** 事件名称的分隔符，默认为'/' */
+    private _delimiter;
+    /** 事件监听器执行时的上下文对象 */
+    private _context;
+    /** 保留的事件消息映射，Key是事件名称，Value是保留的事件消息 */
+    retainedMessages: Map<string, any>;
+    /** 当前注册的监听器总数 */
+    listenerCount: number;
+    types: {
+        events: AllEvents;
+        meta: Expand<FastEventMeta & Meta & Record<string, any>>;
+        context: Expand<Fallback<Context, typeof this>>;
+    };
+    /**
+     * 创建FastEvent实例
+     * @param options - 事件发射器的配置选项
+     *
+     * 默认配置：
+     * - debug: false - 是否启用调试模式
+     * - id: 随机字符串 - 实例唯一标识符
+     * - delimiter: '/' - 事件名称分隔符
+     * - context: null - 监听器执行上下文
+     * - ignoreErrors: true - 是否忽略监听器执行错误
+     */
+    constructor(options?: Partial<FastEventOptions<Meta, Context>>);
+    /** 获取事件发射器的配置选项 */
+    get options(): FastEventOptions<Meta, Context>;
+    get context(): Fallback<Context, typeof this>;
+    get meta(): Meta;
+    /** 获取事件发射器的唯一标识符 */
+    get id(): string;
+    /**
+     * 添加事件监听器到事件树中
+     * @param parts - 事件路径数组
+     * @param listener - 事件监听器函数
+     * @param options - 监听器配置选项
+     * @param options.count - 监听器触发次数限制
+     * @param options.prepend - 是否将监听器添加到监听器列表开头
+     * @returns [节点, 监听器索引] - 返回监听器所在节点和在节点监听器列表中的索引
+     * @private
+     */
+    private _addListener;
+    private _enableDevTools;
+    /**
+     *
+     * 根据parts路径遍历监听器树，并在最后的节点上执行回调函数
+     *
+     * @param parts
+     * @param callback
+     * @returns
+     */
+    private _forEachNodes;
+    /**
+     * 从监听器节点中移除指定的事件监听器
+     * @private
+     * @param node - 监听器节点
+     * @param listener - 需要移除的事件监听器
+     * @description 遍历节点的监听器列表,移除所有匹配的监听器。支持移除普通函数和数组形式的监听器
+     */
+    private _removeListener;
+    private _pipeListener;
+    /**
+     * 注册事件监听器
+     * @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 });
+     * ```
+     */
+    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方法相同的格式：
+     *   - 普通字符串：'user/login'
+     *   - 通配符：'user/*'（匹配单层）或'user/**'（匹配多层）
+     * @param listener - 事件监听器函数
+     * @returns 返回订阅者对象，包含off方法用于取消监听
+     *
+     * @description
+     * 监听器只会在事件首次触发时被调用一次，之后会自动解除注册。
+     * 这是on方法的特例，相当于设置options.count = 1。
+     * 如果事件有保留消息，新注册的监听器会立即收到最近一次的保留消息并解除注册。
+     *
+     * @example
+     * ```ts
+     * // 只监听一次登录事件
+     * emitter.once('user/login', (data) => {
+     *   console.log('用户登录:', data);
+     * });
+     * ```
+     */
+    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 事件监听器函数，可以接收任意类型的事件数据
+     * @returns {FastEventSubscriber} 返回一个订阅者对象，包含 off 方法用于取消监听
+     * @example
+     * ```ts
+     * const subscriber = emitter.onAny((eventName, data) => {
+     *   console.log(eventName, data);
+     * });
+     *
+     * // 取消监听
+     * 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时如果没有指定监听器，则调用此方法
+     *
+     * 此方法供子类继承
+     *
+     */
+    onMessage(message: FastEventMessage<AllEvents, Meta>, args: FastEventListenerArgs<Meta>): 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;
+    off(type: string): void;
+    off(type: Types): void;
+    /**
+     * 移除所有事件监听器
+     * @param entry - 可选的事件前缀,如果提供则只移除指定前缀下的的监听器
+     * @description
+     * - 如果提供了prefix参数,则只清除该前缀下的所有监听器
+     * - 如果没有提供prefix,则清除所有监听器
+     * - 同时会清空保留的事件(_retainedEvents)
+     * - 重置监听器对象为空
+     
+    * @example
+     *
+     * ```ts
+     * emitter.offAll();    // 清除所有监听器
+     * emitter.offAll('a/b'); // 清除a/b下的所有监听器
+     *
+     */
+    offAll(entry?: string): void;
+    /**
+     * 移除保留的事件
+     * @param prefix - 事件前缀。如果不提供，将清除所有保留的事件。
+     *                如果提供前缀，将删除所有以该前缀开头的事件。
+     *                如果前缀不以分隔符结尾，会自动添加分隔符。
+     * @private
+     */
+    private _removeRetainedEvents;
+    clear(prefix?: string): void;
+    /**
+     * 发送最后一次事件的消息给对应的监听器
+     *
+     * @param type - 事件类型,支持通配符(*)匹配
+     * @private
+     *
+     * 处理流程:
+     * 1. 如果事件类型包含通配符,则遍历所有保留的消息,匹配符合模式的事件
+     * 2. 如果是普通事件类型,则直接获取对应的保留消息
+     * 3. 遍历匹配到的消息,查找对应路径的监听器节点
+     * 4. 执行所有匹配到的监听器
+     */
+    private _emitRetainMessage;
+    /**
+     * 遍历监听器节点树
+     * @param node 当前遍历的监听器节点
+     * @param parts 事件名称按'.'分割的部分数组
+     * @param callback 遍历到目标节点时的回调函数
+     * @param index 当前遍历的parts数组索引,默认为0
+     * @param lastFollowing  当命中**时该值为true, 注意**只能作在路径的最后面，如a.**有效，而a.**.b无效
+     * @private
+     *
+     * 支持三种匹配模式:
+     * - 精确匹配: 'a.b.c'
+     * - 单层通配: 'a.*.c'
+     * - 多层通配: 'a.**'
+     */
+    private _traverseToPath;
+    private _traverseListeners;
+    private _onListenerError;
+    /**
+     * 执行单个监听器函数
+     * @param listener - 要执行的监听器函数或包装过的监听器对象
+     * @param message - 事件消息对象，包含type、payload和meta
+     * @param args - 监听器参数
+     * @param catchErrors - 是否捕获并处理执行过程中的错误
+     * @returns 监听器的执行结果或错误对象（如果配置了ignoreErrors）
+     * @private
+     *
+     * @description
+     * 执行单个监听器函数，处理以下情况：
+     * - 如果监听器是包装过的（有__wrappedListener属性），调用包装的函数
+     * - 否则直接调用监听器函数
+     * - 使用配置的上下文（_context）作为this
+     * - 捕获并处理执行过程中的错误：
+     *   - 如果有onListenerError回调，调用它
+     *   - 如果配置了ignoreErrors，返回错误对象
+     *   - 否则抛出错误
+     */
+    private _executeListener;
+    private _getListenerExecutor;
+    /**
+     * 执行监听器节点列表中的所有监听器函数
+     * @param nodes 监听器节点列表
+     * @param message 事件消息对象
+     * @param args 监听器参数
+     * @param args 监听器参数
+     * @returns 所有监听器函数的执行结果数组
+     * @private
+     *
+     * 执行流程:
+     * 1. 将所有节点中的监听器函数展平为一维数组
+     * 2. 通过执行器执行所有监听器函数
+     * 3. 更新监听器的执行次数,并移除达到执行次数限制的监听器
+     */
+    private _executeListeners;
+    /**
+     * 触发事件并执行对应的监听器
+     *
+     * @param type - 事件类型字符串或包含事件信息的对象
+     * @param payload - 事件携带的数据负载
+     * @param retain - 是否保留该事件(用于新订阅者)
+     * @param meta - 事件元数据
+     * @returns 所有监听器的执行结果数组
+     *
+     * @example
+     * // 方式1: 参数形式
+     * emit('user.login', { id: 1 }, true)
+     *
+     * // 方式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);
+     *
+     * // 清除保留事件
+     * emitter.emit("user/login")
+     *
+     * ```
+     */
+    emit<T extends Types = Types>(type: T, directive: symbol): any[];
+    emit(type: string, directive: symbol): any[];
+    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 - 事件类型，可以是字符串或预定义的事件类型
+     * @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()
+     * });
+     * ```
+     */
+    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 - 要等待的事件类型
+     * @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('等待登录超时');
+     * }
+     *
+     * // 无限等待事件
+     * const event = await emitter.waitFor('server/ready');
+     * console.log('服务器就绪');
+     * ```
+     */
+    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 - 作用域前缀，将自动添加到该作用域下所有事件名称前
+     * @returns 新的FastEventScope实例
+     *
+     * @description
+     * 创建一个新的事件作用域，用于在特定命名空间下管理事件。
+     *
+     * 重要特性：
+     * - 作用域与父事件发射器共享同一个监听器表
+     * - 作用域中的事件会自动添加前缀
+     * - 作用域的所有操作都会映射到父事件发射器上
+     * - 作用域不是完全隔离的，只是提供了事件名称的命名空间
+     *
+     * @example
+     * ```ts
+     * const emitter = new FastEvent();
+     *
+     * // 创建用户相关事件的作用域
+     * const userEvents = emitter.scope('user');
+     *
+     * // 在作用域中监听事件
+     * userEvents.on('login', (data) => {
+     *   // 实际监听的是 'user/login'
+     *   console.log('用户登录:', data);
+     * });
+     *
+     * // 在作用域中触发事件
+     * userEvents.emit('login', { userId: 123 });
+     * // 等同于 emitter.emit('user/login', { userId: 123 })
+     *
+     * // 创建嵌套作用域
+     * const profileEvents = userEvents.scope('profile');
+     * profileEvents.emit('update', { name: 'John' });
+     * // 等同于 emitter.emit('user/profile/update', { name: 'John' })
+     *
+     * // 清理作用域
+     * userEvents.offAll();  // 清理 'user' 前缀下的所有事件
+     * ```
+     */
+    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?: DeepPartial<FastEventScopeOptions<Meta & M, C>>): FastEventScope<ScopeEvents<AllEvents, P> & E, Meta & M, C>;
+    scope<E extends Record<string, any> = Record<string, any>, P extends string = string, M extends Record<string, any> = Record<string, any>, C = Context, ScopeObject extends FastEventScope<any, any, any> = FastEventScope<ScopeEvents<AllEvents, P> & E, Meta & M, C>>(prefix: P, scopeObj: ScopeObject, options?: DeepPartial<FastEventScopeOptions<Meta & M, C>>): ScopeObject;
+}
+
+type FastEventBusNodeOptions<Meta = Record<string, any>, Context = any> = FastEventOptions<Meta, Context> & {};
+declare class FastEventBusNode<Events extends Record<string, any> = Record<string, any>, Meta extends Record<string, any> = Record<string, any>, Context = never> extends FastEvent<Events, Meta, Context> {
+    eventbus?: FastEventBus<any, any, any>;
+    private _subscribers;
+    constructor(options?: DeepPartial<FastEventBusNodeOptions<Meta, Context>>);
+    /**
+     *
+     * 如果事件名称带有名称空间分隔符::，则说明该触发的消息是要转发到其他节点，
+     * 由eventbus进行转发
+     *
+     * emit("otherNode@<事件名>") // 在otherNode节点上触发事件
+     * emit("@<事件名>") // 在当前总线队象上触发事件
+     *
+     * 事件执行前的监听器处理函数
+     * 处理带有命名空间前缀的事件,格式为 "<节点id>::<事件名>"
+     * 如果事件包含命名空间,则将事件转发到对应节点或全局事件总线
+     *
+     * @param message - 事件消息对象
+     * @param args - 事件监听器参数
+     * @returns {boolean} false 表示取消在内部触发事件,undefined 表示继续执行
+     * @private
+     */
+    private _onBeforeExecuteListener;
+    private _onAddListener;
+    /**
+     * 加入事件总线
+     * @param eventBus 要加入的事件总线
+     */
+    connect(eventbus: FastEventBus<any>): void;
+    disconnect(): void;
+    /**
+     *
+     * 订阅来自其他节点的消息
+     *
+     * 在Eventbus中的所有以`node::<节点id>/<事件>`的事件均会被转发到当前节点
+     *
+     * @private
+     */
+    private _onSubscribeForNode;
+    /**
+     * 发送点对点消息到指定节点
+     * @param toNodeId 目标节点ID
+     * @param message 要发送的消息
+     */
+    send<R = any, T extends FastEventBusNodeIds = FastEventBusNodeIds>(toNodeId: T, payload: any, args?: FastEventListenerArgs): R[];
+    send<R = any, T extends string = string>(toNodeId: T, payload: any, args?: FastEventListenerArgs): R[];
+    private _assertConnected;
+    /**
+     * 广播消息到所有其他节点
+     *
+     *
+     * @param message 要广播的消息
+     */
+    broadcast<R = any, T extends FastEventBusEventTypes = FastEventBusEventTypes>(message: FastEventBusMessage<{
+        [K in T]: K extends FastEventBusEventTypes ? FastEventBusEvents[K] : any;
+    }>, args?: FastEventListenerArgs): R[];
+    broadcast<R = any, T extends string = string>(message: FastEventBusMessage<{
+        [K in T]: K extends FastEventBusEventTypes ? FastEventBusEvents[K] : any;
+    }, Meta>, args?: FastEventListenerArgs): R[];
+    broadcast<R = any, T extends FastEventBusEventTypes = FastEventBusEventTypes>(type: T, payload: FastEventBusEvents[T], options?: FastEventListenerArgs<Meta>): R[];
+    broadcast<R = any, T extends string = string>(type: T, payload: T extends FastEventBusEventTypes ? FastEventBusEvents[T] : any, options?: FastEventListenerArgs<Meta>): R[];
+    /**
+     * 处理接收到的消息
+     * 供子类继承重载
+     */
+    onMessage(message: FastEventBusMessage, args: FastEventListenerArgs): void;
+}
+
+/**
+ *
+ * const eventbus = new FastEventBus()
+ *
+ * const node1 = new FastEventBusNode({id:"node1",...})
+ * const node2 = new FastEventBusNode({id:"node2",...})
+ * const node3 = new FastEventBusNode({id:"node3",...})
+ *
+ * - 将节点添加到FastEventBus中
+ * eventbus.add(node1)
+ * eventbus.add(node2)
+ * eventbus.add(node3)
+ * 或者
+ * node1.join(eventbus)
+ * node2.join(eventbus)
+ * node3.join(eventbus)
+ *
+ * - 每个节点均有唯一的节点名称，用于区分不同的节点
+ * - 每个节点是一个独立的FastEvent实例
+ * - 每个节点的配置选项与FastEvent相同
+ * - 节点之间相互独立，互不影响
+ * - FastEventBus负载节点之间的通讯
+ * - 所有节点均可以在onMessage中接收到其订阅或点对点或广播的消息
+ *
+ * - 可以广播消息给所有节点
+ *
+ *   eventbus.broadcast(message)
+ *   node1.broadcast(message)
+ *
+ * - 可以在节点之间进行点对点发送消息
+ *
+ *    eventbus.send(node1.id, message)
+ *    node1.send(node2.id, message)
+ *
+ *
+ * - 节点消息接收到的消息是FastEventBusNodeMessage,增加了from代表是消息来自哪里
+ * - 节点如果要订阅其他节点的消息，需要在事件类型名称加::
+ *    node1.on("node2::test",listener,{...})代表订阅node2的test事件
+ * - 节点可以在全局触发事件
+ *    node1.emit("::test")      在全局(即Eventbus)触发事件
+ *    node2.on("::test",listener,{...})
+ *
+ */
+
+declare class FastEventBus<Events extends Record<string, any> = FastEventBusEvents, Meta extends Record<string, any> = Record<string, any>, Context = never, AllEvents extends Record<string, any> = Exclude<Expand<Events & FastEventBusEvents>, number | symbol>, Types extends keyof AllEvents = Expand<Exclude<keyof (AllEvents), number | symbol>>> extends FastEvent<Events & FastEventBusEvents, Meta, Context> {
+    nodes: Map<string, FastEventBusNode<any, any, any>>;
+    constructor(options?: FastEventBusOptions<Meta, Context>);
+    /**
+     * 添加节点到事件总线
+     * @param node 要添加的节点
+     */
+    add(...nodes: FastEventBusNode<any, any, any>[]): void;
+    /**
+     * 从事件总线移除节点
+     * @param nodeId 要移除的节点ID
+     */
+    remove(nodeId: string): void;
+    /**
+     * 广播消息到所有节点
+     *
+     * broadcast(1)  // 默认广播主题data
+     * broadcast({
+     *    type: 'connect',
+     *    payload: 100
+     * })     *
+     *
+     * @param message 要广播的消息
+     */
+    broadcast<R = any, T extends Types = Types>(message: FastEventBusMessage<{
+        [K in T]: AllEvents[T];
+    }, Meta>, args?: FastEventListenerArgs): R[];
+    broadcast<R = any, T extends string = string>(message: FastEventBusMessage<{
+        [K in T]: K extends Types ? AllEvents[K] : any;
+    }, Meta>, args?: FastEventListenerArgs): R[];
+    broadcast<R = any, T extends string = string>(type: T, payload?: T extends Types ? AllEvents[Types] : any, options?: FastEventListenerArgs<Meta>): R[];
+    broadcast<R = any, T extends Types = Types>(type: T, payload: AllEvents[T], args?: FastEventListenerArgs): R[];
+    /**
+     * 发送消息到指定节点
+     *
+     * 点对点消息的事件名称为data
+     *
+     * @param toNodeId 目标节点ID
+     * @param message 要发送的消息
+     */
+    send<R = any>(message: FastEventBusMessage, args?: FastEventListenerArgs): R[];
+}
+
+declare const NamespaceDelimiter = "::";
+declare const BroadcastEvent = "@";
+declare const NodeDataEvent = "data";
+
+declare const __FastEvent__: unique symbol;
+declare const __FastEventScope__: unique symbol;
+declare class FastEventError extends Error {
+    constructor(message?: string);
+}
+declare class TimeoutError extends FastEventError {
+}
+declare class UnboundError extends FastEventError {
+}
+declare class AbortError extends FastEventError {
+}
+declare class CancelError extends FastEventError {
+}
+declare class QueueOverflowError extends FastEventError {
+}
+declare const FastEventDirectives: {
+    clearRetain: symbol;
+};
+
+export { AbortError, BroadcastEvent, CancelError, type ChangeFieldType, type DeepPartial, type Dict, type Expand, type Fallback, type FaseEventMessageExtends, FastEvent, type FastEventAnyListener, FastEventBus, type FastEventBusEventTypes, type FastEventBusEvents, type FastEventBusMessage, FastEventBusNode, type FastEventBusNodeIds, type FastEventBusNodeOptions, type FastEventBusNodes, type FastEventBusOptions, FastEventDirectives, type FastEventEmitMessage, FastEventError, type FastEventListenOptions, type FastEventListener, type FastEventListenerArgs, type FastEventMessage, type FastEventMeta, type FastEventOptions, FastEventScope, type FastEventScopeMeta, type FastEventScopeOptions, type FastEventSubscriber, type FastEvents, type FastListenerMeta, type FastListenerNode, type FastListeners, type Merge, NamespaceDelimiter, NodeDataEvent, type ObjectKeys, type OptionalItems, type Overloads, type OverrideOptions, type PickScopeEvents, QueueOverflowError, type RequiredItems, type ScopeEvents, TimeoutError, UnboundError, type Unique, __FastEventScope__, __FastEvent__ };