@aionbuilders/pulse 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Killian Di Vincenzo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,538 @@
+# @aionbuilders/pulse
+
+[![NPM Version](https://img.shields.io/npm/v/@aionbuilders/pulse.svg)](https://www.npmjs.com/package/@aionbuilders/pulse)
+[![Bundle Size](https://img.shields.io/bundlephobia/minzip/@aionbuilders/pulse)](https://bundlephobia.com/package/@aionbuilders/pulse)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+
+> A powerful, lightweight event system with pattern matching, middleware, and timeout support for JavaScript applications.
+
+Pulse is a sophisticated event system that extends beyond basic pub/sub patterns. It provides hierarchical topic structures with support for wildcards, middleware chains, response handling, and automatic timeout management.
+
+## Features
+
+- 🔍 **Hierarchical topic matching** with single (`*`), zero-or-more (`**`), and one-or-more (`++`) wildcards
+- ⚡ **Middleware support** for transforming and filtering events
+- ⏱️ **Built-in timeout handling** for asynchronous operations (default 5s)
+- 🔄 **Promise-based API** for modern JavaScript applications
+- 🧠 **Smart event routing** based on pattern matching
+- 💾 **Context management** for storing data within events
+- 💪 **Typed with JSDoc** for excellent IDE integration
+- 🪶 **Lightweight** with zero dependencies
+- 🧪 **Thoroughly tested** with extensive unit tests
+- 🛡️ **Unified error handling** across middlewares and listeners
+
+## Installation
+
+```bash
+# Using npm
+npm install @aionbuilders/pulse
+
+# Using yarn
+yarn add @aionbuilders/pulse
+
+# Using pnpm
+pnpm add @aionbuilders/pulse
+
+# Using bun
+bun add @aionbuilders/pulse
+```
+
+## Quick Start
+
+```javascript
+import { Pulse } from '@aionbuilders/pulse';
+
+// Create a new Pulse instance
+const pulse = new Pulse();
+
+// Subscribe to events
+pulse.on('user:created', ({ event }) => {
+  console.log(`New user created: ${event.data.username}`);
+  event.respond({ success: true });
+});
+
+// Subscribe with wildcards
+pulse.on('user:*:updated', ({ event }) => {
+  console.log(`User property updated: ${event.topic}`);
+});
+
+// Add middleware
+pulse.use('user:**', async ({ event }, next) => {
+  console.log(`[${new Date().toISOString()}] User event: ${event.topic}`);
+  // Call next to continue the middleware chain
+  await next();
+  console.log('Event processing completed');
+});
+
+// Emit events
+const event = await pulse.emit('user:created', {
+  username: 'john_doe',
+  email: 'john@example.com'
+});
+
+console.log(event.responses[0]); // { success: true }
+```
+
+## Core Concepts
+
+### Topics and Patterns
+
+Topics in Pulse are hierarchical, colon-separated strings:
+
+```
+namespace:entity:action
+```
+
+For example:
+- `user:login`
+- `chat:message:sent`
+- `system:database:connected`
+
+Listeners can use patterns to match multiple topics:
+
+- `*`: Matches exactly one section
+  - `user:*` matches `user:login` and `user:logout` but not `user:profile:view`
+
+- `**`: Matches zero or more sections
+  - `user:**` matches `user` (0 sections), `user:login` (1 section), and `user:profile:view` (2 sections)
+  - `**:login` matches `login` (0 sections before), `user:login`, `app:user:login`
+  - `user:**:deleted` matches `user:deleted` (0 sections between), `user:account:deleted`, etc.
+
+- `++`: Matches one or more sections (new in v2.1.3)
+  - `user:++` matches `user:login` and `user:profile:view` but NOT `user`
+  - `++:login` matches `user:login` and `app:user:login` but NOT `login`
+  - `user:++:deleted` matches `user:account:deleted` but NOT `user:deleted`
+
+### Events
+
+When you emit a topic, Pulse creates an Event object containing:
+
+- `topic`: The emitted topic
+- `data`: The payload data
+- `responses`: Array of response data from listeners
+- `errors`: Array of errors that occurred during processing
+- `timestamp`: When the event was created
+- `id`: Unique event identifier
+- `options`: Event options (silent, source, timeout)
+
+### Middleware
+
+Middleware functions allow for pre/post-processing of events:
+
+```javascript
+pulse.use('pattern', async ({ event, pulse, listener }, next) => {
+  // Pre-processing
+  console.log(`Processing ${event.topic}`);
+
+  // Continue chain (required to reach listeners)
+  await next();
+
+  // Post-processing (happens after listener execution)
+  console.log(`Responses: ${event.responses}`);
+});
+```
+
+## Detailed Usage
+
+### Basic Event Subscription
+
+```javascript
+// Basic subscription
+pulse.on('topic', ({ event, pulse, listener }) => {
+  // Handle event
+  // event: the event object
+  // pulse: the pulse instance
+  // listener: the listener object
+});
+
+// Subscribe once (auto-remove after first call)
+pulse.once('topic', ({ event }) => {
+  // This will only be called once
+});
+
+// With options
+pulse.on('topic', ({ event }) => {
+  // Handle event
+}, {
+  once: true, // Auto-remove after being called once
+  autodestroy: {
+    calls: 5,   // Remove after 5 calls
+    timeout: 60000  // Remove after 60 seconds
+  }
+});
+
+// Return a value to automatically add it to responses
+pulse.on('greeting', ({ event }) => {
+  return `Hello, ${event.data.name}!`;  // Automatically added to responses
+});
+```
+
+### Event Emission with Timeout
+
+```javascript
+// Basic emission
+const event = await pulse.emit('topic', { message: 'Hello World' });
+
+// With custom timeout (default is 5000ms)
+const event = await pulse.emit('topic', data, { timeout: 10000 });
+
+// Silent mode (no responses or errors collected)
+const event = await pulse.emit('topic', data, { silent: true });
+```
+
+### Handling Responses
+
+```javascript
+// In listener: set a response
+pulse.on('greeting', ({ event }) => {
+  return `Hello, ${event.data.name}!`;  // Automatically added to responses
+  // Or explicitly:
+  // event.respond(`Hello, ${event.data.name}!`);
+});
+
+// In emitter: get the responses
+const event = await pulse.emit('greeting', { name: 'John' });
+console.log(event.responses[0]);  // "Hello, John!"
+
+// Multiple listeners can add multiple responses
+pulse.on('greeting', ({ event }) => event.respond('Response 1'));
+pulse.on('greeting', ({ event }) => event.respond('Response 2'));
+const event = await pulse.emit('greeting', {});
+console.log(event.responses);  // ['Response 1', 'Response 2']
+```
+
+### Error Handling
+
+```javascript
+// In listener: handle errors
+pulse.on('process', ({ event }) => {
+  try {
+    // Do something that might fail
+    throw new Error('Something went wrong');
+  } catch (err) {
+    event.error(err);
+  }
+});
+
+// Errors thrown in listeners are automatically caught
+pulse.on('process', ({ event }) => {
+  throw new Error('Auto-caught error');  // Automatically added to errors
+});
+
+// In emitter: check for errors
+const event = await pulse.emit('process', data);
+if (event.errors.length > 0) {
+  console.error('Errors occurred:', event.errors);
+}
+```
+
+### Middleware Chains
+
+```javascript
+// Authentication middleware
+pulse.use('secure:**', async ({ event, pulse, listener }, next) => {
+  if (!event.data.token) {
+    event.error(new Error('Authentication required'));
+    return; // Don't call next() to stop the chain
+  }
+
+  // Validate token
+  const user = validateToken(event.data.token);
+  if (!user) {
+    event.error(new Error('Invalid token'));
+    return;
+  }
+
+  // Add user to event data for downstream handlers
+  event.data.user = user;
+
+  // Continue the middleware chain
+  await next();
+});
+
+// Logging middleware
+pulse.use('**', async ({ event }, next) => {
+  console.time(`event:${event.id}`);
+  await next();
+  console.timeEnd(`event:${event.id}`);
+});
+
+// Error handling in middleware (v2.1.3+)
+// Errors thrown in middleware are automatically caught and collected
+pulse.use('user:**', async ({ event }, next) => {
+  throw new Error('Middleware error');  // Auto-caught and added to event.errors
+  // The next middleware and listener will still execute
+});
+```
+
+### Cleaning Up
+
+```javascript
+// Remove a specific listener
+const listener = pulse.on('topic', callback);
+listener.destroy();
+
+// Remove all listeners for a topic
+pulse.off('topic');
+
+// Remove all listeners
+pulse.removeAllListeners();
+
+// Clear pattern cache (v2.1.3+)
+// Useful for long-running applications with dynamic patterns
+pulse.clearPatternCache();
+```
+
+## API Reference
+
+### Pulse Class
+
+#### Constructor
+
+```javascript
+const pulse = new Pulse(options);
+```
+
+**Options:**
+- `EventClass` (optional): Custom event class that extends PulseEvent
+
+#### Methods
+
+| Method | Parameters | Returns | Description |
+|--------|------------|---------|-------------|
+| `on` | `pattern: string`, `callback: Function`, `options?: Object` | `Listener` | Subscribe to events matching the pattern |
+| `once` | `pattern: string`, `callback: Function`, `options?: Object` | `Listener` | Subscribe to events matching the pattern (auto-remove after first call) |
+| `use` | `pattern: string`, `callback: Function` | `Middleware` | Add middleware for events matching the pattern |
+| `emit` | `topic: string`, `data: any`, `options?: Object` | `Promise<PulseEvent>` | Emit an event with the specified topic and data |
+| `off` | `pattern: string` | `void` | Remove all listeners for a pattern |
+| `removeAllListeners` | | `void` | Remove all listeners |
+| `clearPatternCache` | | `void` | Clear the pattern cache (useful for memory management) |
+| `matchesPattern` | `topic: string`, `pattern: string` | `boolean` | Check if a topic matches a pattern |
+
+**Callback signature for listeners:**
+```javascript
+({ event, pulse, listener }) => { /* ... */ }
+```
+
+**Callback signature for middleware:**
+```javascript
+async ({ event, pulse, listener }, next) => { /* ... */ }
+```
+
+#### Listener Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `once` | `boolean` | `false` | If true, the listener will be removed after it is called once |
+| `autodestroy.calls` | `number` | `undefined` | Number of calls after which the listener is removed |
+| `autodestroy.timeout` | `number` | `undefined` | Time in milliseconds after which the listener is removed |
+
+#### Emit Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `timeout` | `number` | `5000` | Time in milliseconds to wait for listener responses before timing out |
+| `silent` | `boolean` | `false` | If true, the event will not collect responses or errors |
+| `source` | `string\|null` | `null` | Optional source identifier for the event |
+
+### Event Class
+
+#### Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `topic` | `string` | The topic of the event |
+| `data` | `any` | The payload data of the event |
+| `responses` | `any[]` | Array of response data from listeners |
+| `errors` | `Error[]` | Array of errors that occurred during processing |
+| `timestamp` | `number` | When the event was created (milliseconds since epoch) |
+| `id` | `string` | Unique event identifier |
+| `options` | `Object` | Event options (silent, source, timeout) |
+
+#### Methods
+
+| Method | Parameters | Returns | Description |
+|--------|------------|---------|-------------|
+| `respond` | `data: any` | `PulseEvent` | Add response data to the event |
+| `error` | `error: Error` | `PulseEvent` | Add an error to the event |
+| `set` | `key: any`, `value: any` | `PulseEvent` | Set a context value (chainable) |
+| `get` | `key: any` | `any` | Get a context value |
+| `has` | `key: any` | `boolean` | Check if a context key exists |
+| `delete` | `key: any` | `boolean` | Delete a context entry |
+| `clearContext` | | `PulseEvent` | Clear all context data (chainable) |
+
+## Advanced Examples
+
+### Using Event Context
+
+Event context allows you to store metadata and share data between middlewares and listeners:
+
+```javascript
+// Middleware can enrich the event with context data
+pulse.use('user:**', async ({ event }, next) => {
+  // Add metadata to event context
+  event.set('processingStarted', Date.now());
+  event.set('correlationId', generateId());
+
+  await next();
+
+  // Access context after processing
+  const duration = Date.now() - event.get('processingStarted');
+  console.log(`Event ${event.get('correlationId')} took ${duration}ms`);
+});
+
+// Listeners can access context data
+pulse.on('user:created', ({ event }) => {
+  console.log(`Correlation ID: ${event.get('correlationId')}`);
+
+  // Store additional metadata
+  event.set('handler', 'user-creation-handler');
+  event.set('version', '1.0');
+
+  // Check if context exists
+  if (event.has('correlationId')) {
+    // Use it for logging/tracking
+  }
+});
+
+// Clear context when needed
+pulse.on('cleanup', ({ event }) => {
+  event.clearContext();
+});
+```
+
+### Creating a Request-Response Pattern
+
+```javascript
+// Create an RPC-like system
+async function callRemote(method, params) {
+  const responseTopic = `response:${Date.now()}:${Math.random().toString(36).substr(2, 9)}`;
+
+  // Create a promise that will resolve when we get a response
+  const responsePromise = new Promise((resolve) => {
+    pulse.once(responseTopic, ({ event }) => {
+      resolve(event.data);
+    });
+  });
+
+  // Add the response topic to the request
+  await pulse.emit(`rpc:${method}`, {
+    params,
+    responseTopic
+  });
+
+  // Wait for the response
+  return responsePromise;
+}
+
+// Handle RPC requests
+pulse.on('rpc:**', ({ event }) => {
+  const method = event.topic.split(':')[1];
+  const { params, responseTopic } = event.data;
+
+  // Process the request
+  const result = processMethod(method, params);
+
+  // Send the response back
+  pulse.emit(responseTopic, result);
+});
+
+// Usage
+const result = await callRemote('getUserProfile', { id: 123 });
+```
+
+### Creating a State Management System
+
+```javascript
+class Store {
+  constructor(pulse, initialState = {}) {
+    this.pulse = pulse;
+    this.state = initialState;
+
+    // Listen for state change requests
+    this.pulse.on('store:set:**', ({ event }) => {
+      const path = event.topic.replace('store:set:', '').split(':');
+      this.setState(path, event.data);
+    });
+  }
+
+  setState(path, value) {
+    let current = this.state;
+    const pathArr = Array.isArray(path) ? path : [path];
+
+    // Navigate to the nested property
+    for (let i = 0; i < pathArr.length - 1; i++) {
+      if (!current[pathArr[i]]) {
+        current[pathArr[i]] = {};
+      }
+      current = current[pathArr[i]];
+    }
+
+    // Set the value
+    const lastKey = pathArr[pathArr.length - 1];
+    const oldValue = current[lastKey];
+    current[lastKey] = value;
+
+    // Emit state change event
+    this.pulse.emit(`store:changed:${path.join(':')}`, {
+      oldValue,
+      newValue: value,
+      path
+    });
+  }
+
+  getState(path) {
+    if (!path) return this.state;
+
+    let current = this.state;
+    const pathArr = Array.isArray(path) ? path : path.split(':');
+
+    for (const key of pathArr) {
+      if (current[key] === undefined) return undefined;
+      current = current[key];
+    }
+
+    return current;
+  }
+}
+
+// Usage
+const store = new Store(pulse, {
+  user: { name: 'John', age: 30 },
+  settings: { theme: 'dark' }
+});
+
+// Listen for changes
+pulse.on('store:changed:user:name', ({ event }) => {
+  console.log(`User's name changed from ${event.data.oldValue} to ${event.data.newValue}`);
+});
+
+// Update state
+pulse.emit('store:set:user:name', 'Jane');
+```
+
+## Performance Considerations
+
+- **Wildcards**: Using many `**` wildcards can impact performance as they require more complex pattern matching
+- **Listener Count**: High numbers of listeners on frequently emitted topics can affect performance
+- **Middleware Complexity**: Complex middleware chains can add overhead to event processing
+
+## Browser Support
+
+Pulse works in all modern browsers and Node.js environments. It uses ES6 features like Promises, Maps, and arrow functions.
+
+## License
+
+MIT © Killian Di Vincenzo
+
+---
+
+## Contributing
+
+Contributions are welcome! Feel free to submit issues and pull requests.
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'Add some amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request

package/dist/core/event.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Base event class for Pulse event system.
+ * Can be extended to create custom event types.
+ */
+export class PulseEvent {
+    /**
+     * @param {string} topic
+     * @param {any} data
+     * @param {Object} [options]
+     * @param {boolean} [options.silent=false] - If true, the event will not collect responses or errors.
+     * @param {string|null} [options.source=null] - The source of the event.
+     * @param {number} [options.timeout=5000] - The timeout for the event in milliseconds.
+     */
+    constructor(topic: string, data: any, options?: {
+        silent?: boolean | undefined;
+        source?: string | null | undefined;
+        timeout?: number | undefined;
+    });
+    topic: string;
+    data: any;
+    options: {
+        silent: boolean;
+        source: string | null;
+        timeout: number;
+    };
+    timestamp: number;
+    id: string;
+    /**
+     * @type {any[]}
+     */
+    responses: any[];
+    /**
+     * @type {Error[]}
+     */
+    errors: Error[];
+    /**
+     * Add a response to the event
+     * @template {PulseEvent} T
+     * @this {T}
+     * @param {any} data
+     * @returns {T} Returns this for chaining
+     */
+    respond<T extends PulseEvent>(this: T, data: any): T;
+    /**
+     * Add an error to the event
+     * @template {PulseEvent} T
+     * @this {T}
+     * @param {Error} err
+     * @returns {T} Returns this for chaining
+     */
+    error<T extends PulseEvent>(this: T, err: Error): T;
+    /**
+     * Set a context value
+     * @template {PulseEvent} T
+     * @this {T}
+     * @param {any} key - The key to set
+     * @param {any} value - The value to associate with the key
+     * @returns {T} Returns this for chaining
+     */
+    set<T extends PulseEvent>(this: T, key: any, value: any): T;
+    /**
+     * Get a context value
+     * @param {any} key - The key to retrieve
+     * @returns {any} The value associated with the key, or undefined if not found
+     */
+    get(key: any): any;
+    /**
+     * Check if a context key exists
+     * @param {any} key - The key to check
+     * @returns {boolean} True if the key exists in the context
+     */
+    has(key: any): boolean;
+    /**
+     * Delete a context entry
+     * @param {any} key - The key to delete
+     * @returns {boolean} True if the key existed and was deleted, false otherwise
+     */
+    delete(key: any): boolean;
+    /**
+     * Clear all context data
+     * @template {PulseEvent} T
+     * @this {T}
+     * @returns {T} Returns this for chaining
+     */
+    clearContext<T extends PulseEvent>(this: T): T;
+    #private;
+}
+//# sourceMappingURL=event.d.ts.map

package/dist/core/event.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"event.d.ts","sourceRoot":"","sources":["../../src/core/event.js"],"names":[],"mappings":"AAGA;;;GAGG;AACH;IAOI;;;;;;;OAOG;IACH,mBAPW,MAAM,QACN,GAAG,YAEX;QAA0B,MAAM;QACF,MAAM;QACX,OAAO;KAClC,EAuBA;IArBG,cAAkB;IAClB,UAAgB;IAChB;gBAPO,OAAO;gBACP,MAAM,GAAC,IAAI;iBACX,MAAM;MAUZ;IAED,kBAA2B;IAC3B,WAA6D;IAE7D;;OAEG;IACH,WAFU,GAAG,EAAE,CAEI;IAEnB;;OAEG;IACH,QAFU,KAAK,EAAE,CAED;IAGpB;;;;;;OAMG;IACH,QAL0B,CAAC,SAAb,UAAW,iBAEd,GAAG,GACD,CAAC,CAMb;IAED;;;;;;OAMG;IACH,MAL0B,CAAC,SAAb,UAAW,gBAEd,KAAK,GACH,CAAC,CAMb;IAED;;;;;;;OAOG;IACH,IAN0B,CAAC,SAAb,UAAW,gBAEd,GAAG,SACH,GAAG,GACD,CAAC,CAKb;IAED;;;;OAIG;IACH,SAHW,GAAG,GACD,GAAG,CAIf;IAED;;;;OAIG;IACH,SAHW,GAAG,GACD,OAAO,CAInB;IAED;;;;OAIG;IACH,YAHW,GAAG,GACD,OAAO,CAInB;IAED;;;;;OAKG;IACH,aAJ0B,CAAC,SAAb,UAAW,YAEZ,CAAC,CAKb;;CACJ"}

package/dist/core/listener.d.ts

@@ -0,0 +1,57 @@
+/**
+* @typedef {Object} ListenerOptions
+* @property {boolean} [once] - If true, the listener will be removed after it is called once.
+* @property {Object} [autodestroy]
+* @property {Number} [autodestroy.timeout] - The time in milliseconds to wait before the listener is removed.
+* @property {Number} [autodestroy.calls] - The number of calls to the listener before it is removed.
+*/
+/**
+ * @template {import('./event').PulseEvent} [TEvent=import('./event').PulseEvent]
+ * @typedef {Object} ListenerContext
+ * @property {import('./pulse').Pulse} pulse
+ * @property {TEvent} event
+ * @property {Listener<TEvent>} listener
+ */
+/**
+ * @template {import('./event').PulseEvent} [TEvent=import('./event').PulseEvent]
+ */
+export class Listener<TEvent extends import("./event").PulseEvent = import("./event").PulseEvent> {
+    /**
+     * @param {import('./pulse').Pulse} pulse
+     * @param {string} pattern
+     * @param {(context: ListenerContext<TEvent>) => void} callback
+     * @param {ListenerOptions} options
+     */
+    constructor(pulse: import("./pulse").Pulse, pattern: string, callback: (context: ListenerContext<TEvent>) => void, options: ListenerOptions);
+    pulse: import("./pulse").Pulse<typeof import("./event").PulseEvent>;
+    pattern: string;
+    options: ListenerOptions;
+    calls: number;
+    timeout: number | null;
+    /** @param {TEvent} event */
+    call: (event: TEvent) => Promise<void>;
+    destroy: () => void;
+    #private;
+}
+export type ListenerOptions = {
+    /**
+     * - If true, the listener will be removed after it is called once.
+     */
+    once?: boolean | undefined;
+    autodestroy?: {
+        /**
+         * - The time in milliseconds to wait before the listener is removed.
+         */
+        timeout?: number | undefined;
+        /**
+         * - The number of calls to the listener before it is removed.
+         */
+        calls?: number | undefined;
+    } | undefined;
+};
+export type ListenerContext<TEvent extends import("./event").PulseEvent = import("./event").PulseEvent> = {
+    pulse: import("./pulse").Pulse;
+    event: TEvent;
+    listener: Listener<TEvent>;
+};
+//# sourceMappingURL=listener.d.ts.map

package/dist/core/listener.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"listener.d.ts","sourceRoot":"","sources":["../../src/core/listener.js"],"names":[],"mappings":"AAAA;;;;;;EAME;AAEF;;;;;;GAMG;AAEH;;GAEG;AACH,sBAF6C,MAAM,SAAtC,OAAQ,SAAS,EAAE,UAAW;IAGvC;;;;;OAKG;IACH,mBALW,OAAO,SAAS,EAAE,KAAK,WACvB,MAAM,YACN,CAAC,OAAO,EAAE,eAAe,CAAC,MAAM,CAAC,KAAK,IAAI,WAC1C,eAAe,EAqBzB;IAlBG,oEAAkB;IAClB,gBAAsB;IAEtB,yBAAsB;IAEtB,cAAc;IACd,uBAAmB;IAiBvB,4BAA4B;IAC5B,OAAc,OADF,MACO,mBAajB;IAEF,oBAWC;;CACJ;;;;;;;;;;;;;;;;;4BArE4C,MAAM,SAAtC,OAAQ,SAAS,EAAE,UAAW;WAE7B,OAAO,SAAS,EAAE,KAAK;WACvB,MAAM;cACN,QAAQ,CAAC,MAAM,CAAC"}

package/dist/core/middleware.d.ts

@@ -0,0 +1,41 @@
+/**
+* @typedef {import('./pulse').Pulse} Pulse
+* @typedef {import('./event').PulseEvent} PulseEvent
+*/
+/**
+* @template {PulseEvent} [TEvent=PulseEvent]
+* @callback NextCallback
+* @returns {Promise<void>}
+*/
+/**
+* @template {PulseEvent} [TEvent=PulseEvent]
+* @callback MiddlewareCallback
+* @param {import('./listener').ListenerContext<TEvent>} context
+* @param {NextCallback<TEvent>} next
+* @returns {Promise<any>}
+*/
+/**
+* @template {PulseEvent} [TEvent=PulseEvent]
+*/
+export class Middleware<TEvent extends PulseEvent = import("./event").PulseEvent> {
+    /**
+    * @param {import('./pulse').Pulse} pulse
+    * @param {String} pattern
+    * @param {MiddlewareCallback<TEvent>} callback
+    */
+    constructor(pulse: import("./pulse").Pulse, pattern: string, callback: MiddlewareCallback<TEvent>);
+    pulse: import("./pulse").Pulse<typeof import("./event").PulseEvent>;
+    pattern: string;
+    callback: MiddlewareCallback<TEvent>;
+    /**
+    * @param {string} topic
+    * @returns {boolean}
+    */
+    matches(topic: string): boolean;
+    destroy(): void;
+}
+export type Pulse = import("./pulse").Pulse;
+export type PulseEvent = import("./event").PulseEvent;
+export type NextCallback<TEvent extends PulseEvent = import("./event").PulseEvent> = () => Promise<void>;
+export type MiddlewareCallback<TEvent extends PulseEvent = import("./event").PulseEvent> = (context: import("./listener").ListenerContext<TEvent>, next: NextCallback<TEvent>) => Promise<any>;
+//# sourceMappingURL=middleware.d.ts.map

package/dist/core/middleware.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"middleware.d.ts","sourceRoot":"","sources":["../../src/core/middleware.js"],"names":[],"mappings":"AAAA;;;EAGE;AAEF;;;;EAIE;AAEF;;;;;;EAME;AAEF;;EAEE;AACF,wBAF0B,MAAM,SAAnB,UAAW;IAGpB;;;;MAIE;IACF,mBAJU,OAAO,SAAS,EAAE,KAAK,6BAEvB,kBAAkB,CAAC,MAAM,CAAC,EAMnC;IAHG,oEAAkB;IAClB,gBAAsB;IACtB,qCAAwB;IAG5B;;;MAGE;IACF,eAHU,MAAM,GACJ,OAAO,CAIlB;IAED,gBAKC;CACJ;oBA/CW,OAAO,SAAS,EAAE,KAAK;yBACvB,OAAO,SAAS,EAAE,UAAU;yBAId,MAAM,SAAnB,UAAW,yCAEZ,OAAO,CAAC,IAAI,CAAC;+BAIC,MAAM,SAAnB,UAAW,6CAEd,OAAO,YAAY,EAAE,eAAe,CAAC,MAAM,CAAC,QAC5C,YAAY,CAAC,MAAM,CAAC,KAClB,OAAO,CAAC,GAAG,CAAC"}

package/dist/core/pulse.d.ts

@@ -0,0 +1,89 @@
+/**
+ * @template {typeof PulseEvent} [TEventClass=typeof PulseEvent]
+ * @typedef {Object} PulseOptions
+ * @property {TEventClass} [EventClass] - Custom event class to use (must extend PulseEvent)
+ */
+/**
+ * @template {typeof PulseEvent} [TEventClass=typeof PulseEvent]
+ */
+export class Pulse<TEventClass extends typeof PulseEvent = typeof PulseEvent> {
+    /**
+     * @param {PulseOptions<TEventClass>} [options]
+     */
+    constructor(options?: PulseOptions<TEventClass>);
+    /** @type {Map<string, Set<import('./listener').Listener<InstanceType<TEventClass>>>>} */
+    listeners: Map<string, Set<import("./listener").Listener<InstanceType<TEventClass>>>>;
+    /** @type {import('./middleware').Middleware<InstanceType<TEventClass>>[]} */
+    middlewares: import("./middleware").Middleware<InstanceType<TEventClass>>[];
+    EventClass: typeof PulseEvent;
+    /**
+     * @param {String} pattern
+     * @param {(context: import('./listener').ListenerContext<InstanceType<TEventClass>>) => any} callback
+     * @param {import('./listener').ListenerOptions} options
+     * @returns {import('./listener').Listener<InstanceType<TEventClass>>}
+     */
+    on: (pattern: string, callback: (context: import("./listener").ListenerContext<InstanceType<TEventClass>>) => any, options?: import("./listener").ListenerOptions) => import("./listener").Listener<InstanceType<TEventClass>>;
+    /**
+     * @param {String} pattern
+     * @param {(context: import('./listener').ListenerContext<InstanceType<TEventClass>>) => any} callback
+     * @param {import('./listener').ListenerOptions} options
+     * @returns {import('./listener').Listener<InstanceType<TEventClass>>}
+     */
+    once: (pattern: string, callback: (context: import("./listener").ListenerContext<InstanceType<TEventClass>>) => any, options?: import("./listener").ListenerOptions) => import("./listener").Listener<InstanceType<TEventClass>>;
+    /**
+     * @param {string} pattern
+     * @param {import('./middleware').MiddlewareCallback<InstanceType<TEventClass>>} callback
+     * @returns {import('./middleware').Middleware<InstanceType<TEventClass>>}
+     */
+    use: (pattern: string, callback: import("./middleware").MiddlewareCallback<InstanceType<TEventClass>>) => import("./middleware").Middleware<InstanceType<TEventClass>>;
+    /**
+     * @param {InstanceType<TEventClass>} event
+     * @param {import('./listener').Listener<InstanceType<TEventClass>>} listener
+     */
+    applyMiddlewaresToListener(event: InstanceType<TEventClass>, listener: import("./listener").Listener<InstanceType<TEventClass>>): Promise<any>;
+    /**
+     * @param {string} topic
+     * @param {any} data
+     * @param {{
+     * timeout?: number,
+     * }} options
+     * @returns {Promise<InstanceType<TEventClass>>}
+     */
+    emit: (topic: string, data: any, options?: {
+        timeout?: number;
+    }) => Promise<InstanceType<TEventClass>>;
+    /**
+     * @param {string} topic
+     * @returns {boolean}
+     */
+    isValidTopic(topic: string): boolean;
+    /**
+     * @param {string} topic
+     * @param {string} pattern
+     * @returns {boolean}
+     */
+    matchesPattern(topic: string, pattern: string): boolean;
+    /**
+     * Remove all listeners for a specific pattern
+     * @param {string} pattern
+     */
+    off(pattern: string): void;
+    /**
+     * Remove all listeners
+     */
+    removeAllListeners(): void;
+    /**
+     * Clear the pattern cache
+     * Useful for memory management in long-running applications
+     */
+    clearPatternCache(): void;
+    #private;
+}
+export type PulseOptions<TEventClass extends typeof PulseEvent = typeof PulseEvent> = {
+    /**
+     * - Custom event class to use (must extend PulseEvent)
+     */
+    EventClass?: TEventClass | undefined;
+};
+import { PulseEvent } from './event.js';
+//# sourceMappingURL=pulse.d.ts.map

package/dist/core/pulse.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pulse.d.ts","sourceRoot":"","sources":["../../src/core/pulse.js"],"names":[],"mappings":"AAIA;;;;GAIG;AAEH;;GAEG;AACH,mBAFkC,WAAW,SAAhC,OAAQ,UAAW;IAG5B;;OAEG;IACH,sBAFW,YAAY,CAAC,WAAW,CAAC,EAiBnC;IAdG,yFAAyF;IACzF,WADW,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,OAAO,YAAY,EAAE,QAAQ,CAAC,YAAY,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAC3D;IAC1B,6EAA6E;IAC7E,aADW,OAAO,cAAc,EAAE,UAAU,CAAC,YAAY,CAAC,WAAW,CAAC,CAAC,EAAE,CACpD;IAKrB,8BAAkD;IActD;;;;;OAKG;IACH,KAAM,eAAO,EAAE,UAJJ,CAAC,OAAO,EAAE,OAAO,YAAY,EAAE,eAAe,CAAC,YAAY,CAAC,WAAW,CAAC,CAAC,KAAK,GAIlE,EAAE,UAHd,OAAO,YAAY,EAAE,eAGK,KAFxB,OAAO,YAAY,EAAE,QAAQ,CAAC,YAAY,CAAC,WAAW,CAAC,CAAC,CASpE;IAED;;;;;OAKG;IACH,OAAQ,eAAO,EAAE,UAJN,CAAC,OAAO,EAAE,OAAO,YAAY,EAAE,eAAe,CAAC,YAAY,CAAC,WAAW,CAAC,CAAC,KAAK,GAIhE,EAAE,UAHhB,OAAO,YAAY,EAAE,eAGO,KAF1B,OAAO,YAAY,EAAE,QAAQ,CAAC,YAAY,CAAC,WAAW,CAAC,CAAC,CAE6B;IAElG;;;;OAIG;IACH,MAAO,SAJI,MAIG,EAAE,UAHL,OAAO,cAAc,EAAE,kBAAkB,CAAC,YAAY,CAAC,WAAW,CAAC,CAGtD,KAFX,OAAO,cAAc,EAAE,UAAU,CAAC,YAAY,CAAC,WAAW,CAAC,CAAC,CAMxE;IAED;;;OAGG;IACH,kCAHW,YAAY,CAAC,WAAW,CAAC,YACzB,OAAO,YAAY,EAAE,QAAQ,CAAC,YAAY,CAAC,WAAW,CAAC,CAAC,gBA2BlE;IAED;;;;;;;OAOG;IACH,OAAc,OAPH,MAOQ,EAAE,MANV,GAMc,EAAE,UALhB;QACR,OAAO,CAAC,EAAE,MAAM,CAAC;KAImB,KAF1B,OAAO,CAAC,YAAY,CAAC,WAAW,CAAC,CAAC,CA+C9C;IA0HD;;;OAGG;IACH,oBAHW,MAAM,GACJ,OAAO,CAKnB;IAED;;;;OAIG;IACH,sBAJW,MAAM,WACN,MAAM,GACJ,OAAO,CAInB;IAED;;;OAGG;IACH,aAFW,MAAM,QAIhB;IAED;;OAEG;IACH,2BAEC;IAED;;;OAGG;IACH,0BAEC;;CAEJ;yBA5TiC,WAAW,SAAhC,OAAQ,UAAW;;;;;;2BALL,YAAY"}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { Pulse } from "./core/pulse.js";
+export { PulseEvent } from "./core/event.js";
+export { Listener } from "./core/listener.js";
+export { Middleware } from "./core/middleware.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.js"],"names":[],"mappings":""}

package/dist/index.js

@@ -0,0 +1 @@
+var R=0;class G{#f=new Map;constructor(f,q,z={}){this.topic=f,this.data=q,this.options={silent:!1,source:null,timeout:5000,...z},this.timestamp=Date.now(),this.id=`${this.topic}-${this.timestamp}-${++R}`,this.responses=[],this.errors=[]}respond(f){if(this.options.silent)return this;return this.responses.push(f),this}error(f){if(this.options.silent)return this;return this.errors.push(f),this}set(f,q){return this.#f.set(f,q),this}get(f){return this.#f.get(f)}has(f){return this.#f.has(f)}delete(f){return this.#f.delete(f)}clearContext(){return this.#f.clear(),this}}class Y{constructor(f,q,z,B){if(this.pulse=f,this.pattern=q,this.#f=z,this.options=B,this.calls=0,this.timeout=null,this.options?.autodestroy?.timeout)this.timeout=setTimeout(()=>{this.destroy()},this.options.autodestroy.timeout);if(this.options?.once)this.options.autodestroy??={},this.options.autodestroy.calls=1}#f;call=async(f)=>{if(this.calls++,this.options?.autodestroy?.calls&&this.calls>=this.options.autodestroy.calls)this.destroy();return Promise.resolve(this.#f({event:f,pulse:this.pulse,listener:this})).then((q)=>{if(q!==void 0&&q!==null)f.respond(q)}).catch((q)=>{f.error(q)})};destroy=()=>{if(this.timeout)clearTimeout(this.timeout);let f=this.pulse.listeners.get(this.pattern);if(f){if(f.delete(this),f.size===0)this.pulse.listeners.delete(this.pattern)}}}class ${constructor(f,q,z){this.pulse=f,this.pattern=q,this.callback=z}matches(f){return this.pulse.matchesPattern(f,this.pattern)}destroy(){this.pulse.middlewares=this.pulse.middlewares.filter((f)=>f!==this),this.destroy=()=>{throw Error("Middleware already destroyed")}}}class K{constructor(f={}){if(this.listeners=new Map,this.middlewares=[],this.#f=new Map,this.EventClass=f.EventClass||G,this.EventClass!==G&&!(this.EventClass.prototype instanceof G))throw Error("EventClass must extend PulseEvent")}#f;#z=1000;on=(f,q,z={})=>{let B=new Y(this,f,q,z),D=f.replace(/\*+|\++/g,"placeholder");if(!this.isValidTopic(D))throw Error(`Invalid pattern: ${f}`);if(!this.listeners.has(f))this.listeners.set(f,new Set);return this.listeners.get(f)?.add(B),B};once=(f,q,z={})=>this.on(f,q,{...z,once:!0});use=(f,q)=>{let z=new $(this,f,q);return this.middlewares.push(z),z};async applyMiddlewaresToListener(f,q){let z=this.middlewares.filter((F)=>F.matches(f.topic));if(z.length===0)return q.call(f);let B=0,D=async()=>{if(B>=z.length)return q.call(f);let F=z[B++];if(!F)return q.call(f);try{return await F.callback({event:f,pulse:this,listener:q},D)}catch(J){let N=J instanceof Error?J:Error(String(J));f.error(N)}};return D()}emit=async(f,q,z={})=>{if(!this.isValidTopic(f))throw Error(`Invalid topic: ${f}`);let B=[];for(let[N,V]of this.listeners.entries())if(this.#q(f,N))B.push(...V);let D=new this.EventClass(f,q,z);if(B.length===0)return D;let F=z?.timeout||5000,J=B.map(async(N)=>{let V;try{let Q=new Promise((H,L)=>{V=setTimeout(()=>{L(Error(`Listener timed out after ${F}ms for topic: ${f}`))},F)});return await Promise.race([this.applyMiddlewaresToListener(D,N),Q])}catch(Q){let H=Q instanceof Error?Q:Error(String(Q));D.error(H)}finally{clearTimeout(V)}});return await Promise.allSettled(J),D};#B(f){if(this.#f.has(f))return this.#f.get(f)||/.*/;let q="^",z=0;while(z<f.length)if(f[z]==="*"&&f[z+1]==="*"){if(z===0){if(z+2>=f.length)q+=".*";else if(f[z+2]===":"){q+="(?:.*:)?",z+=3;continue}}else{if(q.endsWith("\\:"))q=q.slice(0,-2);if(z+2>=f.length)q+="(?::[^:]+(?::[^:]+)*)?";else if(f[z+2]===":"){q+="(?::[^:]+(?::[^:]+)*)?\\:",z+=3;continue}}z+=2}else if(f[z]==="+"&&f[z+1]==="+"){if(z===0){if(z+2>=f.length)q+="[^:]+(?::[^:]+)*";else if(f[z+2]===":"){q+="[^:]+(?::[^:]+)*\\:",z+=3;continue}}else{if(q.endsWith("\\:"))q=q.slice(0,-2);if(z+2>=f.length)q+=":[^:]+(?::[^:]+)*";else if(f[z+2]===":"){q+=":[^:]+(?::[^:]+)*\\:",z+=3;continue}}z+=2}else if(f[z]==="*")q+="[^:]+",z++;else if(f[z]===":"||f[z]===".")q+="\\"+f[z],z++;else q+=f[z],z++;q+="$";let B=new RegExp(q);if(this.#f.size>=this.#z){let D=this.#f.keys().next().value;this.#f.delete(D)}return this.#f.set(f,B),B}#q(f,q){return this.#B(q).test(f)}isValidTopic(f){return/^[a-zA-Z0-9_-]+(?::[a-zA-Z0-9_-]+)*$/.test(f)}matchesPattern(f,q){return this.#q(f,q)}off(f){this.listeners.delete(f)}removeAllListeners(){this.listeners.clear()}clearPatternCache(){this.#f.clear()}}export{G as PulseEvent,K as Pulse,$ as Middleware,Y as Listener};

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@aionbuilders/pulse",
+  "version": "1.0.0",
+  "description": "A powerful, lightweight event system with pattern matching, middleware, and timeout support",
+  "main": "dist/index.js",
+  "module": "dist/index.js",
+  "files": [
+    "dist/",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "events",
+    "pubsub",
+    "middleware",
+    "timeout",
+    "pattern-matching"
+  ],
+  "scripts": {
+    "demo": "bun --watch test/demo.js",
+    "clean": "rm -rf dist",
+    "build": "bun build src/index.js --outdir dist --target node --minify",
+    "generate-types": "tsc --project ./tsc/tsconfig.json",
+    "prepublishOnly": "npm run clean && npm run build && npm run generate-types",
+    "release:alpha": "npm version prerelease && npm publish --tag alpha",
+    "release:stable": "npm version major && npm publish",
+    "release:patch": "npm version patch && npm publish",
+    "release:minor": "npm version minor && npm publish --tag latest"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "author": "Killian Di Vincenzo",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/aionbuilders/pulse.git"
+  },
+  "type": "module",
+  "exports": {
+    ".": "./dist/index.js"
+  }
+}