fastevent 1.1.0 → 1.1.2

package/readme.md

@@ -346,9 +346,23 @@ events.on('process', () => {
 events.emit('process');
 ```
 
-## TypeScript Support
+## Generic Parameters
 
-FastEvent is written in TypeScript and provides full type support:
+FastEvent supports three generic type parameters for precise type control:
+
+```typescript
+class FastEvent<
+    Events extends Record<string, any> = Record<string, any>,
+    Meta extends Record<string, any> = Record<string, any>,
+    Types extends keyof Events = keyof Events
+>
+```
+
+1. `Events`: Defines the mapping between event types and their payload types
+2. `Meta`: Defines the type of metadata that can be attached to events
+3. `Types`: The union type of all event types (usually inferred from Events)
+
+### Basic Type Safety
 
 ```typescript
 // Define event types
@@ -373,6 +387,59 @@ events.emit('wrong/event', {});
 events.emit('user/login', { wrong: 'type' });
 ```
 
+### Custom Metadata Types
+
+```typescript
+// Define metadata structure
+interface MyMeta {
+    timestamp: number;
+    source: string;
+}
+
+// Define events with custom metadata
+const events = new FastEvent<MyEvents, MyMeta>();
+
+events.on('user/login', (message) => {
+    // message.meta is typed as MyMeta
+    const { timestamp, source } = message.meta;
+    console.log(`Login from ${source} at ${timestamp}`);
+});
+
+// Emit with typed metadata
+events.emit('user/login', { id: 1, name: 'Alice' }, false, { timestamp: Date.now(), source: 'web' });
+```
+
+### Advanced Type Usage
+
+```typescript
+// Define events with different payload types
+interface ComplexEvents {
+    'data/number': number;
+    'data/string': string;
+    'data/object': { value: any };
+}
+
+const events = new FastEvent<ComplexEvents>();
+
+// TypeScript ensures type safety for each event
+events.on('data/number', (message) => {
+    const sum = message.payload + 1; // payload is typed as number
+});
+
+events.on('data/string', (message) => {
+    const upper = message.payload.toUpperCase(); // payload is typed as string
+});
+
+events.on('data/object', (message) => {
+    const value = message.payload.value; // payload is typed as { value: any }
+});
+
+// All emissions are type checked
+events.emit('data/number', 42);
+events.emit('data/string', 'hello');
+events.emit('data/object', { value: true });
+```
+
 ## Custom Options
 
 The FastEvent constructor supports multiple options:
@@ -399,6 +466,23 @@ const events = new FastEvent({
   onRemoveListener: (path, listener) => {
     console.log('Listener removed:', path);
   }
+  onClearListeners: () => {
+    console.log('清空监听器:', path);
+  },
+  onExecuteListener: (message: FastEventMessage, returns: any[], listeners: (FastEventListener<any, any, any> | [FastEventListener<any, any>, number])[]) => {
+    console.log('监听器执行后的回调:');
+  }
+});
+```
+
+### debug
+
+Use `debug` option to enable debug mode and import `fastevent/devtools`, so that you can see the events in `Redux Dev Tools`.
+
+```ts
+import 'fastevent/devtools';
+const emitter = new FastEvent({
+    debug: true,
 });
 ```
 

package/readme_cn.md

@@ -346,9 +346,23 @@ events.on('process', () => {
 events.emit('process');
 ```
 
-## TypeScript 类型支持
+## 泛型参数
 
-FastEvent 使用 TypeScript 编写，提供完整的类型支持：
+FastEvent 支持三个泛型类型参数来实现精确的类型控制：
+
+```typescript
+class FastEvent<
+    Events extends Record<string, any> = Record<string, any>,
+    Meta extends Record<string, any> = Record<string, any>,
+    Types extends keyof Events = keyof Events
+>
+```
+
+1. `Events`：定义事件类型和对应的载荷（payload）类型的映射
+2. `Meta`：定义可以附加到事件的元数据类型
+3. `Types`：所有事件类型的联合类型（通常从 Events 中推导）
+
+### 基本类型安全
 
 ```typescript
 // 定义事件类型
@@ -373,6 +387,59 @@ events.emit('wrong/event', {});
 events.emit('user/login', { wrong: 'type' });
 ```
 
+### 自定义元数据类型
+
+```typescript
+// 定义元数据结构
+interface MyMeta {
+    timestamp: number;
+    source: string;
+}
+
+// 创建带自定义元数据的事件发射器
+const events = new FastEvent<MyEvents, MyMeta>();
+
+events.on('user/login', (message) => {
+    // message.meta 的类型为 MyMeta
+    const { timestamp, source } = message.meta;
+    console.log(`来自 ${source} 的登录，时间：${timestamp}`);
+});
+
+// 发送带类型化元数据的事件
+events.emit('user/login', { id: 1, name: 'Alice' }, false, { timestamp: Date.now(), source: 'web' });
+```
+
+### 高级类型用法
+
+```typescript
+// 定义具有不同载荷类型的事件
+interface ComplexEvents {
+    'data/number': number;
+    'data/string': string;
+    'data/object': { value: any };
+}
+
+const events = new FastEvent<ComplexEvents>();
+
+// TypeScript 确保每个事件的类型安全
+events.on('data/number', (message) => {
+    const sum = message.payload + 1; // payload 的类型为 number
+});
+
+events.on('data/string', (message) => {
+    const upper = message.payload.toUpperCase(); // payload 的类型为 string
+});
+
+events.on('data/object', (message) => {
+    const value = message.payload.value; // payload 的类型为 { value: any }
+});
+
+// 所有的事件发送都会进行类型检查
+events.emit('data/number', 42);
+events.emit('data/string', 'hello');
+events.emit('data/object', { value: true });
+```
+
 ## 自定义选项
 
 FastEvent 构造函数支持多个选项：
@@ -398,10 +465,27 @@ const events = new FastEvent({
   },
   onRemoveListener: (path, listener) => {
     console.log('移除监听器:', path);
+  },
+  onClearListeners: () => {
+    console.log('清空监听器:', path);
+  },
+  onExecuteListener: (message: FastEventMessage, returns: any[], listeners: (FastEventListener<any, any, any> | [FastEventListener<any, any>, number])[]) => {
+    console.log('监听器执行后的回调:');
   }
 });
 ```
 
+### 调试
+
+启用`debug=true`并导入`fastevent/devtools`,可以在`Redux Dev Tools`中查看事件.
+
+```ts
+import 'fastevent/devtools';
+const emitter = new FastEvent<MyEvents>({
+    debug: true,
+});
+```
+
 # 性能
 
 ![](./bench.png)

package/src/__tests__/scope.test.ts

@@ -95,14 +95,14 @@ describe("scope", () => {
         ]);
 
         expect(results[0].status).toBe('fulfilled');
-        expect((results[0] as any).value).toEqual({ type: 'a/b/c/x', payload: 'payload1', meta: undefined });
+        expect((results[0] as any).value).toEqual({ type: 'x', payload: 'payload1', meta: undefined });
 
         expect(results[1].status).toBe('rejected');
         //@ts-ignore
         expect(results[1].reason).toBeInstanceOf(Error);
 
         expect(results[2].status).toBe('fulfilled');
-        expect((results[2] as any).value).toEqual({ type: 'a/b/c/z', payload: 'payload3', meta: undefined });
+        expect((results[2] as any).value).toEqual({ type: 'z', payload: 'payload3', meta: undefined });
     });
 
 

package/src/__tests__/types.test.ts

@@ -85,6 +85,28 @@ describe("Types", () => {
         })
         emitter.emit("x/y/z", 1)
 
+        emitter.on("x/y/z", (message) => {
+            type cases = [
+                Expect<Equal<typeof message.type, "x/y/z">>,
+                Expect<Equal<typeof message.payload, unknown>>
+            ]
+        })
+
+        emitter.on("x/y/z/a", (message) => {
+            type cases = [
+                Expect<Equal<typeof message.type, "x/y/z/a">>,
+                Expect<Equal<typeof message.payload, 1>>
+            ]
+        })
+        emitter.waitFor("x/y/z/a").then((message) => {
+            type cases = [
+                Expect<Equal<typeof message.type, "x/y/z/a">>,
+                Expect<Equal<typeof message.payload, 1>>
+            ]
+        })
+
+
+
         // ----- scope -----
 
         const scope = emitter.scope("x/y/z")
@@ -116,19 +138,8 @@ describe("Types", () => {
                 Expect<Equal<typeof message.payload, 3>>
             ]
         })
-        emitter.on("x/y/z", (message) => {
-            type cases = [
-                Expect<Equal<typeof message.type, "x/y/z">>,
-                Expect<Equal<typeof message.payload, unknown>>
-            ]
-        })
 
-        emitter.on("x/y/z/a", (message) => {
-            type cases = [
-                Expect<Equal<typeof message.type, "x/y/z/a">>,
-                Expect<Equal<typeof message.payload, 1>>
-            ]
-        })
+
 
     })
 })

package/src/__tests__/waitFor.test.ts

@@ -53,6 +53,7 @@ describe("waitfor", () => {
                 emitter.emit('event3', 'payload3');
             }, 300);
 
+
             // Assert
             Promise.all([
                 event1Promise,

package/src/devTools.ts

@@ -0,0 +1,166 @@
+/**
+ * 
+ *  基于开发工具
+ * 
+ *  Redux DevTools 是一个实用工具，用于开发和调试 Redux 应用程序。
+ *  FLEXEVENT是基于Redux DevTools 的简单包装，可以让开发者使用Redux DevTools
+ *  来查看FLEXEVENT的状态变化 
+ * 
+ *  import { createStore } from "@FLEXEVENTjs/react"
+ *  import { install } from "@FLEXEVENTjs/devtools"
+ * 
+ *  
+ *  const store = createStore({})
+ * 
+ *  install()
+ * 
+ */
+
+//@ts-ignore
+import { legacy_createStore as createStore } from "redux"
+import { WeakObjectMap } from "./utils/WeakObjectMap"
+import { FastEvent } from "./event"
+
+const initialState = {
+
+}
+
+
+function getDefaultFastEventState(instance: FastEvent) {
+    return {
+        messageCount: 0,
+        listenerCount: instance.listenerCount,
+        retainMessageCount: instance.retainedMessages.size,
+    }
+}
+
+export class FlexEventDevTools {
+    private reduxStore: any
+    private _installed: boolean = false
+    fastEvents = new WeakObjectMap()
+    constructor() {
+        this.install()
+    }
+    add(instance: FastEvent) {
+        this.fastEvents.set(instance.id, instance)
+
+        instance.options.onAddListener = (type: string[], listener: any) => {
+            this.reduxStore.dispatch({
+                type: "__ADD_LISTENER__",
+                event: type.join("/"),
+                listener,
+                fastEventId: instance.id
+            })
+        }
+        instance.options.onRemoveListener = (type: string[], listener: any) => {
+            this.reduxStore.dispatch({
+                type: "__REMOVE_LISTENER__",
+                event: type.join("/"),
+                listener,
+                fastEventId: instance.id
+            })
+        }
+        instance.options.onClearListeners = () => {
+            this.reduxStore.dispatch({
+                type: "__CLEAR_LISTENERS__",
+                fastEventId: instance.id
+            })
+        }
+        instance.options.onExecuteListener = (message, returns, listeners) => {
+            const results = returns.map(r => r instanceof Error ? `Error(${r.message})` : r)
+            const sresults = listeners.map(listener => (listener as any).name || 'anonymous')
+                .reduce((pre, cur, index) => {
+                    pre[cur] = results[index]
+                    return pre
+                }, {})
+            console.log(`FastEvent<\x1B[31m${message.type}<\x1B[30m> is emit, listeners:`, listeners)
+            this.reduxStore.dispatch({
+                type: message.type,
+                payload: message.payload,
+                meta: message.meta,
+                returns: sresults,
+                fastEventId: instance.id
+            })
+        }
+        this.reduxStore.dispatch({
+            type: "__ADD_FASTEVENT__",
+            fastEventId: instance.id
+        })
+    }
+    remove(instance: FastEvent) {
+        if (this.fastEvents.has(instance.id)) {
+            this.fastEvents.delete(instance.id)
+        }
+    }
+    private reducer(state: any = initialState, action: any) {
+        if (action.type.startsWith("@@")) return state
+        const instance = this.fastEvents.get(action.fastEventId) as FastEvent
+        if (action.type === '__ADD_FASTEVENT__') {
+            return {
+                ...state,
+                [action.fastEventId]: getDefaultFastEventState(instance)
+            }
+        } else if (action.type == '__ADD_LISTENER__') {
+            const eventState = state[action.fastEventId] || getDefaultFastEventState(instance)
+            eventState.listenerCount++
+            return {
+                ...state,
+                [action.fastEventId]: {
+                    ...eventState
+                }
+            }
+        } else if (action.type == '__REMOVE_LISTENER__') {
+            const eventState = state[action.fastEventId]
+            if (!eventState) return state
+            eventState.listenerCount++
+            return {
+                ...state,
+                [action.fastEventId]: {
+                    ...eventState
+                }
+            }
+        } else if (action.type === '__CLEAR_LISTENERS__') {
+            const eventState = state[action.fastEventId]
+            if (!eventState) return state
+            eventState.listenerCount++
+            return {
+                ...state,
+                [action.fastEventId]: getDefaultFastEventState(instance)
+            }
+        } else {
+            const eventState = state[action.fastEventId]
+            if (!eventState) return state
+            eventState.messageCount++
+            eventState.listenerCount = instance.listenerCount
+            eventState.retainMessageCount = instance.retainedMessages.size
+            return {
+                ...state,
+                [action.fastEventId]: { ...eventState }
+            }
+        }
+    }
+    private install() {
+        if (this._installed) return
+        this.reduxStore = createStore(
+            this.reducer.bind(this),
+            // @ts-ignore
+            window.__REDUX_DEVTOOLS_EXTENSION__ && window.__REDUX_DEVTOOLS_EXTENSION__()
+        );
+        this._installed = true
+        console.info('%c FlexEventDevTools installed. Please open <Redux devtools> to view. %c', "color:red;", '')
+    }
+}
+
+export function install() {
+    // @ts-ignore
+    if (!globalThis.__FLEXEVENT_DEVTOOLS__) globalThis.__FLEXEVENT_DEVTOOLS__ = new FlexEventDevTools()
+}
+
+declare global {
+    // @ts-ignore
+    var __FLEXEVENT_DEVTOOLS__: FlexEventDevTools
+}
+
+
+install()
+