on-ngx-event-bus 0.0.1

package/README.md

@@ -0,0 +1,224 @@
+<p align="center">
+  <picture>
+    <img
+      alt="Ngx Event Bus"
+      src="./ngx-event-bus-lib-cover.jpg"
+      width="100%"
+    />
+  </picture>
+</p>
+
+# ngx-event-bus
+
+**A lightweight, fully-tested, type-safe global event bus for Angular — powered by decorators, pure functions, and zero shared state.**
+
+Broadcast strongly-typed events anywhere in your app and react to them declaratively —
+without services, DI, providers, RxJS, Signals, or tight coupling.
+
+## Motivation
+
+In many Angular applications, **components that are completely unrelated still need to communicate**.
+
+When the app is not built around a state-management solution, a common approach is to introduce a shared service —
+usually based on RxJS `Subject`'s or Signals — and use it as a communication bridge.
+
+This typically requires:
+- Services, providers, and dependency injections
+- RxJS tools or Signals
+- Manual lifecycle handling to avoid memory leaks (in the case of RxJS)
+
+`ngx-event-bus` takes a different approach.
+
+It is built on **native JavaScript events**, automatically adds and removes event listeners to prevent **memory leaks**, and requires **no services, no DI, and no module setup or imports**. Event handling is simple, declarative, and free from shared state.
+
+## Compatibility 
+
+✅&ensp;**Angular support:** Angular **v9 and above**
+
+Supports **all Angular entities**:
+
+- Components
+- Directives
+- Services
+- Pipes
+
+## Quick Start&ensp;🚀
+
+## Install
+```bash
+# npm
+npm install on-ngx-event-bus
+
+# yarn
+yarn add on-ngx-event-bus
+
+# pnpm
+pnpm add on-ngx-event-bus
+```
+
+## Usage
+
+### Broadcasting an event&ensp;🛜​
+```ts
+import { broadcast, GEvent } from "on-ngx-event-bus";
+
+publish(): void {
+  broadcast(
+    new GEvent("MY_EVENT", {
+      metadata: "My event data..."
+    })
+  );
+}
+```
+
+- The event's payload can be **any type of data** — primitives, objects, functions, and more. (If no payload is provided, the default is null)
+
+---
+
+### Intercepting an event&ensp;📡
+```ts
+import { Component } from "@angular/core";
+import { Interceptor, intercept } from "on-ngx-event-bus";
+
+@Interceptor([
+  { type: "MY_EVENT", action: "handleEvent" }
+])
+@Component({
+  selector: "app-home",
+  template: `Home`
+})
+export class HomeComponent {
+  constructor() {
+    intercept(this);
+  }
+
+  handleEvent(payload: { metadata: string }): void {
+    console.log("Event intercepted: ", payload);
+  }
+}
+```
+- ⚠️&ensp;Mandatory: Always call intercept(this) in the constructor to activate the `@Interceptor`.
+
+- The `@Interceptor` decorator can intercept and handle **any number of events**, without limits.
+
+## 🎯&ensp;Targeted Events
+
+By default, events are **broadcast globally** — each interceptor listening to the same event type will receive them.
+
+However, in some scenarios you may want **only specific listeners** to react to an event, even if multiple interceptors are registered for the same type. To support this, events can be optionally sent with a **`key`** (`string`).
+
+### Broadcasting a targeted event&ensp;🛜​
+
+```ts
+publish(): void {
+  broadcast(
+    new GEvent("MY_EVENT", {
+      metadata: "My event data..."
+    }, "BUS::MY_EVENT::A9F3-77XQ") // 🔑​
+  );
+}
+```
+
+### Intercepting a targeted event&ensp;📡
+
+```ts
+@Interceptor([
+  { type: "MY_EVENT", action: "handleTargetedEvent", key: "BUS::MY_EVENT::A9F3-77XQ" }
+])
+@Component({
+  selector: "app-home",
+  template: `Home`
+})
+export class HomeComponent {
+  constructor() {
+    intercept(this);
+  }
+
+  handleTargetedEvent(): void {
+    console.log("Will be triggered only if the key matches...");
+  }
+}
+```
+- Events broadcast with a mismatched key will be **rejected** by the `@Interceptor`&ensp;❌
+
+
+## Advanced Usage&ensp;⚡
+
+`ngx-event-bus` supports **fully-typed events** in 3 different levels, from quick-and-loose to fully enforced best practices.  
+
+---
+
+### 1️⃣&ensp;Loose / Quick Usage
+```ts
+broadcast(new GEvent("MY_EVENT", {
+  metadata: "Quick, untyped payload"
+}));
+```
+- ✅&ensp;Fast — minimal setup, just fire-and-forget.  
+- ✅&ensp;Flexible — any shape of payload is allowed.  
+- ❌&ensp;No type safety (developer choice)
+
+### 2️⃣&ensp;Generic enforce - Strongly Typed 
+```ts
+broadcast(
+  new GEvent<"MY_EVENT", { metadata: string }>("MY_EVENT", {
+    metadata: "Payload and event name are generic enforced.
+  })
+);
+```
+Or even smarter, with Enums/types and interfaces
+
+```ts
+enum MyEventTypes {
+  MyEvent = "MY_EVENT"
+}
+
+interface MyEventPayload {
+  metadata: string;
+}
+
+broadcast(
+ new GEvent<MyEventTypes.MyEvent, MyEventPayload>(
+   MyEventTypes.MyEvent, {
+     metadata: "Payload and event name are generic enforced.
+   })
+);
+```
+- ✅&ensp;Payload enforced — TypeScript ensures payload shape is correct.
+- ✅&ensp;Event names centralized — reduces typos and keeps event names consistent.
+- ✅&ensp;Better developer experience — IDE autocompletion works.
+- ❌&ensp;Event–payload relationship not fully enforced — nothing prevents using the wrong payload with a given event type.
+
+### 3️⃣&ensp;Fully Enforced, Best Practice&ensp;🥇
+By extending the `GEvent` class, you can create your own fully enforced events. This ensures **both the event type and its payload are strictly typed**, making your code refactor-safe and perfect for large apps.
+
+```ts
+import { GEvent, broadcast } from 'on-ngx-event-bus';
+
+export class MyEvent extends GEvent<MyEventTypes.MyEvent, MyEventPayload> {
+  static readonly TYPE = MyEventTypes.MyEvent;
+
+  constructor(payload: MyEventPayload) {
+    super(MyEvent.TYPE, payload);
+  }
+}
+
+broadcast(
+  new MyEvent({
+    metadata: "Fully typed and refactor-safe!"
+  })
+);
+```
+- ✅&ensp;Fully typed — TypeScript strictly enforces both event type and payload, guaranteeing their correct relationship.
+- ✅&ensp;Refactor-safe — renaming the event or payload interface will automatically propagate errors if used incorrectly.
+- ✅&ensp;Best developer experience — IDE autocompletion, type-checking, and maintainability are maximized.
+- ✅&ensp;Large-app ready — ideal for apps with many events and complex interactions.
+
+---
+
+## Final Thoughts&ensp;✨
+
+`ngx-event-bus` is designed to scale with your application — from small components to large, event-rich Angular systems.
+
+It removes boilerplate, enforces correctness at compile time, and lets you focus on **intent**, not wiring.
+If your app relies on clean, decoupled communication, this library is built for you.

package/fesm2022/on-ngx-event-bus.mjs

@@ -0,0 +1,189 @@
+import { ɵNG_PIPE_DEF as _NG_PIPE_DEF, ɵɵdirectiveInject as __directiveInject, RendererFactory2 } from '@angular/core';
+
+const NG_PIPE_DEF = _NG_PIPE_DEF;
+
+const GLOBAL_HOST = "window";
+
+const DECORATOR_APPLIED = Symbol('__interceptorDecoratorApplied');
+
+const TRUSTED_EVENT = Symbol('__trustedEvent');
+
+const PAYLOAD_PROTOTYPE = Object.freeze({
+    [TRUSTED_EVENT]: true,
+});
+
+/**
+ * Sends a global, system-wide event via the Event Bus.
+ *
+ * The event will be received by all active `@Interceptor`s that are
+ * listening for the same event type.
+ *
+ * Events may optionally include a `key`. When a key is provided,
+ * only interceptors registered with the same key will accept the
+ * event; all others will be rejected.
+ *
+ * The payload is strongly typed and may be any value:
+ * primitives, objects, arrays, etc.
+ *
+ * Internally, the payload is wrapped in a trusted object to ensure
+ * listeners only handle legitimate, system-generated events.
+ * Interceptors always access the original payload via `event.detail.data`.
+ *
+ * @template T - Type of the event name (string literal recommended for type safety).
+ * @template P - Type of the event payload.
+ *
+ * @param event - The typed event instance to broadcast.
+*/
+function broadcast(event) {
+    const trustedPayload = Object.create(PAYLOAD_PROTOTYPE);
+    Object.assign(trustedPayload, {
+        data: event.payload || null,
+        key: event.key
+    });
+    window.dispatchEvent(new CustomEvent(event.type, {
+        detail: trustedPayload,
+    }));
+}
+
+/**
+ * Registers an instance to receive events through its @Interceptor-decorated methods.
+ *
+ * This function must be called inside the class constructor with `this` as the argument:
+ * ```ts
+ * constructor() {
+ *   intercept(this);
+ * }
+ * ```
+ *
+ * Only classes decorated with `@Interceptor` can be intercepted. Calling this on an
+ * undecorated class will throw an error.
+ *
+ * After calling this, methods specified in the `@Interceptor` decorator will receive
+ * events of the corresponding type via the Event Bus.
+ *
+ * @template T - Type of the instance being intercepted.
+ *
+ * @param instance - The class instance to register for interception.
+*/
+function intercept(instance) {
+    return (function () {
+        const unDecorated = !(DECORATOR_APPLIED in (Object.getPrototypeOf(instance)));
+        if (unDecorated) {
+            throw new Error('intercept() function cannot be used inside any Angular classes ' +
+                'that are not decorated with @Interceptor decorator');
+        }
+        instance.constructor.prototype._intercept(instance);
+    })();
+}
+
+/**
+ * Represents a strongly-typed event in the Event Bus system.
+ *
+ * Each `GEvent` has a `type` (string literal recommended for type safety) and a `payload`.
+ * This object is used with the Event Bus functions, ensuring
+ * type-safe communication across your Angular application.
+ *
+ * @template T - Type of the event name. Defaults to `string`, but string literals are recommended.
+ * @template P - Type of the event payload. Defaults to `null` if no payload is needed.
+*/
+class GEvent {
+    /** The type of the event */
+    type;
+    /** The strongly-typed payload of the event */
+    payload;
+    /** Optional key used to scope or target the event */
+    key;
+    /**
+      * Creates a new typed event instance.
+      *
+      * @param type - The event type identifier.
+      * @param payload - Optional event payload.
+      * @param key - Optional key used to target specific interceptors.
+     */
+    constructor(type, payload, key) {
+        this.type = type;
+        this.payload = payload;
+        this.key = key;
+    }
+}
+
+function initListeners(events, instance, renderer2) {
+    return events.map((event) => {
+        return renderer2.listen(GLOBAL_HOST, event.type, data => {
+            // Guard 1:
+            // Event Source - events originated from unknown or external sources will be rejected ❌
+            if (Object.getPrototypeOf(data.detail) !== PAYLOAD_PROTOTYPE) {
+                return;
+            }
+            // Guard 2:
+            // Key-based event filtering - events broadcast with a mismatched key will be rejected ❌
+            if (event.key !== data.detail.key) {
+                return;
+            }
+            // Guard 3:
+            // Interceptor integrity check — ensure the configured action exists and callable, misconfiguration is treated as a hard error ❌
+            if (typeof instance[event.action] !== 'function') {
+                throw new Error(`Interceptor error: "${event.action}" is not a function on ${instance.constructor.name}`);
+            }
+            // Event accepted ✅
+            // At this point, the event is verified, trusted, and correctly targeted.
+            instance[event.action](data.detail.data);
+        });
+    });
+}
+
+function isPipe(target) {
+    return !!target[NG_PIPE_DEF];
+}
+
+/**
+ * Class decorator that registers methods to handle cross-system events.
+ *
+ * Use this decorator on an Angular class to specify which events it should listen to.
+ * Each object in the `events` array defines an event type and the corresponding class
+ * method (action) that should be called when that event is broadcast.
+ *
+ * After decorating the class, you must call `intercept(this)` in the constructor to
+ * activate interception, otherwise the methods will not receive any events.
+ *
+ * @template T - Type of the class constructor being decorated.
+ *
+ * @param events - An array of event descriptors. Each descriptor must include:
+ *   - `type`: the event type string (strongly typed recommended)
+ *   - `action`: the name of the class method to execute when the event occurs
+ * @returns A class constructor function with interception logic applied.
+*/
+function Interceptor(events = []) {
+    return function (orgConstructor) {
+        let listeners = [];
+        orgConstructor.prototype[DECORATOR_APPLIED] = true;
+        orgConstructor.prototype._intercept = function (instance) {
+            const rendererFactory = __directiveInject(RendererFactory2);
+            const renderer2 = rendererFactory.createRenderer(null, null);
+            listeners = initListeners(events, instance, renderer2);
+        };
+        const onDestroy = orgConstructor.prototype.ngOnDestroy;
+        orgConstructor.prototype.ngOnDestroy = function () {
+            listeners.map((listener) => listener());
+            onDestroy && onDestroy.call(this);
+        };
+        if (isPipe(orgConstructor)) {
+            const def = orgConstructor.prototype.constructor.ɵpipe;
+            def.onDestroy = function () {
+                listeners.map((listener) => listener());
+                onDestroy && onDestroy.call(this);
+            };
+        }
+    };
+}
+
+/*
+ * Public API Surface of ngx-event-bus
+*/
+
+/**
+ * Generated bundle index. Do not edit.
+ */
+
+export { GEvent, Interceptor, broadcast, intercept };
+//# sourceMappingURL=on-ngx-event-bus.mjs.map

package/fesm2022/on-ngx-event-bus.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"on-ngx-event-bus.mjs","sources":["../../../projects/ngx-event-bus-lib/src/lib/consts/ng-pipe-def.const.ts","../../../projects/ngx-event-bus-lib/src/lib/consts/global-host.const.ts","../../../projects/ngx-event-bus-lib/src/lib/consts/decorator-applied.const.ts","../../../projects/ngx-event-bus-lib/src/lib/consts/trusted-event.const.ts","../../../projects/ngx-event-bus-lib/src/lib/consts/payload-prototype.const.ts","../../../projects/ngx-event-bus-lib/src/lib/api/broadcast.function.ts","../../../projects/ngx-event-bus-lib/src/lib/api/intercept.function.ts","../../../projects/ngx-event-bus-lib/src/lib/classes/gevent.class.ts","../../../projects/ngx-event-bus-lib/src/lib/utils/init-listeners.util.ts","../../../projects/ngx-event-bus-lib/src/lib/utils/is-pipe.util.ts","../../../projects/ngx-event-bus-lib/src/lib/decorators/interceptor.decorator.ts","../../../projects/ngx-event-bus-lib/src/public-api.ts","../../../projects/ngx-event-bus-lib/src/on-ngx-event-bus.ts"],"sourcesContent":["import { ɵNG_PIPE_DEF } from \"@angular/core\";\n\nexport const NG_PIPE_DEF: 'ɵpipe' = ɵNG_PIPE_DEF as 'ɵpipe';\n","\nexport const GLOBAL_HOST: \"window\" = \"window\";","\nexport const DECORATOR_APPLIED: symbol = Symbol('__interceptorDecoratorApplied');\n","\nexport const TRUSTED_EVENT: symbol = Symbol('__trustedEvent');\n","import { TRUSTED_EVENT } from \"./trusted-event.const\";\n\nexport const PAYLOAD_PROTOTYPE = Object.freeze({\n  [TRUSTED_EVENT]: true,\n});","import { GEvent } from \"../classes\";\nimport { PAYLOAD_PROTOTYPE } from \"../consts\";\n\n/**\n * Sends a global, system-wide event via the Event Bus.\n *\n * The event will be received by all active `@Interceptor`s that are\n * listening for the same event type.\n *\n * Events may optionally include a `key`. When a key is provided,\n * only interceptors registered with the same key will accept the\n * event; all others will be rejected.\n *\n * The payload is strongly typed and may be any value:\n * primitives, objects, arrays, etc.\n *\n * Internally, the payload is wrapped in a trusted object to ensure\n * listeners only handle legitimate, system-generated events.\n * Interceptors always access the original payload via `event.detail.data`.\n *\n * @template T - Type of the event name (string literal recommended for type safety).\n * @template P - Type of the event payload.\n *\n * @param event - The typed event instance to broadcast.\n*/\nexport function broadcast<T extends string, P = null>(\n  event: GEvent<T, P>\n): void {\n  const trustedPayload = Object.create(PAYLOAD_PROTOTYPE);\n\n  Object.assign(trustedPayload, { \n    data: event.payload || null,\n    key: event.key\n  });\n  \n  window.dispatchEvent(\n    new CustomEvent(event.type, {\n      detail: trustedPayload,\n    })\n  );\n}\n","import { DECORATOR_APPLIED } from \"../consts\";\nimport { Args } from \"../models\";\n\n/**\n * Registers an instance to receive events through its @Interceptor-decorated methods.\n *\n * This function must be called inside the class constructor with `this` as the argument:\n * ```ts\n * constructor() {\n *   intercept(this);\n * }\n * ```\n *\n * Only classes decorated with `@Interceptor` can be intercepted. Calling this on an\n * undecorated class will throw an error.\n *\n * After calling this, methods specified in the `@Interceptor` decorator will receive\n * events of the corresponding type via the Event Bus.\n *\n * @template T - Type of the instance being intercepted.\n *\n * @param instance - The class instance to register for interception.\n*/\nexport function intercept<T>(instance: T): void {\n  return (function<U extends Args>(): void {\n    const unDecorated: boolean = !(DECORATOR_APPLIED in (Object.getPrototypeOf(instance)));\n\n    if(unDecorated) {\n      throw new Error('intercept() function cannot be used inside any Angular classes ' +\n                      'that are not decorated with @Interceptor decorator');\n    }\n\n    (instance as InstanceType<U>).constructor.prototype._intercept(instance);\n  })()\n}\n","/**\n * Represents a strongly-typed event in the Event Bus system.\n *\n * Each `GEvent` has a `type` (string literal recommended for type safety) and a `payload`.\n * This object is used with the Event Bus functions, ensuring\n * type-safe communication across your Angular application.\n *\n * @template T - Type of the event name. Defaults to `string`, but string literals are recommended.\n * @template P - Type of the event payload. Defaults to `null` if no payload is needed.\n*/\nexport class GEvent<T extends string, P = null> {\n  /** The type of the event */\n  readonly type: T;\n\n  /** The strongly-typed payload of the event */\n  readonly payload?: P;\n\n  /** Optional key used to scope or target the event */\n  readonly key?: string;\n\n /**\n   * Creates a new typed event instance.\n   *\n   * @param type - The event type identifier.\n   * @param payload - Optional event payload.\n   * @param key - Optional key used to target specific interceptors.\n  */\n  constructor(type: T, payload?: P, key?: string) {\n    this.type = type;\n    this.payload = payload;\n    this.key = key;\n  }\n}\n","import { Renderer2 } from \"@angular/core\";\n\nimport { Args, Event } from \"../models\";\nimport { GLOBAL_HOST, PAYLOAD_PROTOTYPE } from \"../consts\";\n\nexport function initListeners<T extends Args>(events: Event[], instance: InstanceType<T>, renderer2: Renderer2): Function[] {\n  return events.map((event: Event) => {\n    return renderer2.listen(GLOBAL_HOST, event.type, data => {\n      // Guard 1:\n      // Event Source - events originated from unknown or external sources will be rejected ❌\n      if (Object.getPrototypeOf(data.detail) !== PAYLOAD_PROTOTYPE) {\n        return;\n      }\n\n      // Guard 2:\n      // Key-based event filtering - events broadcast with a mismatched key will be rejected ❌\n      if (event.key !== data.detail.key) {\n        return;\n      }\n      \n      // Guard 3:\n      // Interceptor integrity check — ensure the configured action exists and callable, misconfiguration is treated as a hard error ❌\n      if (typeof instance[event.action] !== 'function') {\n        throw new Error(\n          `Interceptor error: \"${event.action}\" is not a function on ${instance.constructor.name}`\n        );\n      }\n      \n      // Event accepted ✅\n      // At this point, the event is verified, trusted, and correctly targeted.\n      instance[event.action](data.detail.data);\n    })\n  })\n}","import { PipeType } from \"../models\";\nimport { NG_PIPE_DEF } from \"../consts\";\n\nexport function isPipe<T>(target: T): target is T {\n  return !!(target as unknown as PipeType<T>)[NG_PIPE_DEF];\n}","import { Renderer2, RendererFactory2, ɵPipeDef, ɵɵdirectiveInject } from \"@angular/core\";\n\nimport { initListeners, isPipe } from \"../utils\";\nimport { DECORATOR_APPLIED } from \"../consts\";\nimport { Event, Args } from \"../models\";\n\n/**\n * Class decorator that registers methods to handle cross-system events.\n *\n * Use this decorator on an Angular class to specify which events it should listen to.\n * Each object in the `events` array defines an event type and the corresponding class\n * method (action) that should be called when that event is broadcast.\n *\n * After decorating the class, you must call `intercept(this)` in the constructor to\n * activate interception, otherwise the methods will not receive any events.\n *\n * @template T - Type of the class constructor being decorated.\n *\n * @param events - An array of event descriptors. Each descriptor must include:\n *   - `type`: the event type string (strongly typed recommended)\n *   - `action`: the name of the class method to execute when the event occurs\n * @returns A class constructor function with interception logic applied.\n*/\nexport function Interceptor<T extends Args>(events: Event[] = []): (orgConstructor: T) => void {  \n  return function(orgConstructor: T): void {\n    let listeners: Function[] = [];\n  \n    orgConstructor.prototype[DECORATOR_APPLIED] = true;\n    orgConstructor.prototype._intercept = function(instance: InstanceType<T>): void {\n      const rendererFactory: RendererFactory2 = ɵɵdirectiveInject(RendererFactory2);\n      const renderer2: Renderer2 = rendererFactory.createRenderer(null, null);\n\n      listeners = initListeners(\n        events, instance, renderer2);\n    }\n    \n    const onDestroy: Function = orgConstructor.prototype.ngOnDestroy;\n    orgConstructor.prototype.ngOnDestroy = function(): void {\n      listeners.map(\n        (listener: Function) => listener());\n       \n      onDestroy && onDestroy.call(this);\n    };\n\n    if(isPipe<T>(orgConstructor)) {\n      const def: ɵPipeDef<T> = orgConstructor.prototype.constructor.ɵpipe;\n      def.onDestroy = function (): void {\n        listeners.map(\n          (listener: Function) => listener());\n   \n        onDestroy && onDestroy.call(this);\n      };\n    }\n  }\n}\n","/*\n * Public API Surface of ngx-event-bus\n*/\nexport * from './lib/api';\nexport * from './lib/classes';\nexport * from './lib/decorators';","/**\n * Generated bundle index. Do not edit.\n */\n\nexport * from './public-api';\n"],"names":["ɵNG_PIPE_DEF","ɵɵdirectiveInject"],"mappings":"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"}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "on-ngx-event-bus",
+  "version": "0.0.1",
+  "author": "Orel Naten <natenorel@gmail.com>",
+  "description": "Broadcast cross-system Angular events — no services, zero DI/providers, zero RxJS/signals, zero leaks, fully typed and effortless.",
+  "keywords": [
+    "angular",
+    "event-bus",
+    "events",
+    "global-events",
+    "intercept",
+    "broadcast",
+    "typed",
+    "lightweight",
+    "angular-events"
+  ],
+  "homepage": "https://github.com/orelnatan/ngx-event-bus-lib",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/orelnatan/ngx-event-bus-lib.git"
+  },
+  "bugs": {
+    "url": "https://github.com/orelnatan/ngx-event-bus-lib/issues"
+  },
+  "license": "MIT",
+  "peerDependencies": {
+    "@angular/common": ">=9.0.0",
+    "@angular/core": ">=9.0.0"
+  },
+  "dependencies": {
+    "tslib": "^2.3.0"
+  },
+  "sideEffects": false,
+  "module": "fesm2022/on-ngx-event-bus.mjs",
+  "typings": "types/on-ngx-event-bus.d.ts",
+  "exports": {
+    "./package.json": {
+      "default": "./package.json"
+    },
+    ".": {
+      "types": "./types/on-ngx-event-bus.d.ts",
+      "default": "./fesm2022/on-ngx-event-bus.mjs"
+    }
+  }
+}

package/types/on-ngx-event-bus.d.ts

@@ -0,0 +1,118 @@
+/**
+ * Represents a strongly-typed event in the Event Bus system.
+ *
+ * Each `GEvent` has a `type` (string literal recommended for type safety) and a `payload`.
+ * This object is used with the Event Bus functions, ensuring
+ * type-safe communication across your Angular application.
+ *
+ * @template T - Type of the event name. Defaults to `string`, but string literals are recommended.
+ * @template P - Type of the event payload. Defaults to `null` if no payload is needed.
+*/
+declare class GEvent<T extends string, P = null> {
+    /** The type of the event */
+    readonly type: T;
+    /** The strongly-typed payload of the event */
+    readonly payload?: P;
+    /** Optional key used to scope or target the event */
+    readonly key?: string;
+    /**
+      * Creates a new typed event instance.
+      *
+      * @param type - The event type identifier.
+      * @param payload - Optional event payload.
+      * @param key - Optional key used to target specific interceptors.
+     */
+    constructor(type: T, payload?: P, key?: string);
+}
+
+/**
+ * Sends a global, system-wide event via the Event Bus.
+ *
+ * The event will be received by all active `@Interceptor`s that are
+ * listening for the same event type.
+ *
+ * Events may optionally include a `key`. When a key is provided,
+ * only interceptors registered with the same key will accept the
+ * event; all others will be rejected.
+ *
+ * The payload is strongly typed and may be any value:
+ * primitives, objects, arrays, etc.
+ *
+ * Internally, the payload is wrapped in a trusted object to ensure
+ * listeners only handle legitimate, system-generated events.
+ * Interceptors always access the original payload via `event.detail.data`.
+ *
+ * @template T - Type of the event name (string literal recommended for type safety).
+ * @template P - Type of the event payload.
+ *
+ * @param event - The typed event instance to broadcast.
+*/
+declare function broadcast<T extends string, P = null>(event: GEvent<T, P>): void;
+
+/**
+ * Registers an instance to receive events through its @Interceptor-decorated methods.
+ *
+ * This function must be called inside the class constructor with `this` as the argument:
+ * ```ts
+ * constructor() {
+ *   intercept(this);
+ * }
+ * ```
+ *
+ * Only classes decorated with `@Interceptor` can be intercepted. Calling this on an
+ * undecorated class will throw an error.
+ *
+ * After calling this, methods specified in the `@Interceptor` decorator will receive
+ * events of the corresponding type via the Event Bus.
+ *
+ * @template T - Type of the instance being intercepted.
+ *
+ * @param instance - The class instance to register for interception.
+*/
+declare function intercept<T>(instance: T): void;
+
+/**
+ * Describes an Event Bus mapping for a class method.
+ *
+ * Used in the `@Interceptor` decorator to specify which class method should
+ * respond to a particular event type.
+ *
+ * @property type - The event type string that this method should listen to.
+ * @property action - The name of the class method to execute when the event is intercepted.
+ * @property key - Optional event key used to scope or target events.
+*/
+interface Event {
+    /** The event type string */
+    type: string;
+    /** The class method name that handles the event */
+    action: string;
+    /** Optional key used to filter events */
+    key?: string;
+}
+
+type Args = {
+    new (...args: any[]): {
+        [key: string]: any;
+    };
+};
+
+/**
+ * Class decorator that registers methods to handle cross-system events.
+ *
+ * Use this decorator on an Angular class to specify which events it should listen to.
+ * Each object in the `events` array defines an event type and the corresponding class
+ * method (action) that should be called when that event is broadcast.
+ *
+ * After decorating the class, you must call `intercept(this)` in the constructor to
+ * activate interception, otherwise the methods will not receive any events.
+ *
+ * @template T - Type of the class constructor being decorated.
+ *
+ * @param events - An array of event descriptors. Each descriptor must include:
+ *   - `type`: the event type string (strongly typed recommended)
+ *   - `action`: the name of the class method to execute when the event occurs
+ * @returns A class constructor function with interception logic applied.
+*/
+declare function Interceptor<T extends Args>(events?: Event[]): (orgConstructor: T) => void;
+
+export { GEvent, Interceptor, broadcast, intercept };