@asaidimu/utils-events 1.2.2 → 1.2.4

package/index.d.cts

@@ -0,0 +1,200 @@
+//#region src/sync/debouncer.d.ts
+/**
+ * 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;
+//#endregion
+//#region src/events/types.d.ts
+/**
+ * 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.
+   * @param options -  Extra options to determine the behaviour of the
+   * subscription
+   * @returns A function to unsubscribe from the event.
+   */
+  subscribe<TEventName extends keyof TEventMap | "*">(eventName: TEventName, callback: TEventName extends "*" ? (payload: TEventMap[keyof TEventMap], event: keyof TEventMap) => void : (payload: TEventMap[TEventName]) => void, options?: SubscribeOptions): () => 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: TEventName extends "*" ? (payload: TEventMap[keyof TEventMap], event: keyof TEventMap) => void : (payload: TEventMap[TEventName]) => void, options?: SubscribeOptions): () => 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.
+   *
+   * @param options - Optional configuration object.
+   * @param options.permanent - If `true`, the bus becomes permanently unusable after clearing.
+   *                            Defaults to `false`.
+   * @returns {void}
+   */
+  clear: (options?: {
+    permanent?: boolean;
+  }) => 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;
+}
+interface SubscribeOptions {
+  /**
+   * Debounce delay in milliseconds. When multiple events arrive in quick
+   * succession, the callback runs only after the quiet period ends, using the
+   * latest payload. Default = no debouncing.
+   */
+  debounce?: number;
+}
+//#endregion
+//#region src/events/events.d.ts
+/**
+ * Creates a typed event bus.
+ *
+ * Options are validated eagerly so misconfiguration surfaces at construction
+ * time rather than silently producing wrong behaviour at runtime.
+ *
+ * The bus now supports a universal wildcard event named `*`. Subscribing to
+ * `*` will receive all event payloads. Emitting to `*` is forbidden.
+ */
+declare function createEventBus<TEventMap extends Record<string, any>>(options?: EventBusOptions): EventBus<TEventMap>;
+//#endregion
+//#region src/events/event-class.d.ts
+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: TEventName extends "*" ? (payload: TEventMap[keyof TEventMap], event: keyof TEventMap) => void : (payload: TEventMap[TEventName]) => void, options?: SubscribeOptions): () => 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: TEventName extends "*" ? (payload: TEventMap[keyof TEventMap], event: keyof TEventMap) => void : (payload: TEventMap[TEventName]) => void, options?: SubscribeOptions): () => 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;
+}
+//#endregion
+export { type DebouncerResult, EventBus, EventBusOptions, EventError, EventMetrics, Events, SubscribeOptions, createEventBus };

package/index.d.ts

@@ -1,149 +1,124 @@
-/**
- * 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;
+import { DebouncerResult } from "@asaidimu/utils-sync";
 
+//#region src/events/types.d.ts
 /**
  * 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;
-    };
+  batch?: {
     /**
-     * Called when a subscriber callback throws. Defaults to console.error.
-     * Errors in one subscriber do not prevent other subscribers from running.
+     * Maximum number of events to accumulate before forcing a synchronous
+     * flush, regardless of the batch delay timer.
      */
-    errorHandler?: (error: EventError) => void;
+    size: number;
     /**
-     * When set, events are broadcast to other instances via BroadcastChannel.
-     * Only applies in environments that support BroadcastChannel.
+     * Milliseconds to wait (quiet period) before flushing a batch.
+     * Only applies when `deferred: true`.
+     * @default 16
      */
-    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;
-    };
+    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.
-     * @param options -  Extra options to determine the behaviour of the
-     * subscription
-     * @returns A function to unsubscribe from the event.
-     */
-    subscribe<TEventName extends keyof TEventMap | "*">(eventName: TEventName, callback: TEventName extends "*" ? (payload: TEventMap[keyof TEventMap], event: keyof TEventMap) => void : (payload: TEventMap[TEventName]) => void, options?: SubscribeOptions): () => 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: TEventName extends "*" ? (payload: TEventMap[keyof TEventMap], event: keyof TEventMap) => void : (payload: TEventMap[TEventName]) => void, options?: SubscribeOptions): () => 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.
-     *
-     * @param options - Optional configuration object.
-     * @param options.permanent - If `true`, the bus becomes permanently unusable after clearing.
-     *                            Defaults to `false`.
-     * @returns {void}
-     */
-    clear: (options?: {
-        permanent?: boolean;
-    }) => void;
+  /**
+   * 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.
+   * @param options -  Extra options to determine the behaviour of the
+   * subscription
+   * @returns A function to unsubscribe from the event.
+   */
+  subscribe<TEventName extends keyof TEventMap | "*">(eventName: TEventName, callback: TEventName extends "*" ? (payload: TEventMap[keyof TEventMap], event: keyof TEventMap) => void : (payload: TEventMap[TEventName]) => void, options?: SubscribeOptions): () => 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: TEventName extends "*" ? (payload: TEventMap[keyof TEventMap], event: keyof TEventMap) => void : (payload: TEventMap[TEventName]) => void, options?: SubscribeOptions): () => 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.
+   *
+   * @param options - Optional configuration object.
+   * @param options.permanent - If `true`, the bus becomes permanently unusable after clearing.
+   *                            Defaults to `false`.
+   * @returns {void}
+   */
+  clear: (options?: {
+    permanent?: boolean;
+  }) => 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;
+  /** 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;
+  /** Optional name of the event that caused the error. */
+  eventName?: string;
+  /** Optional payload that caused the error. */
+  payload?: unknown;
 }
 interface SubscribeOptions {
-    /**
-     * Debounce delay in milliseconds. When multiple events arrive in quick
-     * succession, the callback runs only after the quiet period ends, using the
-     * latest payload. Default = no debouncing.
-     */
-    debounce?: number;
+  /**
+   * Debounce delay in milliseconds. When multiple events arrive in quick
+   * succession, the callback runs only after the quiet period ends, using the
+   * latest payload. Default = no debouncing.
+   */
+  debounce?: number;
 }
-
+//#endregion
+//#region src/events/events.d.ts
 /**
  * Creates a typed event bus.
  *
@@ -154,43 +129,44 @@ interface SubscribeOptions {
  * `*` will receive all event payloads. Emitting to `*` is forbidden.
  */
 declare function createEventBus<TEventMap extends Record<string, any>>(options?: EventBusOptions): EventBus<TEventMap>;
-
+//#endregion
+//#region src/events/event-class.d.ts
 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: TEventName extends "*" ? (payload: TEventMap[keyof TEventMap], event: keyof TEventMap) => void : (payload: TEventMap[TEventName]) => void, options?: SubscribeOptions): () => 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: TEventName extends "*" ? (payload: TEventMap[keyof TEventMap], event: keyof TEventMap) => void : (payload: TEventMap[TEventName]) => void, options?: SubscribeOptions): () => 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;
+  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: TEventName extends "*" ? (payload: TEventMap[keyof TEventMap], event: keyof TEventMap) => void : (payload: TEventMap[TEventName]) => void, options?: SubscribeOptions): () => 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: TEventName extends "*" ? (payload: TEventMap[keyof TEventMap], event: keyof TEventMap) => void : (payload: TEventMap[TEventName]) => void, options?: SubscribeOptions): () => 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, type SubscribeOptions, createEventBus };
+//#endregion
+export { type DebouncerResult, EventBus, EventBusOptions, EventError, EventMetrics, Events, SubscribeOptions, createEventBus };

package/index.js

@@ -1 +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??{},s=n.errorHandler??(e=>console.error("EventBus Error:",e)),r=null!=n.batch?.size,i=n.batch?.size,o=n.batch?.delay??16;if(r&&(i<=0||!Number.isFinite(i)))throw new Error(`EventBus: batch.size must be a positive finite number, got ${i}.`);if(r&&(o<0||!Number.isFinite(o)))throw new Error(`EventBus: batch.delay must be a non-negative finite number, got ${o}.`);const a=n.broadcast?.channel,c=null!=a&&a.length>0,l=new Map,u=new Map;let d=[];const h=r?new e({delay:o}):null;let f=0,m=0;const g=new Map,p=()=>{if(!c)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(a);return e.onmessage=e=>{const{name:t,payload:n}=e.data;v(t,n)},e};let b=p();const _=(e,t)=>{f++,m+=t,g.set(e,(g.get(e)??0)+1)},v=(e,t)=>{const n=l.get(e);if(n&&n.size>0)for(const{callback:r}of Array.from(n.values()))try{r(t)}catch(n){const r=n instanceof Error?n:Object.assign(new Error(String(n)),{cause:n}),i=Object.assign(r,{eventName:e,payload:t});s(i)}if(u.size>0)for(const{callback:n}of Array.from(u.values()))try{n(t&&"object"==typeof t?{...t}:t,e)}catch(e){const n=e instanceof Error?e:Object.assign(new Error(String(e)),{cause:e}),r=Object.assign(n,{eventName:"*",payload:t});s(r)}},y=(t,n,s)=>{let r,i;void 0!==s&&s>0?(i=new e({delay:s,leading:!1}),r=(e,t)=>{i.fire(()=>{void 0!==t?n(e,t):n(e)})}):r=n;const o={callback:r,debouncer:i};if("*"===t)return u.set(n,o),()=>{const e=u.get(n);e&&(e.debouncer?.cancel(),u.delete(n))};{l.has(t)||l.set(t,new Map);const e=l.get(t);return e.set(n,o),()=>{const s=e.get(n);s&&(s.debouncer?.cancel(),e.delete(n),0===e.size&&l.delete(t))}}},w=()=>{const e=d;d=[];for(const{name:t,payload:n}of e){const e=performance.now();v(t,n),_(t,performance.now()-e)}};return{subscribe:(e,t,n)=>y(e,t,n?.debounce),once(e,t,n){let s;return s=y(e,(e,n)=>{s(),n?t(e,n):t(e)},n?.debounce),s},emit({name:e,payload:t}){if("*"===e)throw new Error('EventBus: Emitting to wildcard event "*" is forbidden.');if(r)return d.push({name:e,payload:t}),d.length>=i?(h.cancel(),void w()):(h.fire(()=>w()),void b?.postMessage({name:e,payload:t}));const n=performance.now();v(e,t),_(e,performance.now()-n),b?.postMessage({name:e,payload:t})},metrics:()=>({totalEvents:f,activeSubscriptions:Array.from(l.values()).reduce((e,t)=>e+t.size,0)+u.size,eventCounts:new Map(g),averageEmitDuration:f>0?m/f:0}),clear:e=>{h?.cancel(),d=[];for(const e of l.values())for(const{debouncer:t}of e.values())t?.cancel();l.clear();for(const{debouncer:e}of u.values())e?.cancel();u.clear(),f=0,m=0,g.clear(),b?.close(),b=e?.permanent?null:p()}}}exports.Events=class{bus;constructor(e){this.bus=t(e)}subscribe(e,t,n){return this.bus.subscribe(e,t,n)}once(e,t,n){return this.bus.once(e,t,n)}emit(e){return this.bus.emit(e)}metrics(){return this.bus.metrics()}clear(){return this.bus.clear()}},exports.createEventBus=t;
+Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});let e=require("@asaidimu/utils-sync");function t(t){let n=t??{},r=n.errorHandler??(e=>console.error(`EventBus Error:`,e)),i=n.batch?.size!=null,a=n.batch?.size,o=n.batch?.delay??16;if(i&&(a<=0||!Number.isFinite(a)))throw Error(`EventBus: batch.size must be a positive finite number, got ${a}.`);if(i&&(o<0||!Number.isFinite(o)))throw Error(`EventBus: batch.delay must be a non-negative finite number, got ${o}.`);let s=n.broadcast?.channel,c=s!=null&&s.length>0,l=new Map,u=new Map,d=[],f=i?new e.Debouncer({delay:o}):null,p=0,m=0,h=new Map,g=()=>{if(!c)return null;if(typeof BroadcastChannel>`u`)return console.warn(`EventBus: BroadcastChannel is not supported in this environment. Cross-tab notifications are disabled.`),null;let e=new BroadcastChannel(s);return e.onmessage=e=>{let{name:t,payload:n}=e.data;y(t,n)},e},_=g(),v=(e,t)=>{p++,m+=t,h.set(e,(h.get(e)??0)+1)},y=(e,t)=>{let n=l.get(e);if(n&&n.size>0)for(let{callback:i}of Array.from(n.values()))try{i(t)}catch(n){let i=n instanceof Error?n:Object.assign(Error(String(n)),{cause:n});r(Object.assign(i,{eventName:e,payload:t}))}if(u.size>0)for(let{callback:n}of Array.from(u.values()))try{n(t&&typeof t==`object`?{...t}:t,e)}catch(e){let n=e instanceof Error?e:Object.assign(Error(String(e)),{cause:e});r(Object.assign(n,{eventName:`*`,payload:t}))}},b=(t,n,r)=>{let i,a;r!==void 0&&r>0?(a=new e.Debouncer({delay:r,leading:!1}),i=(e,t)=>{a.fire(()=>{t===void 0?n(e):n(e,t)})}):i=n;let o={callback:i,debouncer:a};if(t===`*`)return u.set(n,o),()=>{let e=u.get(n);e&&(e.debouncer?.cancel(),u.delete(n))};{l.has(t)||l.set(t,new Map);let e=l.get(t);return e.set(n,o),()=>{let r=e.get(n);r&&(r.debouncer?.cancel(),e.delete(n),e.size===0&&l.delete(t))}}},x=()=>{let e=d;d=[];for(let{name:t,payload:n}of e){let e=performance.now();y(t,n),v(t,performance.now()-e)}};return{subscribe(e,t,n){return b(e,t,n?.debounce)},once(e,t,n){let r;return r=b(e,(e,n)=>{r(),n?t(e,n):t(e)},n?.debounce),r},emit({name:e,payload:t}){if(e===`*`)throw Error(`EventBus: Emitting to wildcard event "*" is forbidden.`);if(i){if(d.push({name:e,payload:t}),d.length>=a){f.cancel(),x();return}f.fire(()=>x()),_?.postMessage({name:e,payload:t});return}let n=performance.now();y(e,t),v(e,performance.now()-n),_?.postMessage({name:e,payload:t})},metrics:()=>({totalEvents:p,activeSubscriptions:Array.from(l.values()).reduce((e,t)=>e+t.size,0)+u.size,eventCounts:new Map(h),averageEmitDuration:p>0?m/p:0}),clear:e=>{f?.cancel(),d=[];for(let e of l.values())for(let{debouncer:t}of e.values())t?.cancel();l.clear();for(let{debouncer:e}of u.values())e?.cancel();u.clear(),p=0,m=0,h.clear(),_?.close(),_=e?.permanent?null:g()}}}var n=class{bus;constructor(e){this.bus=t(e)}subscribe(e,t,n){return this.bus.subscribe(e,t,n)}once(e,t,n){return this.bus.once(e,t,n)}emit(e){return this.bus.emit(e)}metrics(){return this.bus.metrics()}clear(){return this.bus.clear()}};exports.Events=n,exports.createEventBus=t;

package/index.mjs

@@ -1 +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(n=>{this._enqueue(e,n)})}fire(e){this._enqueue(e,void 0)}_enqueue(e,n){if(this._pendingFn=e,n&&this._pendingResolvers.push(n),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 n of e)n({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,n=this._pendingResolvers.splice(0);let t;this._pendingFn=void 0;try{t={status:"ok",value:await e()}}catch(e){t={status:"error",error:e}}for(const e of n)e(t);return t}};function n(n){const t=n??{},r=t.errorHandler??(e=>console.error("EventBus Error:",e)),s=null!=t.batch?.size,i=t.batch?.size,o=t.batch?.delay??16;if(s&&(i<=0||!Number.isFinite(i)))throw new Error(`EventBus: batch.size must be a positive finite number, got ${i}.`);if(s&&(o<0||!Number.isFinite(o)))throw new Error(`EventBus: batch.delay must be a non-negative finite number, got ${o}.`);const a=t.broadcast?.channel,c=null!=a&&a.length>0,l=new Map,d=new Map;let u=[];const h=s?new e({delay:o}):null;let f=0,m=0;const g=new Map,b=()=>{if(!c)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(a);return e.onmessage=e=>{const{name:n,payload:t}=e.data;v(n,t)},e};let p=b();const _=(e,n)=>{f++,m+=n,g.set(e,(g.get(e)??0)+1)},v=(e,n)=>{const t=l.get(e);if(t&&t.size>0)for(const{callback:s}of Array.from(t.values()))try{s(n)}catch(t){const s=t instanceof Error?t:Object.assign(new Error(String(t)),{cause:t}),i=Object.assign(s,{eventName:e,payload:n});r(i)}if(d.size>0)for(const{callback:t}of Array.from(d.values()))try{t(n&&"object"==typeof n?{...n}:n,e)}catch(e){const t=e instanceof Error?e:Object.assign(new Error(String(e)),{cause:e}),s=Object.assign(t,{eventName:"*",payload:n});r(s)}},y=(n,t,r)=>{let s,i;void 0!==r&&r>0?(i=new e({delay:r,leading:!1}),s=(e,n)=>{i.fire(()=>{void 0!==n?t(e,n):t(e)})}):s=t;const o={callback:s,debouncer:i};if("*"===n)return d.set(t,o),()=>{const e=d.get(t);e&&(e.debouncer?.cancel(),d.delete(t))};{l.has(n)||l.set(n,new Map);const e=l.get(n);return e.set(t,o),()=>{const r=e.get(t);r&&(r.debouncer?.cancel(),e.delete(t),0===e.size&&l.delete(n))}}},w=()=>{const e=u;u=[];for(const{name:n,payload:t}of e){const e=performance.now();v(n,t),_(n,performance.now()-e)}};return{subscribe:(e,n,t)=>y(e,n,t?.debounce),once(e,n,t){let r;return r=y(e,(e,t)=>{r(),t?n(e,t):n(e)},t?.debounce),r},emit({name:e,payload:n}){if("*"===e)throw new Error('EventBus: Emitting to wildcard event "*" is forbidden.');if(s)return u.push({name:e,payload:n}),u.length>=i?(h.cancel(),void w()):(h.fire(()=>w()),void p?.postMessage({name:e,payload:n}));const t=performance.now();v(e,n),_(e,performance.now()-t),p?.postMessage({name:e,payload:n})},metrics:()=>({totalEvents:f,activeSubscriptions:Array.from(l.values()).reduce((e,n)=>e+n.size,0)+d.size,eventCounts:new Map(g),averageEmitDuration:f>0?m/f:0}),clear:e=>{h?.cancel(),u=[];for(const e of l.values())for(const{debouncer:n}of e.values())n?.cancel();l.clear();for(const{debouncer:e}of d.values())e?.cancel();d.clear(),f=0,m=0,g.clear(),p?.close(),p=e?.permanent?null:b()}}}var t=class{bus;constructor(e){this.bus=n(e)}subscribe(e,n,t){return this.bus.subscribe(e,n,t)}once(e,n,t){return this.bus.once(e,n,t)}emit(e){return this.bus.emit(e)}metrics(){return this.bus.metrics()}clear(){return this.bus.clear()}};export{t as Events,n as createEventBus};
+import{Debouncer as e}from"@asaidimu/utils-sync";function t(t){let n=t??{},r=n.errorHandler??(e=>console.error(`EventBus Error:`,e)),i=n.batch?.size!=null,a=n.batch?.size,o=n.batch?.delay??16;if(i&&(a<=0||!Number.isFinite(a)))throw Error(`EventBus: batch.size must be a positive finite number, got ${a}.`);if(i&&(o<0||!Number.isFinite(o)))throw Error(`EventBus: batch.delay must be a non-negative finite number, got ${o}.`);let s=n.broadcast?.channel,c=s!=null&&s.length>0,l=new Map,u=new Map,d=[],f=i?new e({delay:o}):null,p=0,m=0,h=new Map,g=()=>{if(!c)return null;if(typeof BroadcastChannel>`u`)return console.warn(`EventBus: BroadcastChannel is not supported in this environment. Cross-tab notifications are disabled.`),null;let e=new BroadcastChannel(s);return e.onmessage=e=>{let{name:t,payload:n}=e.data;y(t,n)},e},_=g(),v=(e,t)=>{p++,m+=t,h.set(e,(h.get(e)??0)+1)},y=(e,t)=>{let n=l.get(e);if(n&&n.size>0)for(let{callback:i}of Array.from(n.values()))try{i(t)}catch(n){let i=n instanceof Error?n:Object.assign(Error(String(n)),{cause:n});r(Object.assign(i,{eventName:e,payload:t}))}if(u.size>0)for(let{callback:n}of Array.from(u.values()))try{n(t&&typeof t==`object`?{...t}:t,e)}catch(e){let n=e instanceof Error?e:Object.assign(Error(String(e)),{cause:e});r(Object.assign(n,{eventName:`*`,payload:t}))}},b=(t,n,r)=>{let i,a;r!==void 0&&r>0?(a=new e({delay:r,leading:!1}),i=(e,t)=>{a.fire(()=>{t===void 0?n(e):n(e,t)})}):i=n;let o={callback:i,debouncer:a};if(t===`*`)return u.set(n,o),()=>{let e=u.get(n);e&&(e.debouncer?.cancel(),u.delete(n))};{l.has(t)||l.set(t,new Map);let e=l.get(t);return e.set(n,o),()=>{let r=e.get(n);r&&(r.debouncer?.cancel(),e.delete(n),e.size===0&&l.delete(t))}}},x=()=>{let e=d;d=[];for(let{name:t,payload:n}of e){let e=performance.now();y(t,n),v(t,performance.now()-e)}};return{subscribe(e,t,n){return b(e,t,n?.debounce)},once(e,t,n){let r;return r=b(e,(e,n)=>{r(),n?t(e,n):t(e)},n?.debounce),r},emit({name:e,payload:t}){if(e===`*`)throw Error(`EventBus: Emitting to wildcard event "*" is forbidden.`);if(i){if(d.push({name:e,payload:t}),d.length>=a){f.cancel(),x();return}f.fire(()=>x()),_?.postMessage({name:e,payload:t});return}let n=performance.now();y(e,t),v(e,performance.now()-n),_?.postMessage({name:e,payload:t})},metrics:()=>({totalEvents:p,activeSubscriptions:Array.from(l.values()).reduce((e,t)=>e+t.size,0)+u.size,eventCounts:new Map(h),averageEmitDuration:p>0?m/p:0}),clear:e=>{f?.cancel(),d=[];for(let e of l.values())for(let{debouncer:t}of e.values())t?.cancel();l.clear();for(let{debouncer:e}of u.values())e?.cancel();u.clear(),p=0,m=0,h.clear(),_?.close(),_=e?.permanent?null:g()}}}var n=class{bus;constructor(e){this.bus=t(e)}subscribe(e,t,n){return this.bus.subscribe(e,t,n)}once(e,t,n){return this.bus.once(e,t,n)}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

@@ -1,6 +1,6 @@
 {
   "name": "@asaidimu/utils-events",
-  "version": "1.2.2",
+  "version": "1.2.4",
   "description": "A lightweight, type-safe event bus implementation for TypeScript applications.",
   "main": "index.js",
   "module": "index.mjs",
@@ -35,7 +35,8 @@
     }
   },
   "dependencies": {
-    "uuid": "^14.0.0"
+    "uuid": "^14.0.0",
+    "@asaidimu/utils-sync": "^2.3.2"
   },
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",
@@ -61,5 +62,6 @@
         }
       ]
     ]
-  }
+  },
+  "peerDependencies": {}
 }

package/index.d.mts

@@ -1,196 +0,0 @@
-/**
- * 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.
-     * @param options -  Extra options to determine the behaviour of the
-     * subscription
-     * @returns A function to unsubscribe from the event.
-     */
-    subscribe<TEventName extends keyof TEventMap | "*">(eventName: TEventName, callback: TEventName extends "*" ? (payload: TEventMap[keyof TEventMap], event: keyof TEventMap) => void : (payload: TEventMap[TEventName]) => void, options?: SubscribeOptions): () => 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: TEventName extends "*" ? (payload: TEventMap[keyof TEventMap], event: keyof TEventMap) => void : (payload: TEventMap[TEventName]) => void, options?: SubscribeOptions): () => 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.
-     *
-     * @param options - Optional configuration object.
-     * @param options.permanent - If `true`, the bus becomes permanently unusable after clearing.
-     *                            Defaults to `false`.
-     * @returns {void}
-     */
-    clear: (options?: {
-        permanent?: boolean;
-    }) => 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;
-}
-interface SubscribeOptions {
-    /**
-     * Debounce delay in milliseconds. When multiple events arrive in quick
-     * succession, the callback runs only after the quiet period ends, using the
-     * latest payload. Default = no debouncing.
-     */
-    debounce?: number;
-}
-
-/**
- * Creates a typed event bus.
- *
- * Options are validated eagerly so misconfiguration surfaces at construction
- * time rather than silently producing wrong behaviour at runtime.
- *
- * The bus now supports a universal wildcard event named `*`. Subscribing to
- * `*` will receive all event payloads. Emitting to `*` is forbidden.
- */
-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: TEventName extends "*" ? (payload: TEventMap[keyof TEventMap], event: keyof TEventMap) => void : (payload: TEventMap[TEventName]) => void, options?: SubscribeOptions): () => 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: TEventName extends "*" ? (payload: TEventMap[keyof TEventMap], event: keyof TEventMap) => void : (payload: TEventMap[TEventName]) => void, options?: SubscribeOptions): () => 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, type SubscribeOptions, createEventBus };