feat: add getListeners and tag option

Author: zhangfisher

docs/zh/guide/use/devTools.md

@@ -1,8 +1,9 @@
-# 调试工具
+# 调试与诊断
 
-`FastEvent` 提供了调试工具，可以在`Redux DevTools`中查看触发的事件、监听器数量等信息。
 
-## 安装和使用步骤
+## 调试插件
+
+`FastEvent` 提供了调试工具，可以在`Redux DevTools`中查看触发的事件、监听器数量等信息。
 
 ### 第 1 步：安装 Redux DevTools
 
@@ -43,3 +44,70 @@ const emitter = new FastEvent({
 每次事件触发时，你都可以在`Redux DevTools`中看到详细的状态变化信息，这对于调试和理解应用的事件流非常有帮助。
 
 ![](./devtools.png)
+
+
+## 监听信息
+
+`FastEvent`还提供了一些辅助机制来帮助调试。
+
+- **获取事件监听器元数据**
+
+```ts
+import { FastEvent } from 'fastevent';
+const emitter = new FastEvent();
+
+const listener1 = () => {}
+const listener2 = () => {}
+const listener3 = () => {}
+
+emitter.on('test', listener1)
+emitter.on('test', listener2,{count: 10})
+emitter.once('test', listener3)
+
+const metas = emitter.getListeners('test');  // [!code ++]
+console.log(metas);
+// [[listener1,0,0],[listener2,10,0],[listener3,0,1]]
+
+
+```
+
+- `getListeners`方法用于获取事件监听器元数据，返回监听器注册信息`FastListenerMeta`。
+
+```ts
+type FastListenerMeta = [TypedFastEventListener<any, any>, number, number, string?]
+```
+
+`FastListenerMeta`是一个数组，包含以下信息：
+| 位置 | 类型 | 说明 |
+| --- | --- | --- |
+| `0` | `TypedFastEventListener` | 监听器函数 |
+| `1` | `number` | 监听器调用限制次数，`0`表示无限制，`1`代表只调用一次 |
+| `2` | `number` | 监听器实际执行的次数，当达到限制次数后，监听器将被移除 |
+| `3` | `string` | 额外的信息，用于标识监听器 |
+
+
+- **事件监听器标签**
+
+使用`getListeners`方法获取监听器元数据时，有时无法获取监听函数的更详细信息。
+此时，你可以为监听器添加额外的标签，用于标识监听器。
+
+
+```ts
+import { FastEvent } from 'fastevent';
+const emitter = new FastEvent();
+
+const listener = () => {} 
+
+emitter.on('test', listener, {
+    tag: 'modulex'  //[!code ++]
+}) 
+
+const metas = emitter.getListeners('test');  // [!code ++]
+console.log(metas);
+// [[listener,0,0,modulex]] // [!code ++]
+
+```
+
+:::warning 提示
+通过`FastEvent.listeners`可以查看所有的监听器注册信息。
+:::

packages/native/src/__tests__/listener.meta.test.ts

@@ -0,0 +1,42 @@
+import { describe, test, expect } from "vitest"
+import { FastEvent } from "../event"
+
+describe("监听器元数据", async () => {
+    test("获取指定事件的注册元信息", () => {
+        const emitter = new FastEvent()
+        const events: string[] = []
+        emitter.on("x", ({ type }) => {
+            events.push(type)
+        })
+        emitter.on("x", ({ type }) => {
+            events.push(type)
+        }, { count: 2 })
+
+        const metas = emitter.getListeners("x")
+
+        expect(metas[0][1]).toBe(0)
+        expect(metas[0][2]).toBe(0)
+        expect(metas[1][1]).toBe(2)
+        expect(metas[1][2]).toBe(0)
+    })
+
+    test("触发事件时提供额外的tag", () => {
+        const emitter = new FastEvent()
+        const events: string[] = []
+        emitter.on("x", ({ type }) => {
+            events.push(type)
+        }, { tag: "a" })
+        emitter.on("x", ({ type }) => {
+            events.push(type)
+        }, { count: 2, tag: "b" })
+
+        const metas = emitter.getListeners("x")
+
+        expect(metas[0][1]).toBe(0)
+        expect(metas[0][2]).toBe(0)
+        expect(metas[0][3]).toBe('a')
+        expect(metas[1][1]).toBe(2)
+        expect(metas[1][2]).toBe(0)
+        expect(metas[1][3]).toBe('b')
+    })
+})

packages/native/src/event.ts

@@ -134,6 +134,7 @@ export class FastEvent<
         let index: number = 0
         const node = this._forEachNodes(parts, (node) => {
             const newListener = [listener, count, 0] as unknown as FastListenerMeta
+            if (options.tag) newListener.push(options.tag)
             if (prepend) {
                 node.__listeners.splice(0, 0, newListener)
                 index = 0
@@ -762,6 +763,16 @@ export class FastEvent<
         }
         return results
     }
+
+    getListeners(type: keyof AllEvents): FastListenerMeta[]
+    getListeners(type: string): FastListenerMeta[] {
+        const nodes: FastListenerNode[] = []
+        const parts = type.split(this._delimiter);
+        this._traverseToPath(this.listeners, parts, (node) => {
+            nodes.push(node)
+        })
+        return nodes[0].__listeners
+    }
     /**
      * 异步触发事件
      * @param type - 事件类型，可以是字符串或预定义的事件类型

packages/native/src/types.ts

@@ -100,9 +100,14 @@ export type FastEventListener<
 
 
 /**
- * [监听器函数引用，需要执行多少次，实际执行的次数(用于负载均衡时记录)]
+ * [ 
+ *      监听器函数引用，
+ *      需要执行多少次，                     =0代表不限
+ *      实际执行的次数(用于负载均衡时记录)
+ *      标签            用于调试一般可以标识监听器类型或任意信息
+ * ]
  */
-export type FastListenerMeta = [TypedFastEventListener<any, any>, number, number]
+export type FastListenerMeta = [TypedFastEventListener<any, any>, number, number, string?]
 
 export type FastListenerNode = {
     __listeners: FastListenerMeta[];
@@ -201,6 +206,15 @@ export type FastEventListenOptions<
     off?: (message: TypedFastEventMessage<Events, Meta>, args: FastEventListenerArgs<Meta>) => boolean
     // 对监听器函数进行包装装饰，返回包装后的函数
     pipes?: FastListenerPipe[]
+    /**
+     * 为监听器添加一个tag，在监听器注册表中记录,用于调试使用
+     * 
+     * emitter.on(type,listener,{tag:"x"})
+     * 
+     * emitter.getListeners(tag)
+     * 
+     */
+    tag?: string
 }