fastevent 1.1.3 → 2.0.0

package/readme.md

@@ -48,10 +48,105 @@ events.emit({
     payload: { id: 1, name: 'Alice' },
     meta: { timestamp: Date.now() },
 });
+
+// Using TypeScript with type safety
+interface MyEvents {
+    'user/login': { id: number; name: string };
+    'user/logout': { id: number };
+}
+
+const typedEvents = new FastEvent<MyEvents>();
+
+// TypeScript will enforce correct event types and payloads
+typedEvents.on('user/login', (message) => {
+    const { id, name } = message.payload; // Properly typed
+});
 ```
 
 # Guide
 
+## Event Triggering
+
+FastEvent provides flexible ways to trigger events with different parameter combinations:
+
+### Basic Event Triggering
+
+```typescript
+const events = new FastEvent();
+
+// Method 1: Parameters form
+events.emit('user/login', { id: 1, name: 'Alice' });
+
+// Method 2: Message object form
+events.emit({
+    type: 'user/login',
+    payload: { id: 1, name: 'Alice' },
+    meta: { timestamp: Date.now() },
+});
+```
+
+### Retained Events
+
+Set `retain=true` to store the event for new subscribers:
+
+```typescript
+// Emit and retain the event
+events.emit('config/update', { theme: 'dark' }, true);
+
+// Later subscribers will immediately receive the retained event
+events.on('config/update', (message) => {
+    console.log('Config:', message.payload); // { theme: 'dark' }
+});
+```
+
+### Event Metadata
+
+Metadata can be provided at different levels and will be merged:
+
+```typescript
+const events = new FastEvent({
+    meta: { app: 'MyApp' }, // Global metadata
+});
+
+// Event-specific metadata
+events.emit('order/create', { id: '123' }, false, {
+    timestamp: Date.now(),
+});
+
+// Listener receives merged metadata:
+// { type: 'order/create', app: 'MyApp', timestamp: ... }
+```
+
+### Return Values
+
+`emit()` returns an array of listener results:
+
+```typescript
+events.on('calculate', () => 1);
+events.on('calculate', () => 2);
+
+const results = events.emit('calculate');
+console.log(results); // [1, 2]
+```
+
+### Type-safe Event Triggering
+
+With TypeScript, event payloads are type-checked:
+
+```typescript
+interface MyEvents {
+    'user/login': { id: number; name: string };
+}
+
+const events = new FastEvent<MyEvents>();
+
+// Valid - payload matches type
+events.emit('user/login', { id: 1, name: 'Alice' });
+
+// Error - payload type mismatch
+events.emit('user/login', { id: '1' }); // TypeScript error
+```
+
 ## Event Message Format
 
 FastEvent uses a standardized message format for all events:
@@ -111,8 +206,45 @@ events.emit('user/login', data);
 
 // Clear all listeners in the scope
 userScope.offAll(); // Equivalent to events.offAll('user')
+
+// Nested scopes
+const profileScope = userScope.scope('profile');
+profileScope.on('update', (message) => {
+    // Will receive events emitted as 'user/profile/update'
+    console.log('Profile update:', message.payload);
+});
+
+// Scope with metadata
+const adminScope = events.scope('admin', {
+    meta: { role: 'admin' },
+    context: { adminId: 1 },
+});
+
+adminScope.on('action', function (message) {
+    console.log('Admin meta:', message.meta); // Contains { role: 'admin' }
+    console.log('Context:', this.adminId); // Access to scope context
+});
+
+// Type-safe scopes
+interface UserEvents {
+    login: { id: number };
+    logout: { id: number };
+}
+
+const typedUserScope = events.scope<'user', UserEvents>('user');
+typedUserScope.on('login', (message) => {
+    const { id } = message.payload; // Properly typed as { id: number }
+});
 ```
 
+Scopes provide several benefits:
+
+1. Namespace organization - Group related events under a common prefix
+2. Code organization - Separate event handling logic by domain
+3. Metadata inheritance - Share common metadata across related events
+4. Context binding - Provide specific execution context for event handlers
+5. Type safety - Enforce type checking for scoped events
+
 ## Listener Options
 
 When subscribing to events, you can specify additional options:
@@ -253,18 +385,146 @@ events.on('config/update', (message) => {
 });
 ```
 
-## Multi-level Events
+## Multi-level Events and Wildcards
 
-Support for publishing and subscribing to multi-level events.
+FastEvent supports hierarchical event structures with powerful wildcard matching capabilities.
 
-By default, '/' is used as the event path delimiter, but you can use custom delimiters:
+### Event Path Structure
+
+Events can be organized in a hierarchical structure using path delimiters (default is '/'):
 
 ```typescript
-const events = new FastEvent({
+const events = new FastEvent();
+
+// Basic multi-level events
+events.on('user/profile/update', handler);
+events.on('user/settings/theme/change', handler);
+
+// Custom delimiter
+const customEvents = new FastEvent({
     delimiter: '.',
 });
+customEvents.on('user.profile.update', handler);
+```
+
+### Wildcard Patterns
+
+FastEvent supports two types of wildcards:
+
+1. Single-level wildcard (`*`):
+    - Matches exactly one level in the event path
+    - Can be used at any level in the path
+
+```typescript
+// Match any user type
+events.on('user/*/login', (message) => {
+    console.log('User type:', message.type.split('/')[1]);
+    // Matches: user/admin/login, user/guest/login, etc.
+});
+
+// Match any action
+events.on('api/users/*/action/*', (message) => {
+    const [, , userId, , action] = message.type.split('/');
+    console.log(`User ${userId} performed ${action}`);
+    // Matches: api/users/123/action/update, api/users/456/action/delete, etc.
+});
+```
+
+2. Multi-level wildcard (`**`):
+    - Matches zero or more levels in the event path
+    - Must be used at the end of the path pattern
+
+```typescript
+// Match all user-related events
+events.on('user/**', (message) => {
+    console.log('User event:', message.type);
+    // Matches: user/login, user/profile/update, user/settings/theme/change, etc.
+});
+
+// Match all API events
+events.on('api/**', (message) => {
+    console.log('API event:', message.type, message.payload);
+    // Matches: api/get, api/users/create, api/posts/123/comments/add, etc.
+});
 ```
 
+### Advanced Wildcard Usage
+
+```typescript
+const events = new FastEvent();
+
+// Using single-level wildcards
+events.on('service/*/user/update', (message) => {
+    // Matches patterns like:
+    // service/auth/user/update
+    // service/admin/user/update
+    const parts = message.type.split('/');
+    const serviceType = parts[1];
+    console.log(`${serviceType} service user update:`, message.payload);
+});
+
+// Using multi-level wildcard at the end
+events.on('service/auth/**', (message) => {
+    // Matches patterns like:
+    // service/auth/user/update
+    // service/auth/user/profile/update
+    // service/auth/settings/theme/change
+    console.log('Auth service event:', message.type, message.payload);
+});
+
+// Type-safe events with TypeScript
+interface ApiEvents {
+    'api/users/profile': { userId: string; data: any };
+    'api/posts/comments': { postId: string; commentId: string; text: string };
+}
+
+const typedEvents = new FastEvent<ApiEvents>();
+
+// Exact match with type safety
+typedEvents.on('api/users/profile', (message) => {
+    const { userId, data } = message.payload; // Properly typed
+});
+
+// Wildcard listeners still work but lose some type safety
+typedEvents.on('api/*', (message) => {
+    // message.payload type is any here
+    console.log('API event:', message.type);
+});
+
+// Wildcard event monitoring
+events.on('**', (message) => {
+    console.log('Event intercepted:', {
+        type: message.type,
+        timestamp: new Date(),
+        payload: message.payload,
+    });
+});
+
+// Example usage
+events.emit('service/auth/user/profile/update', { name: 'John' });
+events.emit('api/users/123/profile', { userId: '123', data: { age: 30 } });
+```
+
+### Important Notes
+
+1. Wildcard Limitations:
+
+    - `**` wildcard must be at the end of the path
+    - `*` can be used multiple times in a path
+    - Wildcards cannot be combined in a single segment (e.g., 'a/\*\*/b' is invalid)
+
+2. Performance Considerations:
+
+    - Specific patterns (without wildcards) are matched faster
+    - `*` wildcards are more efficient than `**`
+    - Excessive use of `**` wildcards may impact performance
+
+3. Best Practices:
+    - Use specific patterns when possible
+    - Limit the use of `**` wildcards
+    - Consider the event hierarchy carefully
+    - Use TypeScript interfaces for type safety
+
 ## Global Event Listening
 
 Use `onAny` to listen to all events:
@@ -282,7 +542,7 @@ events.onAny(handler, { prepend: true });
 
 ## Metadata (Meta)
 
-Metadata is a mechanism for providing additional context information for events. You can set metadata globally or add specific metadata for individual events.
+Metadata is a mechanism for providing additional context information for events. You can set metadata at different levels: globally, scope-level, or event-specific.
 
 ### Global Metadata
 
@@ -302,30 +562,83 @@ events.on('user/login', (message) => {
 });
 ```
 
+### Scope Metadata
+
+When creating a scope, you can provide metadata that will be merged with global metadata:
+
+```typescript
+const events = new FastEvent({
+    meta: { app: 'MyApp' },
+});
+
+const userScope = events.scope('user', {
+    meta: { domain: 'user' },
+});
+
+userScope.on('login', (message) => {
+    console.log('Metadata:', message.meta);
+    // { type: 'user/login', app: 'MyApp', domain: 'user' }
+});
+
+// Nested scopes merge metadata recursively
+const profileScope = userScope.scope('profile', {
+    meta: { section: 'profile' },
+});
+
+profileScope.on('update', (message) => {
+    console.log('Metadata:', message.meta);
+    // { type: 'user/profile/update', app: 'MyApp', domain: 'user', section: 'profile' }
+});
+```
+
 ### Event-specific Metadata
 
-Additional metadata can be passed when publishing events, which will be merged with global metadata:
+Additional metadata can be passed when publishing events, which will be merged with higher-level metadata:
 
 ```typescript
 const events = new FastEvent({
     meta: { app: 'MyApp' },
 });
 
+const userScope = events.scope('user', {
+    meta: { domain: 'user' },
+});
+
 // Add specific metadata when publishing event
-events.emit(
-    'order/create',
-    { orderId: '123' }, // Event data
+userScope.emit(
+    'login',
+    { userId: '123' }, // Event data
     false, // Don't retain
     { timestamp: Date.now() }, // Event-specific metadata
 );
 
 // Listener receives merged metadata
-events.on('order/create', (message) => {
-    console.log('Order:', message.payload); // { orderId: '123' }
-    console.log('Metadata:', message.meta); // { type: 'order/create', app: 'MyApp', timestamp: ... }
+userScope.on('login', (message) => {
+    console.log('Metadata:', message.meta);
+    // { type: 'user/login', app: 'MyApp', domain: 'user', timestamp: ... }
 });
 ```
 
+### Metadata Merge Rules
+
+1. Priority (highest to lowest):
+
+    - Event-specific metadata
+    - Scope metadata (innermost to outermost)
+    - Global metadata
+    - System metadata (type is always added)
+
+2. Merge behavior:
+
+    - Shallow merge (top-level properties only)
+    - Later values override earlier ones
+    - No deep merging of nested objects
+
+3. Special cases:
+    - `type` is always preserved as the full event path
+    - `undefined` values will remove the property from the result
+    - Arrays are replaced, not concatenated
+
 ## Error Handling
 
 FastEvent provides error handling mechanisms:
@@ -440,51 +753,205 @@ events.emit('data/string', 'hello');
 events.emit('data/object', { value: true });
 ```
 
-## Custom Options
+## Event Hooks
+
+FastEvent provides several hooks for monitoring and debugging the event system:
+
+```typescript
+const events = new FastEvent({
+    // Called when a new listener is added
+    onAddListener: (path: string[], listener: Function) => {
+        console.log('New listener added for:', path.join('/'));
+    },
+
+    // Called when a listener is removed
+    onRemoveListener: (path: string[], listener: Function) => {
+        console.log('Listener removed from:', path.join('/'));
+    },
+
+    // Called when listeners are cleared
+    onClearListeners: () => {
+        console.log('All listeners cleared');
+    },
+
+    // Called when a listener throws an error
+    onListenerError: (type: string, error: Error) => {
+        console.error(`Error in listener for ${type}:`, error);
+    },
+
+    // Called after listeners are executed (debug mode only)
+    onExecuteListener: (message, returns, listeners) => {
+        console.log('Event executed:', {
+            type: message.type,
+            payload: message.payload,
+            results: returns,
+            listenerCount: listeners.length,
+        });
+    },
+});
+```
+
+These hooks provide valuable insights into the event system's operation:
+
+1. `onAddListener`: Monitor listener registration
+
+    - Called whenever a new event listener is added
+    - Receives the event path array and listener function
+    - Useful for tracking event subscriptions
 
-The FastEvent constructor supports multiple options:
+2. `onRemoveListener`: Track listener removal
+
+    - Called when a listener is removed
+    - Helps monitor event unsubscription patterns
+    - Receives the same parameters as onAddListener
+
+3. `onClearListeners`: Notifies of bulk listener removal
+
+    - Called when offAll() is invoked
+    - Useful for cleanup monitoring
+    - No parameters provided
+
+4. `onListenerError`: Error handling hook
+
+    - Called when a listener throws an error
+    - Receives the event type and error object
+    - Enables centralized error handling
+    - Only called if ignoreErrors is true
+
+5. `onExecuteListener`: Execution monitoring (debug mode)
+    - Only active when debug: true is set
+    - Provides detailed execution information
+    - Includes message, return values, and listener list
+    - Useful for debugging and performance monitoring
+
+Example usage:
 
 ```typescript
 const events = new FastEvent({
-  // Event path delimiter, default is '/'
-  delimiter: '.',
-  // Context for event handlers
-  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);
-  },
-  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
+    debug: true, // Enable debug mode for onExecuteListener
+    onAddListener: (path, listener) => {
+        console.log(`Listener added for ${path.join('/')}`);
+        // Track listener count or patterns
+    },
+    onListenerError: (type, error) => {
+        console.error(`Error in ${type}:`, error);
+        // Log to monitoring system
+    },
+    onExecuteListener: (message, returns, listeners) => {
+        console.log(`Event ${message.type} executed:`, {
+            executionTime: Date.now(),
+            listenerCount: listeners.length,
+            results: returns,
+        });
+        // Monitor event execution patterns
+    },
+});
+
+// Example events that trigger hooks
+events.on('user/login', () => {
+    // onAddListener will be called
+});
+
+events.on('data/process', () => {
+    throw new Error('Process failed');
+    // onListenerError will be called
+});
+
+events.emit('user/login', { id: 1 });
+// onExecuteListener will be called (if debug: true)
+
+events.offAll();
+// onClearListeners will be called
+```
+
+# Parameters
+
+FastEvent constructor accepts the following configuration options:
+
+````typescript
+interface FastEventOptions<Meta = Record<string, any>, Context = any> {
+    /**
+     * Unique identifier for the emitter instance
+     * @default Randomly generated string
+     */
+    id?: string;
+
+    /**
+     * Whether to enable debug mode
+     * @default false
+     * @remarks When true, events can be viewed in Redux DevTools
+     */
+    debug?: boolean;
+
+    /**
+     * Delimiter for event path segments
+     * @default '/'
+     * @example
+     * ```ts
+     * new FastEvent({ delimiter: '.' }); // Use dot as delimiter
+     * ```
+     */
+    delimiter?: string;
+
+    /**
+     * Default execution context for event handlers
+     * @default null
+     */
+    context?: Context;
+
+    /**
+     * Whether to ignore listener errors
+     * @default true
+     */
+    ignoreErrors?: boolean;
+
+    /**
+     * Global metadata attached to all events
+     * @default undefined
+     */
+    meta?: Meta;
+
+    /**
+     * Callback when a listener is added
+     * @param path - Array of path segments
+     * @param listener - The listener function
+     */
+    onAddListener?: (path: string[], listener: Function) => void;
+
+    /**
+     * Callback when a listener is removed
+     * @param path - Array of path segments
+     * @param listener - The listener function
+     */
+    onRemoveListener?: (path: string[], listener: Function) => void;
+
+    /**
+     * Callback when all listeners are cleared
+     */
+    onClearListeners?: () => void;
+
+    /**
+     * Callback when a listener throws an error
+     * @param type - Event type
+     * @param error - The error object
+     */
+    onListenerError?: (type: string, error: Error) => void;
+
+    /**
+     * Callback after listeners are executed (debug mode only)
+     * @param message - Event message
+     * @param returns - Array of listener return values
+     * @param listeners - Array of executed listeners
+     */
+    onExecuteListener?: (message: FastEventMessage, returns: any[], listeners: (FastEventListener<any, any, any> | [FastEventListener<any, any>, number])[]) => void;
+}
+
+// Debug mode usage
 import 'fastevent/devtools';
 const emitter = new FastEvent({
-    debug: true,
+    debug: true, // Enable debug mode to view events in Redux DevTools
 });
-```
+````
 
 # Performance
 

package/.changeset/README.md

@@ -1,8 +0,0 @@
-# Changesets
-
-Hello and welcome! This folder has been automatically generated by `@changesets/cli`, a build tool that works
-with multi-package repos, or single-package repos to help you version and publish your code. You can
-find the full documentation for it [in our repository](https://github.com/changesets/changesets)
-
-We have a quick list of common questions to get you started engaging with this project in
-[our documentation](https://github.com/changesets/changesets/blob/main/docs/common-questions.md)

package/.changeset/config.json

@@ -1,11 +0,0 @@
-{
-  "$schema": "https://unpkg.com/@changesets/config@3.1.1/schema.json",
-  "changelog": "@changesets/cli/changelog",
-  "commit": true,
-  "fixed": [],
-  "linked": [],
-  "access": "public",
-  "baseBranch": "master",
-  "updateInternalDependencies": "patch",
-  "ignore": []
-}