fastevent 2.5.0 → 2.5.1

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "fastevent",
-    "version": "2.5.0",
+    "version": "2.5.1",
     "description": "The Ultimate Event Trigger Library – Fast, Feature-Rich, Battle-Tested!",
     "main": "dist/index.js",
     "module": "dist/index.mjs",

package/readme.md

@@ -55,7 +55,7 @@ events.onAny((message) => {
 Listener functions receive a `Message` object that contains the following properties:
 
 ```ts
-events.on('user/login', (message) => {
+events.on("user/login", (message) => {
     // {
     //     type: 'user/login', // Event name
     //     payload: { id: 1 }, // Event data
@@ -72,13 +72,13 @@ Retain the last event data, so subsequent subscribers can immediately receive th
 const events = new FastEvent();
 
 // Publish and retain event
-events.emit('config/theme', { dark: true }, true);
+events.emit("config/theme", { dark: true }, true);
 // Equivalent to
-events.emit('config/theme', { dark: true }, { retain: true });
+events.emit("config/theme", { dark: true }, { retain: true });
 
 // Subsequent subscribers immediately receive the retained value
-events.on('config/theme', (message) => {
-    console.log('Theme:', message.payload); // Immediately outputs: { dark: true }
+events.on("config/theme", (message) => {
+    console.log("Theme:", message.payload); // Immediately outputs: { dark: true }
 });
 ```
 
@@ -86,25 +86,25 @@ events.on('config/theme', (message) => {
 
 `FastEvent` supports hierarchical event publishing and subscription.
 
--   The default event hierarchy delimiter is `/`, which can be modified via `options.delimiter`
--   Two types of wildcards are supported when subscribing to events: `*` matches a single path level, `**` matches multiple path levels (only used at the end of event names)
+- The default event hierarchy delimiter is `/`, which can be modified via `options.delimiter`
+- Two types of wildcards are supported when subscribing to events: `*` matches a single path level, `**` matches multiple path levels (only used at the end of event names)
 
 ```typescript
 const events = new FastEvent();
 
 // Match user/*/login
-events.on('user/*/login', (message) => {
-    console.log('Any user type login:', message.payload);
+events.on("user/*/login", (message) => {
+    console.log("Any user type login:", message.payload);
 });
 
 // Match all events under user
-events.on('user/**', (message) => {
-    console.log('All user-related events:', message.payload);
+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 the ** 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 the ** handler will be called
 ```
 
 ## Removing Listeners
@@ -113,21 +113,21 @@ events.emit('user/admin/profile/update', { name: 'New' }); // Only the ** handle
 
 ```typescript
 // Return a subscriber object to remove the listener, recommended approach
-const subscriber = events.on('user/login', handler);
+const subscriber = events.on("user/login", handler);
 subscriber.off();
 
 // Remove a specific listener
 events.off(listener);
 // Remove all listeners for a specific event
-events.off('user/login');
+events.off("user/login");
 // Remove a specific listener for a specific event
-events.off('user/login', listener);
+events.off("user/login", listener);
 // Remove listeners using wildcard patterns
-events.off('user/*');
+events.off("user/*");
 // Remove all listeners
 events.offAll();
 // Remove all listeners under a specific prefix
-events.offAll('user');
+events.offAll("user");
 ```
 
 ## Event Scopes
@@ -140,15 +140,15 @@ Scopes allow you to handle events within a specific namespace.
 const events = new FastEvent();
 
 // Create a user-related scope
-const userScope = events.scope('user');
+const userScope = events.scope("user");
 
 // The following two approaches are equivalent:
-userScope.on('login', handler);
-events.on('user/login', handler);
+userScope.on("login", handler);
+events.on("user/login", handler);
 
 // The following two approaches are also equivalent:
-userScope.emit('login', data);
-events.emit('user/login', data);
+userScope.emit("login", data);
+events.emit("user/login", data);
 
 // Clear all listeners in the scope
 userScope.offAll(); // Equivalent to events.offAll('user')
@@ -164,16 +164,16 @@ const events = new FastEvent();
 async function waitForLogin() {
     try {
         // Wait for login event with a 5-second timeout
-        const userData = await events.waitFor('user/login', 5000);
-        console.log('User logged in:', userData);
+        const userData = await events.waitFor("user/login", 5000);
+        console.log("User logged in:", userData);
     } catch (error) {
-        console.log('Login wait timeout');
+        console.log("Login wait timeout");
     }
 }
 
 waitForLogin();
 // Later trigger the login event
-events.emit('user/login', { id: 1, name: 'Alice' });
+events.emit("user/login", { id: 1, name: "Alice" });
 ```
 
 ## Event Hooks
@@ -184,23 +184,24 @@ events.emit('user/login', { id: 1, name: 'Alice' });
 const otherEvents = new FastEvent();
 const events = new FastEvent({
     // Called when a new listener is added
-    onAddListener: (type, listener, options) => {
-        console.log('Added new listener:', type);
+    onAddBeforeListener: (type, listener, options) => {
+        console.log("Added new listener:", type);
         // Return false to prevent the listener from being added
         return false;
         // Can directly return a FastEventSubscriber
         // For example: transfer events starting with `@` to another FastEvent
-        if (type.startsWith('@')) {
+        if (type.startsWith("@")) {
             return otherEvents.on(type, listener, options);
         }
     },
+    onAddBeforeListener
     // Called when a listener is removed
     onRemoveListener: (type, listener) => {
-        console.log('Removed listener:', type);
+        console.log("Removed listener:", type);
     },
     // Called when listeners are cleared
     onClearListeners: () => {
-        console.log('All listeners cleared');
+        console.log("All listeners cleared");
     },
     // Called when a listener throws an error
     onListenerError: (error, listener, message, args) => {
@@ -208,19 +209,19 @@ const events = new FastEvent({
     },
     // Called before a listener executes
     onBeforeExecuteListener: (message, args) => {
-        console.log('Before executing event listener');
+        console.log("Before executing event listener");
         // Return false to prevent listener execution
         return false;
 
         // Forward events to another FastEvent
         // For example: forward events starting with `@` to another FastEvent
-        if (type.startsWith('@')) {
+        if (type.startsWith("@")) {
             return otherEvents.emit(message.type);
         }
     },
     // Called after a listener executes
     onAfterExecuteListener: (message, returns, listeners) => {
-        console.log('After executing event listener');
+        console.log("After executing event listener");
         // Can intercept and modify return values here
     },
 });
@@ -233,20 +234,20 @@ By default, all listeners are executed in parallel when an event is triggered.
 `FastEvent` provides powerful listener execution mechanisms that allow developers to control how listeners are executed.
 
 ```typescript
-import { race } from 'fastevent/executors';
+import { race } from "fastevent/executors";
 const events = new FastEvent({
     executor: race(),
 });
 
-events.on('task/start', async () => {
+events.on("task/start", async () => {
     /* Time-consuming operation 1 */
 });
-events.on('task/start', async () => {
+events.on("task/start", async () => {
     /* Time-consuming operation 2 */
 });
 
 // The two listeners will execute in parallel, returning the fastest result
-await events.emitAsync('task/start');
+await events.emitAsync("task/start");
 ```
 
 **Built-in Support**:
@@ -268,14 +269,14 @@ await events.emitAsync('task/start');
 Listener pipes are used to wrap listener functions during event subscription to implement various common advanced features.
 
 ```typescript
-import { queue } from 'fastevent/pipes';
+import { queue } from "fastevent/pipes";
 const events = new FastEvent();
 
 // default queue size is 10
 events.on(
-    'data/update',
+    "data/update",
     (data) => {
-        console.log('Processing data:', data);
+        console.log("Processing data:", data);
     },
     {
         pipes: [queue({ size: 10 })],
@@ -303,29 +304,29 @@ const otherEmitter = new FastEvent();
 const emitter = new FastEvent({
     onAddListener: (type, listener, options) => {
         // Subscription forwarding rule: when event name starts with `@/`, forward subscription to another `FastEvent` instance
-        if (type.startsWith('@/')) {
+        if (type.startsWith("@/")) {
             return otherEmitter.on(type.substring(2), listener, options);
         }
     },
     onBeforeExecuteListener: (message, args) => {
         // Event forwarding rule: when event name starts with `@/`, publish to another `FastEvent` instance
-        if (message.type.startsWith('@/')) {
+        if (message.type.startsWith("@/")) {
             message.type = message.type.substring(2);
             return otherEmitter.emit(message, args);
         }
     },
 });
 const events: any[] = [];
-otherEmitter.on('data', ({ payload }) => {
+otherEmitter.on("data", ({ payload }) => {
     events.push(payload);
 });
 // Subscribe to otherEmitter's data event
-emitter.on('@/data', ({ payload }) => {
+emitter.on("@/data", ({ payload }) => {
     expect(payload).toBe(1);
     events.push(payload);
 });
 // Publish data event to otherEmitter
-const subscriber = emitter.emit('@/data', 1);
+const subscriber = emitter.emit("@/data", 1);
 subscriber.off();
 ```
 
@@ -338,32 +339,32 @@ You can set metadata at different levels: global, scope level, or event-specific
 ```typescript
 const events = new FastEvent({
     meta: {
-        version: '1.0',
-        environment: 'production',
+        version: "1.0",
+        environment: "production",
     },
 });
 
-events.on('user/login', (message) => {
-    console.log('Event data:', message.payload);
-    console.log('Metadata:', message.meta); // Includes type, version, and environment
+events.on("user/login", (message) => {
+    console.log("Event data:", message.payload);
+    console.log("Metadata:", message.meta); // Includes type, version, and environment
 });
 
 // Using scope-level metadata
-const userScope = events.scope('user', {
-    meta: { domain: 'user' },
+const userScope = events.scope("user", {
+    meta: { domain: "user" },
 });
 // Add specific metadata when publishing events
 userScope.emit(
-    'login',
-    { userId: '123' },
+    "login",
+    { userId: "123" },
     {
         meta: { timestamp: Date.now() }, // Event-specific metadata
     },
 );
 
 // Listeners receive merged metadata
-userScope.on('login', (message) => {
-    console.log('Metadata:', message.meta);
+userScope.on("login", (message) => {
+    console.log("Metadata:", message.meta);
 });
 ```
 
@@ -374,22 +375,22 @@ userScope.on('login', (message) => {
 ```typescript
 // Define events with different payload types
 interface ComplexEvents {
-    'data/number': number;
-    'data/string': string;
-    'data/object': { value: any };
+    "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) => {
+events.on("data/number", (message) => {
     const sum = message.payload + 1; // payload type is number
 });
 
 // All event emissions are type-checked
-events.emit('data/number', 42);
-events.emit('data/string', 'hello');
-events.emit('data/object', { value: true });
+events.emit("data/number", 42);
+events.emit("data/string", "hello");
+events.emit("data/object", { value: true });
 ```
 
 ## Unit Testing