fastevent 1.0.4 → 1.1.1

package/readme.md

@@ -4,9 +4,9 @@ FastEvent is a powerful TypeScript event management library that provides flexib
 
 Compared to `EventEmitter2`, `FastEvent` has the following advantages:
 
-- `FastEvent` performs about `1+` times better than `EventEmitter2` when publishing and subscribing with wildcards.
-- `FastEvent` has a package size of `6.3kb`, while `EventEmitter2` is `43.4kb`.
-- `FastEvent` offers more comprehensive features.
+-   `FastEvent` performs about `1+` times better than `EventEmitter2` when publishing and subscribing with wildcards.
+-   `FastEvent` has a package size of `6.3kb`, while `EventEmitter2` is `43.4kb`.
+-   `FastEvent` offers more comprehensive features.
 
 # Installation
 
@@ -33,43 +33,67 @@ import { FastEvent } from 'fastevent';
 const events = new FastEvent();
 
 // Subscribe to event
-events.on('user/login', (user) => {
-  console.log('User login:', user);
+events.on('user/login', (message) => {
+    console.log('User login:', message.payload);
+    console.log('Event type:', message.type);
+    console.log('Metadata:', message.meta);
 });
 
-// Publish event
+// Publish event - Method 1: Parameters
 events.emit('user/login', { id: 1, name: 'Alice' });
+
+// Publish event - Method 2: Message object
+events.emit({
+    type: 'user/login',
+    payload: { id: 1, name: 'Alice' },
+    meta: { timestamp: Date.now() },
+});
 ```
 
 # Guide
 
+## Event Message Format
+
+FastEvent uses a standardized message format for all events:
+
+```typescript
+type FastEventMessage<T = string, P = any, M = unknown> = {
+    type: T; // Event type
+    payload: P; // Event data
+    meta: M; // Event metadata
+};
+```
+
+Event listeners always receive this message object, providing consistent access to event data and metadata.
+
 ## Event Wildcards
 
 FastEvent supports two types of wildcards:
-- `*`: Matches a single path level
-- `**`: Matches multiple path levels
+
+-   `*`: Matches a single path level
+-   `**`: Matches multiple path levels
 
 ```typescript
 const events = new FastEvent();
 
 // Matches user/*/login
-events.on('user/*/login', (data) => {
-  console.log('Any user type login:', data);
+events.on('user/*/login', (message) => {
+    console.log('Any user type login:', message.payload);
 });
 
 // Matches all events under user
-events.on('user/**', (data) => {
-  console.log('All user-related events:', data);
+events.on('user/**', (message) => {
+    console.log('All user-related events:', message.payload);
 });
 
 // Trigger events
-events.emit('user/admin/login', { id: 1 });  // Both handlers will be called
-events.emit('user/admin/profile/update', { name: 'New' });  // Only ** handler will be called
+events.emit('user/admin/login', { id: 1 }); // Both handlers will be called
+events.emit('user/admin/profile/update', { name: 'New' }); // Only ** handler will be called
 ```
 
 ## Event Scoping
 
-Scopes allow you to handle events within specific namespaces:
+Scopes allow you to handle events within specific namespaces. Note that scopes share the same listener table with the parent emitter:
 
 ```typescript
 const events = new FastEvent();
@@ -77,13 +101,59 @@ const events = new FastEvent();
 // Create user-related scope
 const userScope = events.scope('user');
 
-// Subscribe to events within the scope
-userScope.on('login', (data) => {
-  console.log('User login:', data);
-});
+// These are equivalent:
+userScope.on('login', handler);
+events.on('user/login', handler);
+
+// These are also equivalent:
+userScope.emit('login', data);
+events.emit('user/login', data);
+
+// Clear all listeners in the scope
+userScope.offAll(); // Equivalent to events.offAll('user')
+```
+
+## Listener Options
+
+When subscribing to events, you can specify additional options:
+
+```typescript
+interface FastEventListenOptions {
+    // Number of times the listener should be called (0 for unlimited, 1 for once)
+    count?: number;
+    // Add the listener to the beginning of the listeners array
+    prepend?: boolean;
+}
+
+// Example: Listen for first 3 occurrences
+events.on('data', handler, { count: 3 });
+
+// Example: Ensure handler is called before other listeners
+events.on('important', handler, { prepend: true });
+```
+
+## Removing Listeners
+
+FastEvent provides multiple ways to remove listeners:
 
-// Equivalent to events.emit('user/login', data)
-userScope.emit('login', { id: 1 });
+```typescript
+// Remove specific listener
+events.off(listener);
+
+// Remove all listeners for an event
+events.off('user/login');
+
+// Remove specific listener for an event
+events.off('user/login', listener);
+
+// Remove all listeners with wildcard pattern
+events.off('user/*');
+
+// Remove all listeners
+events.offAll();
+
+// Remove all listeners under a prefix
+events.offAll('user');
 ```
 
 ## One-time Events
@@ -94,11 +164,11 @@ Use `once` to subscribe to events that trigger only once:
 const events = new FastEvent();
 
 events.once('startup', () => {
-  console.log('Application started');
+    console.log('Application started');
 });
 
-events.emit('startup');  // Output: Application started
-events.emit('startup');  // No output, listener has been removed
+// Equivalent to:
+events.on('startup', handler, { count: 1 });
 ```
 
 ## Asynchronous Events
@@ -109,15 +179,42 @@ Support for asynchronous event handling:
 const events = new FastEvent();
 
 events.on('data/fetch', async () => {
-  const response = await fetch('https://api.example.com/data');
-  return await response.json();
+    const response = await fetch('https://api.example.com/data');
+    return await response.json();
 });
 
-// Async event publishing
+// Async event publishing returns array of results/errors
 const results = await events.emitAsync('data/fetch');
 console.log('Results from all handlers:', results);
 ```
 
+## Listener Return Values
+
+Both `emit` and `emitAsync` methods return the results from all event listeners:
+
+```typescript
+const events = new FastEvent();
+
+// Synchronous listeners with return values
+events.on('calculate', () => 1);
+events.on('calculate', () => 2);
+events.on('calculate', () => 3);
+
+// Get array of return values
+const results = events.emit('calculate');
+console.log('Results:', results); // [1, 2, 3]
+
+// Asynchronous listeners
+events.on('process', async () => 'result 1');
+events.on('process', async () => 'result 2');
+
+// Get array of resolved values/errors
+const asyncResults = await events.emitAsync('process');
+console.log('Async results:', asyncResults); // ['result 1', 'result 2']
+```
+
+For asynchronous events, `emitAsync` will wait for all listeners to complete and return an array containing either the resolved values or error objects if a listener fails.
+
 ## Event Waiting
 
 Use `waitFor` to wait for specific events:
@@ -126,13 +223,13 @@ Use `waitFor` to wait for specific events:
 const events = new FastEvent();
 
 async function waitForLogin() {
-  try {
-    // Wait for login event with 5 seconds timeout
-    const userData = await events.waitFor('user/login', 5000);
-    console.log('User logged in:', userData);
-  } catch (error) {
-    console.log('Login wait timeout');
-  }
+    try {
+        // Wait for login event with 5 seconds timeout
+        const userData = await events.waitFor('user/login', 5000);
+        console.log('User logged in:', userData);
+    } catch (error) {
+        console.log('Login wait timeout');
+    }
 }
 
 waitForLogin();
@@ -151,8 +248,8 @@ const events = new FastEvent();
 events.emit('config/update', { theme: 'dark' }, true);
 
 // Later subscribers will immediately receive the retained data
-events.on('config/update', (config) => {
-  console.log('Config:', config);  // Immediately outputs: Config: { theme: 'dark' }
+events.on('config/update', (message) => {
+    console.log('Config:', message.payload); // Immediately outputs: Config: { theme: 'dark' }
 });
 ```
 
@@ -164,7 +261,7 @@ By default, '/' is used as the event path delimiter, but you can use custom deli
 
 ```typescript
 const events = new FastEvent({
-  delimiter: '.'
+    delimiter: '.',
 });
 ```
 
@@ -175,12 +272,12 @@ Use `onAny` to listen to all events:
 ```typescript
 const events = new FastEvent();
 
-events.onAny((data, meta) => {
-  console.log(`Event ${meta.type} triggered:`, data);
+events.onAny((message) => {
+    console.log(`Event ${message.type} triggered:`, message.payload);
 });
 
-events.emit('user/login', { id: 1 });  // Output: Event user/login triggered: { id: 1 }
-events.emit('system/error', 'Connection failed');  // Output: Event system/error triggered: Connection failed
+// Can also use prepend option
+events.onAny(handler, { prepend: true });
 ```
 
 ## Metadata (Meta)
@@ -193,15 +290,15 @@ Set global metadata when creating a FastEvent instance:
 
 ```typescript
 const events = new FastEvent({
-  meta: {
-    version: '1.0',
-    environment: 'production'
-  }
+    meta: {
+        version: '1.0',
+        environment: 'production',
+    },
 });
 
-events.on('user/login', (data, meta) => {
-  console.log('Event data:', data);
-  console.log('Metadata:', meta);  // Contains type, version, and environment
+events.on('user/login', (message) => {
+    console.log('Event data:', message.payload);
+    console.log('Metadata:', message.meta); // Contains type, version, and environment
 });
 ```
 
@@ -211,20 +308,21 @@ Additional metadata can be passed when publishing events, which will be merged w
 
 ```typescript
 const events = new FastEvent({
-  meta: { app: 'MyApp' }
+    meta: { app: 'MyApp' },
 });
 
 // Add specific metadata when publishing event
-events.emit('order/create', 
-  { orderId: '123' },  // Event data
-  false,  // Don't retain
-  { timestamp: Date.now() }  // Event-specific metadata
+events.emit(
+    'order/create',
+    { orderId: '123' }, // Event data
+    false, // Don't retain
+    { timestamp: Date.now() }, // Event-specific metadata
 );
 
 // Listener receives merged metadata
-events.on('order/create', (data, meta) => {
-  console.log('Order:', data);  // { orderId: '123' }
-  console.log('Metadata:', meta);  // { type: 'order/create', app: 'MyApp', timestamp: ... }
+events.on('order/create', (message) => {
+    console.log('Order:', message.payload); // { orderId: '123' }
+    console.log('Metadata:', message.meta); // { type: 'order/create', app: 'MyApp', timestamp: ... }
 });
 ```
 
@@ -234,20 +332,114 @@ FastEvent provides error handling mechanisms:
 
 ```typescript
 const events = new FastEvent({
-  ignoreErrors: true,  // Default is true, won't throw errors
-  onListenerError: (type, error) => {
-    console.error(`Error handling event ${type}:`, error);
-  }
+    ignoreErrors: true, // Default is true, won't throw errors
+    onListenerError: (type, error) => {
+        console.error(`Error handling event ${type}:`, error);
+    },
 });
 
 events.on('process', () => {
-  throw new Error('Processing failed');
+    throw new Error('Processing failed');
 });
 
 // Won't throw error, will trigger onListenerError instead
 events.emit('process');
 ```
 
+## Generic Parameters
+
+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
+interface MyEvents {
+    'user/login': { id: number; name: string };
+    'user/logout': { id: number };
+}
+
+// Create typed event emitter
+const events = new FastEvent<MyEvents>();
+
+// Type checking for event names and payload
+events.on('user/login', (message) => {
+    // message.payload is typed as { id: number; name: string }
+    const { id, name } = message.payload;
+});
+
+// Error: wrong event name
+events.emit('wrong/event', {});
+
+// Error: wrong payload type
+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:
@@ -255,18 +447,18 @@ The FastEvent constructor supports multiple options:
 ```typescript
 const events = new FastEvent({
   // Event path delimiter, default is '/'
-  delimiter: '.',  
+  delimiter: '.',
   // Context for event handlers
-  context: null,  
+  context: null,
   // Metadata, passed to all event handlers
   meta: { ... },
-  
+
   // Error handling
   ignoreErrors: true,
   onListenerError: (type, error) => {
     console.error(`Event error:`, type, error);
   },
-  
+
   // Callbacks for listener addition/removal
   onAddListener: (path, listener) => {
     console.log('Listener added:', path);
@@ -274,9 +466,26 @@ 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,
 });
 ```
 
 # Performance
 
-![](./bench.png)
+![](./bench.png)