fastevent 1.0.4 → 1.1.1

package/.prettierrc.js

@@ -0,0 +1,20 @@
+module.exports = {
+    // 每行末尾不添加分号
+    semi: true,
+    // 字符串使用单引号
+    singleQuote: true,
+    // tab缩进长度,默认为2
+    tabWidth: 4,
+    // 对象中打印空格
+    bracketSpacing: true,
+    // 文末自动添加空格等结尾
+    endOfLine: 'auto',
+    // 换行长度,默认80
+    printWidth: 180,
+    // 多行后面打印逗号
+    trailingComma: 'all',
+    // 箭头函数总是加小括号
+    arrowParens: 'always',
+    // 換行 保留??
+    proseWrap: 'preserve',
+};

package/.vscode/settings.json

@@ -0,0 +1,18 @@
+{
+    "terminal.integrated.persistentSessionReviveProcess": "onExitAndWindowClose",
+    "files.exclude": {
+        "**/.git": true,
+        "**/.svn": true,
+        "**/.hg": true,
+        "**/CVS": true,
+        "**/.DS_Store": true,
+        "**/Thumbs.db": true,
+        "**/node_modules": false
+    },
+    "editor.tabSize": 4,
+    "editor.insertSpaces": true,
+    "editor.detectIndentation": false,
+    "editor.formatOnSave": true,
+    "prettier.tabWidth": 4,
+    "oxlint.enable": true
+}

package/CHANGELOG.md

@@ -1,32 +1,48 @@
 # fastevent
 
+## 1.1.1
+
+### Patch Changes
+
+-   c93387f: feat: 新增加了 fastevent/devtools 功能，可以导入在`Redux Dev Tools`查看事件，用于调试。
+    feat: 新增加了 debug 选项，用于调试时使用。
+    feat: 增加了 onExecuteListener 选项，在每次执行侦听器后执行，仅当 debug=true 时有效
+    feat: 增加了 onClearListener 选项，在清空侦听器时执行
+    fix: 修改了类型提示错误
+
+## 1.1.0
+
+### Minor Changes
+
+-   02ffb88: 修改事件侦听器的接收为 FastEventMessage
+
 ## 1.0.4
 
 ### Patch Changes
 
-- 3cf1e87: 更新 meta 泛型参数的位置
+-   3cf1e87: 更新 meta 泛型参数的位置
 
 ## 1.0.3
 
 ### Patch Changes
 
-- 0c54b10: 调整 onAny 侦听器的执行优先级
+-   0c54b10: 调整 onAny 侦听器的执行优先级
 
 ## 1.0.2
 
 ### Patch Changes
 
-- 02c6d3e: fix scope.on error
+-   02c6d3e: fix scope.on error
 
 ## 1.0.1
 
 ### Patch Changes
 
-- b7d21e2: add prepend option for on
-- 8807aaa: update scope on options
+-   b7d21e2: add prepend option for on
+-   8807aaa: update scope on options
 
 ## 1.0.0
 
 ### Major Changes
 
-- b8b8c13: first release
+-   b8b8c13: first release

package/dist/devTools.d.mts

@@ -0,0 +1,308 @@
+/**
+ * 一个基于弱引用（WeakRef）的键值映射集合
+ *
+ * @template T - 值的类型，必须是对象类型（继承自 `object`）
+ *
+ * @example
+ * const map = new WeakObjectMap<MyObject>();
+ * map.set('key1', obj1);
+ * const retrieved = map.get('key1'); // 返回 obj1 或 undefined（如果已被垃圾回收）
+ */
+declare class WeakObjectMap<T extends object> {
+    private map;
+    private finalizationRegistry;
+    /**
+     * 构造一个新的 WeakObjectMap 实例
+     */
+    constructor();
+    /**
+     * 设置键值对
+     * @param key - 字符串键名
+     * @param value - 要存储的对象值（会被自动包装为弱引用）
+     */
+    set(key: string, value: T): void;
+    /**
+     * 获取指定键对应的值
+     * @param key - 要查找的键名
+     * @returns 如果值存在且未被垃圾回收则返回值，否则返回 undefined
+     */
+    get(key: string): T | undefined;
+    /**
+     * 删除指定键的映射
+     * @param key - 要删除的键名
+     * @returns 如果键存在并已删除则返回 true，否则返回 false
+     */
+    delete(key: string): boolean;
+    /**
+     * 检查是否存在指定键的映射（且值未被垃圾回收）
+     * @param key - 要检查的键名
+     * @returns 如果键存在且值未被回收则返回 true，否则返回 false
+     */
+    has(key: string): boolean;
+}
+
+type FastEventMessage<T = string, P = any, M = unknown> = {
+    type: T;
+    payload: P;
+    meta: M;
+};
+type FastEventListener<T = string, P = any, M = unknown> = (message: FastEventMessage<T, P, M>) => any | Promise<any>;
+type FastListenerNode = {
+    __listeners: (FastEventListener<any, any, any> | [FastEventListener<any, any>, number])[];
+} & {
+    [key: string]: FastListenerNode;
+};
+type FastEventSubscriber = {
+    off: () => void;
+};
+type FastListeners = FastListenerNode;
+type FastEventOptions<M = unknown> = {
+    id?: string;
+    debug?: boolean;
+    delimiter?: string;
+    context?: any;
+    ignoreErrors?: boolean;
+    onListenerError?: ((type: string, error: Error) => void);
+    meta?: M;
+    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;
+};
+type FastEvents = Record<string, any>;
+type ScopeEvents<T extends Record<string, any>, Prefix extends string> = {
+    [K in keyof T as K extends `${Prefix}/${infer Rest}` ? Rest : never]: T[K];
+};
+type FastEventListenOptions = {
+    count?: number;
+    prepend?: boolean;
+};
+
+declare class FastEventScope<Events extends FastEvents = FastEvents, Meta extends Record<string, any> = Record<string, any>, Types extends keyof Events = keyof Events> {
+    emitter: FastEvent<Events, Meta, Types>;
+    prefix: string;
+    constructor(emitter: FastEvent<Events, Meta, Types>, prefix: string);
+    private _getScopeListener;
+    private _getScopeType;
+    private _fixScopeType;
+    on<T extends Types = Types>(type: T, listener: FastEventListener<T, Events[T], Meta>, options?: FastEventListenOptions): FastEventSubscriber;
+    on<T extends string>(type: T, listener: FastEventListener<T, Events[T], Meta>, options?: FastEventListenOptions): FastEventSubscriber;
+    on(type: '**', listener: FastEventListener<any, any, Meta>): FastEventSubscriber;
+    once<T extends string>(type: T, listener: FastEventListener<T, Events[T], Meta>, options?: FastEventListenOptions): FastEventSubscriber;
+    once<T extends Types = Types>(type: T, listener: FastEventListener<Types, Events[T], Meta>, options?: FastEventListenOptions): FastEventSubscriber;
+    onAny<P = any>(listener: FastEventListener<Types, P, Meta>, options?: FastEventListenOptions): FastEventSubscriber;
+    offAll(): 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;
+    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>>;
+    scope(prefix: string): FastEventScope<ScopeEvents<Events, string>, Record<string, any>, keyof ScopeEvents<Events, string>>;
+}
+
+declare class FastEvent<Events extends FastEvents = FastEvents, Meta extends Record<string, any> = Record<string, any>, Types extends keyof Events = keyof Events> {
+    listeners: FastListeners;
+    private _options;
+    private _delimiter;
+    private _context;
+    retainedMessages: Map<string, any>;
+    listenerCount: number;
+    constructor(options?: FastEventOptions<Meta>);
+    get options(): FastEventOptions;
+    get id(): string;
+    private _addListener;
+    private _enableDevTools;
+    /**
+     *
+     * 根据parts路径遍历侦听器树，并在最后的节点上执行回调函数
+     *
+     * @param parts
+     * @param callback
+     * @returns
+     */
+    private _forEachNodes;
+    /**
+     * 从监听器节点中移除指定的事件监听器
+     * @private
+     * @param node - 监听器节点
+     * @param listener - 需要移除的事件监听器
+     * @description 遍历节点的监听器列表,移除所有匹配的监听器。支持移除普通函数和数组形式的监听器
+     */
+    private _removeListener;
+    on<T extends string>(type: T, listener: FastEventListener<T, Events[T], Meta>, options?: FastEventListenOptions): FastEventSubscriber;
+    on<T extends Types = Types>(type: T, listener: FastEventListener<Types, Events[T], Meta>, options?: FastEventListenOptions): FastEventSubscriber;
+    on<P = any>(type: '**', listener: FastEventListener<Types, P, Meta>): FastEventSubscriber;
+    once<T extends Types = Types>(type: T, listener: FastEventListener<T, Events[T], Meta>): FastEventSubscriber;
+    once<T extends string>(type: T, listener: FastEventListener<T, Events[T], Meta>): FastEventSubscriber;
+    /**
+     * 注册一个监听器，用于监听所有事件
+     * @param listener 事件监听器函数，可以接收任意类型的事件数据
+     * @returns {FastEventSubscriber} 返回一个订阅者对象，包含 off 方法用于取消监听
+     * @example
+     * ```ts
+     * const subscriber = emitter.onAny((eventName, data) => {
+     *   console.log(eventName, data);
+     * });
+     *
+     * // 取消监听
+     * subscriber.off();
+     * ```
+     */
+    onAny<P = any>(listener: FastEventListener<string, P, Meta>, 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;
+    /**
+     * 移除所有事件监听器
+     * @param entry - 可选的事件前缀,如果提供则只移除指定前缀下的的监听器
+     * @description
+     * - 如果提供了prefix参数,则只清除该前缀下的所有监听器
+     * - 如果没有提供prefix,则清除所有监听器
+     * - 同时会清空保留的事件(_retainedEvents)
+     * - 重置监听器对象为空
+
+    * @example
+     *
+     * ```ts
+     * emitter.offAll();    // 清除所有监听器
+     * emitter.offAll('a/b'); // 清除a/b下的所有监听器
+     *
+     */
+    offAll(entry?: string): void;
+    private _getListenerNode;
+    /**
+     * 移除保留的事件
+     * @param prefix - 事件前缀。如果不提供，将清除所有保留的事件。
+     *                如果提供前缀，将删除所有以该前缀开头的事件。
+     *                如果前缀不以分隔符结尾，会自动添加分隔符。
+     * @private
+     */
+    private _removeRetainedEvents;
+    clear(): void;
+    private _createMeta;
+    private _emitForLastEvent;
+    /**
+     * 遍历监听器节点树
+     * @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 _executeListener;
+    /**
+     * 执行监听器节点中的所有监听函数
+     * @param node - FastListenerNode类型的监听器节点
+     * @param payload - 事件携带的数据
+     * @param type - 事件类型
+     * @returns 返回所有监听函数的执行结果数组
+     * @private
+     *
+     * @description
+     * 遍历执行节点中的所有监听函数:
+     * - 对于普通监听器，直接执行并收集结果
+     * - 对于带次数限制的监听器(数组形式)，执行后递减次数，当次数为0时移除该监听器
+     */
+    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)
+     */
+    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[];
+    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][]>;
+    /**
+     * 等待指定事件发生
+     *
+     * waitFor("x")
+     *
+     * @param type
+     * @param timeout  超时时间，单位毫秒，默认为 0，表示无限等待
+     */
+    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>>;
+    /**
+     * 创建事件域
+     *
+     * 注意：
+     *
+     *  事件域与当前事件对象共享相同的侦听器表
+     *  也就是说，如果在事件域中触发事件，当前事件对象也会触发该事件
+     *  两者工不是完全隔离的,仅是事件侦听和触发时的事件类型不同而已
+     *
+     * const emitter = new FastEvent()
+     *
+     * const scope= emitter.scope("a/b")
+     *
+     * scope.on("x",()=>{})   == emitter.on("a/b/x",()=>{})
+     * scope.emit("x",1)      == emitter.emit("a/b/x",1)
+     * scope.offAll()         == emitter.offAll("a/b")
+     *
+     */
+    scope<T extends string>(prefix: T): FastEventScope<ScopeEvents<Events, T>, Record<string, any>, keyof ScopeEvents<Events, T>>;
+}
+
+/**
+ *
+ *  基于开发工具
+ *
+ *  Redux DevTools 是一个实用工具，用于开发和调试 Redux 应用程序。
+ *  FLEXEVENT是基于Redux DevTools 的简单包装，可以让开发者使用Redux DevTools
+ *  来查看FLEXEVENT的状态变化
+ *
+ *  import { createStore } from "@FLEXEVENTjs/react"
+ *  import { install } from "@FLEXEVENTjs/devtools"
+ *
+ *
+ *  const store = createStore({})
+ *
+ *  install()
+ *
+ */
+
+declare class FlexEventDevTools {
+    private reduxStore;
+    private _installed;
+    fastEvents: WeakObjectMap<object>;
+    constructor();
+    add(instance: FastEvent): void;
+    remove(instance: FastEvent): void;
+    private reducer;
+    private install;
+}
+declare function install(): void;
+declare global {
+    var __FLEXEVENT_DEVTOOLS__: FlexEventDevTools;
+}
+
+export { FlexEventDevTools, install };