@asaidimu/utils-events 1.0.2 → 1.1.0

package/README.md

@@ -69,7 +69,7 @@ pnpm add @asaidimu/utils-events
 ## Quick Start
 
 ```typescript
-import { createEventBus } from '@asaidimu/utils-events';
+import { createEventBus } from "@asaidimu/utils-events";
 
 // 1. Define your event map
 interface AppEvents {
@@ -82,12 +82,12 @@ interface AppEvents {
 const bus = createEventBus<AppEvents>();
 
 // 3. Subscribe
-const unsubscribe = bus.subscribe('userLogin', (payload) => {
+const unsubscribe = bus.subscribe("userLogin", (payload) => {
   console.log(`Welcome ${payload.name}!`);
 });
 
 // 4. Emit an event
-bus.emit({ name: 'userLogin', payload: { userId: '123', name: 'Alice' } });
+bus.emit({ name: "userLogin", payload: { userId: "123", name: "Alice" } });
 // Logs: "Welcome Alice!"
 
 // 5. Unsubscribe when done
@@ -102,20 +102,20 @@ unsubscribe();
 
 ```typescript
 function createEventBus<TEventMap extends Record<string, any>>(
-  options?: EventBusOptions
-): EventBus<TEventMap>
+  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.        |
+| 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).
 
@@ -133,7 +133,7 @@ subscribe<TEventName extends keyof TEventMap>(
 Registers a permanent listener. Returns an **unsubscribe function**.
 
 ```typescript
-const off = bus.subscribe('dataUpdate', ({ records }) => {
+const off = bus.subscribe("dataUpdate", ({ records }) => {
   updateUI(records);
 });
 
@@ -155,8 +155,8 @@ once<TEventName extends keyof TEventMap>(
 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');
+bus.once("userLogin", (payload) => {
+  console.log("First login only");
 });
 
 // The callback will run at most once.
@@ -178,7 +178,7 @@ emit<TEventName extends keyof TEventMap>(
 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 } });
+bus.emit({ name: "dataUpdate", payload: { records: 42 } });
 ```
 
 ---
@@ -226,9 +226,9 @@ When many events are fired in rapid succession (e.g., keystrokes, scroll handler
 ```typescript
 const batchedBus = createEventBus<MyEvents>({
   batch: {
-    size: 20,    // flush after 20 queued events
-    delay: 100   // or after 100ms of inactivity
-  }
+    size: 20, // flush after 20 queued events
+    delay: 100, // or after 100ms of inactivity
+  },
 });
 ```
 
@@ -242,15 +242,15 @@ Enable the `broadcast` option to automatically send every emitted event to other
 
 ```typescript
 const bus = createEventBus<MyEvents>({
-  broadcast: { channel: 'my-app-events' }
+  broadcast: { channel: "my-app-events" },
 });
 
 // In tab A
-bus.emit({ name: 'userLogin', payload: { userId: '1' } });
+bus.emit({ name: "userLogin", payload: { userId: "1" } });
 
 // In tab B (same origin)
-bus.subscribe('userLogin', (payload) => {
-  console.log('Another tab logged in:', payload.userId);
+bus.subscribe("userLogin", (payload) => {
+  console.log("Another tab logged in:", payload.userId);
 });
 ```
 
@@ -265,9 +265,9 @@ const bus = createEventBus<MyEvents>({
   errorHandler: (err) => {
     myErrorTracker.capture(err, {
       eventName: err.eventName,
-      payload: err.payload
+      payload: err.payload,
     });
-  }
+  },
 });
 ```
 

package/index.d.mts

@@ -128,6 +128,9 @@ interface EventError extends Error {
 
 /**
  * Creates a typed event bus.
+ *
+ * Options are validated eagerly so misconfiguration surfaces at construction
+ * time rather than silently producing wrong behaviour at runtime.
  */
 declare function createEventBus<TEventMap extends Record<string, any>>(options?: EventBusOptions): EventBus<TEventMap>;
 

package/index.d.ts

@@ -128,6 +128,9 @@ interface EventError extends Error {
 
 /**
  * Creates a typed event bus.
+ *
+ * Options are validated eagerly so misconfiguration surfaces at construction
+ * time rather than silently producing wrong behaviour at runtime.
  */
 declare function createEventBus<TEventMap extends Record<string, any>>(options?: EventBusOptions): EventBus<TEventMap>;
 

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??{},{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;
+"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??{},i=n.errorHandler??(e=>console.error("EventBus Error:",e)),s=null!=n.batch?.size,r=n.batch?.size,a=n.batch?.delay??16;if(s&&(r<=0||!Number.isFinite(r)))throw new Error(`EventBus: batch.size must be a positive finite number, got ${r}.`);if(s&&(a<0||!Number.isFinite(a)))throw new Error(`EventBus: batch.delay must be a non-negative finite number, got ${a}.`);const o=n.broadcast?.channel,c=null!=o&&o.length>0,l=new Map;let u=[];const d=s?new e({delay:a}):null;let h=0,m=0;const _=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(o);return e.onmessage=e=>{const{name:t,payload:n}=e.data;v(t,n)},e};let g=p();const f=(e,t)=>{h++,m+=t,_.set(e,(_.get(e)??0)+1)},v=(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});i(r)}},b=(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)}},y=()=>{const e=u;u=[];for(const{name:t,payload:n}of e){const e=performance.now();v(t,n),f(t,performance.now()-e)}};return{subscribe:(e,t)=>b(e,t),once:(e,t)=>{let n;return n=b(e,(e=>{n(),t(e)})),n},emit:({name:e,payload:t})=>{if(s)return u.push({name:e,payload:t}),u.length>=r?(d.cancel(),void y()):(d.fire((()=>y())),void g?.postMessage({name:e,payload:t}));const n=performance.now();v(e,t),f(e,performance.now()-n),g?.postMessage({name:e,payload:t})},metrics:()=>({totalEvents:h,activeSubscriptions:Array.from(l.values()).reduce(((e,t)=>e+t.size),0),eventCounts:new Map(_),averageEmitDuration:h>0?m/h:0}),clear:()=>{d?.cancel(),u=[],l.clear(),h=0,m=0,_.clear(),g?.close(),g=p()}}}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

@@ -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((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};
+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??{},i=n.errorHandler??(e=>console.error("EventBus Error:",e)),s=null!=n.batch?.size,r=n.batch?.size,a=n.batch?.delay??16;if(s&&(r<=0||!Number.isFinite(r)))throw new Error(`EventBus: batch.size must be a positive finite number, got ${r}.`);if(s&&(a<0||!Number.isFinite(a)))throw new Error(`EventBus: batch.delay must be a non-negative finite number, got ${a}.`);const o=n.broadcast?.channel,c=null!=o&&o.length>0,l=new Map;let d=[];const u=s?new e({delay:a}):null;let h=0,m=0;const _=new Map,g=()=>{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(o);return e.onmessage=e=>{const{name:t,payload:n}=e.data;b(t,n)},e};let p=g();const f=(e,t)=>{h++,m+=t,_.set(e,(_.get(e)??0)+1)},b=(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});i(r)}},v=(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)}},y=()=>{const e=d;d=[];for(const{name:t,payload:n}of e){const e=performance.now();b(t,n),f(t,performance.now()-e)}};return{subscribe:(e,t)=>v(e,t),once:(e,t)=>{let n;return n=v(e,(e=>{n(),t(e)})),n},emit:({name:e,payload:t})=>{if(s)return d.push({name:e,payload:t}),d.length>=r?(u.cancel(),void y()):(u.fire((()=>y())),void p?.postMessage({name:e,payload:t}));const n=performance.now();b(e,t),f(e,performance.now()-n),p?.postMessage({name:e,payload:t})},metrics:()=>({totalEvents:h,activeSubscriptions:Array.from(l.values()).reduce(((e,t)=>e+t.size),0),eventCounts:new Map(_),averageEmitDuration:h>0?m/h:0}),clear:()=>{u?.cancel(),d=[],l.clear(),h=0,m=0,_.clear(),p?.close(),p=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

@@ -1,6 +1,6 @@
 {
   "name": "@asaidimu/utils-events",
-  "version": "1.0.2",
+  "version": "1.1.0",
   "description": "A lightweight, type-safe event bus implementation for TypeScript applications.",
   "main": "index.js",
   "module": "index.mjs",