@cloudcome/utils-core/dist/emitter.d.ts

cloudcome core utils

/**
 * 事件类型映射，key 为事件名称，value 为事件参数类型数组
 */
export type EmitterMap = Record<string, unknown[]>;
/**
 * 事件监听器函数类型
 * @template E - EmitterMap 类型
 * @template K - 事件名称类型
 */
export type EmitterListener<E extends EmitterMap, K extends keyof E> = (...payloads: E[K]) => false | unknown;
/**
 * 事件发射器类，用于管理事件监听和触发
 * @template E - 事件类型映射
 *
 * @example
 * type MyEvents = {
 *   'click': [x: number, y: number];
 *   'change': [value: string];
 * };
 *
 * const emitter = new Emitter<MyEvents>();
 * emitter.on('click', (x, y) => {
 *   console.log(`Clicked at (${x}, ${y})`);
 * });
 * emitter.emit('click', 10, 20);
 */
export declare class Emitter<E extends EmitterMap> {
    #private;
    /**
     * 注册事件监听器
     * @param event - 要监听的事件名称
     * @param listener - 事件监听器函数
     * @example
     * emitter.on('click', (x, y) => {
     *   console.log(`Clicked at (${x}, ${y})`);
     * });
     */
    on<K extends keyof E>(event: K, listener: EmitterListener<E, K>): void;
    /**
     * 移除事件监听器，有三种使用方式：
     * 1. 移除特定事件的特定监听器
     * 2. 移除特定事件的所有监听器
     * 3. 移除所有事件的所有监听器
     * @param event - 要移除的事件名称（可选）
     * @param listener - 要移除的监听器函数（可选）
     * @example
     * // 移除特定事件的特定监听器
     * emitter.off('click', clickHandler);
     *
     * // 移除特定事件的所有监听器
     * emitter.off('click');
     *
     * // 移除所有事件的所有监听器
     * emitter.off();
     */
    off<K extends keyof E>(event?: K, listener?: EmitterListener<E, K>): void;
    /**
     * 触发指定事件，调用所有注册的监听器
     * @param event - 要触发的事件名称
     * @param payloads - 传递给监听器的参数
     * @remarks
     * 监听器会按照注册的顺序依次执行，如果某个监听器返回 false，
     * 则后续监听器将不会被执行
     * @example
     * emitter.emit('click', 10, 20);
     */
    emit<K extends keyof E>(event: K, ...payloads: Parameters<EmitterListener<E, K>>): void;
}