@siggn/core 0.0.5 → 0.1.1

package/README.md

@@ -1,6 +1,8 @@
+[![npm version](https://badge.fury.io/js/%40siggn%2Fcore.svg)](https://www.npmjs.com/package/%40siggn%2Fcore)
+
 # @siggn/core
 
-A lightweight and type-safe event-driven pub/sub system for TypeScript projects.
+A lightweight and type-safe event bus system for TypeScript projects.
 
 ## Features
 
@@ -122,9 +124,9 @@ siggn.publish({ type: 'user_deleted', userId: '123' });
 logger.unsubscribe();
 ```
 
-### Extending message types with `createChild`
+### Extending message types with `createClone`
 
-The `createChild` method allows you to create a new, independent `Siggn` instance that inherits the
+The `createClone` method allows you to create a new, independent `Siggn` instance that inherits the
 message types of its parent. This is useful for creating specialized message buses that extend a
 base set of events without affecting the parent bus.
 
@@ -136,7 +138,7 @@ const baseSiggn = new Siggn<Message>();
 type AdminMessage = { type: 'admin_login'; adminId: string };
 
 // 2. Create a child bus that understands both `Message` and `AdminMessage`
-const adminSiggn = baseSiggn.createChild<AdminMessage>();
+const adminSiggn = baseSiggn.createClone<AdminMessage>();
 
 // 3. Subscribe to events on the child bus
 adminSiggn.subscribe('audit-log', 'user_created', (msg) => {
@@ -160,43 +162,75 @@ baseSiggn.publish({ type: 'user_created', userId: 'def', name: 'Bob' });
 // No output, because the subscription is on `adminSiggn`.
 ```
 
+### Automatic Garbage Collection
+
+Siggn is designed to prevent memory leaks even if subscriptions are not explicitly unsubscribed. It achieves this through the use of `WeakRef` and `FinalizationRegistry`:
+
+While explicit `unsubscribe` calls are still good practice for immediate cleanup and control, Siggn provides a robust safety net against common memory leak scenarios.
+
 ## API
 
 ### `new Siggn<T>()`
 
-Creates a new message bus instance. `T` is a union type of all possible messages.
+Creates a new message bus instance.
+
+- `T`: A union type representing all possible messages.
 
 ### `publish(msg)`
 
 Publishes a message to all relevant subscribers.
 
+- `msg`: The message object to be published. It must conform to the `Msg` type.
+
 ### `subscribe(id, type, callback)`
 
-Subscribes a callback to a specific message type with a unique subscriber ID.
+Subscribes a callback to a specific message type.
+
+- `id`: A unique `SiggnId` (string) to identify the subscriber.
+- `type`: The `type` of the message to subscribe to.
+- `callback`: A function that executes when a message of the specified `type` is published. It receives the message as its only argument.
 
 ### `subscribeAll(id, callback)`
 
-Subscribes a callback to all message types with a unique subscriber ID. The callback will receive
-every message published on the bus.
+Subscribes a callback to all message types.
+
+- `id`: A unique `SiggnId` to identify the subscriber.
+- `callback`: A function that executes for every message published. It receives the message as its only argument.
 
 ### `unsubscribe(id)`
 
-Removes all subscriptions associated with a specific subscriber ID.
+Removes all subscriptions (specific and global) associated with a subscriber ID.
+
+- `id`: The `SiggnId` of the subscriber to remove.
+
+### `unsubscribeGlobal(id)`
+
+Removes a global subscription for a given subscriber ID.
+
+- `id`: The `SiggnId` of the global subscriber to remove.
 
 ### `make(id)`
 
-Returns a helper object with `subscribe`, `subscribeMany`, `subscribeAll`, and `unsubscribe` methods
-pre-bound to the provided ID. This is useful for encapsulating subscription logic within a component
-or service.
+Returns a helper object with `subscribe`, `subscribeMany`, `subscribeAll`, and `unsubscribe` methods pre-bound to the provided ID.
+
+- `id`: A `SiggnId` to pre-bind to the subscription methods.
 
 ### `subscribeMany(id, setup)`
 
-A convenience method to subscribe to multiple message types for a single ID.
+Subscribes to multiple message types for a single ID.
+
+- `id`: A `SiggnId` to identify the subscriber.
+- `setup`: A function that receives a `subscribe` helper to register multiple subscriptions under the same `id`.
+
+### `createClone<C>()`
+
+Creates a new, independent `Siggn` instance that inherits the parent's message types and adds new ones.
+
+- `C`: A union type of additional message types for the new instance.
 
-### `createChild<C>()`
+### `subscriptionsCount()`
 
-Creates a new, independent `Siggn` instance whose message types are a union of the parent's types
-and the new child-specific types `C`.
+Returns the total number of subscriptions.
 
 ## License
 

package/dist/index.cjs.js

@@ -1,2 +1,2 @@
-"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});class r{nextId=0;subscriptions;subscribeAllSubscriptions=[];constructor(){this.subscriptions=new Map}createClone(){return new r}makeId(i){return i??`sub_${(this.nextId++).toString(36)}`}make(i){return{subscribe:(s,t)=>{this.subscribe(i,s,t)},unsubscribe:()=>{this.unsubscribe(i)},subscribeMany:s=>{this.subscribeMany(i,s)},subscribeAll:s=>{this.subscribeAll(i,s)}}}subscribeMany(i,s){s((t,b)=>this.subscribe(i,t,b))}subscribe(i,s,t){this.subscriptions.has(s)||this.subscriptions.set(s,[]),this.subscriptions.get(s)?.push({id:i,callback:t})}subscribeAll(i,s){this.subscribeAllSubscriptions.push({id:i,callback:s})}publish(i){this.subscribeAllSubscriptions.forEach(s=>{s.callback(i)}),this.subscriptions.has(i.type)&&this.subscriptions.get(i.type)?.forEach(s=>{s.callback(i)})}unsubscribe(i){this.subscribeAllSubscriptions=this.subscribeAllSubscriptions.filter(s=>s.id!==i);for(const[s,t]of this.subscriptions)this.subscriptions.set(s,t.filter(b=>b.id!==i))}}exports.Siggn=r;
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});class b{nextId=0;subscriptions;globalSubscriptions;middlewares;constructor(){this.subscriptions=new Map,this.globalSubscriptions=[],this.middlewares=[]}use(s){this.middlewares.push(s)}createClone(){return new b}makeId(s){return s??`sub_${(this.nextId++).toString(36)}`}make(s){return{subscribe:(i,t)=>{this.subscribe(s,i,t)},unsubscribe:()=>{this.unsubscribe(s)},subscribeMany:i=>{this.subscribeMany(s,i)},subscribeAll:i=>{this.subscribeAll(s,i)}}}subscribeMany(s,i){i((t,r)=>this.subscribe(s,t,r))}subscribe(s,i,t){this.subscriptions.has(i)||this.subscriptions.set(i,[]),this.subscriptions.get(i)?.push({id:s,ref:t})}subscribeAll(s,i){this.globalSubscriptions.push({id:s,ref:i})}publish(s){this.globalSubscriptions.forEach(i=>{i.ref(s)}),this.subscriptions.has(s.type)&&this.subscriptions.get(s.type)?.forEach(i=>{i.ref(s)})}unsubscribe(s){this.unsubscribeGlobal(s);for(const[i,t]of this.subscriptions)this.subscriptions.set(i,t.filter(r=>r.id!==s))}unsubscribeGlobal(s){this.globalSubscriptions=this.globalSubscriptions.filter(i=>i.id!==s)}}exports.Siggn=b;
 //# sourceMappingURL=index.cjs.js.map

package/dist/index.cjs.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.cjs.js","sources":["../src/siggn.ts"],"sourcesContent":["import type { Msg, Subscription, SiggnId } from './types.js';\n\nexport class Siggn<T extends Msg> {\n  private nextId = 0;\n  private subscriptions: Map<T['type'], Array<Subscription<T, any>>>;\n  private subscribeAllSubscriptions: Array<Subscription<T, any>> = [];\n\n  constructor() {\n    this.subscriptions = new Map();\n  }\n\n  createClone<C extends Msg>() {\n    return new Siggn<C | T>();\n  }\n\n  makeId(id?: string): SiggnId {\n    return id ?? `sub_${(this.nextId++).toString(36)}`;\n  }\n\n  make(id: SiggnId): {\n    subscribe: <K extends T['type']>(\n      type: K,\n      callback: (msg: Extract<T, { type: K }>) => void,\n    ) => void;\n    unsubscribe: () => void;\n    subscribeMany: (\n      setup: (\n        subscribe: <K extends T['type']>(\n          type: K,\n          callback: (msg: Extract<T, { type: K }>) => void,\n        ) => void,\n      ) => void,\n    ) => void;\n    subscribeAll: (callback: (msg: T) => void) => void;\n  } {\n    return {\n      subscribe: (type, callback) => {\n        this.subscribe(id, type, callback);\n      },\n      unsubscribe: () => {\n        this.unsubscribe(id);\n      },\n      subscribeMany: (setup) => {\n        this.subscribeMany(id, setup);\n      },\n      subscribeAll: (callback) => {\n        this.subscribeAll(id, callback);\n      },\n    };\n  }\n\n  subscribeMany(\n    id: SiggnId,\n    setup: (\n      subscribe: <K extends T['type']>(\n        type: K,\n        callback: (msg: Extract<T, { type: K }>) => void,\n      ) => void,\n    ) => void,\n  ) {\n    setup((type, callback) => this.subscribe(id, type, callback));\n  }\n\n  subscribe<K extends T['type']>(\n    id: SiggnId,\n    type: K,\n    callback: (msg: Extract<T, { type: K }>) => void,\n  ) {\n    if (!this.subscriptions.has(type)) {\n      this.subscriptions.set(type, []);\n    }\n\n    this.subscriptions.get(type)?.push({ id, callback });\n  }\n\n  subscribeAll(id: SiggnId, callback: (msg: T) => void) {\n    this.subscribeAllSubscriptions.push({ id, callback });\n  }\n\n  publish(msg: T) {\n    this.subscribeAllSubscriptions.forEach((sub) => {\n      sub.callback(msg as Extract<T, { type: any }>);\n    });\n\n    if (!this.subscriptions.has(msg.type)) {\n      return;\n    }\n\n    this.subscriptions.get(msg.type)?.forEach((sub) => {\n      sub.callback(msg as Extract<T, { type: any }>);\n    });\n  }\n\n  unsubscribe(id: SiggnId) {\n    this.subscribeAllSubscriptions = this.subscribeAllSubscriptions.filter((s) => s.id !== id);\n\n    for (const [type, subscriptions] of this.subscriptions) {\n      this.subscriptions.set(\n        type,\n        subscriptions.filter((sub) => sub.id !== id),\n      );\n    }\n  }\n}\n"],"names":["Siggn","id","type","callback","setup","msg","sub","subscriptions"],"mappings":"gFAEO,MAAMA,CAAqB,CACxB,OAAS,EACT,cACA,0BAAyD,CAAA,EAEjE,aAAc,CACZ,KAAK,kBAAoB,GAC3B,CAEA,aAA6B,CAC3B,OAAO,IAAIA,CACb,CAEA,OAAOC,EAAsB,CAC3B,OAAOA,GAAM,QAAQ,KAAK,UAAU,SAAS,EAAE,CAAC,EAClD,CAEA,KAAKA,EAeH,CACA,MAAO,CACL,UAAW,CAACC,EAAMC,IAAa,CAC7B,KAAK,UAAUF,EAAIC,EAAMC,CAAQ,CACnC,EACA,YAAa,IAAM,CACjB,KAAK,YAAYF,CAAE,CACrB,EACA,cAAgBG,GAAU,CACxB,KAAK,cAAcH,EAAIG,CAAK,CAC9B,EACA,aAAeD,GAAa,CAC1B,KAAK,aAAaF,EAAIE,CAAQ,CAChC,CAAA,CAEJ,CAEA,cACEF,EACAG,EAMA,CACAA,EAAM,CAACF,EAAMC,IAAa,KAAK,UAAUF,EAAIC,EAAMC,CAAQ,CAAC,CAC9D,CAEA,UACEF,EACAC,EACAC,EACA,CACK,KAAK,cAAc,IAAID,CAAI,GAC9B,KAAK,cAAc,IAAIA,EAAM,CAAA,CAAE,EAGjC,KAAK,cAAc,IAAIA,CAAI,GAAG,KAAK,CAAE,GAAAD,EAAI,SAAAE,EAAU,CACrD,CAEA,aAAaF,EAAaE,EAA4B,CACpD,KAAK,0BAA0B,KAAK,CAAE,GAAAF,EAAI,SAAAE,EAAU,CACtD,CAEA,QAAQE,EAAQ,CACd,KAAK,0BAA0B,QAASC,GAAQ,CAC9CA,EAAI,SAASD,CAAgC,CAC/C,CAAC,EAEI,KAAK,cAAc,IAAIA,EAAI,IAAI,GAIpC,KAAK,cAAc,IAAIA,EAAI,IAAI,GAAG,QAASC,GAAQ,CACjDA,EAAI,SAASD,CAAgC,CAC/C,CAAC,CACH,CAEA,YAAYJ,EAAa,CACvB,KAAK,0BAA4B,KAAK,0BAA0B,OAAQ,GAAM,EAAE,KAAOA,CAAE,EAEzF,SAAW,CAACC,EAAMK,CAAa,IAAK,KAAK,cACvC,KAAK,cAAc,IACjBL,EACAK,EAAc,OAAQD,GAAQA,EAAI,KAAOL,CAAE,CAAA,CAGjD,CACF"}
+{"version":3,"file":"index.cjs.js","sources":["../src/siggn.ts"],"sourcesContent":["import type { Msg, Subscription, SiggnId, Middleware } from './types.js';\n\n/**\n * A type-safe message bus for dispatching and subscribing to events.\n * @template T A union of all possible message types.\n * @since 0.0.5\n */\nexport class Siggn<M extends Msg> {\n  private nextId = 0;\n  private subscriptions: Map<M['type'], Array<Subscription<M, any>>>;\n  private globalSubscriptions: Array<Subscription<M, any>>;\n  private middlewares: Middleware<M>[];\n\n  /**\n   * Creates a new Siggn instance.\n   * @category Lifecycle\n   * @since 0.0.5\n   */\n  constructor() {\n    this.subscriptions = new Map();\n    this.globalSubscriptions = [];\n    this.middlewares = [];\n  }\n\n  use(mw: Middleware<M>) {\n    this.middlewares.push(mw);\n  }\n\n  /**\n   * Creates a new, independent `Siggn` instance that inherits the message\n   * types of its parent and adds new ones.\n   *\n   * @template C The new message types to add.\n   * @returns A new `Siggn` instance with combined message types.\n   * @category Lifecycle\n   * @since 0.0.5\n   * @example\n   * \n```typescript\n * const baseSiggn = new Siggn<{ type: 'A' }>();\n * const childSiggn = baseSiggn.createClone<{ type: 'B' }>();\n * // childSiggn can now publish and subscribe to types 'A' and 'B'.\n * ```\n   */\n  createClone<C extends Msg>() {\n    return new Siggn<M | C>();\n  }\n\n  /**\n   * Generates a unique ID for a subscriber.\n   * If an ID is provided, it will be used; otherwise, a new one is generated.\n   *\n   * @param id An optional ID to use.\n   * @returns A unique subscriber ID.\n   * @category Utilities\n   * @since 0.0.5\n   * @example\n   * \n```typescript\n * const siggn = new Siggn();\n * const id1 = siggn.makeId(); // e.g., \"sub_0\"\n * const id2 = siggn.makeId('custom-id'); // \"custom-id\"\n * ```\n   */\n  makeId(id?: string): SiggnId {\n    return id ?? `sub_${(this.nextId++).toString(36)}`;\n  }\n\n  /**\n   * Creates a subscription helper object that is pre-configured with a\n   * specific subscriber ID. This simplifies managing multiple subscriptions\n   * for a single component or service.\n   *\n   * @param id The subscriber ID to use for all subscriptions.\n   * @returns An object with `subscribe`, `unsubscribe`, `subscribeMany`, and `subscribeAll` methods.\n   * @category Subscription\n   * @since 0.0.5\n   * @example\n   * \n```typescript\n * const siggn = new Siggn<{ type: 'event' }>();\n * const component = siggn.make('my-component');\n * component.subscribe('event', () => console.log('event received!'));\n * component.unsubscribe();\n * ```\n   */\n  make(id: SiggnId): {\n    subscribe: <T extends M['type']>(\n      type: T,\n      callback: (msg: Extract<M, { type: T }>) => void,\n    ) => void;\n    unsubscribe: () => void;\n    subscribeMany: (\n      setup: (\n        subscribe: <T extends M['type']>(\n          type: T,\n          callback: (msg: Extract<M, { type: T }>) => void,\n        ) => void,\n      ) => void,\n    ) => void;\n    subscribeAll: (callback: (msg: M) => void) => void;\n  } {\n    return {\n      subscribe: (type, callback) => {\n        this.subscribe(id, type, callback);\n      },\n      unsubscribe: () => {\n        this.unsubscribe(id);\n      },\n      subscribeMany: (setup) => {\n        this.subscribeMany(id, setup);\n      },\n      subscribeAll: (callback) => {\n        this.subscribeAll(id, callback);\n      },\n    };\n  }\n\n  /**\n   * Subscribes to multiple message types using a single subscriber ID.\n   *\n   * @param id The subscriber ID.\n   * @param setup A function that receives a `subscribe` helper to register callbacks.\n   * @category Subscription\n   * @since 0.0.5\n   * @example\n   * \n```typescript\n * const siggn = new Siggn<{ type: 'A' } | { type: 'B' }>();\n * siggn.subscribeMany('subscriber-1', (subscribe) => {\n *   subscribe('A', () => console.log('A received'));\n *   subscribe('B', () => console.log('B received'));\n * });\n * ```\n   */\n  subscribeMany(\n    id: SiggnId,\n    setup: (\n      subscribe: <T extends M['type']>(\n        type: T,\n        callback: (msg: Extract<M, { type: T }>) => void,\n      ) => void,\n    ) => void,\n  ) {\n    setup((type, callback) => this.subscribe(id, type, callback));\n  }\n\n  /**\n   * Subscribes to a specific message type.\n   *\n   * @param id The subscriber ID.\n   * @param type The message type to subscribe to.\n   * @param callback The function to call when a message of the specified type is published.\n   * @category Subscription\n   * @since 0.0.5\n   * @example\n   * \n```typescript\n * const siggn = new Siggn<{ type: 'my-event', payload: string }>();\n * siggn.subscribe('subscriber-1', 'my-event', (msg) => {\n *   console.log(msg.payload);\n * });\n * ```\n   */\n  subscribe<T extends M['type']>(\n    id: SiggnId,\n    type: T,\n    callback: (msg: Extract<M, { type: T }>) => void,\n  ) {\n    if (!this.subscriptions.has(type)) {\n      this.subscriptions.set(type, []);\n    }\n\n    this.subscriptions.get(type)?.push({ id, ref: callback });\n  }\n\n  /**\n   * Subscribes to all message types. The callback will be invoked for every\n   * message published on the bus.\n   *\n   * @param id The subscriber ID.\n   * @param callback The function to call for any message.\n   * @category Subscription\n   * @since 0.0.5\n   * @example\n   * \n```typescript\n * const siggn = new Siggn<{ type: 'A' } | { type: 'B' }>();\n * siggn.subscribeAll('logger', (msg) => {\n *   console.log(`Received message of type: ${msg.type}`);\n * });\n * ```\n   */\n  subscribeAll(id: SiggnId, callback: (msg: M) => void) {\n    this.globalSubscriptions.push({ id, ref: callback });\n  }\n\n  /**\n   * Publishes a message to all relevant subscribers.\n   *\n   * @param msg The message to publish.\n   * @category Publishing\n   * @since 0.0.5\n   * @example\n   * \n```typescript\n * const siggn = new Siggn<{ type: 'my-event' }>();\n * siggn.subscribe('sub-1', 'my-event', () => console.log('received'));\n * siggn.publish({ type: 'my-event' }); // \"received\"\n * ```\n   */\n  publish(msg: M) {\n    this.globalSubscriptions.forEach((sub) => {\n      sub.ref(msg as Extract<M, { type: any }>);\n    });\n\n    if (!this.subscriptions.has(msg.type)) {\n      return;\n    }\n\n    this.subscriptions.get(msg.type)?.forEach((sub) => {\n      sub.ref(msg as Extract<M, { type: any }>);\n    });\n  }\n\n  /**\n   * Removes all subscriptions (both specific and global) for a given\n   * subscriber ID.\n   *\n   * @param id The subscriber ID to unsubscribe.\n   * @category Subscription\n   * @since 0.0.5\n   * @example\n   * \n```typescript\n * const siggn = new Siggn<{ type: 'my-event' }>();\n * siggn.subscribe('sub-1', 'my-event', () => console.log('received'));\n * siggn.unsubscribe('sub-1');\n * siggn.publish({ type: 'my-event' }); // (nothing is logged)\n * ```\n   */\n  unsubscribe(id: SiggnId) {\n    this.unsubscribeGlobal(id);\n\n    for (const [type, subscriptions] of this.subscriptions) {\n      this.subscriptions.set(\n        type,\n        subscriptions.filter((sub) => sub.id !== id),\n      );\n    }\n  }\n\n  /**\n   * Removes a global subscription for a given subscriber ID.\n   *\n   * @param id The subscriber ID to unsubscribe.\n   * @category Subscription\n   * @since 0.0.5\n   * @example\n   * \n```typescript\n * const siggn = new Siggn<{ type: 'my-event' }>();\n * siggn.subscribeAll('logger', console.log);\n * siggn.unsubscribeGlobal('logger');\n * siggn.publish({ type: 'my-event' }); // (nothing is logged)\n * ```\n   */\n  unsubscribeGlobal(id: SiggnId) {\n    this.globalSubscriptions = this.globalSubscriptions.filter((s) => s.id !== id);\n  }\n}\n"],"names":["Siggn","mw","id","type","callback","setup","msg","sub","subscriptions","s"],"mappings":"gFAOO,MAAMA,CAAqB,CACxB,OAAS,EACT,cACA,oBACA,YAOR,aAAc,CACZ,KAAK,kBAAoB,IACzB,KAAK,oBAAsB,CAAA,EAC3B,KAAK,YAAc,CAAA,CACrB,CAEA,IAAIC,EAAmB,CACrB,KAAK,YAAY,KAAKA,CAAE,CAC1B,CAkBA,aAA6B,CAC3B,OAAO,IAAID,CACb,CAkBA,OAAOE,EAAsB,CAC3B,OAAOA,GAAM,QAAQ,KAAK,UAAU,SAAS,EAAE,CAAC,EAClD,CAoBA,KAAKA,EAeH,CACA,MAAO,CACL,UAAW,CAACC,EAAMC,IAAa,CAC7B,KAAK,UAAUF,EAAIC,EAAMC,CAAQ,CACnC,EACA,YAAa,IAAM,CACjB,KAAK,YAAYF,CAAE,CACrB,EACA,cAAgBG,GAAU,CACxB,KAAK,cAAcH,EAAIG,CAAK,CAC9B,EACA,aAAeD,GAAa,CAC1B,KAAK,aAAaF,EAAIE,CAAQ,CAChC,CAAA,CAEJ,CAmBA,cACEF,EACAG,EAMA,CACAA,EAAM,CAACF,EAAMC,IAAa,KAAK,UAAUF,EAAIC,EAAMC,CAAQ,CAAC,CAC9D,CAmBA,UACEF,EACAC,EACAC,EACA,CACK,KAAK,cAAc,IAAID,CAAI,GAC9B,KAAK,cAAc,IAAIA,EAAM,CAAA,CAAE,EAGjC,KAAK,cAAc,IAAIA,CAAI,GAAG,KAAK,CAAE,GAAAD,EAAI,IAAKE,EAAU,CAC1D,CAmBA,aAAaF,EAAaE,EAA4B,CACpD,KAAK,oBAAoB,KAAK,CAAE,GAAAF,EAAI,IAAKE,EAAU,CACrD,CAgBA,QAAQE,EAAQ,CACd,KAAK,oBAAoB,QAASC,GAAQ,CACxCA,EAAI,IAAID,CAAgC,CAC1C,CAAC,EAEI,KAAK,cAAc,IAAIA,EAAI,IAAI,GAIpC,KAAK,cAAc,IAAIA,EAAI,IAAI,GAAG,QAASC,GAAQ,CACjDA,EAAI,IAAID,CAAgC,CAC1C,CAAC,CACH,CAkBA,YAAYJ,EAAa,CACvB,KAAK,kBAAkBA,CAAE,EAEzB,SAAW,CAACC,EAAMK,CAAa,IAAK,KAAK,cACvC,KAAK,cAAc,IACjBL,EACAK,EAAc,OAAQD,GAAQA,EAAI,KAAOL,CAAE,CAAA,CAGjD,CAiBA,kBAAkBA,EAAa,CAC7B,KAAK,oBAAsB,KAAK,oBAAoB,OAAQO,GAAMA,EAAE,KAAOP,CAAE,CAC/E,CACF"}

package/dist/index.es.js

@@ -1,56 +1,214 @@
 class r {
   nextId = 0;
   subscriptions;
-  subscribeAllSubscriptions = [];
+  globalSubscriptions;
+  middlewares;
+  /**
+   * Creates a new Siggn instance.
+   * @category Lifecycle
+   * @since 0.0.5
+   */
   constructor() {
-    this.subscriptions = /* @__PURE__ */ new Map();
+    this.subscriptions = /* @__PURE__ */ new Map(), this.globalSubscriptions = [], this.middlewares = [];
   }
+  use(s) {
+    this.middlewares.push(s);
+  }
+  /**
+     * Creates a new, independent `Siggn` instance that inherits the message
+     * types of its parent and adds new ones.
+     *
+     * @template C The new message types to add.
+     * @returns A new `Siggn` instance with combined message types.
+     * @category Lifecycle
+     * @since 0.0.5
+     * @example
+     * 
+  ```typescript
+   * const baseSiggn = new Siggn<{ type: 'A' }>();
+   * const childSiggn = baseSiggn.createClone<{ type: 'B' }>();
+   * // childSiggn can now publish and subscribe to types 'A' and 'B'.
+   * ```
+     */
   createClone() {
     return new r();
   }
-  makeId(i) {
-    return i ?? `sub_${(this.nextId++).toString(36)}`;
+  /**
+     * Generates a unique ID for a subscriber.
+     * If an ID is provided, it will be used; otherwise, a new one is generated.
+     *
+     * @param id An optional ID to use.
+     * @returns A unique subscriber ID.
+     * @category Utilities
+     * @since 0.0.5
+     * @example
+     * 
+  ```typescript
+   * const siggn = new Siggn();
+   * const id1 = siggn.makeId(); // e.g., "sub_0"
+   * const id2 = siggn.makeId('custom-id'); // "custom-id"
+   * ```
+     */
+  makeId(s) {
+    return s ?? `sub_${(this.nextId++).toString(36)}`;
   }
-  make(i) {
+  /**
+     * Creates a subscription helper object that is pre-configured with a
+     * specific subscriber ID. This simplifies managing multiple subscriptions
+     * for a single component or service.
+     *
+     * @param id The subscriber ID to use for all subscriptions.
+     * @returns An object with `subscribe`, `unsubscribe`, `subscribeMany`, and `subscribeAll` methods.
+     * @category Subscription
+     * @since 0.0.5
+     * @example
+     * 
+  ```typescript
+   * const siggn = new Siggn<{ type: 'event' }>();
+   * const component = siggn.make('my-component');
+   * component.subscribe('event', () => console.log('event received!'));
+   * component.unsubscribe();
+   * ```
+     */
+  make(s) {
     return {
-      subscribe: (s, b) => {
-        this.subscribe(i, s, b);
+      subscribe: (i, t) => {
+        this.subscribe(s, i, t);
       },
       unsubscribe: () => {
-        this.unsubscribe(i);
+        this.unsubscribe(s);
       },
-      subscribeMany: (s) => {
-        this.subscribeMany(i, s);
+      subscribeMany: (i) => {
+        this.subscribeMany(s, i);
       },
-      subscribeAll: (s) => {
-        this.subscribeAll(i, s);
+      subscribeAll: (i) => {
+        this.subscribeAll(s, i);
       }
     };
   }
-  subscribeMany(i, s) {
-    s((b, t) => this.subscribe(i, b, t));
+  /**
+     * Subscribes to multiple message types using a single subscriber ID.
+     *
+     * @param id The subscriber ID.
+     * @param setup A function that receives a `subscribe` helper to register callbacks.
+     * @category Subscription
+     * @since 0.0.5
+     * @example
+     * 
+  ```typescript
+   * const siggn = new Siggn<{ type: 'A' } | { type: 'B' }>();
+   * siggn.subscribeMany('subscriber-1', (subscribe) => {
+   *   subscribe('A', () => console.log('A received'));
+   *   subscribe('B', () => console.log('B received'));
+   * });
+   * ```
+     */
+  subscribeMany(s, i) {
+    i((t, b) => this.subscribe(s, t, b));
   }
-  subscribe(i, s, b) {
-    this.subscriptions.has(s) || this.subscriptions.set(s, []), this.subscriptions.get(s)?.push({ id: i, callback: b });
+  /**
+     * Subscribes to a specific message type.
+     *
+     * @param id The subscriber ID.
+     * @param type The message type to subscribe to.
+     * @param callback The function to call when a message of the specified type is published.
+     * @category Subscription
+     * @since 0.0.5
+     * @example
+     * 
+  ```typescript
+   * const siggn = new Siggn<{ type: 'my-event', payload: string }>();
+   * siggn.subscribe('subscriber-1', 'my-event', (msg) => {
+   *   console.log(msg.payload);
+   * });
+   * ```
+     */
+  subscribe(s, i, t) {
+    this.subscriptions.has(i) || this.subscriptions.set(i, []), this.subscriptions.get(i)?.push({ id: s, ref: t });
   }
-  subscribeAll(i, s) {
-    this.subscribeAllSubscriptions.push({ id: i, callback: s });
+  /**
+     * Subscribes to all message types. The callback will be invoked for every
+     * message published on the bus.
+     *
+     * @param id The subscriber ID.
+     * @param callback The function to call for any message.
+     * @category Subscription
+     * @since 0.0.5
+     * @example
+     * 
+  ```typescript
+   * const siggn = new Siggn<{ type: 'A' } | { type: 'B' }>();
+   * siggn.subscribeAll('logger', (msg) => {
+   *   console.log(`Received message of type: ${msg.type}`);
+   * });
+   * ```
+     */
+  subscribeAll(s, i) {
+    this.globalSubscriptions.push({ id: s, ref: i });
   }
-  publish(i) {
-    this.subscribeAllSubscriptions.forEach((s) => {
-      s.callback(i);
-    }), this.subscriptions.has(i.type) && this.subscriptions.get(i.type)?.forEach((s) => {
-      s.callback(i);
+  /**
+     * Publishes a message to all relevant subscribers.
+     *
+     * @param msg The message to publish.
+     * @category Publishing
+     * @since 0.0.5
+     * @example
+     * 
+  ```typescript
+   * const siggn = new Siggn<{ type: 'my-event' }>();
+   * siggn.subscribe('sub-1', 'my-event', () => console.log('received'));
+   * siggn.publish({ type: 'my-event' }); // "received"
+   * ```
+     */
+  publish(s) {
+    this.globalSubscriptions.forEach((i) => {
+      i.ref(s);
+    }), this.subscriptions.has(s.type) && this.subscriptions.get(s.type)?.forEach((i) => {
+      i.ref(s);
     });
   }
-  unsubscribe(i) {
-    this.subscribeAllSubscriptions = this.subscribeAllSubscriptions.filter((s) => s.id !== i);
-    for (const [s, b] of this.subscriptions)
+  /**
+     * Removes all subscriptions (both specific and global) for a given
+     * subscriber ID.
+     *
+     * @param id The subscriber ID to unsubscribe.
+     * @category Subscription
+     * @since 0.0.5
+     * @example
+     * 
+  ```typescript
+   * const siggn = new Siggn<{ type: 'my-event' }>();
+   * siggn.subscribe('sub-1', 'my-event', () => console.log('received'));
+   * siggn.unsubscribe('sub-1');
+   * siggn.publish({ type: 'my-event' }); // (nothing is logged)
+   * ```
+     */
+  unsubscribe(s) {
+    this.unsubscribeGlobal(s);
+    for (const [i, t] of this.subscriptions)
       this.subscriptions.set(
-        s,
-        b.filter((t) => t.id !== i)
+        i,
+        t.filter((b) => b.id !== s)
       );
   }
+  /**
+     * Removes a global subscription for a given subscriber ID.
+     *
+     * @param id The subscriber ID to unsubscribe.
+     * @category Subscription
+     * @since 0.0.5
+     * @example
+     * 
+  ```typescript
+   * const siggn = new Siggn<{ type: 'my-event' }>();
+   * siggn.subscribeAll('logger', console.log);
+   * siggn.unsubscribeGlobal('logger');
+   * siggn.publish({ type: 'my-event' }); // (nothing is logged)
+   * ```
+     */
+  unsubscribeGlobal(s) {
+    this.globalSubscriptions = this.globalSubscriptions.filter((i) => i.id !== s);
+  }
 }
 export {
   r as Siggn

package/dist/index.es.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.es.js","sources":["../src/siggn.ts"],"sourcesContent":["import type { Msg, Subscription, SiggnId } from './types.js';\n\nexport class Siggn<T extends Msg> {\n  private nextId = 0;\n  private subscriptions: Map<T['type'], Array<Subscription<T, any>>>;\n  private subscribeAllSubscriptions: Array<Subscription<T, any>> = [];\n\n  constructor() {\n    this.subscriptions = new Map();\n  }\n\n  createClone<C extends Msg>() {\n    return new Siggn<C | T>();\n  }\n\n  makeId(id?: string): SiggnId {\n    return id ?? `sub_${(this.nextId++).toString(36)}`;\n  }\n\n  make(id: SiggnId): {\n    subscribe: <K extends T['type']>(\n      type: K,\n      callback: (msg: Extract<T, { type: K }>) => void,\n    ) => void;\n    unsubscribe: () => void;\n    subscribeMany: (\n      setup: (\n        subscribe: <K extends T['type']>(\n          type: K,\n          callback: (msg: Extract<T, { type: K }>) => void,\n        ) => void,\n      ) => void,\n    ) => void;\n    subscribeAll: (callback: (msg: T) => void) => void;\n  } {\n    return {\n      subscribe: (type, callback) => {\n        this.subscribe(id, type, callback);\n      },\n      unsubscribe: () => {\n        this.unsubscribe(id);\n      },\n      subscribeMany: (setup) => {\n        this.subscribeMany(id, setup);\n      },\n      subscribeAll: (callback) => {\n        this.subscribeAll(id, callback);\n      },\n    };\n  }\n\n  subscribeMany(\n    id: SiggnId,\n    setup: (\n      subscribe: <K extends T['type']>(\n        type: K,\n        callback: (msg: Extract<T, { type: K }>) => void,\n      ) => void,\n    ) => void,\n  ) {\n    setup((type, callback) => this.subscribe(id, type, callback));\n  }\n\n  subscribe<K extends T['type']>(\n    id: SiggnId,\n    type: K,\n    callback: (msg: Extract<T, { type: K }>) => void,\n  ) {\n    if (!this.subscriptions.has(type)) {\n      this.subscriptions.set(type, []);\n    }\n\n    this.subscriptions.get(type)?.push({ id, callback });\n  }\n\n  subscribeAll(id: SiggnId, callback: (msg: T) => void) {\n    this.subscribeAllSubscriptions.push({ id, callback });\n  }\n\n  publish(msg: T) {\n    this.subscribeAllSubscriptions.forEach((sub) => {\n      sub.callback(msg as Extract<T, { type: any }>);\n    });\n\n    if (!this.subscriptions.has(msg.type)) {\n      return;\n    }\n\n    this.subscriptions.get(msg.type)?.forEach((sub) => {\n      sub.callback(msg as Extract<T, { type: any }>);\n    });\n  }\n\n  unsubscribe(id: SiggnId) {\n    this.subscribeAllSubscriptions = this.subscribeAllSubscriptions.filter((s) => s.id !== id);\n\n    for (const [type, subscriptions] of this.subscriptions) {\n      this.subscriptions.set(\n        type,\n        subscriptions.filter((sub) => sub.id !== id),\n      );\n    }\n  }\n}\n"],"names":["Siggn","id","type","callback","setup","msg","sub","subscriptions"],"mappings":"AAEO,MAAMA,EAAqB;AAAA,EACxB,SAAS;AAAA,EACT;AAAA,EACA,4BAAyD,CAAA;AAAA,EAEjE,cAAc;AACZ,SAAK,oCAAoB,IAAA;AAAA,EAC3B;AAAA,EAEA,cAA6B;AAC3B,WAAO,IAAIA,EAAA;AAAA,EACb;AAAA,EAEA,OAAOC,GAAsB;AAC3B,WAAOA,KAAM,QAAQ,KAAK,UAAU,SAAS,EAAE,CAAC;AAAA,EAClD;AAAA,EAEA,KAAKA,GAeH;AACA,WAAO;AAAA,MACL,WAAW,CAACC,GAAMC,MAAa;AAC7B,aAAK,UAAUF,GAAIC,GAAMC,CAAQ;AAAA,MACnC;AAAA,MACA,aAAa,MAAM;AACjB,aAAK,YAAYF,CAAE;AAAA,MACrB;AAAA,MACA,eAAe,CAACG,MAAU;AACxB,aAAK,cAAcH,GAAIG,CAAK;AAAA,MAC9B;AAAA,MACA,cAAc,CAACD,MAAa;AAC1B,aAAK,aAAaF,GAAIE,CAAQ;AAAA,MAChC;AAAA,IAAA;AAAA,EAEJ;AAAA,EAEA,cACEF,GACAG,GAMA;AACA,IAAAA,EAAM,CAACF,GAAMC,MAAa,KAAK,UAAUF,GAAIC,GAAMC,CAAQ,CAAC;AAAA,EAC9D;AAAA,EAEA,UACEF,GACAC,GACAC,GACA;AACA,IAAK,KAAK,cAAc,IAAID,CAAI,KAC9B,KAAK,cAAc,IAAIA,GAAM,CAAA,CAAE,GAGjC,KAAK,cAAc,IAAIA,CAAI,GAAG,KAAK,EAAE,IAAAD,GAAI,UAAAE,GAAU;AAAA,EACrD;AAAA,EAEA,aAAaF,GAAaE,GAA4B;AACpD,SAAK,0BAA0B,KAAK,EAAE,IAAAF,GAAI,UAAAE,GAAU;AAAA,EACtD;AAAA,EAEA,QAAQE,GAAQ;AAKd,IAJA,KAAK,0BAA0B,QAAQ,CAACC,MAAQ;AAC9C,MAAAA,EAAI,SAASD,CAAgC;AAAA,IAC/C,CAAC,GAEI,KAAK,cAAc,IAAIA,EAAI,IAAI,KAIpC,KAAK,cAAc,IAAIA,EAAI,IAAI,GAAG,QAAQ,CAACC,MAAQ;AACjD,MAAAA,EAAI,SAASD,CAAgC;AAAA,IAC/C,CAAC;AAAA,EACH;AAAA,EAEA,YAAYJ,GAAa;AACvB,SAAK,4BAA4B,KAAK,0BAA0B,OAAO,CAAC,MAAM,EAAE,OAAOA,CAAE;AAEzF,eAAW,CAACC,GAAMK,CAAa,KAAK,KAAK;AACvC,WAAK,cAAc;AAAA,QACjBL;AAAA,QACAK,EAAc,OAAO,CAACD,MAAQA,EAAI,OAAOL,CAAE;AAAA,MAAA;AAAA,EAGjD;AACF;"}
+{"version":3,"file":"index.es.js","sources":["../src/siggn.ts"],"sourcesContent":["import type { Msg, Subscription, SiggnId, Middleware } from './types.js';\n\n/**\n * A type-safe message bus for dispatching and subscribing to events.\n * @template T A union of all possible message types.\n * @since 0.0.5\n */\nexport class Siggn<M extends Msg> {\n  private nextId = 0;\n  private subscriptions: Map<M['type'], Array<Subscription<M, any>>>;\n  private globalSubscriptions: Array<Subscription<M, any>>;\n  private middlewares: Middleware<M>[];\n\n  /**\n   * Creates a new Siggn instance.\n   * @category Lifecycle\n   * @since 0.0.5\n   */\n  constructor() {\n    this.subscriptions = new Map();\n    this.globalSubscriptions = [];\n    this.middlewares = [];\n  }\n\n  use(mw: Middleware<M>) {\n    this.middlewares.push(mw);\n  }\n\n  /**\n   * Creates a new, independent `Siggn` instance that inherits the message\n   * types of its parent and adds new ones.\n   *\n   * @template C The new message types to add.\n   * @returns A new `Siggn` instance with combined message types.\n   * @category Lifecycle\n   * @since 0.0.5\n   * @example\n   * \n```typescript\n * const baseSiggn = new Siggn<{ type: 'A' }>();\n * const childSiggn = baseSiggn.createClone<{ type: 'B' }>();\n * // childSiggn can now publish and subscribe to types 'A' and 'B'.\n * ```\n   */\n  createClone<C extends Msg>() {\n    return new Siggn<M | C>();\n  }\n\n  /**\n   * Generates a unique ID for a subscriber.\n   * If an ID is provided, it will be used; otherwise, a new one is generated.\n   *\n   * @param id An optional ID to use.\n   * @returns A unique subscriber ID.\n   * @category Utilities\n   * @since 0.0.5\n   * @example\n   * \n```typescript\n * const siggn = new Siggn();\n * const id1 = siggn.makeId(); // e.g., \"sub_0\"\n * const id2 = siggn.makeId('custom-id'); // \"custom-id\"\n * ```\n   */\n  makeId(id?: string): SiggnId {\n    return id ?? `sub_${(this.nextId++).toString(36)}`;\n  }\n\n  /**\n   * Creates a subscription helper object that is pre-configured with a\n   * specific subscriber ID. This simplifies managing multiple subscriptions\n   * for a single component or service.\n   *\n   * @param id The subscriber ID to use for all subscriptions.\n   * @returns An object with `subscribe`, `unsubscribe`, `subscribeMany`, and `subscribeAll` methods.\n   * @category Subscription\n   * @since 0.0.5\n   * @example\n   * \n```typescript\n * const siggn = new Siggn<{ type: 'event' }>();\n * const component = siggn.make('my-component');\n * component.subscribe('event', () => console.log('event received!'));\n * component.unsubscribe();\n * ```\n   */\n  make(id: SiggnId): {\n    subscribe: <T extends M['type']>(\n      type: T,\n      callback: (msg: Extract<M, { type: T }>) => void,\n    ) => void;\n    unsubscribe: () => void;\n    subscribeMany: (\n      setup: (\n        subscribe: <T extends M['type']>(\n          type: T,\n          callback: (msg: Extract<M, { type: T }>) => void,\n        ) => void,\n      ) => void,\n    ) => void;\n    subscribeAll: (callback: (msg: M) => void) => void;\n  } {\n    return {\n      subscribe: (type, callback) => {\n        this.subscribe(id, type, callback);\n      },\n      unsubscribe: () => {\n        this.unsubscribe(id);\n      },\n      subscribeMany: (setup) => {\n        this.subscribeMany(id, setup);\n      },\n      subscribeAll: (callback) => {\n        this.subscribeAll(id, callback);\n      },\n    };\n  }\n\n  /**\n   * Subscribes to multiple message types using a single subscriber ID.\n   *\n   * @param id The subscriber ID.\n   * @param setup A function that receives a `subscribe` helper to register callbacks.\n   * @category Subscription\n   * @since 0.0.5\n   * @example\n   * \n```typescript\n * const siggn = new Siggn<{ type: 'A' } | { type: 'B' }>();\n * siggn.subscribeMany('subscriber-1', (subscribe) => {\n *   subscribe('A', () => console.log('A received'));\n *   subscribe('B', () => console.log('B received'));\n * });\n * ```\n   */\n  subscribeMany(\n    id: SiggnId,\n    setup: (\n      subscribe: <T extends M['type']>(\n        type: T,\n        callback: (msg: Extract<M, { type: T }>) => void,\n      ) => void,\n    ) => void,\n  ) {\n    setup((type, callback) => this.subscribe(id, type, callback));\n  }\n\n  /**\n   * Subscribes to a specific message type.\n   *\n   * @param id The subscriber ID.\n   * @param type The message type to subscribe to.\n   * @param callback The function to call when a message of the specified type is published.\n   * @category Subscription\n   * @since 0.0.5\n   * @example\n   * \n```typescript\n * const siggn = new Siggn<{ type: 'my-event', payload: string }>();\n * siggn.subscribe('subscriber-1', 'my-event', (msg) => {\n *   console.log(msg.payload);\n * });\n * ```\n   */\n  subscribe<T extends M['type']>(\n    id: SiggnId,\n    type: T,\n    callback: (msg: Extract<M, { type: T }>) => void,\n  ) {\n    if (!this.subscriptions.has(type)) {\n      this.subscriptions.set(type, []);\n    }\n\n    this.subscriptions.get(type)?.push({ id, ref: callback });\n  }\n\n  /**\n   * Subscribes to all message types. The callback will be invoked for every\n   * message published on the bus.\n   *\n   * @param id The subscriber ID.\n   * @param callback The function to call for any message.\n   * @category Subscription\n   * @since 0.0.5\n   * @example\n   * \n```typescript\n * const siggn = new Siggn<{ type: 'A' } | { type: 'B' }>();\n * siggn.subscribeAll('logger', (msg) => {\n *   console.log(`Received message of type: ${msg.type}`);\n * });\n * ```\n   */\n  subscribeAll(id: SiggnId, callback: (msg: M) => void) {\n    this.globalSubscriptions.push({ id, ref: callback });\n  }\n\n  /**\n   * Publishes a message to all relevant subscribers.\n   *\n   * @param msg The message to publish.\n   * @category Publishing\n   * @since 0.0.5\n   * @example\n   * \n```typescript\n * const siggn = new Siggn<{ type: 'my-event' }>();\n * siggn.subscribe('sub-1', 'my-event', () => console.log('received'));\n * siggn.publish({ type: 'my-event' }); // \"received\"\n * ```\n   */\n  publish(msg: M) {\n    this.globalSubscriptions.forEach((sub) => {\n      sub.ref(msg as Extract<M, { type: any }>);\n    });\n\n    if (!this.subscriptions.has(msg.type)) {\n      return;\n    }\n\n    this.subscriptions.get(msg.type)?.forEach((sub) => {\n      sub.ref(msg as Extract<M, { type: any }>);\n    });\n  }\n\n  /**\n   * Removes all subscriptions (both specific and global) for a given\n   * subscriber ID.\n   *\n   * @param id The subscriber ID to unsubscribe.\n   * @category Subscription\n   * @since 0.0.5\n   * @example\n   * \n```typescript\n * const siggn = new Siggn<{ type: 'my-event' }>();\n * siggn.subscribe('sub-1', 'my-event', () => console.log('received'));\n * siggn.unsubscribe('sub-1');\n * siggn.publish({ type: 'my-event' }); // (nothing is logged)\n * ```\n   */\n  unsubscribe(id: SiggnId) {\n    this.unsubscribeGlobal(id);\n\n    for (const [type, subscriptions] of this.subscriptions) {\n      this.subscriptions.set(\n        type,\n        subscriptions.filter((sub) => sub.id !== id),\n      );\n    }\n  }\n\n  /**\n   * Removes a global subscription for a given subscriber ID.\n   *\n   * @param id The subscriber ID to unsubscribe.\n   * @category Subscription\n   * @since 0.0.5\n   * @example\n   * \n```typescript\n * const siggn = new Siggn<{ type: 'my-event' }>();\n * siggn.subscribeAll('logger', console.log);\n * siggn.unsubscribeGlobal('logger');\n * siggn.publish({ type: 'my-event' }); // (nothing is logged)\n * ```\n   */\n  unsubscribeGlobal(id: SiggnId) {\n    this.globalSubscriptions = this.globalSubscriptions.filter((s) => s.id !== id);\n  }\n}\n"],"names":["Siggn","mw","id","type","callback","setup","msg","sub","subscriptions","s"],"mappings":"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"}

package/dist/siggn.d.ts

@@ -1,29 +1,188 @@
-import { Msg, SiggnId } from './types.js';
-export declare class Siggn<T extends Msg> {
+import { Msg, SiggnId, Middleware } from './types.js';
+/**
+ * A type-safe message bus for dispatching and subscribing to events.
+ * @template T A union of all possible message types.
+ * @since 0.0.5
+ */
+export declare class Siggn<M extends Msg> {
     private nextId;
     private subscriptions;
-    private subscribeAllSubscriptions;
+    private globalSubscriptions;
+    private middlewares;
+    /**
+     * Creates a new Siggn instance.
+     * @category Lifecycle
+     * @since 0.0.5
+     */
     constructor();
-    createClone<C extends Msg>(): Siggn<T | C>;
+    use(mw: Middleware<M>): void;
+    /**
+     * Creates a new, independent `Siggn` instance that inherits the message
+     * types of its parent and adds new ones.
+     *
+     * @template C The new message types to add.
+     * @returns A new `Siggn` instance with combined message types.
+     * @category Lifecycle
+     * @since 0.0.5
+     * @example
+     *
+  ```typescript
+   * const baseSiggn = new Siggn<{ type: 'A' }>();
+   * const childSiggn = baseSiggn.createClone<{ type: 'B' }>();
+   * // childSiggn can now publish and subscribe to types 'A' and 'B'.
+   * ```
+     */
+    createClone<C extends Msg>(): Siggn<M | C>;
+    /**
+     * Generates a unique ID for a subscriber.
+     * If an ID is provided, it will be used; otherwise, a new one is generated.
+     *
+     * @param id An optional ID to use.
+     * @returns A unique subscriber ID.
+     * @category Utilities
+     * @since 0.0.5
+     * @example
+     *
+  ```typescript
+   * const siggn = new Siggn();
+   * const id1 = siggn.makeId(); // e.g., "sub_0"
+   * const id2 = siggn.makeId('custom-id'); // "custom-id"
+   * ```
+     */
     makeId(id?: string): SiggnId;
+    /**
+     * Creates a subscription helper object that is pre-configured with a
+     * specific subscriber ID. This simplifies managing multiple subscriptions
+     * for a single component or service.
+     *
+     * @param id The subscriber ID to use for all subscriptions.
+     * @returns An object with `subscribe`, `unsubscribe`, `subscribeMany`, and `subscribeAll` methods.
+     * @category Subscription
+     * @since 0.0.5
+     * @example
+     *
+  ```typescript
+   * const siggn = new Siggn<{ type: 'event' }>();
+   * const component = siggn.make('my-component');
+   * component.subscribe('event', () => console.log('event received!'));
+   * component.unsubscribe();
+   * ```
+     */
     make(id: SiggnId): {
-        subscribe: <K extends T['type']>(type: K, callback: (msg: Extract<T, {
-            type: K;
+        subscribe: <T extends M['type']>(type: T, callback: (msg: Extract<M, {
+            type: T;
         }>) => void) => void;
         unsubscribe: () => void;
-        subscribeMany: (setup: (subscribe: <K extends T['type']>(type: K, callback: (msg: Extract<T, {
-            type: K;
+        subscribeMany: (setup: (subscribe: <T extends M['type']>(type: T, callback: (msg: Extract<M, {
+            type: T;
         }>) => void) => void) => void) => void;
-        subscribeAll: (callback: (msg: T) => void) => void;
+        subscribeAll: (callback: (msg: M) => void) => void;
     };
-    subscribeMany(id: SiggnId, setup: (subscribe: <K extends T['type']>(type: K, callback: (msg: Extract<T, {
-        type: K;
+    /**
+     * Subscribes to multiple message types using a single subscriber ID.
+     *
+     * @param id The subscriber ID.
+     * @param setup A function that receives a `subscribe` helper to register callbacks.
+     * @category Subscription
+     * @since 0.0.5
+     * @example
+     *
+  ```typescript
+   * const siggn = new Siggn<{ type: 'A' } | { type: 'B' }>();
+   * siggn.subscribeMany('subscriber-1', (subscribe) => {
+   *   subscribe('A', () => console.log('A received'));
+   *   subscribe('B', () => console.log('B received'));
+   * });
+   * ```
+     */
+    subscribeMany(id: SiggnId, setup: (subscribe: <T extends M['type']>(type: T, callback: (msg: Extract<M, {
+        type: T;
     }>) => void) => void) => void): void;
-    subscribe<K extends T['type']>(id: SiggnId, type: K, callback: (msg: Extract<T, {
-        type: K;
+    /**
+     * Subscribes to a specific message type.
+     *
+     * @param id The subscriber ID.
+     * @param type The message type to subscribe to.
+     * @param callback The function to call when a message of the specified type is published.
+     * @category Subscription
+     * @since 0.0.5
+     * @example
+     *
+  ```typescript
+   * const siggn = new Siggn<{ type: 'my-event', payload: string }>();
+   * siggn.subscribe('subscriber-1', 'my-event', (msg) => {
+   *   console.log(msg.payload);
+   * });
+   * ```
+     */
+    subscribe<T extends M['type']>(id: SiggnId, type: T, callback: (msg: Extract<M, {
+        type: T;
     }>) => void): void;
-    subscribeAll(id: SiggnId, callback: (msg: T) => void): void;
-    publish(msg: T): void;
+    /**
+     * Subscribes to all message types. The callback will be invoked for every
+     * message published on the bus.
+     *
+     * @param id The subscriber ID.
+     * @param callback The function to call for any message.
+     * @category Subscription
+     * @since 0.0.5
+     * @example
+     *
+  ```typescript
+   * const siggn = new Siggn<{ type: 'A' } | { type: 'B' }>();
+   * siggn.subscribeAll('logger', (msg) => {
+   *   console.log(`Received message of type: ${msg.type}`);
+   * });
+   * ```
+     */
+    subscribeAll(id: SiggnId, callback: (msg: M) => void): void;
+    /**
+     * Publishes a message to all relevant subscribers.
+     *
+     * @param msg The message to publish.
+     * @category Publishing
+     * @since 0.0.5
+     * @example
+     *
+  ```typescript
+   * const siggn = new Siggn<{ type: 'my-event' }>();
+   * siggn.subscribe('sub-1', 'my-event', () => console.log('received'));
+   * siggn.publish({ type: 'my-event' }); // "received"
+   * ```
+     */
+    publish(msg: M): void;
+    /**
+     * Removes all subscriptions (both specific and global) for a given
+     * subscriber ID.
+     *
+     * @param id The subscriber ID to unsubscribe.
+     * @category Subscription
+     * @since 0.0.5
+     * @example
+     *
+  ```typescript
+   * const siggn = new Siggn<{ type: 'my-event' }>();
+   * siggn.subscribe('sub-1', 'my-event', () => console.log('received'));
+   * siggn.unsubscribe('sub-1');
+   * siggn.publish({ type: 'my-event' }); // (nothing is logged)
+   * ```
+     */
     unsubscribe(id: SiggnId): void;
+    /**
+     * Removes a global subscription for a given subscriber ID.
+     *
+     * @param id The subscriber ID to unsubscribe.
+     * @category Subscription
+     * @since 0.0.5
+     * @example
+     *
+  ```typescript
+   * const siggn = new Siggn<{ type: 'my-event' }>();
+   * siggn.subscribeAll('logger', console.log);
+   * siggn.unsubscribeGlobal('logger');
+   * siggn.publish({ type: 'my-event' }); // (nothing is logged)
+   * ```
+     */
+    unsubscribeGlobal(id: SiggnId): void;
 }
 //# sourceMappingURL=siggn.d.ts.map

package/dist/siggn.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"siggn.d.ts","sourceRoot":"","sources":["../src/siggn.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,GAAG,EAAgB,OAAO,EAAE,MAAM,YAAY,CAAC;AAE7D,qBAAa,KAAK,CAAC,CAAC,SAAS,GAAG;IAC9B,OAAO,CAAC,MAAM,CAAK;IACnB,OAAO,CAAC,aAAa,CAA8C;IACnE,OAAO,CAAC,yBAAyB,CAAmC;;IAMpE,WAAW,CAAC,CAAC,SAAS,GAAG;IAIzB,MAAM,CAAC,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO;IAI5B,IAAI,CAAC,EAAE,EAAE,OAAO,GAAG;QACjB,SAAS,EAAE,CAAC,CAAC,SAAS,CAAC,CAAC,MAAM,CAAC,EAC7B,IAAI,EAAE,CAAC,EACP,QAAQ,EAAE,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC,EAAE;YAAE,IAAI,EAAE,CAAC,CAAA;SAAE,CAAC,KAAK,IAAI,KAC7C,IAAI,CAAC;QACV,WAAW,EAAE,MAAM,IAAI,CAAC;QACxB,aAAa,EAAE,CACb,KAAK,EAAE,CACL,SAAS,EAAE,CAAC,CAAC,SAAS,CAAC,CAAC,MAAM,CAAC,EAC7B,IAAI,EAAE,CAAC,EACP,QAAQ,EAAE,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC,EAAE;YAAE,IAAI,EAAE,CAAC,CAAA;SAAE,CAAC,KAAK,IAAI,KAC7C,IAAI,KACN,IAAI,KACN,IAAI,CAAC;QACV,YAAY,EAAE,CAAC,QAAQ,EAAE,CAAC,GAAG,EAAE,CAAC,KAAK,IAAI,KAAK,IAAI,CAAC;KACpD;IAiBD,aAAa,CACX,EAAE,EAAE,OAAO,EACX,KAAK,EAAE,CACL,SAAS,EAAE,CAAC,CAAC,SAAS,CAAC,CAAC,MAAM,CAAC,EAC7B,IAAI,EAAE,CAAC,EACP,QAAQ,EAAE,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC,EAAE;QAAE,IAAI,EAAE,CAAC,CAAA;KAAE,CAAC,KAAK,IAAI,KAC7C,IAAI,KACN,IAAI;IAKX,SAAS,CAAC,CAAC,SAAS,CAAC,CAAC,MAAM,CAAC,EAC3B,EAAE,EAAE,OAAO,EACX,IAAI,EAAE,CAAC,EACP,QAAQ,EAAE,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC,EAAE;QAAE,IAAI,EAAE,CAAC,CAAA;KAAE,CAAC,KAAK,IAAI;IASlD,YAAY,CAAC,EAAE,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC,GAAG,EAAE,CAAC,KAAK,IAAI;IAIpD,OAAO,CAAC,GAAG,EAAE,CAAC;IAcd,WAAW,CAAC,EAAE,EAAE,OAAO;CAUxB"}
+{"version":3,"file":"siggn.d.ts","sourceRoot":"","sources":["../src/siggn.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,GAAG,EAAgB,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAEzE;;;;GAIG;AACH,qBAAa,KAAK,CAAC,CAAC,SAAS,GAAG;IAC9B,OAAO,CAAC,MAAM,CAAK;IACnB,OAAO,CAAC,aAAa,CAA8C;IACnE,OAAO,CAAC,mBAAmB,CAA8B;IACzD,OAAO,CAAC,WAAW,CAAkB;IAErC;;;;OAIG;;IAOH,GAAG,CAAC,EAAE,EAAE,UAAU,CAAC,CAAC,CAAC;IAIrB;;;;;;;;;;;;;;;OAeG;IACH,WAAW,CAAC,CAAC,SAAS,GAAG;IAIzB;;;;;;;;;;;;;;;OAeG;IACH,MAAM,CAAC,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO;IAI5B;;;;;;;;;;;;;;;;;OAiBG;IACH,IAAI,CAAC,EAAE,EAAE,OAAO,GAAG;QACjB,SAAS,EAAE,CAAC,CAAC,SAAS,CAAC,CAAC,MAAM,CAAC,EAC7B,IAAI,EAAE,CAAC,EACP,QAAQ,EAAE,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC,EAAE;YAAE,IAAI,EAAE,CAAC,CAAA;SAAE,CAAC,KAAK,IAAI,KAC7C,IAAI,CAAC;QACV,WAAW,EAAE,MAAM,IAAI,CAAC;QACxB,aAAa,EAAE,CACb,KAAK,EAAE,CACL,SAAS,EAAE,CAAC,CAAC,SAAS,CAAC,CAAC,MAAM,CAAC,EAC7B,IAAI,EAAE,CAAC,EACP,QAAQ,EAAE,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC,EAAE;YAAE,IAAI,EAAE,CAAC,CAAA;SAAE,CAAC,KAAK,IAAI,KAC7C,IAAI,KACN,IAAI,KACN,IAAI,CAAC;QACV,YAAY,EAAE,CAAC,QAAQ,EAAE,CAAC,GAAG,EAAE,CAAC,KAAK,IAAI,KAAK,IAAI,CAAC;KACpD;IAiBD;;;;;;;;;;;;;;;;OAgBG;IACH,aAAa,CACX,EAAE,EAAE,OAAO,EACX,KAAK,EAAE,CACL,SAAS,EAAE,CAAC,CAAC,SAAS,CAAC,CAAC,MAAM,CAAC,EAC7B,IAAI,EAAE,CAAC,EACP,QAAQ,EAAE,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC,EAAE;QAAE,IAAI,EAAE,CAAC,CAAA;KAAE,CAAC,KAAK,IAAI,KAC7C,IAAI,KACN,IAAI;IAKX;;;;;;;;;;;;;;;;OAgBG;IACH,SAAS,CAAC,CAAC,SAAS,CAAC,CAAC,MAAM,CAAC,EAC3B,EAAE,EAAE,OAAO,EACX,IAAI,EAAE,CAAC,EACP,QAAQ,EAAE,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC,EAAE;QAAE,IAAI,EAAE,CAAC,CAAA;KAAE,CAAC,KAAK,IAAI;IASlD;;;;;;;;;;;;;;;;OAgBG;IACH,YAAY,CAAC,EAAE,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC,GAAG,EAAE,CAAC,KAAK,IAAI;IAIpD;;;;;;;;;;;;;OAaG;IACH,OAAO,CAAC,GAAG,EAAE,CAAC;IAcd;;;;;;;;;;;;;;;OAeG;IACH,WAAW,CAAC,EAAE,EAAE,OAAO;IAWvB;;;;;;;;;;;;;;OAcG;IACH,iBAAiB,CAAC,EAAE,EAAE,OAAO;CAG9B"}

package/dist/types.d.ts

@@ -2,14 +2,15 @@ export type Msg = {
     type: string;
     [key: string]: unknown;
 };
-export type Subscription<T extends Msg, K extends T['type']> = {
+export type Subscription<M extends Msg, T extends M['type']> = {
     id: string;
-    callback: (msg: Extract<T, {
-        type: K;
+    ref: (msg: Extract<M, {
+        type: T;
     }>) => void;
 };
 export type SubscriptionMap<T extends Msg> = {
     [K in T['type']]: Array<Subscription<T, K>>;
 };
 export type SiggnId = string;
+export type Middleware<M extends Msg> = (msg: M, next: () => void) => void | Promise<void>;
 //# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,GAAG,GAAG;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB,CAAC;AAEF,MAAM,MAAM,YAAY,CAAC,CAAC,SAAS,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC,MAAM,CAAC,IAAI;IAC7D,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC,EAAE;QAAE,IAAI,EAAE,CAAC,CAAA;KAAE,CAAC,KAAK,IAAI,CAAC;CAClD,CAAC;AAEF,MAAM,MAAM,eAAe,CAAC,CAAC,SAAS,GAAG,IAAI;KAC1C,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,GAAG,KAAK,CAAC,YAAY,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;CAC5C,CAAC;AAEF,MAAM,MAAM,OAAO,GAAG,MAAM,CAAC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,GAAG,GAAG;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB,CAAC;AAEF,MAAM,MAAM,YAAY,CAAC,CAAC,SAAS,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC,MAAM,CAAC,IAAI;IAC7D,EAAE,EAAE,MAAM,CAAC;IACX,GAAG,EAAE,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC,EAAE;QAAE,IAAI,EAAE,CAAC,CAAA;KAAE,CAAC,KAAK,IAAI,CAAC;CAC7C,CAAC;AAEF,MAAM,MAAM,eAAe,CAAC,CAAC,SAAS,GAAG,IAAI;KAC1C,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,GAAG,KAAK,CAAC,YAAY,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;CAC5C,CAAC;AAEF,MAAM,MAAM,OAAO,GAAG,MAAM,CAAC;AAE7B,MAAM,MAAM,UAAU,CAAC,CAAC,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,IAAI,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@siggn/core",
-  "version": "0.0.5",
+  "version": "0.1.1",
   "description": "A lightweight message bus system for Typescript",
   "keywords": [
     "pub/sub",
@@ -52,6 +52,7 @@
     "dev": "vite build --watch",
     "clean": "rm -rf dist",
     "test": "vitest run",
+    "coverage": "vitest run --coverage",
     "build": "vite build"
   }
 }