@asaidimu/utils-events 1.0.0

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Saidimu
+
+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,303 @@
+# @asaidimu/utils-events
+
+[![npm version](https://img.shields.io/npm/v/@asaidimu/utils-events.svg)](https://www.npmjs.com/package/@asaidimu/utils-events)
+[![license](https://img.shields.io/npm/l/@asaidimu/utils-events.svg)](https://github.com/asaidimu/erp-utils/blob/main/LICENSE)
+[![build status](https://img.shields.io/github/actions/workflow/status/asaidimu/erp-utils/ci.yml?branch=main)](https://github.com/asaidimu/erp-utils/actions)
+
+A lightweight, type-safe event bus for TypeScript applications with batching, cross-instance broadcast, and built-in metrics.
+
+> **Why another event bus?**
+> Many existing solutions either lack type safety or force a heavy dependency. This bus provides full TypeScript inference, optional batching to reduce synchronous dispatch overhead, and automatic cross-instance synchronisation – all in a tiny, zero-dependency package.
+
+---
+
+## 📚 Table of Contents
+
+- [Overview & Features](#overview--features)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [API Reference](#api-reference)
+  - [`createEventBus`](#createeventbus)
+  - [`.subscribe()`](#subscribe)
+  - [`.once()`](#once)
+  - [`.emit()`](#emit)
+  - [`.metrics()`](#metrics)
+  - [`.clear()`](#clear)
+- [Advanced Usage](#advanced-usage)
+  - [Batching / Deferred Mode](#batching--deferred-mode)
+  - [Cross-instance Broadcast](#cross-instance-broadcast)
+  - [Custom Error Handling](#custom-error-handling)
+- [Architecture Notes](#architecture-notes)
+- [Development & Contributing](#development--contributing)
+- [License](#license)
+
+---
+
+## Overview & Features
+
+`@asaidimu/utils-events` is a typed event bus designed for modern frontend and Node.js applications. It lets you define a strongly-typed event map once, then enjoy full autocompletion and compile-time checks for every `emit`, `subscribe`, and `once` call.
+
+### Key Features
+
+- 🔒 **Type-safe** – infer payload types from a single `EventMap` interface.
+- ⚡ **Batching (deferred mode)** – coalesce rapid-fire events into a single flush to reduce layout thrashing and improve performance.
+- 📡 **Cross-instance broadcast** – synchronise events across browser tabs using `BroadcastChannel` (with graceful fallback).
+- 🩺 **Built-in metrics** – track total events, active subscriptions, per-event counts, and average dispatch duration.
+- 🧹 **Cleanup utilities** – unsubscribe handles, `.clear()` to fully reset the bus.
+- 🪶 **Zero runtime dependencies** – small footprint, easy to audit.
+
+---
+
+## Installation
+
+```bash
+npm install @asaidimu/utils-events
+```
+
+```bash
+yarn add @asaidimu/utils-events
+```
+
+```bash
+pnpm add @asaidimu/utils-events
+```
+
+> **Requirements**: TypeScript 4.7+ (for `Record` generic inference) and a modern runtime that supports `performance.now()` and optionally `BroadcastChannel`.
+
+---
+
+## Quick Start
+
+```typescript
+import { createEventBus } from '@asaidimu/utils-events';
+
+// 1. Define your event map
+interface AppEvents {
+  userLogin: { userId: string; name: string };
+  dataUpdate: { records: number };
+  error: { message: string; code?: number };
+}
+
+// 2. Create the bus
+const bus = createEventBus<AppEvents>();
+
+// 3. Subscribe
+const unsubscribe = bus.subscribe('userLogin', (payload) => {
+  console.log(`Welcome ${payload.name}!`);
+});
+
+// 4. Emit an event
+bus.emit({ name: 'userLogin', payload: { userId: '123', name: 'Alice' } });
+// Logs: "Welcome Alice!"
+
+// 5. Unsubscribe when done
+unsubscribe();
+```
+
+---
+
+## API Reference
+
+### `createEventBus`
+
+```typescript
+function createEventBus<TEventMap extends Record<string, any>>(
+  options?: EventBusOptions
+): EventBus<TEventMap>
+```
+
+Creates a new event bus instance.
+
+#### Options
+
+| Option               | Type                          | Default                     | Description                                                                 |
+| -------------------- | ----------------------------- | --------------------------- | --------------------------------------------------------------------------- |
+| `batch.size`         | `number`                      | `undefined`                 | Enables **deferred mode**; flush when queue reaches this size.              |
+| `batch.delay`        | `number`                      | `1000` (if batching)        | Quiet period (ms) before flushing a batch.                                  |
+| `errorHandler`       | `(error: EventError) => void` | `console.error`             | Custom error handler for subscriber callbacks.                              |
+| `broadcast.channel`  | `string`                      | `"event-bus-channel"`       | Enables cross-instance broadcast using the given `BroadcastChannel` name.        |
+
+> If `batch.size` is provided, the bus runs in **deferred mode** (events are queued and flushed asynchronously). Otherwise it runs in **synchronous mode** (events are dispatched immediately).
+
+---
+
+### `.subscribe()`
+
+```typescript
+subscribe<TEventName extends keyof TEventMap>(
+  eventName: TEventName,
+  callback: (payload: TEventMap[TEventName]) => void
+): () => void
+```
+
+Registers a permanent listener. Returns an **unsubscribe function**.
+
+```typescript
+const off = bus.subscribe('dataUpdate', ({ records }) => {
+  updateUI(records);
+});
+
+// Later
+off();
+```
+
+---
+
+### `.once()`
+
+```typescript
+once<TEventName extends keyof TEventMap>(
+  eventName: TEventName,
+  callback: (payload: TEventMap[TEventName]) => void
+): () => void
+```
+
+Registers a one-time listener that automatically unsubscribes after the first emission. Returns a **cancel function** (to unsubscribe before it fires).
+
+```typescript
+bus.once('userLogin', (payload) => {
+  console.log('First login only');
+});
+
+// The callback will run at most once.
+```
+
+---
+
+### `.emit()`
+
+```typescript
+emit<TEventName extends keyof TEventMap>(
+  event: {
+    name: TEventName;
+    payload: TEventMap[TEventName];
+  }
+): void
+```
+
+Dispatches an event. In **synchronous mode** all subscribers run immediately. In **deferred mode** the event is queued and flushed according to `batch.size` and `batch.delay`. Cross-instance messages are sent **immediately** even in deferred mode to avoid latency.
+
+```typescript
+bus.emit({ name: 'dataUpdate', payload: { records: 42 } });
+```
+
+---
+
+### `.metrics()`
+
+```typescript
+metrics(): EventMetrics
+```
+
+Returns performance and usage statistics.
+
+```typescript
+console.log(bus.metrics());
+// {
+//   totalEvents: 127,
+//   activeSubscriptions: 5,
+//   eventCounts: Map { 'userLogin' => 45, 'dataUpdate' => 82 },
+//   averageEmitDuration: 0.32   // ms
+// }
+```
+
+---
+
+### `.clear()`
+
+```typescript
+clear(): void
+```
+
+Removes all subscriptions, clears the event queue (if in deferred mode), resets all metrics, and **re-opens** the `BroadcastChannel` (if enabled). After calling `clear()` the bus is fully reusable.
+
+```typescript
+bus.clear(); // fresh start
+```
+
+---
+
+## Advanced Usage
+
+### Batching / Deferred Mode
+
+When many events are fired in rapid succession (e.g., keystrokes, scroll handlers), synchronous dispatch can cause performance issues. Batching coalesces them into a single microtask / timer flush.
+
+```typescript
+const batchedBus = createEventBus<MyEvents>({
+  batch: {
+    size: 20,    // flush after 20 queued events
+    delay: 100   // or after 100ms of inactivity
+  }
+});
+```
+
+- If the queue reaches `batch.size` before the timer expires, it flushes immediately.
+- The timer resets on every new event (quiet period).
+- Metrics are still collected per event, so you can measure the real dispatch cost.
+
+### Cross-instance Broadcast
+
+Enable the `broadcast` option to automatically send every emitted event to other instances that share the same `channel` name. Events received from another instances are dispatched to **local subscribers** exactly as if they were emitted locally.
+
+```typescript
+const bus = createEventBus<MyEvents>({
+  broadcast: { channel: 'my-app-events' }
+});
+
+// In tab A
+bus.emit({ name: 'userLogin', payload: { userId: '1' } });
+
+// In tab B (same origin)
+bus.subscribe('userLogin', (payload) => {
+  console.log('Another tab logged in:', payload.userId);
+});
+```
+
+> ⚠️ `BroadcastChannel` is **not supported** in Node.js. The bus will log a warning and disable cross-instance functionality gracefully. For Node.js, simply omit the `broadcast` option.
+
+### Custom Error Handling
+
+By default, any error thrown inside a subscriber callback is caught and logged to `console.error`. Override this to send errors to a monitoring service.
+
+```typescript
+const bus = createEventBus<MyEvents>({
+  errorHandler: (err) => {
+    myErrorTracker.capture(err, {
+      eventName: err.eventName,
+      payload: err.payload
+    });
+  }
+});
+```
+
+The `EventError` interface extends `Error` and adds optional `eventName` and `payload` fields.
+
+---
+
+## Architecture Notes
+
+- **Subscriber snapshotting**: When an event is dispatched, the bus iterates over a **snapshot** of the current subscribers. This prevents bugs where a callback calls `unsubscribe()` on itself and stops other listeners from running.
+- **Metrics overhead**: `performance.now()` is called twice per synchronous event (or per event inside a batch). This overhead is negligible (< 0.01ms) but can be ignored if not needed.
+- **Cross-instance isolation**: `BroadcastChannel` does **not** send messages to the originating tab. Therefore there is no risk of infinite loops when broadcasting.
+- **Debouncer**: The batching mechanism uses an internal `Debouncer` utility that guarantees a final flush after the quiet period, even if no new events arrive.
+
+---
+
+### Reporting Issues
+
+Please use the [GitHub issue tracker](https://github.com/asaidimu/erp-utils/issues) and include:
+
+- A minimal reproduction (code snippet)
+- Expected vs actual behaviour
+- Environment (browser / Node, version)
+
+---
+
+## License
+
+MIT © [Saidimu](https://github.com/asaidimu). See [LICENSE](https://github.com/asaidimu/erp-utils/blob/main/LICENSE) for details.
+
+---
+
+**Built with ❤️ for type-safe event-driven architectures.**

package/index.d.mts

@@ -0,0 +1,172 @@
+/**
+ * Result when the debounced function successfully executed.
+ */
+type DebouncerOk<T> = {
+    status: "ok";
+    value: T;
+};
+/**
+ * Result when the debounced function threw an error.
+ */
+type DebouncerError = {
+    status: "error";
+    error: unknown;
+};
+/**
+ * Result when the debounced call was cancelled before execution.
+ */
+type DebouncerCancelled = {
+    status: "cancelled";
+};
+/**
+ * Discriminated union of all possible Debouncer outcomes.
+ *
+ * - `DebouncerOk<T>`: function ran and returned a value.
+ * - `DebouncerError`: function ran and threw an error.
+ * - `DebouncerCancelled`: call was cancelled before it ran.
+ */
+type DebouncerResult<T> = DebouncerOk<T> | DebouncerError | DebouncerCancelled;
+
+/**
+ * Options for configuring the EventBus.
+ * Each field has an independent default — passing a partial object is safe.
+ */
+interface EventBusOptions {
+    batch?: {
+        /**
+         * Maximum number of events to accumulate before forcing a synchronous
+         * flush, regardless of the batch delay timer.
+         */
+        size: number;
+        /**
+         * Milliseconds to wait (quiet period) before flushing a batch.
+         * Only applies when `deferred: true`.
+         * @default 16
+         */
+        delay?: number;
+    };
+    /**
+     * Called when a subscriber callback throws. Defaults to console.error.
+     * Errors in one subscriber do not prevent other subscribers from running.
+     */
+    errorHandler?: (error: EventError) => void;
+    /**
+     * When set, events are broadcast to other instances via BroadcastChannel.
+     * Only applies in environments that support BroadcastChannel.
+     */
+    broadcast?: {
+        /**
+         * The BroadcastChannel name used for cross-tab communication.
+         * Must be unique per logical bus if you run multiple buses.
+         * Only applies when `crossTab: true`.
+         */
+        channel: string;
+    };
+}
+/**
+ * Interface defining the shape of the EventBus.
+ * @template TEventMap - A record mapping event names to their respective payload types.
+ */
+interface EventBus<TEventMap extends Record<string, any>> {
+    /**
+     * Subscribes to a specific event by name.
+     * @param eventName - The name of the event to subscribe to.
+     * @param callback - The function to call when the event is emitted.
+     * @returns A function to unsubscribe from the event.
+     */
+    subscribe: <TEventName extends keyof TEventMap>(eventName: TEventName, callback: (payload: TEventMap[TEventName]) => void) => () => void;
+    /**
+     * Subscribes to an event and automatically unsubscribes after it fires once.
+     * @param eventName - The name of the event to subscribe to.
+     * @param callback - The function to call when the event is emitted.
+     * @returns A function to cancel the one-shot subscription before it fires.
+     */
+    once: <TEventName extends keyof TEventMap>(eventName: TEventName, callback: (payload: TEventMap[TEventName]) => void) => () => void;
+    /**
+     * Emits an event with a payload to all subscribed listeners.
+     * @param event - An object containing the event name and payload.
+     */
+    emit: <TEventName extends keyof TEventMap>(event: {
+        name: TEventName;
+        payload: TEventMap[TEventName];
+    }) => void;
+    /**
+     * Retrieves metrics about event bus usage.
+     * @returns An object containing various metrics.
+     */
+    metrics: () => EventMetrics;
+    /**
+     * Clears all subscriptions and resets metrics.
+     * After calling clear(), the bus is fully reset and can be reused —
+     * cross-tab communication is re-established if it was previously enabled.
+     */
+    clear: () => void;
+}
+/**
+ * Interface defining the metrics tracked by the EventBus.
+ */
+interface EventMetrics {
+    /** Total number of events emitted (both sync and deferred paths). */
+    totalEvents: number;
+    /** Number of active subscriptions across all event names. */
+    activeSubscriptions: number;
+    /** Map of event names to their emission counts. */
+    eventCounts: Map<string, number>;
+    /** Average duration of event dispatch in milliseconds. */
+    averageEmitDuration: number;
+}
+/**
+ * Custom error interface for event bus errors.
+ * @extends Error
+ */
+interface EventError extends Error {
+    /** Optional name of the event that caused the error. */
+    eventName?: string;
+    /** Optional payload that caused the error. */
+    payload?: unknown;
+}
+
+/**
+ * Creates a typed event bus.
+ */
+declare function createEventBus<TEventMap extends Record<string, any>>(options?: EventBusOptions): EventBus<TEventMap>;
+
+declare class Events<TEventMap extends Record<string, any>> implements EventBus<TEventMap> {
+    private bus;
+    constructor(options?: EventBusOptions);
+    /**
+     * Subscribes to a specific event by name.
+     * @param eventName - The name of the event to subscribe to.
+     * @param callback - The function to call when the event is emitted.
+     * @returns A function to unsubscribe from the event.
+     */
+    subscribe<TEventName extends keyof TEventMap>(eventName: TEventName, callback: (payload: TEventMap[TEventName]) => void): () => void;
+    /**
+     * Subscribes to an event and automatically unsubscribes after it fires once.
+     * @param eventName - The name of the event to subscribe to.
+     * @param callback - The function to call when the event is emitted.
+     * @returns A function to cancel the one-shot subscription before it fires.
+     */
+    once<TEventName extends keyof TEventMap>(eventName: TEventName, callback: (payload: TEventMap[TEventName]) => void): () => void;
+    /**
+     * Emits an event with a payload to all subscribed listeners.
+     * @param event - An object containing the event name and payload.
+     */
+    emit<TEventName extends keyof TEventMap>(event: {
+        name: TEventName;
+        payload: TEventMap[TEventName];
+    }): void;
+    /**
+     * Retrieves metrics about event bus usage.
+     * @returns An object containing various metrics.
+     */
+    metrics(): EventMetrics;
+    /**
+     * Clears all subscriptions and resets metrics.
+     * After calling clear(), the bus is fully reset and can be reused —
+     * cross-tab communication is re-established if it was previously enabled.
+     */
+    clear(): void;
+}
+
+export { type DebouncerResult, type EventBus, type EventBusOptions, type EventError, type EventMetrics, Events, createEventBus };

package/index.d.ts

@@ -0,0 +1,172 @@
+/**
+ * Result when the debounced function successfully executed.
+ */
+type DebouncerOk<T> = {
+    status: "ok";
+    value: T;
+};
+/**
+ * Result when the debounced function threw an error.
+ */
+type DebouncerError = {
+    status: "error";
+    error: unknown;
+};
+/**
+ * Result when the debounced call was cancelled before execution.
+ */
+type DebouncerCancelled = {
+    status: "cancelled";
+};
+/**
+ * Discriminated union of all possible Debouncer outcomes.
+ *
+ * - `DebouncerOk<T>`: function ran and returned a value.
+ * - `DebouncerError`: function ran and threw an error.
+ * - `DebouncerCancelled`: call was cancelled before it ran.
+ */
+type DebouncerResult<T> = DebouncerOk<T> | DebouncerError | DebouncerCancelled;
+
+/**
+ * Options for configuring the EventBus.
+ * Each field has an independent default — passing a partial object is safe.
+ */
+interface EventBusOptions {
+    batch?: {
+        /**
+         * Maximum number of events to accumulate before forcing a synchronous
+         * flush, regardless of the batch delay timer.
+         */
+        size: number;
+        /**
+         * Milliseconds to wait (quiet period) before flushing a batch.
+         * Only applies when `deferred: true`.
+         * @default 16
+         */
+        delay?: number;
+    };
+    /**
+     * Called when a subscriber callback throws. Defaults to console.error.
+     * Errors in one subscriber do not prevent other subscribers from running.
+     */
+    errorHandler?: (error: EventError) => void;
+    /**
+     * When set, events are broadcast to other instances via BroadcastChannel.
+     * Only applies in environments that support BroadcastChannel.
+     */
+    broadcast?: {
+        /**
+         * The BroadcastChannel name used for cross-tab communication.
+         * Must be unique per logical bus if you run multiple buses.
+         * Only applies when `crossTab: true`.
+         */
+        channel: string;
+    };
+}
+/**
+ * Interface defining the shape of the EventBus.
+ * @template TEventMap - A record mapping event names to their respective payload types.
+ */
+interface EventBus<TEventMap extends Record<string, any>> {
+    /**
+     * Subscribes to a specific event by name.
+     * @param eventName - The name of the event to subscribe to.
+     * @param callback - The function to call when the event is emitted.
+     * @returns A function to unsubscribe from the event.
+     */
+    subscribe: <TEventName extends keyof TEventMap>(eventName: TEventName, callback: (payload: TEventMap[TEventName]) => void) => () => void;
+    /**
+     * Subscribes to an event and automatically unsubscribes after it fires once.
+     * @param eventName - The name of the event to subscribe to.
+     * @param callback - The function to call when the event is emitted.
+     * @returns A function to cancel the one-shot subscription before it fires.
+     */
+    once: <TEventName extends keyof TEventMap>(eventName: TEventName, callback: (payload: TEventMap[TEventName]) => void) => () => void;
+    /**
+     * Emits an event with a payload to all subscribed listeners.
+     * @param event - An object containing the event name and payload.
+     */
+    emit: <TEventName extends keyof TEventMap>(event: {
+        name: TEventName;
+        payload: TEventMap[TEventName];
+    }) => void;
+    /**
+     * Retrieves metrics about event bus usage.
+     * @returns An object containing various metrics.
+     */
+    metrics: () => EventMetrics;
+    /**
+     * Clears all subscriptions and resets metrics.
+     * After calling clear(), the bus is fully reset and can be reused —
+     * cross-tab communication is re-established if it was previously enabled.
+     */
+    clear: () => void;
+}
+/**
+ * Interface defining the metrics tracked by the EventBus.
+ */
+interface EventMetrics {
+    /** Total number of events emitted (both sync and deferred paths). */
+    totalEvents: number;
+    /** Number of active subscriptions across all event names. */
+    activeSubscriptions: number;
+    /** Map of event names to their emission counts. */
+    eventCounts: Map<string, number>;
+    /** Average duration of event dispatch in milliseconds. */
+    averageEmitDuration: number;
+}
+/**
+ * Custom error interface for event bus errors.
+ * @extends Error
+ */
+interface EventError extends Error {
+    /** Optional name of the event that caused the error. */
+    eventName?: string;
+    /** Optional payload that caused the error. */
+    payload?: unknown;
+}
+
+/**
+ * Creates a typed event bus.
+ */
+declare function createEventBus<TEventMap extends Record<string, any>>(options?: EventBusOptions): EventBus<TEventMap>;
+
+declare class Events<TEventMap extends Record<string, any>> implements EventBus<TEventMap> {
+    private bus;
+    constructor(options?: EventBusOptions);
+    /**
+     * Subscribes to a specific event by name.
+     * @param eventName - The name of the event to subscribe to.
+     * @param callback - The function to call when the event is emitted.
+     * @returns A function to unsubscribe from the event.
+     */
+    subscribe<TEventName extends keyof TEventMap>(eventName: TEventName, callback: (payload: TEventMap[TEventName]) => void): () => void;
+    /**
+     * Subscribes to an event and automatically unsubscribes after it fires once.
+     * @param eventName - The name of the event to subscribe to.
+     * @param callback - The function to call when the event is emitted.
+     * @returns A function to cancel the one-shot subscription before it fires.
+     */
+    once<TEventName extends keyof TEventMap>(eventName: TEventName, callback: (payload: TEventMap[TEventName]) => void): () => void;
+    /**
+     * Emits an event with a payload to all subscribed listeners.
+     * @param event - An object containing the event name and payload.
+     */
+    emit<TEventName extends keyof TEventMap>(event: {
+        name: TEventName;
+        payload: TEventMap[TEventName];
+    }): void;
+    /**
+     * Retrieves metrics about event bus usage.
+     * @returns An object containing various metrics.
+     */
+    metrics(): EventMetrics;
+    /**
+     * Clears all subscriptions and resets metrics.
+     * After calling clear(), the bus is fully reset and can be reused —
+     * cross-tab communication is re-established if it was previously enabled.
+     */
+    clear(): void;
+}
+
+export { type DebouncerResult, type EventBus, type EventBusOptions, type EventError, type EventMetrics, Events, createEventBus };

package/index.js

@@ -0,0 +1 @@
+"use strict";var e=class{_delay;_leading;_timer;_pendingFn;_pendingResolvers=[];_leadingFired=!1;constructor(e){this._delay=e?.delay??300,this._leading=e?.leading??!1}do(e){return new Promise((t=>{this._enqueue(e,t)}))}fire(e){this._enqueue(e,void 0)}_enqueue(e,t){if(this._pendingFn=e,t&&this._pendingResolvers.push(t),this._leading&&!this._leadingFired)return this._leadingFired=!0,this._fire(),clearTimeout(this._timer),void(this._timer=setTimeout((()=>{this._leadingFired=!1,void 0!==this._pendingFn&&this._fire()}),this._delay));clearTimeout(this._timer),this._timer=setTimeout((()=>{this._leadingFired=!1,this._fire()}),this._delay)}cancel(){clearTimeout(this._timer),this._timer=void 0,this._pendingFn=void 0,this._leadingFired=!1;const e=this._pendingResolvers.splice(0);for(const t of e)t({status:"cancelled"})}async flush(){return this._pendingFn?(clearTimeout(this._timer),this._timer=void 0,this._leadingFired=!1,this._fire()):null}pending(){return void 0!==this._pendingFn}async _fire(){const e=this._pendingFn,t=this._pendingResolvers.splice(0);let n;this._pendingFn=void 0;try{n={status:"ok",value:await e()}}catch(e){n={status:"error",error:e}}for(const e of t)e(n);return n}};function t(t){const n=t??{},{deferred:s,batchSize:r,batchDelay:i,errorHandler:a,broadcast:o,channel:c}={deferred:null!=n.batch?.size,batchSize:n.batch?.size,batchDelay:n.batch?.delay||16,errorHandler:n.errorHandler||(e=>console.error("EventBus Error:",e)),broadcast:null!=n.broadcast?.channel&&n.broadcast.channel.length>0,channel:null!=n.broadcast?.channel&&n.broadcast.channel.length>0?n.broadcast?.channel:"event-bus-channel"},l=new Map;let d=[],h=0,u=0;const _=new Map,g=()=>{if(!o)return null;if("undefined"==typeof BroadcastChannel)return console.warn("EventBus: BroadcastChannel is not supported in this environment. Cross-tab notifications are disabled."),null;const e=new BroadcastChannel(c);return e.onmessage=e=>{const{name:t,payload:n}=e.data;f(t,n)},e};let m=g();const p=(e,t)=>{h++,u+=t,_.set(e,(_.get(e)??0)+1)},f=(e,t)=>{const n=l.get(e);if(n&&0!==n.size)for(const s of Array.from(n))try{s(t)}catch(n){const s=n instanceof Error?n:Object.assign(new Error(String(n)),{cause:n}),r=Object.assign(s,{eventName:e,payload:t});a(r)}},b=()=>{const e=d;d=[];for(const{name:t,payload:n}of e){const e=performance.now();f(t,n),p(t,performance.now()-e)}},v=new e({delay:i});return{subscribe:(e,t)=>{l.has(e)||l.set(e,new Set);const n=l.get(e);return n.add(t),()=>{n.delete(t),0===n.size&&l.delete(e)}},once:(e,t)=>{let n;const s=e=>{n(),t(e)};return n=(()=>{l.has(e)||l.set(e,new Set);const t=l.get(e);return t.add(s),()=>{t.delete(s),0===t.size&&l.delete(e)}})(),n},emit:({name:e,payload:t})=>{if(s)return d.push({name:e,payload:t}),d.length>=r?(v.cancel(),void b()):(v.fire((()=>b())),void m?.postMessage({name:e,payload:t}));const n=performance.now();f(e,t),p(e,performance.now()-n),m?.postMessage({name:e,payload:t})},metrics:()=>({totalEvents:h,activeSubscriptions:Array.from(l.values()).reduce(((e,t)=>e+t.size),0),eventCounts:_,averageEmitDuration:h>0?u/h:0}),clear:()=>{l.clear(),d=[],v.cancel(),h=0,u=0,_.clear(),m?.close(),m=g()}}}exports.Events=class{bus;constructor(e){this.bus=t(e)}subscribe(e,t){return this.bus.subscribe(e,t)}once(e,t){return this.bus.once(e,t)}emit(e){return this.bus.emit(e)}metrics(){return this.bus.metrics()}clear(){return this.bus.clear()}},exports.createEventBus=t;

package/index.mjs

@@ -0,0 +1 @@
+var e=class{_delay;_leading;_timer;_pendingFn;_pendingResolvers=[];_leadingFired=!1;constructor(e){this._delay=e?.delay??300,this._leading=e?.leading??!1}do(e){return new Promise((t=>{this._enqueue(e,t)}))}fire(e){this._enqueue(e,void 0)}_enqueue(e,t){if(this._pendingFn=e,t&&this._pendingResolvers.push(t),this._leading&&!this._leadingFired)return this._leadingFired=!0,this._fire(),clearTimeout(this._timer),void(this._timer=setTimeout((()=>{this._leadingFired=!1,void 0!==this._pendingFn&&this._fire()}),this._delay));clearTimeout(this._timer),this._timer=setTimeout((()=>{this._leadingFired=!1,this._fire()}),this._delay)}cancel(){clearTimeout(this._timer),this._timer=void 0,this._pendingFn=void 0,this._leadingFired=!1;const e=this._pendingResolvers.splice(0);for(const t of e)t({status:"cancelled"})}async flush(){return this._pendingFn?(clearTimeout(this._timer),this._timer=void 0,this._leadingFired=!1,this._fire()):null}pending(){return void 0!==this._pendingFn}async _fire(){const e=this._pendingFn,t=this._pendingResolvers.splice(0);let n;this._pendingFn=void 0;try{n={status:"ok",value:await e()}}catch(e){n={status:"error",error:e}}for(const e of t)e(n);return n}};function t(t){const n=t??{},{deferred:r,batchSize:s,batchDelay:i,errorHandler:a,broadcast:o,channel:c}={deferred:null!=n.batch?.size,batchSize:n.batch?.size,batchDelay:n.batch?.delay||16,errorHandler:n.errorHandler||(e=>console.error("EventBus Error:",e)),broadcast:null!=n.broadcast?.channel&&n.broadcast.channel.length>0,channel:null!=n.broadcast?.channel&&n.broadcast.channel.length>0?n.broadcast?.channel:"event-bus-channel"},l=new Map;let d=[],h=0,u=0;const _=new Map,g=()=>{if(!o)return null;if("undefined"==typeof BroadcastChannel)return console.warn("EventBus: BroadcastChannel is not supported in this environment. Cross-tab notifications are disabled."),null;const e=new BroadcastChannel(c);return e.onmessage=e=>{const{name:t,payload:n}=e.data;f(t,n)},e};let m=g();const p=(e,t)=>{h++,u+=t,_.set(e,(_.get(e)??0)+1)},f=(e,t)=>{const n=l.get(e);if(n&&0!==n.size)for(const r of Array.from(n))try{r(t)}catch(n){const r=n instanceof Error?n:Object.assign(new Error(String(n)),{cause:n}),s=Object.assign(r,{eventName:e,payload:t});a(s)}},b=()=>{const e=d;d=[];for(const{name:t,payload:n}of e){const e=performance.now();f(t,n),p(t,performance.now()-e)}},v=new e({delay:i});return{subscribe:(e,t)=>{l.has(e)||l.set(e,new Set);const n=l.get(e);return n.add(t),()=>{n.delete(t),0===n.size&&l.delete(e)}},once:(e,t)=>{let n;const r=e=>{n(),t(e)};return n=(()=>{l.has(e)||l.set(e,new Set);const t=l.get(e);return t.add(r),()=>{t.delete(r),0===t.size&&l.delete(e)}})(),n},emit:({name:e,payload:t})=>{if(r)return d.push({name:e,payload:t}),d.length>=s?(v.cancel(),void b()):(v.fire((()=>b())),void m?.postMessage({name:e,payload:t}));const n=performance.now();f(e,t),p(e,performance.now()-n),m?.postMessage({name:e,payload:t})},metrics:()=>({totalEvents:h,activeSubscriptions:Array.from(l.values()).reduce(((e,t)=>e+t.size),0),eventCounts:_,averageEmitDuration:h>0?u/h:0}),clear:()=>{l.clear(),d=[],v.cancel(),h=0,u=0,_.clear(),m?.close(),m=g()}}}var n=class{bus;constructor(e){this.bus=t(e)}subscribe(e,t){return this.bus.subscribe(e,t)}once(e,t){return this.bus.once(e,t)}emit(e){return this.bus.emit(e)}metrics(){return this.bus.metrics()}clear(){return this.bus.clear()}};export{n as Events,t as createEventBus};

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@asaidimu/utils-events",
+  "version": "1.0.0",
+  "description": "A lightweight, type-safe event bus implementation for TypeScript applications.",
+  "main": "index.js",
+  "module": "index.mjs",
+  "types": "index.d.ts",
+  "keywords": [
+    "typescript",
+    "utility"
+  ],
+  "author": "Saidimu <47994458+asaidimu@users.noreply.github.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/asaidimu/erp-utils.git"
+  },
+  "bugs": {
+    "url": "https://github.com/asaidimu/erp-utils/issues"
+  },
+  "homepage": "https://github.com/asaidimu/erp-utils/tree/main/src/events#readme",
+  "files": [
+    "./*"
+  ],
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./index.d.ts",
+        "default": "./index.mjs"
+      },
+      "require": {
+        "types": "./index.d.ts",
+        "default": "./index.js"
+      }
+    }
+  },
+  "dependencies": {},
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "tag": "latest",
+    "access": "public"
+  },
+  "release": {
+    "plugins": [
+      [
+        "@semantic-release/npm",
+        {
+          "pkgRoot": "./dist"
+        }
+      ],
+      [
+        "@semantic-release/git",
+        {
+          "assets": [
+            "CHANGELOG.md",
+            "package.json"
+          ],
+          "message": "chore(release): Release @asaidimu/utils-events v${nextRelease.version} [skip ci]\n\n${nextRelease.notes}"
+        }
+      ]
+    ]
+  }
+}