@d1g1tal/subscribr 4.0.4 → 4.1.8

package/README.md

@@ -1,75 +1,433 @@
 # subscribr
-JavaScript Publish/Subscribe
 
-This simple class enables you to subscribe and publish events using the Observer pattern.
+[![CI](https://github.com/D1g1talEntr0py/subscribr/actions/workflows/ci.yml/badge.svg)](https://github.com/D1g1talEntr0py/subscribr/actions/workflows/ci.yml)
+[![Codecov](https://codecov.io/gh/D1g1talEntr0py/subscribr/branch/main/graph/badge.svg)](https://codecov.io/gh/D1g1talEntr0py/subscribr)
+[![npm version](https://img.shields.io/npm/v/@d1g1tal/subscribr.svg)](https://www.npmjs.com/package/@d1g1tal/subscribr)
+[![License: ISC](https://img.shields.io/badge/License-ISC-blue.svg)](https://opensource.org/licenses/ISC)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.9-blue.svg)](https://www.typescriptlang.org/)
 
-Basically, you subscribe your event handler using the `Subscribr` instance and are returned a `Subscription` instance.
+A lightweight TypeScript publish/subscribe library implementing the Observer pattern.
 
-When the event is published, your event handler will be called.
+## Features
+
+- 🎯 **Simple API** - Subscribe, publish, and unsubscribe with ease
+- 🔒 **Type-safe** - Full TypeScript support with strict typing
+- 🎪 **Context binding** - Maintain proper `this` context in handlers
+- 🔄 **Once subscriptions** - Auto-unsubscribe after first event via options
+- 🛡️ **Error handling** - Built-in error boundary prevents cascading failures
+- ✅ **Validation** - Event name validation for reliable behavior
+- 📦 **Lightweight** - Minimal dependencies (@d1g1tal/collections)
+- 🧪 **Well-tested** - Comprehensive test coverage
+
+## Installation
 
-### Installation:
 ```bash
 # Install with pnpm
-pnpm install @d1g1tal/subscribr
+pnpm add @d1g1tal/subscribr
 
-# Install with NPM
+# Install with npm
 npm install @d1g1tal/subscribr
-```
-Or Script tags from downloaded script or from a NPM CDN like jsDelivr
-
-```html
-<!-- Load as global script -->
-<script src="/subscribr/dist/iife/subscribr.min.js"></script>
 
-<!-- Load from CDN -->
-<script src="https://cdn.jsdelivr.net/npm/@d1g1tal/subscribr@3/dist/iife/subscribr.min.js"></script>
+# Install with yarn
+yarn add @d1g1tal/subscribr
+```
 
-<!-- Load as ES Module -->
-<script type="module">
-	import Subscribr from '/app/js/subscribr.min.js';
-</script>
+### CDN Usage
 
-<!-- Load from CDN -->
+```html
+<!-- Load as ES Module from CDN -->
 <script type="module">
-	import Subscribr from 'https://cdn.jsdelivr.net/npm/@d1g1tal/subscribr@3/dist/subscribr.min.js';
+  import Subscribr from 'https://cdn.jsdelivr.net/npm/@d1g1tal/subscribr@4/dist/subscribr.js';
 </script>
 ```
 
-### Usage:
+## Quick Start
+
 ```javascript
-// ES Module
 import Subscribr from '@d1g1tal/subscribr';
 
+// Create a new instance
+const subscribr = new Subscribr();
+
+// Subscribe to an event
+const subscription = subscribr.subscribe('user-login', (event, data) => {
+  console.log('User logged in:', data.userId);
+});
+
+// Publish an event
+subscribr.publish('user-login', undefined, { userId: 123 });
+// Output: User logged in: 123
+
+// Check if subscribed
+console.log(subscribr.isSubscribed(subscription)); // true
+
+// Unsubscribe
+subscribr.unsubscribe(subscription);
+console.log(subscribr.isSubscribed(subscription)); // false
+```
+
+## API Reference
+
+### Constructor
+
+#### `new Subscribr()`
+
+Creates a new Subscribr instance.
+
+```javascript
+const subscribr = new Subscribr();
+```
+
+---
+
+### Methods
+
+#### `subscribe(eventName, eventHandler, context?, options?)`
+
+Subscribe to an event.
+
+**Parameters:**
+- `eventName` (string) - The name of the event to subscribe to
+- `eventHandler` (function) - The handler function `(event: Event, data?: unknown) => void`
+- `context` (any, optional) - The `this` context for the handler (defaults to the handler itself)
+- `options` (object, optional) - Subscription options
+  - `once` (boolean) - If true, automatically unsubscribe after first event
+
+**Returns:** `Subscription` - A subscription object for managing the subscription
+
+**Throws:**
+- `TypeError` - If event name is not a non-empty string
+- `Error` - If event name has leading or trailing whitespace
+
+```javascript
+// Basic subscription
+const subscription = subscribr.subscribe('my-event', (event, data) => {
+  console.log('Event received:', event.type, data);
+});
+
+// With custom context
+const myObject = {
+  name: 'MyObject',
+  handleEvent(event, data) {
+    console.log(this.name, 'received:', data);
+  }
+};
+subscribr.subscribe('my-event', myObject.handleEvent, myObject);
+
+// One-time subscription using options
+subscribr.subscribe('init', (event, data) => {
+  console.log('Initialization complete:', data);
+}, undefined, { once: true });
+
+subscribr.publish('init', undefined, { status: 'ready' });
+// Output: Initialization complete: { status: 'ready' }
+
+subscribr.publish('init', undefined, { status: 'ready' });
+// No output - handler was auto-unsubscribed
+```
+
+---
+
+#### `publish(eventName, event?, data?)`
+
+Publish an event to all subscribed handlers.
+
+**Parameters:**
+- `eventName` (string) - The name of the event to publish
+- `event` (Event, optional) - A custom event object (defaults to `new CustomEvent(eventName)`)
+- `data` (any, optional) - Data to pass to event handlers
+
+**Returns:** `void`
+
+**Throws:**
+- `TypeError` - If event name is not a non-empty string
+- `Error` - If event name has leading or trailing whitespace
+
+```javascript
+// Publish with just event name and data
+subscribr.publish('user-action', undefined, { action: 'click', target: 'button' });
+
+// Publish with custom event
+const customEvent = new CustomEvent('custom-event', { detail: 'info' });
+subscribr.publish('custom-event', customEvent, { extra: 'data' });
+```
+
+---
+
+#### `unsubscribe(subscription)`
+
+Unsubscribe from an event.
+
+**Parameters:**
+- `subscription` (Subscription) - The subscription object returned from `subscribe()` or `once()`
+
+**Returns:** `boolean` - `true` if successfully unsubscribed, `false` if subscription wasn't found
+
+```javascript
+const subscription = subscribr.subscribe('my-event', handler);
+const result = subscribr.unsubscribe(subscription); // true
+const result2 = subscribr.unsubscribe(subscription); // false (already unsubscribed)
+```
+
+---
+
+#### `isSubscribed(subscription)`
+
+Check if a subscription is still active.
+
+**Parameters:**
+- `subscription` (Subscription) - The subscription object to check
+
+**Returns:** `boolean` - `true` if the subscription is active, `false` otherwise
+
+```javascript
+const subscription = subscribr.subscribe('my-event', handler);
+subscribr.isSubscribed(subscription); // true
+subscribr.unsubscribe(subscription);
+subscribr.isSubscribed(subscription); // false
+```
+
+---
+
+#### `setErrorHandler(errorHandler)`
+
+Set a custom error handler for handling errors that occur in event listeners. By default, errors are logged to the console.
+
+**Parameters:**
+- `errorHandler` (function) - The error handler function `(error: Error, eventName: string, event: Event, data?: unknown) => void`
+
+**Returns:** `void`
+
+```javascript
+// Set a custom error handler
+subscribr.setErrorHandler((error, eventName, event, data) => {
+  console.error(`Error in handler for '${eventName}':`, error.message);
+  // Send to error tracking service
+  errorTracker.report(error, { eventName, data });
+});
+
+// Now if a handler throws an error, it won't break other handlers
+subscribr.subscribe('my-event', () => {
+  throw new Error('Oops!');
+});
+
+subscribr.subscribe('my-event', () => {
+  console.log('This still runs!'); // ✅ Executes despite the error above
+});
+
+subscribr.publish('my-event');
+// Output: Error in handler for 'my-event': Oops!
+// Output: This still runs!
+```
+
+---
+
+## Usage Examples
+
+### Multiple Handlers for the Same Event
+
+```javascript
+const subscribr = new Subscribr();
+
+subscribr.subscribe('data-update', (event, data) => {
+  console.log('Handler 1:', data);
+});
+
+subscribr.subscribe('data-update', (event, data) => {
+  console.log('Handler 2:', data);
+});
+
+subscribr.publish('data-update', undefined, { value: 42 });
+// Output:
+// Handler 1: { value: 42 }
+// Handler 2: { value: 42 }
+```
+
+### Using with DOM Events
+
+```javascript
+const subscribr = new Subscribr();
+
+subscribr.subscribe('user-click', (event, data) => {
+  console.log('User clicked:', data.elementId);
+});
+
+document.getElementById('myButton').addEventListener('click', (event) => {
+  subscribr.publish('user-click', event, { elementId: event.target.id });
+});
+```
+
+### Class-based Event Handling
+
+```javascript
+class UserManager {
+  constructor(subscribr) {
+    this.subscribr = subscribr;
+    this.users = [];
+
+    // Subscribe with proper context binding
+    this.subscribr.subscribe('user-added', this.onUserAdded, this);
+  }
+
+  onUserAdded(event, data) {
+    // 'this' correctly refers to UserManager instance
+    this.users.push(data.user);
+    console.log(`Total users: ${this.users.length}`);
+  }
+
+  addUser(user) {
+    this.subscribr.publish('user-added', undefined, { user });
+  }
+}
+
+const subscribr = new Subscribr();
+const manager = new UserManager(subscribr);
+manager.addUser({ id: 1, name: 'Alice' });
+// Output: Total users: 1
+```
+
+### Error-Resistant Event System
+
+```javascript
 const subscribr = new Subscribr();
-const eventName = 'myEvent';
 
-// Subscribr.prototype.subscribe returns a Subscription object.
-const mySubscription = subscribr.subscribe(eventName, (event, data) => console.log(`Event: '${event.type}' published with data: ${data}`));
+// Set up error tracking
+subscribr.setErrorHandler((error, eventName, event, data) => {
+  console.error(`Error in handler for '${eventName}':`, error.message);
+  // Send to error tracking service (if available)
+});
+
+// Even if one handler fails, others continue
+subscribr.subscribe('process-data', (event, data) => {
+  if (!data.valid) throw new Error('Invalid data');
+  processData(data);
+});
 
-// Publish the event with just the name and a CustomEvent will be created with the eventName. All handlers that have subscribed are called
-subscribr.publish(eventName, { foo: 'bar', zip: 'fizz' }); // Event: 'myEvent' published with data: { foo: 'bar', zip: 'fizz' }
+subscribr.subscribe('process-data', (event, data) => {
+  // This still executes even if the previous handler throws
+  updateUI(data);
+});
+```
 
-// Is the event subscribed?
-const isSubscribed = subscribr.isSubscribed(mySubscription); // true
+### One-Time Subscriptions
 
-const isUnsubscribed = subscribr.unsubscribe(mySubscription); // true
+```javascript
+const subscribr = new Subscribr();
 
-const isSubscribed = subscribr.isSubscribed(mySubscription); // false
+// One-time subscription using options
+subscribr.subscribe('app-ready', (event, data) => {
+  console.log('App initialized with config:', data.config);
+  startApplication(data.config);
+}, undefined, { once: true });
 
+// This will only trigger the handler once
+subscribr.publish('app-ready', undefined, { config: { theme: 'dark' } });
+subscribr.publish('app-ready', undefined, { config: { theme: 'light' } }); // Ignored
+```
 
-// Subscribe to a DOM event
-const eventTargetSubscription = subsribr.subscribe('eventTargetChanged', (event, data) => console.log(`Event target changed with data: ${data}`));
+## TypeScript Support
 
-// Add some event to an event target (DOMElement)
-new EventTarget().addEventListener('change', function(event) {
-	// Publish the event and all handlers that have subscribed are called
-	subscribr.publish('eventTargetChanged', event, { value: this.value }); // Event target changed with data: {value: 'new value'}
+Full TypeScript support with strict typing:
+
+```typescript
+import Subscribr from '@d1g1tal/subscribr';
+
+interface UserData {
+  userId: number;
+  userName: string;
+}
+
+const subscribr = new Subscribr();
+
+subscribr.subscribe('user-login', (event: Event, data?: UserData) => {
+  if (data) {
+    console.log(`User ${data.userName} (ID: ${data.userId}) logged in`);
+  }
+});
+
+subscribr.publish<UserData>('user-login', undefined, {
+  userId: 123,
+  userName: 'Alice'
 });
+```
+
+## Event Name Validation
+
+Event names are validated to prevent common mistakes:
+
+```javascript
+// ❌ These will throw errors:
+subscribr.subscribe('', handler);           // TypeError: Event name must be a non-empty string
+subscribr.subscribe(' event', handler);     // Error: Event name cannot have leading or trailing whitespace
+subscribr.subscribe('event ', handler);     // Error: Event name cannot have leading or trailing whitespace
+subscribr.subscribe(null, handler);         // TypeError: Event name must be a non-empty string
+
+// ✅ These are valid:
+subscribr.subscribe('my-event', handler);
+subscribr.subscribe('user:login', handler);
+subscribr.subscribe('data_update', handler);
+```
+
+## Best Practices
+
+1. **Always unsubscribe** when done to prevent memory leaks:
+   ```javascript
+   const subscription = subscribr.subscribe('event', handler);
+   // ... later
+   subscribr.unsubscribe(subscription);
+   ```
+
+2. **Use `{ once: true }` option for one-time events** to avoid manual cleanup:
+   ```javascript
+   subscribr.subscribe('init', handler, undefined, { once: true }); // Auto-unsubscribes
+   ```
+
+3. **Set up error handling** for production applications:
+   ```javascript
+   subscribr.setErrorHandler((error, eventName) => {
+     console.error(`Event '${eventName}' error:`, error);
+     // Report to error tracking service if available
+   });
+   ```
+
+4. **Use meaningful event names** with consistent naming conventions:
+   ```javascript
+   // Good
+   subscribr.subscribe('user-login', handler);
+   subscribr.subscribe('data-updated', handler);
+
+   // Avoid
+   subscribr.subscribe('event1', handler);
+   subscribr.subscribe('stuff', handler);
+   ```
+
+5. **Bind context properly** for class methods:
+   ```javascript
+   class MyClass {
+     constructor() {
+       subscribr.subscribe('event', this.handleEvent, this);
+     }
+     handleEvent(event, data) {
+       // 'this' refers to MyClass instance
+     }
+   }
+   ```
+
+## Browser Support
+
+Supports all modern browsers with ES6 module support and Node.js ≥ 20.15.1
+
+## License
+
+ISC
+
+## Contributing
 
-// Is the event subscribed?
-const isSubscribed = subscribr.isSubscribed(eventTargetSubscription); // true
+Contributions are welcome! Please feel free to submit a Pull Request.
 
-const isUnsubscribed = subscribr.unsubscribe(eventTargetSubscription); // true
+## Links
 
-const isSubscribed = subscribr.isSubscribed(eventTargetSubscription); // false
-```
+- [GitHub Repository](https://github.com/D1g1talEntr0py/subscribr)
+- [npm Package](https://www.npmjs.com/package/@d1g1tal/subscribr)
+- [Issue Tracker](https://github.com/D1g1talEntr0py/subscribr/issues)
+- [Changelog](./CHANGELOG.md)

package/dist/subscribr.d.ts

@@ -1,15 +1,22 @@
 /** Context event listener function. */
-type ContextEventListener = (event: Event, data?: unknown) => void;
+type EventHandler = (event: Event, data?: unknown) => void;
+/** Error handler function for handling errors in event listeners. */
+type ErrorHandler = (error: Error, eventName: string, event: Event, data?: unknown) => void;
+/** Subscription options. */
+interface SubscriptionOptions {
+    /** If true, the subscription will automatically unsubscribe after the first event. */
+    once?: boolean;
+}
 
 /** A wrapper for an event handler that binds a context to the event handler. */
 declare class ContextEventHandler {
     private readonly context;
-    private readonly eventListener;
+    private readonly eventHandler;
     /**
      * @param context The context to bind to the event handler.
-     * @param eventListener The event handler to call when the event is published.
+     * @param eventHandler The event handler to call when the event is published.
      */
-    constructor(context: unknown, eventListener: ContextEventListener);
+    constructor(context: unknown, eventHandler: EventHandler);
     /**
      * Call the event handler for the provided event.
      *
@@ -59,16 +66,24 @@ declare class Subscription {
 /** A class that allows objects to subscribe to events and be notified when the event is published. */
 declare class Subscribr {
     private readonly subscribers;
-    constructor();
+    private errorHandler?;
+    /**
+     * Set a custom error handler for handling errors that occur in event listeners.
+     * If not set, errors will be logged to the console.
+     *
+     * @param errorHandler The error handler function to call when an error occurs in an event listener.
+     */
+    setErrorHandler(errorHandler: ErrorHandler): void;
     /**
      * Subscribe to an event
      *
      * @param eventName The event name to subscribe to.
      * @param eventHandler The event handler to call when the event is published.
      * @param context The context to bind to the event handler.
+     * @param options Subscription options.
      * @returns An object used to check if the subscription still exists and to unsubscribe from the event.
      */
-    subscribe(eventName: string, eventHandler: ContextEventListener, context?: unknown): Subscription;
+    subscribe(eventName: string, eventHandler: EventHandler, context?: unknown, options?: SubscriptionOptions): Subscription;
     /**
      * Unsubscribe from the event
      *
@@ -92,6 +107,18 @@ declare class Subscribr {
      * @returns true if the event name and handler are subscribed, false otherwise.
      */
     isSubscribed({ eventName, contextEventHandler }: Subscription): boolean;
+    /**
+     * Validate the event name
+     *
+     * @param eventName The event name to validate.
+     * @throws {TypeError} If the event name is not a non-empty string.
+     * @throws {Error} If the event name has leading or trailing whitespace.
+     */
+    private validateEventName;
+    /**
+     * Clears all subscriptions. The instance should not be used after calling this method.
+     */
+    destroy(): void;
     /**
      * A String value that is used in the creation of the default string
      * description of an object. Called by the built-in method {@link Object.prototype.toString}.
@@ -101,4 +128,5 @@ declare class Subscribr {
     get [Symbol.toStringTag](): string;
 }
 
-export { ContextEventHandler, type ContextEventListener, Subscribr, Subscription };
+export { ContextEventHandler, Subscribr, Subscription };
+export type { ErrorHandler, EventHandler, SubscriptionOptions };

package/dist/subscribr.js

@@ -1,2 +1,257 @@
-var s=class extends Map{set(e,t){return super.set(e,(super.get(e)??new Set).add(t)),this}hasValue(e,t){let n=super.get(e);return n?n.has(t):!1}find(e,t){let n=this.get(e);if(n!==void 0)return Array.from(n).find(t)}deleteValue(e,t){if(t===void 0)return this.delete(e);let n=super.get(e);if(n){let i=n.delete(t);return n.size===0&&super.delete(e),i}return!1}get[Symbol.toStringTag](){return"SetMultiMap"}};var r=class{context;eventListener;constructor(e,t){this.context=e,this.eventListener=t}handle(e,t){this.eventListener.call(this.context,e,t)}get[Symbol.toStringTag](){return"ContextEventHandler"}};var l=class{_eventName;_contextEventHandler;constructor(e,t){this._eventName=e,this._contextEventHandler=t}get eventName(){return this._eventName}get contextEventHandler(){return this._contextEventHandler}get[Symbol.toStringTag](){return"Subscription"}};var u=class{subscribers;constructor(){this.subscribers=new s}subscribe(e,t,n=t){let i=new r(n,t);return this.subscribers.set(e,i),new l(e,i)}unsubscribe({eventName:e,contextEventHandler:t}){let n=this.subscribers.get(e)??new Set,i=n.delete(t);return i&&n.size===0&&this.subscribers.delete(e),i}publish(e,t=new CustomEvent(e),n){this.subscribers.get(e)?.forEach(i=>i.handle(t,n))}isSubscribed({eventName:e,contextEventHandler:t}){return this.subscribers.get(e)?.has(t)??!1}get[Symbol.toStringTag](){return"Subscribr"}};export{r as ContextEventHandler,u as Subscribr,l as Subscription};
+// node_modules/.pnpm/@d1g1tal+collections@2.1.1_typescript@5.9.3/node_modules/@d1g1tal/collections/src/set-multi-map.ts
+var SetMultiMap = class extends Map {
+  /**
+   * Adds a new element with a specified key and value to the SetMultiMap.
+   * If an element with the same key already exists, the value will be added to the underlying {@link Set}.
+   * If the value already exists in the {@link Set}, it will not be added again.
+   *
+   * @param key The key to set.
+   * @param value The value to add to the SetMultiMap
+   * @returns The SetMultiMap with the updated key and value.
+   */
+  set(key, value) {
+    super.set(key, value instanceof Set ? value : (super.get(key) ?? /* @__PURE__ */ new Set()).add(value));
+    return this;
+  }
+  /**
+   * Finds a specific value for a specific key using an iterator function.
+   * @param key The key to find the value for.
+   * @param iterator The iterator function to use to find the value.
+   * @returns The value for the specified key
+   */
+  find(key, iterator) {
+    const values = this.get(key);
+    if (values !== void 0) {
+      return Array.from(values).find(iterator);
+    }
+    return void 0;
+  }
+  /**
+   * Checks if a specific key has a specific value.
+   *
+   * @param key The key to check.
+   * @param value The value to check.
+   * @returns True if the key has the value, false otherwise.
+   */
+  hasValue(key, value) {
+    const values = super.get(key);
+    return values ? values.has(value) : false;
+  }
+  /**
+   * Removes a specific value from a specific key.
+   * @param key The key to remove the value from.
+   * @param value The value to remove.
+   * @returns True if the value was removed, false otherwise.
+   */
+  deleteValue(key, value) {
+    if (value === void 0) {
+      return this.delete(key);
+    }
+    const values = super.get(key);
+    if (values) {
+      const deleted = values.delete(value);
+      if (values.size === 0) {
+        super.delete(key);
+      }
+      return deleted;
+    }
+    return false;
+  }
+  /**
+   * The string tag of the SetMultiMap.
+   * @returns The string tag of the SetMultiMap.
+   */
+  get [Symbol.toStringTag]() {
+    return "SetMultiMap";
+  }
+};
+
+// src/context-event-handler.ts
+var ContextEventHandler = class {
+  context;
+  eventHandler;
+  /**
+   * @param context The context to bind to the event handler.
+   * @param eventHandler The event handler to call when the event is published.
+   */
+  constructor(context, eventHandler) {
+    this.context = context;
+    this.eventHandler = eventHandler;
+  }
+  /**
+   * Call the event handler for the provided event.
+   *
+   * @param event The event to handle
+   * @param data The value to be passed to the event handler as a parameter.
+   */
+  handle(event, data) {
+    this.eventHandler.call(this.context, event, data);
+  }
+  /**
+   * A String value that is used in the creation of the default string
+   * description of an object. Called by the built-in method {@link Object.prototype.toString}.
+   *
+   * @returns The default string description of this object.
+   */
+  get [Symbol.toStringTag]() {
+    return "ContextEventHandler";
+  }
+};
+
+// src/subscription.ts
+var Subscription = class {
+  _eventName;
+  _contextEventHandler;
+  /**
+   * @param eventName The event name.
+   * @param contextEventHandler The context event handler.
+   */
+  constructor(eventName, contextEventHandler) {
+    this._eventName = eventName;
+    this._contextEventHandler = contextEventHandler;
+  }
+  /**
+   * Gets the event name for the subscription.
+   *
+   * @returns The event name.
+   */
+  get eventName() {
+    return this._eventName;
+  }
+  /**
+   * Gets the context event handler.
+   *
+   * @returns The context event handler
+   */
+  get contextEventHandler() {
+    return this._contextEventHandler;
+  }
+  /**
+   * A String value that is used in the creation of the default string
+   * description of an object. Called by the built-in method {@link Object.prototype.toString}.
+   *
+   * @returns The default string description of this object.
+   */
+  get [Symbol.toStringTag]() {
+    return "Subscription";
+  }
+};
+
+// src/subscribr.ts
+var Subscribr = class {
+  subscribers = new SetMultiMap();
+  errorHandler;
+  /**
+   * Set a custom error handler for handling errors that occur in event listeners.
+   * If not set, errors will be logged to the console.
+   *
+   * @param errorHandler The error handler function to call when an error occurs in an event listener.
+   */
+  setErrorHandler(errorHandler) {
+    this.errorHandler = errorHandler;
+  }
+  /**
+   * Subscribe to an event
+   *
+   * @param eventName The event name to subscribe to.
+   * @param eventHandler The event handler to call when the event is published.
+   * @param context The context to bind to the event handler.
+   * @param options Subscription options.
+   * @returns An object used to check if the subscription still exists and to unsubscribe from the event.
+   */
+  subscribe(eventName, eventHandler, context = eventHandler, options) {
+    this.validateEventName(eventName);
+    if (options?.once) {
+      const originalHandler = eventHandler;
+      eventHandler = (event, data) => {
+        originalHandler.call(context, event, data);
+        this.unsubscribe(subscription);
+      };
+    }
+    const contextEventHandler = new ContextEventHandler(context, eventHandler);
+    this.subscribers.set(eventName, contextEventHandler);
+    const subscription = new Subscription(eventName, contextEventHandler);
+    return subscription;
+  }
+  /**
+   * Unsubscribe from the event
+   *
+   * @param subscription The subscription to unsubscribe.
+   * @returns true if eventListener has been removed successfully. false if the value is not found or if the value is not an object.
+   */
+  unsubscribe({ eventName, contextEventHandler }) {
+    const contextEventHandlers = this.subscribers.get(eventName) ?? /* @__PURE__ */ new Set();
+    const removed = contextEventHandlers.delete(contextEventHandler);
+    if (removed && contextEventHandlers.size === 0) {
+      this.subscribers.delete(eventName);
+    }
+    return removed;
+  }
+  /**
+   * Publish an event
+   *
+   * @template T
+   * @param eventName The name of the event.
+   * @param event The event to be handled.
+   * @param data The value to be passed to the event handler as a parameter.
+   */
+  publish(eventName, event = new CustomEvent(eventName), data) {
+    this.validateEventName(eventName);
+    this.subscribers.get(eventName)?.forEach((contextEventHandler) => {
+      try {
+        contextEventHandler.handle(event, data);
+      } catch (error) {
+        if (this.errorHandler) {
+          this.errorHandler(error, eventName, event, data);
+        } else {
+          console.error(`Error in event handler for '${eventName}':`, error);
+        }
+      }
+    });
+  }
+  /**
+   * Check if the event and handler are subscribed.
+   *
+   * @param subscription The subscription object.
+   * @returns true if the event name and handler are subscribed, false otherwise.
+   */
+  isSubscribed({ eventName, contextEventHandler }) {
+    return this.subscribers.get(eventName)?.has(contextEventHandler) ?? false;
+  }
+  /**
+   * Validate the event name
+   *
+   * @param eventName The event name to validate.
+   * @throws {TypeError} If the event name is not a non-empty string.
+   * @throws {Error} If the event name has leading or trailing whitespace.
+   */
+  validateEventName(eventName) {
+    if (!eventName || typeof eventName !== "string") {
+      throw new TypeError("Event name must be a non-empty string");
+    }
+    if (eventName.trim() !== eventName) {
+      throw new Error("Event name cannot have leading or trailing whitespace");
+    }
+  }
+  /**
+   * Clears all subscriptions. The instance should not be used after calling this method.
+   */
+  destroy() {
+    this.subscribers.clear();
+  }
+  /**
+   * A String value that is used in the creation of the default string
+   * description of an object. Called by the built-in method {@link Object.prototype.toString}.
+   *
+   * @returns The default string description of this object.
+   */
+  get [Symbol.toStringTag]() {
+    return "Subscribr";
+  }
+};
+export {
+  ContextEventHandler,
+  Subscribr,
+  Subscription
+};
 //# sourceMappingURL=subscribr.js.map

package/dist/subscribr.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
-  "sources": ["../node_modules/.pnpm/@d1g1tal+collections@2.1.0_typescript@5.9.3/node_modules/@d1g1tal/collections/src/set-multi-map.ts", "../src/context-event-handler.ts", "../src/subscription.ts", "../src/subscribr.ts"],
-  "sourcesContent": ["/** A {@link Map} that can contain multiple, unique, values for the same key. */\nexport class SetMultiMap<K, V> extends Map<K, Set<V>>{\n\t/**\n\t * Adds a new element with a specified key and value to the SetMultiMap.\n\t * If an element with the same key already exists, the value will be added to the underlying {@link Set}.\n\t * If the value already exists in the {@link Set}, it will not be added again.\n\t *\n\t * @param key The key to set.\n\t * @param value The value to add to the SetMultiMap\n\t * @returns The SetMultiMap with the updated key and value.\n\t */\n\t// @ts-expect-error I am overriding the set method from the Map class\n\toverride set(key: K, value: V): SetMultiMap<K, V> {\n\t\tsuper.set(key, (super.get(key) ?? new Set()).add(value));\n\n\t\treturn this;\n\t}\n\n\t/**\n\t * Checks if a specific key has a specific value.\n\t *\n\t * @param key The key to check.\n\t * @param value The value to check.\n\t * @returns True if the key has the value, false otherwise.\n\t */\n\thasValue(key: K, value: V): boolean {\n\t\tconst values = super.get(key);\n\n\t\treturn values ? values.has(value) : false;\n\t}\n\n\t/**\n\t * Finds a specific value for a specific key using an iterator function.\n\t * @param key The key to find the value for.\n\t * @param iterator The iterator function to use to find the value.\n\t * @returns The value for the specified key\n\t */\n\tfind(key: K, iterator: (value: V) => boolean): V | undefined {\n\t\tconst values = this.get(key);\n\n\t\tif (values !== undefined) {\n\t\t\treturn Array.from(values).find(iterator);\n\t\t}\n\n\t\treturn undefined;\n\t}\n\n\t/**\n\t * Removes a specific value from a specific key.\n\t * @param key The key to remove the value from.\n\t * @param value The value to remove.\n\t * @returns True if the value was removed, false otherwise.\n\t */\n\tdeleteValue(key: K, value: V | undefined): boolean {\n\t\tif (value === undefined) { return this.delete(key) }\n\n\t\tconst values = super.get(key);\n\t\tif (values) {\n\t\t\tconst deleted = values.delete(value);\n\n\t\t\tif (values.size === 0) {\n\t\t\t\tsuper.delete(key);\n\t\t\t}\n\n\t\t\treturn deleted;\n\t\t}\n\n\t\treturn false;\n\t}\n\n\t/**\n\t * The string tag of the SetMultiMap.\n\t * @returns The string tag of the SetMultiMap.\n\t */\n\toverride get [Symbol.toStringTag](): string {\n\t\treturn 'SetMultiMap';\n\t}\n}", "import type { ContextEventListener } from './@types';\n\n/** A wrapper for an event handler that binds a context to the event handler. */\nexport class ContextEventHandler {\n\tprivate readonly context: unknown;\n\tprivate readonly eventListener: ContextEventListener;\n\n\t/**\n\t * @param context The context to bind to the event handler.\n\t * @param eventListener The event handler to call when the event is published.\n\t */\n\tconstructor(context: unknown, eventListener: ContextEventListener) {\n\t\tthis.context = context;\n\t\tthis.eventListener = eventListener;\n\t}\n\n\t/**\n\t * Call the event handler for the provided event.\n\t *\n\t * @param event The event to handle\n\t * @param data The value to be passed to the event handler as a parameter.\n\t */\n\thandle(event: Event, data?: unknown): void {\n\t\tthis.eventListener.call(this.context, event, data);\n\t}\n\n\t/**\n\t * A String value that is used in the creation of the default string\n\t * description of an object. Called by the built-in method {@link Object.prototype.toString}.\n\t *\n\t * @returns The default string description of this object.\n\t */\n\tget [Symbol.toStringTag](): string {\n\t\treturn 'ContextEventHandler';\n\t}\n}", "import type { ContextEventHandler } from './context-event-handler';\n\n/** Represents a subscription to an event. */\nexport class Subscription {\n\tprivate readonly _eventName: string;\n\tprivate readonly _contextEventHandler: ContextEventHandler;\n\n\t/**\n\t * @param eventName The event name.\n\t * @param contextEventHandler The context event handler.\n\t */\n\tconstructor(eventName: string, contextEventHandler: ContextEventHandler) {\n\t\tthis._eventName = eventName;\n\t\tthis._contextEventHandler = contextEventHandler;\n\t}\n\n\t/**\n\t * Gets the event name for the subscription.\n\t *\n\t * @returns The event name.\n\t */\n\tget eventName(): string {\n\t\treturn this._eventName;\n\t}\n\n\t/**\n\t * Gets the context event handler.\n\t *\n\t * @returns The context event handler\n\t */\n\tget contextEventHandler(): ContextEventHandler {\n\t\treturn this._contextEventHandler;\n\t}\n\n\t/**\n\t * A String value that is used in the creation of the default string\n\t * description of an object. Called by the built-in method {@link Object.prototype.toString}.\n\t *\n\t * @returns The default string description of this object.\n\t */\n\tget [Symbol.toStringTag](): string {\n\t\treturn 'Subscription';\n\t}\n}", "import { SetMultiMap } from '@d1g1tal/collections/src';\nimport { ContextEventHandler } from './context-event-handler';\nimport { Subscription } from './subscription';\nimport type { ContextEventListener } from './@types';\n\n/** A class that allows objects to subscribe to events and be notified when the event is published. */\nexport class Subscribr {\n\tprivate readonly subscribers: SetMultiMap<string, ContextEventHandler>;\n\n\tconstructor() {\n\t\tthis.subscribers = new SetMultiMap();\n\t}\n\n\t/**\n\t * Subscribe to an event\n\t *\n\t * @param eventName The event name to subscribe to.\n\t * @param eventHandler The event handler to call when the event is published.\n\t * @param context The context to bind to the event handler.\n\t * @returns An object used to check if the subscription still exists and to unsubscribe from the event.\n\t */\n\tsubscribe(eventName: string, eventHandler: ContextEventListener, context: unknown = eventHandler): Subscription {\n\t\tconst contextEventHandler = new ContextEventHandler(context, eventHandler);\n\t\tthis.subscribers.set(eventName, contextEventHandler);\n\n\t\treturn new Subscription(eventName, contextEventHandler);\n\t}\n\n\t/**\n\t * Unsubscribe from the event\n\t *\n\t * @param subscription The subscription to unsubscribe.\n\t * @returns true if eventListener has been removed successfully. false if the value is not found or if the value is not an object.\n\t */\n\tunsubscribe({ eventName, contextEventHandler }: Subscription): boolean {\n\t\tconst contextEventHandlers = this.subscribers.get(eventName) ?? new Set();\n\t\tconst removed = contextEventHandlers.delete(contextEventHandler);\n\n\t\tif (removed && contextEventHandlers.size === 0) {\tthis.subscribers.delete(eventName) }\n\n\t\treturn removed;\n\t}\n\n\t/**\n\t * Publish an event\n\t *\n\t * @template T\n\t * @param eventName The name of the event.\n\t * @param event The event to be handled.\n\t * @param data The value to be passed to the event handler as a parameter.\n\t */\n\tpublish<T>(eventName: string, event: Event = new CustomEvent(eventName), data?: T): void {\n\t\tthis.subscribers.get(eventName)?.forEach((contextEventHandler: ContextEventHandler) => contextEventHandler.handle(event, data));\n\t}\n\n\t/**\n\t * Check if the event and handler are subscribed.\n\t *\n\t * @param subscription The subscription object.\n\t * @returns true if the event name and handler are subscribed, false otherwise.\n\t */\n\tisSubscribed({ eventName, contextEventHandler }: Subscription): boolean {\n\t\treturn this.subscribers.get(eventName)?.has(contextEventHandler) ?? false;\n\t}\n\n\t/**\n\t * A String value that is used in the creation of the default string\n\t * description of an object. Called by the built-in method {@link Object.prototype.toString}.\n\t *\n\t * @returns The default string description of this object.\n\t */\n\tget [Symbol.toStringTag](): string {\n\t\treturn 'Subscribr';\n\t}\n}"],
-  "mappings": "AACO,IAAMA,EAAN,cAAgC,GAAc,CAW3C,IAAIC,EAAQC,EAA6B,CACjD,aAAM,IAAID,GAAM,MAAM,IAAIA,CAAG,GAAK,IAAI,KAAO,IAAIC,CAAK,CAAC,EAEhD,IACR,CASA,SAASD,EAAQC,EAAmB,CACnC,IAAMC,EAAS,MAAM,IAAIF,CAAG,EAE5B,OAAOE,EAASA,EAAO,IAAID,CAAK,EAAI,EACrC,CAQA,KAAKD,EAAQG,EAAgD,CAC5D,IAAMD,EAAS,KAAK,IAAIF,CAAG,EAE3B,GAAIE,IAAW,OACd,OAAO,MAAM,KAAKA,CAAM,EAAE,KAAKC,CAAQ,CAIzC,CAQA,YAAYH,EAAQC,EAA+B,CAClD,GAAIA,IAAU,OAAa,OAAO,KAAK,OAAOD,CAAG,EAEjD,IAAME,EAAS,MAAM,IAAIF,CAAG,EAC5B,GAAIE,EAAQ,CACX,IAAME,EAAUF,EAAO,OAAOD,CAAK,EAEnC,OAAIC,EAAO,OAAS,GACnB,MAAM,OAAOF,CAAG,EAGVI,CACR,CAEA,MAAO,EACR,CAMA,IAAc,OAAO,WAAW,GAAY,CAC3C,MAAO,aACR,CACD,EC1EO,IAAMC,EAAN,KAA0B,CACf,QACA,cAMjB,YAAYC,EAAkBC,EAAqC,CAClE,KAAK,QAAUD,EACf,KAAK,cAAgBC,CACtB,CAQA,OAAOC,EAAcC,EAAsB,CAC1C,KAAK,cAAc,KAAK,KAAK,QAASD,EAAOC,CAAI,CAClD,CAQA,IAAK,OAAO,WAAW,GAAY,CAClC,MAAO,qBACR,CACD,EChCO,IAAMC,EAAN,KAAmB,CACR,WACA,qBAMjB,YAAYC,EAAmBC,EAA0C,CACxE,KAAK,WAAaD,EAClB,KAAK,qBAAuBC,CAC7B,CAOA,IAAI,WAAoB,CACvB,OAAO,KAAK,UACb,CAOA,IAAI,qBAA2C,CAC9C,OAAO,KAAK,oBACb,CAQA,IAAK,OAAO,WAAW,GAAY,CAClC,MAAO,cACR,CACD,ECrCO,IAAMC,EAAN,KAAgB,CACL,YAEjB,aAAc,CACb,KAAK,YAAc,IAAIC,CACxB,CAUA,UAAUC,EAAmBC,EAAoCC,EAAmBD,EAA4B,CAC/G,IAAME,EAAsB,IAAIC,EAAoBF,EAASD,CAAY,EACzE,YAAK,YAAY,IAAID,EAAWG,CAAmB,EAE5C,IAAIE,EAAaL,EAAWG,CAAmB,CACvD,CAQA,YAAY,CAAE,UAAAH,EAAW,oBAAAG,CAAoB,EAA0B,CACtE,IAAMG,EAAuB,KAAK,YAAY,IAAIN,CAAS,GAAK,IAAI,IAC9DO,EAAUD,EAAqB,OAAOH,CAAmB,EAE/D,OAAII,GAAWD,EAAqB,OAAS,GAAK,KAAK,YAAY,OAAON,CAAS,EAE5EO,CACR,CAUA,QAAWP,EAAmBQ,EAAe,IAAI,YAAYR,CAAS,EAAGS,EAAgB,CACxF,KAAK,YAAY,IAAIT,CAAS,GAAG,QAASG,GAA6CA,EAAoB,OAAOK,EAAOC,CAAI,CAAC,CAC/H,CAQA,aAAa,CAAE,UAAAT,EAAW,oBAAAG,CAAoB,EAA0B,CACvE,OAAO,KAAK,YAAY,IAAIH,CAAS,GAAG,IAAIG,CAAmB,GAAK,EACrE,CAQA,IAAK,OAAO,WAAW,GAAY,CAClC,MAAO,WACR,CACD",
-  "names": ["SetMultiMap", "key", "value", "values", "iterator", "deleted", "ContextEventHandler", "context", "eventListener", "event", "data", "Subscription", "eventName", "contextEventHandler", "Subscribr", "SetMultiMap", "eventName", "eventHandler", "context", "contextEventHandler", "ContextEventHandler", "Subscription", "contextEventHandlers", "removed", "event", "data"]
+  "sources": ["../node_modules/.pnpm/@d1g1tal+collections@2.1.1_typescript@5.9.3/node_modules/@d1g1tal/collections/src/set-multi-map.ts", "../src/context-event-handler.ts", "../src/subscription.ts", "../src/subscribr.ts"],
+  "sourcesContent": ["/** A {@link Map} that can contain multiple, unique, values for the same key. */\nexport class SetMultiMap<K, V> extends Map<K, Set<V>>{\n\t/**\n\t * Adds a new element with a specified key and value to the SetMultiMap.\n\t * If an element with the same key already exists, the value will be added to the underlying {@link Set}.\n\t * If the value already exists in the {@link Set}, it will not be added again.\n\t *\n\t * @param key - The key to set.\n\t * @param value - The value to add to the SetMultiMap.\n\t * @returns The SetMultiMap with the updated key and value.\n\t */\n\toverride set(key: K, value: V): this;\n\t/**\n\t * Adds a new Set with a specified key and value to the SetMultiMap.\n\t * If an element with the same key already exists, the value will be added to the underlying {@link Set}.\n\t * If the value already exists in the {@link Set}, it will not be added again.\n\t *\n\t * @param key - The key to set.\n\t * @param value - The set of values to add to the SetMultiMap.\n\t * @returns The SetMultiMap with the updated key and value.\n\t */\n\toverride set(key: K, value: Set<V>): this;\n\t/**\n\t * Adds a new element with a specified key and value to the SetMultiMap.\n\t * If an element with the same key already exists, the value will be added to the underlying {@link Set}.\n\t * If the value already exists in the {@link Set}, it will not be added again.\n\t *\n\t * @param key The key to set.\n\t * @param value The value to add to the SetMultiMap\n\t * @returns The SetMultiMap with the updated key and value.\n\t */\n\toverride set(key: K, value: V | Set<V>): SetMultiMap<K, V> {\n\t\tsuper.set(key, value instanceof Set ? value : (super.get(key) ?? new Set<V>()).add(value));\n\n\t\treturn this;\n\t}\n\n\t/**\n\t * Finds a specific value for a specific key using an iterator function.\n\t * @param key The key to find the value for.\n\t * @param iterator The iterator function to use to find the value.\n\t * @returns The value for the specified key\n\t */\n\tfind(key: K, iterator: (value: V) => boolean): V | undefined {\n\t\tconst values = this.get(key);\n\n\t\tif (values !== undefined) {\n\t\t\treturn Array.from(values).find(iterator);\n\t\t}\n\n\t\treturn undefined;\n\t}\n\n\t/**\n\t * Checks if a specific key has a specific value.\n\t *\n\t * @param key The key to check.\n\t * @param value The value to check.\n\t * @returns True if the key has the value, false otherwise.\n\t */\n\thasValue(key: K, value: V): boolean {\n\t\tconst values = super.get(key);\n\n\t\treturn values ? values.has(value) : false;\n\t}\n\n\t/**\n\t * Removes a specific value from a specific key.\n\t * @param key The key to remove the value from.\n\t * @param value The value to remove.\n\t * @returns True if the value was removed, false otherwise.\n\t */\n\tdeleteValue(key: K, value: V | undefined): boolean {\n\t\tif (value === undefined) { return this.delete(key) }\n\n\t\tconst values = super.get(key);\n\t\tif (values) {\n\t\t\tconst deleted = values.delete(value);\n\n\t\t\tif (values.size === 0) {\n\t\t\t\tsuper.delete(key);\n\t\t\t}\n\n\t\t\treturn deleted;\n\t\t}\n\n\t\treturn false;\n\t}\n\n\t/**\n\t * The string tag of the SetMultiMap.\n\t * @returns The string tag of the SetMultiMap.\n\t */\n\toverride get [Symbol.toStringTag](): string {\n\t\treturn 'SetMultiMap';\n\t}\n}", "import type { EventHandler } from './@types';\n\n/** A wrapper for an event handler that binds a context to the event handler. */\nexport class ContextEventHandler {\n\tprivate readonly context: unknown;\n\tprivate readonly eventHandler: EventHandler;\n\n\t/**\n\t * @param context The context to bind to the event handler.\n\t * @param eventHandler The event handler to call when the event is published.\n\t */\n\tconstructor(context: unknown, eventHandler: EventHandler) {\n\t\tthis.context = context;\n\t\tthis.eventHandler = eventHandler;\n\t}\n\n\t/**\n\t * Call the event handler for the provided event.\n\t *\n\t * @param event The event to handle\n\t * @param data The value to be passed to the event handler as a parameter.\n\t */\n\thandle(event: Event, data?: unknown): void {\n\t\tthis.eventHandler.call(this.context, event, data);\n\t}\n\n\t/**\n\t * A String value that is used in the creation of the default string\n\t * description of an object. Called by the built-in method {@link Object.prototype.toString}.\n\t *\n\t * @returns The default string description of this object.\n\t */\n\tget [Symbol.toStringTag](): string {\n\t\treturn 'ContextEventHandler';\n\t}\n}", "import type { ContextEventHandler } from './context-event-handler';\n\n/** Represents a subscription to an event. */\nexport class Subscription {\n\tprivate readonly _eventName: string;\n\tprivate readonly _contextEventHandler: ContextEventHandler;\n\n\t/**\n\t * @param eventName The event name.\n\t * @param contextEventHandler The context event handler.\n\t */\n\tconstructor(eventName: string, contextEventHandler: ContextEventHandler) {\n\t\tthis._eventName = eventName;\n\t\tthis._contextEventHandler = contextEventHandler;\n\t}\n\n\t/**\n\t * Gets the event name for the subscription.\n\t *\n\t * @returns The event name.\n\t */\n\tget eventName(): string {\n\t\treturn this._eventName;\n\t}\n\n\t/**\n\t * Gets the context event handler.\n\t *\n\t * @returns The context event handler\n\t */\n\tget contextEventHandler(): ContextEventHandler {\n\t\treturn this._contextEventHandler;\n\t}\n\n\t/**\n\t * A String value that is used in the creation of the default string\n\t * description of an object. Called by the built-in method {@link Object.prototype.toString}.\n\t *\n\t * @returns The default string description of this object.\n\t */\n\tget [Symbol.toStringTag](): string {\n\t\treturn 'Subscription';\n\t}\n}", "import { SetMultiMap } from '@d1g1tal/collections/src';\nimport { ContextEventHandler } from './context-event-handler';\nimport { Subscription } from './subscription';\nimport type { EventHandler, ErrorHandler, SubscriptionOptions } from './@types';\n\n/** A class that allows objects to subscribe to events and be notified when the event is published. */\nexport class Subscribr {\n\tprivate readonly subscribers: SetMultiMap<string, ContextEventHandler> = new SetMultiMap();\n\tprivate errorHandler?: ErrorHandler;\n\n\t/**\n\t * Set a custom error handler for handling errors that occur in event listeners.\n\t * If not set, errors will be logged to the console.\n\t *\n\t * @param errorHandler The error handler function to call when an error occurs in an event listener.\n\t */\n\tsetErrorHandler(errorHandler: ErrorHandler): void {\n\t\tthis.errorHandler = errorHandler;\n\t}\n\n\t/**\n\t * Subscribe to an event\n\t *\n\t * @param eventName The event name to subscribe to.\n\t * @param eventHandler The event handler to call when the event is published.\n\t * @param context The context to bind to the event handler.\n\t * @param options Subscription options.\n\t * @returns An object used to check if the subscription still exists and to unsubscribe from the event.\n\t */\n\tsubscribe(eventName: string, eventHandler: EventHandler, context: unknown = eventHandler, options?: SubscriptionOptions): Subscription {\n\t\tthis.validateEventName(eventName);\n\n\t\t// If once option is set, wrap the handler to auto-unsubscribe\n\t\tif (options?.once) {\n\t\t\tconst originalHandler = eventHandler;\n\t\t\teventHandler = (event: Event, data?: unknown) => {\n\t\t\t\toriginalHandler.call(context, event, data);\n\t\t\t\tthis.unsubscribe(subscription);\n\t\t\t};\n\t\t}\n\n\t\tconst contextEventHandler = new ContextEventHandler(context, eventHandler);\n\t\tthis.subscribers.set(eventName, contextEventHandler);\n\n\t\tconst subscription = new Subscription(eventName, contextEventHandler);\n\n\t\treturn subscription;\n\t}\n\n\t/**\n\t * Unsubscribe from the event\n\t *\n\t * @param subscription The subscription to unsubscribe.\n\t * @returns true if eventListener has been removed successfully. false if the value is not found or if the value is not an object.\n\t */\n\tunsubscribe({ eventName, contextEventHandler }: Subscription): boolean {\n\t\tconst contextEventHandlers = this.subscribers.get(eventName) ?? new Set();\n\t\tconst removed = contextEventHandlers.delete(contextEventHandler);\n\n\t\tif (removed && contextEventHandlers.size === 0) {\tthis.subscribers.delete(eventName) }\n\n\t\treturn removed;\n\t}\n\n\t/**\n\t * Publish an event\n\t *\n\t * @template T\n\t * @param eventName The name of the event.\n\t * @param event The event to be handled.\n\t * @param data The value to be passed to the event handler as a parameter.\n\t */\n\tpublish<T>(eventName: string, event: Event = new CustomEvent(eventName), data?: T): void {\n\t\tthis.validateEventName(eventName);\n\t\tthis.subscribers.get(eventName)?.forEach((contextEventHandler: ContextEventHandler) => {\n\t\t\ttry {\n\t\t\t\tcontextEventHandler.handle(event, data);\n\t\t\t} catch (error) {\n\t\t\t\tif (this.errorHandler) {\n\t\t\t\t\tthis.errorHandler(error as Error, eventName, event, data);\n\t\t\t\t} else {\n\t\t\t\t\tconsole.error(`Error in event handler for '${eventName}':`, error);\n\t\t\t\t}\n\t\t\t}\n\t\t});\n\t}\n\n\t/**\n\t * Check if the event and handler are subscribed.\n\t *\n\t * @param subscription The subscription object.\n\t * @returns true if the event name and handler are subscribed, false otherwise.\n\t */\n\tisSubscribed({ eventName, contextEventHandler }: Subscription): boolean {\n\t\treturn this.subscribers.get(eventName)?.has(contextEventHandler) ?? false;\n\t}\n\n\t/**\n\t * Validate the event name\n\t *\n\t * @param eventName The event name to validate.\n\t * @throws {TypeError} If the event name is not a non-empty string.\n\t * @throws {Error} If the event name has leading or trailing whitespace.\n\t */\n\tprivate validateEventName(eventName: string): void {\n\t\tif (!eventName || typeof eventName !== 'string') {\n\t\t\tthrow new TypeError('Event name must be a non-empty string');\n\t\t}\n\n\t\tif (eventName.trim() !== eventName) {\n\t\t\tthrow new Error('Event name cannot have leading or trailing whitespace');\n\t\t}\n\t}\n\n\t/**\n\t * Clears all subscriptions. The instance should not be used after calling this method.\n\t */\n\tdestroy(): void {\n\t\tthis.subscribers.clear();\n\t}\n\n\t/**\n\t * A String value that is used in the creation of the default string\n\t * description of an object. Called by the built-in method {@link Object.prototype.toString}.\n\t *\n\t * @returns The default string description of this object.\n\t */\n\tget [Symbol.toStringTag](): string {\n\t\treturn 'Subscribr';\n\t}\n}"],
+  "mappings": ";AACO,IAAM,cAAN,cAAgC,IAAc;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EA8B3C,IAAI,KAAQ,OAAsC;AAC1D,UAAM,IAAI,KAAK,iBAAiB,MAAM,SAAS,MAAM,IAAI,GAAG,KAAK,oBAAI,IAAO,GAAG,IAAI,KAAK,CAAC;AAEzF,WAAO;AAAA,EACR;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQA,KAAK,KAAQ,UAAgD;AAC5D,UAAM,SAAS,KAAK,IAAI,GAAG;AAE3B,QAAI,WAAW,QAAW;AACzB,aAAO,MAAM,KAAK,MAAM,EAAE,KAAK,QAAQ;AAAA,IACxC;AAEA,WAAO;AAAA,EACR;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EASA,SAAS,KAAQ,OAAmB;AACnC,UAAM,SAAS,MAAM,IAAI,GAAG;AAE5B,WAAO,SAAS,OAAO,IAAI,KAAK,IAAI;AAAA,EACrC;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQA,YAAY,KAAQ,OAA+B;AAClD,QAAI,UAAU,QAAW;AAAE,aAAO,KAAK,OAAO,GAAG;AAAA,IAAE;AAEnD,UAAM,SAAS,MAAM,IAAI,GAAG;AAC5B,QAAI,QAAQ;AACX,YAAM,UAAU,OAAO,OAAO,KAAK;AAEnC,UAAI,OAAO,SAAS,GAAG;AACtB,cAAM,OAAO,GAAG;AAAA,MACjB;AAEA,aAAO;AAAA,IACR;AAEA,WAAO;AAAA,EACR;AAAA;AAAA;AAAA;AAAA;AAAA,EAMA,KAAc,OAAO,WAAW,IAAY;AAC3C,WAAO;AAAA,EACR;AACD;;;AC7FO,IAAM,sBAAN,MAA0B;AAAA,EACf;AAAA,EACA;AAAA;AAAA;AAAA;AAAA;AAAA,EAMjB,YAAY,SAAkB,cAA4B;AACzD,SAAK,UAAU;AACf,SAAK,eAAe;AAAA,EACrB;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQA,OAAO,OAAc,MAAsB;AAC1C,SAAK,aAAa,KAAK,KAAK,SAAS,OAAO,IAAI;AAAA,EACjD;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQA,KAAK,OAAO,WAAW,IAAY;AAClC,WAAO;AAAA,EACR;AACD;;;AChCO,IAAM,eAAN,MAAmB;AAAA,EACR;AAAA,EACA;AAAA;AAAA;AAAA;AAAA;AAAA,EAMjB,YAAY,WAAmB,qBAA0C;AACxE,SAAK,aAAa;AAClB,SAAK,uBAAuB;AAAA,EAC7B;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOA,IAAI,YAAoB;AACvB,WAAO,KAAK;AAAA,EACb;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOA,IAAI,sBAA2C;AAC9C,WAAO,KAAK;AAAA,EACb;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQA,KAAK,OAAO,WAAW,IAAY;AAClC,WAAO;AAAA,EACR;AACD;;;ACrCO,IAAM,YAAN,MAAgB;AAAA,EACL,cAAwD,IAAI,YAAY;AAAA,EACjF;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQR,gBAAgB,cAAkC;AACjD,SAAK,eAAe;AAAA,EACrB;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAWA,UAAU,WAAmB,cAA4B,UAAmB,cAAc,SAA6C;AACtI,SAAK,kBAAkB,SAAS;AAGhC,QAAI,SAAS,MAAM;AAClB,YAAM,kBAAkB;AACxB,qBAAe,CAAC,OAAc,SAAmB;AAChD,wBAAgB,KAAK,SAAS,OAAO,IAAI;AACzC,aAAK,YAAY,YAAY;AAAA,MAC9B;AAAA,IACD;AAEA,UAAM,sBAAsB,IAAI,oBAAoB,SAAS,YAAY;AACzE,SAAK,YAAY,IAAI,WAAW,mBAAmB;AAEnD,UAAM,eAAe,IAAI,aAAa,WAAW,mBAAmB;AAEpE,WAAO;AAAA,EACR;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQA,YAAY,EAAE,WAAW,oBAAoB,GAA0B;AACtE,UAAM,uBAAuB,KAAK,YAAY,IAAI,SAAS,KAAK,oBAAI,IAAI;AACxE,UAAM,UAAU,qBAAqB,OAAO,mBAAmB;AAE/D,QAAI,WAAW,qBAAqB,SAAS,GAAG;AAAE,WAAK,YAAY,OAAO,SAAS;AAAA,IAAE;AAErF,WAAO;AAAA,EACR;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAUA,QAAW,WAAmB,QAAe,IAAI,YAAY,SAAS,GAAG,MAAgB;AACxF,SAAK,kBAAkB,SAAS;AAChC,SAAK,YAAY,IAAI,SAAS,GAAG,QAAQ,CAAC,wBAA6C;AACtF,UAAI;AACH,4BAAoB,OAAO,OAAO,IAAI;AAAA,MACvC,SAAS,OAAO;AACf,YAAI,KAAK,cAAc;AACtB,eAAK,aAAa,OAAgB,WAAW,OAAO,IAAI;AAAA,QACzD,OAAO;AACN,kBAAQ,MAAM,+BAA+B,SAAS,MAAM,KAAK;AAAA,QAClE;AAAA,MACD;AAAA,IACD,CAAC;AAAA,EACF;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQA,aAAa,EAAE,WAAW,oBAAoB,GAA0B;AACvE,WAAO,KAAK,YAAY,IAAI,SAAS,GAAG,IAAI,mBAAmB,KAAK;AAAA,EACrE;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EASQ,kBAAkB,WAAyB;AAClD,QAAI,CAAC,aAAa,OAAO,cAAc,UAAU;AAChD,YAAM,IAAI,UAAU,uCAAuC;AAAA,IAC5D;AAEA,QAAI,UAAU,KAAK,MAAM,WAAW;AACnC,YAAM,IAAI,MAAM,uDAAuD;AAAA,IACxE;AAAA,EACD;AAAA;AAAA;AAAA;AAAA,EAKA,UAAgB;AACf,SAAK,YAAY,MAAM;AAAA,EACxB;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQA,KAAK,OAAO,WAAW,IAAY;AAClC,WAAO;AAAA,EACR;AACD;",
+  "names": []
 }

package/package.json

@@ -1,74 +1,72 @@
 {
-  "name": "@d1g1tal/subscribr",
-  "version": "4.0.4",
-  "description": "JavaScript Publish/Subscribe Library",
-  "author": "Jason DiMeo",
-  "license": "ISC",
-  "homepage": "https://github.com/D1g1talEntr0py/subscribr#readme",
-  "bugs": {
-    "url": "https://github.com/D1g1talEntr0py/subscribr/issues"
-  },
-  "keywords": [
-    "JavaScript",
-    "ObserverPattern",
-    "Publish/Subscribe"
-  ],
-  "publishConfig": {
-    "access": "public"
-  },
-  "type": "module",
-  "exports": {
-    ".": {
-      "types": "./dist/subscribr.d.ts",
-      "import": "./dist/subscribr.js"
-    },
-    "./src": {
-      "types": "./dist/subscribr.d.ts",
-      "import": "./src/index.ts"
-    }
-  },
-  "files": [
-    "/src",
-    "/dist"
-  ],
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/D1g1talEntr0py/subscribr.git"
-  },
-  "dependencies": {
-    "@d1g1tal/collections": "^2.1.0"
-  },
-  "devDependencies": {
-    "@d1g1tal/chrysalis": "^2.5.0",
-    "@eslint/compat": "^1.4.0",
-    "@eslint/js": "^9.37.0",
-    "@types/node": "^24.7.1",
-    "@typescript-eslint/eslint-plugin": "^8.46.0",
-    "@typescript-eslint/parser": "^8.46.0",
-    "@vitest/coverage-v8": "^3.2.4",
-    "eslint": "^9.37.0",
-    "eslint-plugin-compat": "^6.0.2",
-    "eslint-plugin-jsdoc": "^61.1.0",
-    "tsbuild": "link:../tsbuild",
-    "typescript-eslint": "^8.46.0",
-    "vitest": "^3.2.4"
-  },
-  "peerDependencies": {
-    "typescript": "^5.0.0"
-  },
-  "browserslist": [
-    "defaults and fully supports es6-module",
-    "node >= 20.15.1"
-  ],
-  "scripts": {
-    "build": "tsbuild",
-    "build:minify": "tsbuild --minify --force",
-    "build:watch": "tsbuild --watch",
-    "type-check": "tsbuild --typeCheck",
-    "lint": "eslint ./src",
-    "test": "vitest run",
-    "test:coverage": "vitest run --coverage",
-    "test:watch": "vitest",
-    "prepublish": "pnpm lint && pnpm test && pnpm -s build"
-  }
-}
+	"name": "@d1g1tal/subscribr",
+	"version": "4.1.8",
+	"packageManager": "pnpm@10.30.1",
+	"description": "JavaScript Publish/Subscribe Library",
+	"author": "Jason DiMeo",
+	"license": "ISC",
+	"homepage": "https://github.com/D1g1talEntr0py/subscribr#readme",
+	"bugs": {
+		"url": "https://github.com/D1g1talEntr0py/subscribr/issues"
+	},
+	"keywords": [
+		"JavaScript",
+		"ObserverPattern",
+		"Publish/Subscribe"
+	],
+	"publishConfig": {
+		"access": "public"
+	},
+	"type": "module",
+	"exports": {
+		".": {
+			"types": "./dist/subscribr.d.ts",
+			"import": "./dist/subscribr.js"
+		},
+		"./src": {
+			"types": "./dist/subscribr.d.ts",
+			"import": "./src/index.ts"
+		}
+	},
+	"files": [
+		"/src",
+		"/dist"
+	],
+	"scripts": {
+		"build": "tsbuild",
+		"build:minify": "tsbuild --minify --force",
+		"build:watch": "tsbuild --watch",
+		"type-check": "tsbuild --noEmit",
+		"lint": "eslint ./src",
+		"test": "vitest run",
+		"test:coverage": "vitest run --coverage",
+		"test:watch": "vitest",
+		"prepublish": "pnpm lint && pnpm test && pnpm -s build --force"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/D1g1talEntr0py/subscribr.git"
+	},
+	"dependencies": {
+		"@d1g1tal/collections": "^2.1.1"
+	},
+	"devDependencies": {
+		"@d1g1tal/tsbuild": "1.0.0",
+		"@eslint/compat": "^2.0.2",
+		"@eslint/js": "^10.0.1",
+		"@types/node": "^25.3.0",
+		"@typescript-eslint/eslint-plugin": "^8.56.0",
+		"@typescript-eslint/parser": "^8.56.0",
+		"@vitest/coverage-v8": "^4.0.18",
+		"eslint": "^10.0.1",
+		"eslint-plugin-compat": "^6.2.0",
+		"eslint-plugin-jsdoc": "^62.7.0",
+		"typescript": "^5.9.3",
+		"typescript-eslint": "^8.56.0",
+		"vitest": "^4.0.18"
+	},
+	"browserslist": [
+		"defaults and fully supports es6-module",
+		"node >= 20.15.1"
+	]
+}

package/src/@types/index.ts

@@ -1,4 +1,13 @@
 /** Context event listener function. */
-type ContextEventListener = (event: Event, data?: unknown) => void;
+type EventHandler = (event: Event, data?: unknown) => void;
 
-export type { ContextEventListener };
+/** Error handler function for handling errors in event listeners. */
+type ErrorHandler = (error: Error, eventName: string, event: Event, data?: unknown) => void;
+
+/** Subscription options. */
+interface SubscriptionOptions {
+	/** If true, the subscription will automatically unsubscribe after the first event. */
+	once?: boolean;
+}
+
+export type { EventHandler, ErrorHandler, SubscriptionOptions };

package/src/context-event-handler.ts

@@ -1,17 +1,17 @@
-import type { ContextEventListener } from './@types';
+import type { EventHandler } from './@types';
 
 /** A wrapper for an event handler that binds a context to the event handler. */
 export class ContextEventHandler {
 	private readonly context: unknown;
-	private readonly eventListener: ContextEventListener;
+	private readonly eventHandler: EventHandler;
 
 	/**
 	 * @param context The context to bind to the event handler.
-	 * @param eventListener The event handler to call when the event is published.
+	 * @param eventHandler The event handler to call when the event is published.
 	 */
-	constructor(context: unknown, eventListener: ContextEventListener) {
+	constructor(context: unknown, eventHandler: EventHandler) {
 		this.context = context;
-		this.eventListener = eventListener;
+		this.eventHandler = eventHandler;
 	}
 
 	/**
@@ -21,7 +21,7 @@ export class ContextEventHandler {
 	 * @param data The value to be passed to the event handler as a parameter.
 	 */
 	handle(event: Event, data?: unknown): void {
-		this.eventListener.call(this.context, event, data);
+		this.eventHandler.call(this.context, event, data);
 	}
 
 	/**

package/src/index.ts

@@ -1,4 +1,4 @@
 export { Subscribr } from './subscribr';
 export { Subscription } from './subscription';
 export { ContextEventHandler } from './context-event-handler';
-export type { ContextEventListener } from './@types';
+export type { EventHandler } from './@types';

package/src/subscribr.ts

@@ -1,14 +1,21 @@
 import { SetMultiMap } from '@d1g1tal/collections/src';
 import { ContextEventHandler } from './context-event-handler';
 import { Subscription } from './subscription';
-import type { ContextEventListener } from './@types';
+import type { EventHandler, ErrorHandler, SubscriptionOptions } from './@types';
 
 /** A class that allows objects to subscribe to events and be notified when the event is published. */
 export class Subscribr {
-	private readonly subscribers: SetMultiMap<string, ContextEventHandler>;
+	private readonly subscribers: SetMultiMap<string, ContextEventHandler> = new SetMultiMap();
+	private errorHandler?: ErrorHandler;
 
-	constructor() {
-		this.subscribers = new SetMultiMap();
+	/**
+	 * Set a custom error handler for handling errors that occur in event listeners.
+	 * If not set, errors will be logged to the console.
+	 *
+	 * @param errorHandler The error handler function to call when an error occurs in an event listener.
+	 */
+	setErrorHandler(errorHandler: ErrorHandler): void {
+		this.errorHandler = errorHandler;
 	}
 
 	/**
@@ -17,13 +24,27 @@ export class Subscribr {
 	 * @param eventName The event name to subscribe to.
 	 * @param eventHandler The event handler to call when the event is published.
 	 * @param context The context to bind to the event handler.
+	 * @param options Subscription options.
 	 * @returns An object used to check if the subscription still exists and to unsubscribe from the event.
 	 */
-	subscribe(eventName: string, eventHandler: ContextEventListener, context: unknown = eventHandler): Subscription {
+	subscribe(eventName: string, eventHandler: EventHandler, context: unknown = eventHandler, options?: SubscriptionOptions): Subscription {
+		this.validateEventName(eventName);
+
+		// If once option is set, wrap the handler to auto-unsubscribe
+		if (options?.once) {
+			const originalHandler = eventHandler;
+			eventHandler = (event: Event, data?: unknown) => {
+				originalHandler.call(context, event, data);
+				this.unsubscribe(subscription);
+			};
+		}
+
 		const contextEventHandler = new ContextEventHandler(context, eventHandler);
 		this.subscribers.set(eventName, contextEventHandler);
 
-		return new Subscription(eventName, contextEventHandler);
+		const subscription = new Subscription(eventName, contextEventHandler);
+
+		return subscription;
 	}
 
 	/**
@@ -50,7 +71,18 @@ export class Subscribr {
 	 * @param data The value to be passed to the event handler as a parameter.
 	 */
 	publish<T>(eventName: string, event: Event = new CustomEvent(eventName), data?: T): void {
-		this.subscribers.get(eventName)?.forEach((contextEventHandler: ContextEventHandler) => contextEventHandler.handle(event, data));
+		this.validateEventName(eventName);
+		this.subscribers.get(eventName)?.forEach((contextEventHandler: ContextEventHandler) => {
+			try {
+				contextEventHandler.handle(event, data);
+			} catch (error) {
+				if (this.errorHandler) {
+					this.errorHandler(error as Error, eventName, event, data);
+				} else {
+					console.error(`Error in event handler for '${eventName}':`, error);
+				}
+			}
+		});
 	}
 
 	/**
@@ -63,6 +95,30 @@ export class Subscribr {
 		return this.subscribers.get(eventName)?.has(contextEventHandler) ?? false;
 	}
 
+	/**
+	 * Validate the event name
+	 *
+	 * @param eventName The event name to validate.
+	 * @throws {TypeError} If the event name is not a non-empty string.
+	 * @throws {Error} If the event name has leading or trailing whitespace.
+	 */
+	private validateEventName(eventName: string): void {
+		if (!eventName || typeof eventName !== 'string') {
+			throw new TypeError('Event name must be a non-empty string');
+		}
+
+		if (eventName.trim() !== eventName) {
+			throw new Error('Event name cannot have leading or trailing whitespace');
+		}
+	}
+
+	/**
+	 * Clears all subscriptions. The instance should not be used after calling this method.
+	 */
+	destroy(): void {
+		this.subscribers.clear();
+	}
+
 	/**
 	 * A String value that is used in the creation of the default string
 	 * description of an object. Called by the built-in method {@link Object.prototype.toString}.