@wild-framework/events 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Wild Framework contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,29 @@
+# @wild-framework/events
+
+Typed event bus for [Wild Framework](https://github.com/your-org/wild-framework).
+
+## Install
+
+```bash
+pnpm add @wild-framework/events
+```
+
+## Usage
+
+```ts
+import { EventBus } from "@wild-framework/events";
+
+class UserRegistered {
+    constructor(public readonly user: User) {}
+}
+
+events.listen(UserRegistered, async (event) => {
+    await mail.send(event.user.email);
+});
+
+await events.dispatch(new UserRegistered(user));
+```
+
+## License
+
+MIT

package/dist/bus.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Any class constructor. Events are identified by their constructor.
+ */
+type EventConstructor<T = unknown> = abstract new (...args: any[]) => T;
+/**
+ * A listener function that receives a typed event instance.
+ */
+type Listener<T> = (event: T) => void | Promise<void>;
+/**
+ * Typed event bus.
+ *
+ * Events are classes (past tense per NAMING.md). Listeners are registered
+ * by event constructor and receive fully typed event instances.
+ *
+ * On dispatch, all matching listeners are called. If any listener throws,
+ * the errors are collected and thrown as an `EventDispatchError`.
+ */
+export declare class EventBus {
+    private listeners;
+    /**
+     * Register a listener for an event class.
+     *
+     * The listener receives a typed event instance.
+     *
+     * @example
+     * events.listen(UserRegistered, async (event) => {
+     *     // event is UserRegistered
+     * });
+     */
+    listen<T>(eventClass: EventConstructor<T>, listener: Listener<T>): void;
+    /**
+     * Remove a previously registered listener.
+     */
+    remove<T>(eventClass: EventConstructor<T>, listener: Listener<T>): void;
+    /**
+     * Dispatch an event to all registered listeners.
+     *
+     * Listeners are called in registration order. If any listener throws,
+     * errors are collected and thrown as `EventDispatchError` after all
+     * listeners have been called.
+     */
+    dispatch<T extends object>(event: T): Promise<void>;
+    /**
+     * Check whether any listeners are registered for an event class.
+     */
+    has<T>(eventClass: EventConstructor<T>): boolean;
+}
+export {};
+//# sourceMappingURL=bus.d.ts.map

package/dist/bus.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bus.d.ts","sourceRoot":"","sources":["../src/bus.ts"],"names":[],"mappings":"AAEA;;GAEG;AACH,KAAK,gBAAgB,CAAC,CAAC,GAAG,OAAO,IAAI,QAAQ,MAAM,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,CAAC,CAAC;AAExE;;GAEG;AACH,KAAK,QAAQ,CAAC,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;AAEtD;;;;;;;;GAQG;AACH,qBAAa,QAAQ;IACjB,OAAO,CAAC,SAAS,CAAmD;IAMpE;;;;;;;;;OASG;IACH,MAAM,CAAC,CAAC,EAAE,UAAU,EAAE,gBAAgB,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,QAAQ,CAAC,CAAC,CAAC,GAAG,IAAI;IASvE;;OAEG;IACH,MAAM,CAAC,CAAC,EAAE,UAAU,EAAE,gBAAgB,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,QAAQ,CAAC,CAAC,CAAC,GAAG,IAAI;IAQvE;;;;;;OAMG;IACG,QAAQ,CAAC,CAAC,SAAS,MAAM,EAAE,KAAK,EAAE,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IA0BzD;;OAEG;IACH,GAAG,CAAC,CAAC,EAAE,UAAU,EAAE,gBAAgB,CAAC,CAAC,CAAC,GAAG,OAAO;CAInD"}

package/dist/bus.js

@@ -0,0 +1,80 @@
+import { EventDispatchError } from "./errors.js";
+/**
+ * Typed event bus.
+ *
+ * Events are classes (past tense per NAMING.md). Listeners are registered
+ * by event constructor and receive fully typed event instances.
+ *
+ * On dispatch, all matching listeners are called. If any listener throws,
+ * the errors are collected and thrown as an `EventDispatchError`.
+ */
+export class EventBus {
+    listeners = new Map();
+    // -------------------------------------------------------------------
+    // Registration
+    // -------------------------------------------------------------------
+    /**
+     * Register a listener for an event class.
+     *
+     * The listener receives a typed event instance.
+     *
+     * @example
+     * events.listen(UserRegistered, async (event) => {
+     *     // event is UserRegistered
+     * });
+     */
+    listen(eventClass, listener) {
+        let set = this.listeners.get(eventClass);
+        if (!set) {
+            set = new Set();
+            this.listeners.set(eventClass, set);
+        }
+        set.add(listener);
+    }
+    /**
+     * Remove a previously registered listener.
+     */
+    remove(eventClass, listener) {
+        this.listeners.get(eventClass)?.delete(listener);
+    }
+    // -------------------------------------------------------------------
+    // Dispatch
+    // -------------------------------------------------------------------
+    /**
+     * Dispatch an event to all registered listeners.
+     *
+     * Listeners are called in registration order. If any listener throws,
+     * errors are collected and thrown as `EventDispatchError` after all
+     * listeners have been called.
+     */
+    async dispatch(event) {
+        const eventClass = event.constructor;
+        const listeners = this.listeners.get(eventClass);
+        if (!listeners || listeners.size === 0) {
+            return;
+        }
+        const failures = [];
+        for (const listener of listeners) {
+            try {
+                await listener(event);
+            }
+            catch (error) {
+                failures.push({
+                    listener: listener.name || "anonymous",
+                    error: error instanceof Error ? error : new Error(String(error)),
+                });
+            }
+        }
+        if (failures.length > 0) {
+            throw new EventDispatchError(failures);
+        }
+    }
+    /**
+     * Check whether any listeners are registered for an event class.
+     */
+    has(eventClass) {
+        const set = this.listeners.get(eventClass);
+        return (set?.size ?? 0) > 0;
+    }
+}
+//# sourceMappingURL=bus.js.map

package/dist/bus.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bus.js","sourceRoot":"","sources":["../src/bus.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAYjD;;;;;;;;GAQG;AACH,MAAM,OAAO,QAAQ;IACT,SAAS,GAAG,IAAI,GAAG,EAAwC,CAAC;IAEpE,sEAAsE;IACtE,eAAe;IACf,sEAAsE;IAEtE;;;;;;;;;OASG;IACH,MAAM,CAAI,UAA+B,EAAE,QAAqB;QAC5D,IAAI,GAAG,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;QACzC,IAAI,CAAC,GAAG,EAAE,CAAC;YACP,GAAG,GAAG,IAAI,GAAG,EAAE,CAAC;YAChB,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,UAAU,EAAE,GAAG,CAAC,CAAC;QACxC,CAAC;QACD,GAAG,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IACtB,CAAC;IAED;;OAEG;IACH,MAAM,CAAI,UAA+B,EAAE,QAAqB;QAC5D,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC,QAAQ,CAAC,CAAC;IACrD,CAAC;IAED,sEAAsE;IACtE,WAAW;IACX,sEAAsE;IAEtE;;;;;;OAMG;IACH,KAAK,CAAC,QAAQ,CAAmB,KAAQ;QACrC,MAAM,UAAU,GAAG,KAAK,CAAC,WAAkC,CAAC;QAC5D,MAAM,SAAS,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;QAEjD,IAAI,CAAC,SAAS,IAAI,SAAS,CAAC,IAAI,KAAK,CAAC,EAAE,CAAC;YACrC,OAAO;QACX,CAAC;QAED,MAAM,QAAQ,GAA8C,EAAE,CAAC;QAE/D,KAAK,MAAM,QAAQ,IAAI,SAAS,EAAE,CAAC;YAC/B,IAAI,CAAC;gBACD,MAAM,QAAQ,CAAC,KAAK,CAAC,CAAC;YAC1B,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACb,QAAQ,CAAC,IAAI,CAAC;oBACV,QAAQ,EAAE,QAAQ,CAAC,IAAI,IAAI,WAAW;oBACtC,KAAK,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;iBACnE,CAAC,CAAC;YACP,CAAC;QACL,CAAC;QAED,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACtB,MAAM,IAAI,kBAAkB,CAAC,QAAQ,CAAC,CAAC;QAC3C,CAAC;IACL,CAAC;IAED;;OAEG;IACH,GAAG,CAAI,UAA+B;QAClC,MAAM,GAAG,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;QAC3C,OAAO,CAAC,GAAG,EAAE,IAAI,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC;IAChC,CAAC;CACJ"}

package/dist/errors.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Thrown when one or more listeners fail during event dispatch.
+ *
+ * Each error includes the listener that failed and the original error.
+ */
+export declare class EventDispatchError extends Error {
+    readonly failures: Array<{
+        listener: string;
+        error: Error;
+    }>;
+    constructor(failures: Array<{
+        listener: string;
+        error: Error;
+    }>);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,qBAAa,kBAAmB,SAAQ,KAAK;IACzC,SAAgB,QAAQ,EAAE,KAAK,CAAC;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,KAAK,CAAA;KAAE,CAAC,CAAC;gBAExD,QAAQ,EAAE,KAAK,CAAC;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,KAAK,CAAA;KAAE,CAAC;CAMlE"}

package/dist/errors.js

@@ -0,0 +1,15 @@
+/**
+ * Thrown when one or more listeners fail during event dispatch.
+ *
+ * Each error includes the listener that failed and the original error.
+ */
+export class EventDispatchError extends Error {
+    failures;
+    constructor(failures) {
+        const names = failures.map((f) => f.listener).join(", ");
+        super(`Event dispatch failed for listener(s): ${names}`);
+        this.name = "EventDispatchError";
+        this.failures = failures;
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,OAAO,kBAAmB,SAAQ,KAAK;IACzB,QAAQ,CAA4C;IAEpE,YAAY,QAAmD;QAC3D,MAAM,KAAK,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACzD,KAAK,CAAC,0CAA0C,KAAK,EAAE,CAAC,CAAC;QACzD,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAC;QACjC,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;IAC7B,CAAC;CACJ"}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { EventBus } from "./bus.js";
+export { EventProvider } from "./provider.js";
+export { EventDispatchError } from "./errors.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AACpC,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAC9C,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC"}

package/dist/index.js

@@ -0,0 +1,4 @@
+export { EventBus } from "./bus.js";
+export { EventProvider } from "./provider.js";
+export { EventDispatchError } from "./errors.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AACpC,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAC9C,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC"}

package/dist/provider.d.ts

@@ -0,0 +1,11 @@
+import type { Provider, Application } from "@wild-framework/core";
+/**
+ * Registers the event bus with the application.
+ *
+ * Must be registered after `ContainerProvider`.
+ * Other providers resolve `EventBus` from the container and register listeners.
+ */
+export declare class EventProvider implements Provider {
+    register(app: Application): void;
+}
+//# sourceMappingURL=provider.d.ts.map

package/dist/provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAIlE;;;;;GAKG;AACH,qBAAa,aAAc,YAAW,QAAQ;IAC1C,QAAQ,CAAC,GAAG,EAAE,WAAW,GAAG,IAAI;CAKnC"}

package/dist/provider.js

@@ -0,0 +1,16 @@
+import { Container } from "@wild-framework/container";
+import { EventBus } from "./bus.js";
+/**
+ * Registers the event bus with the application.
+ *
+ * Must be registered after `ContainerProvider`.
+ * Other providers resolve `EventBus` from the container and register listeners.
+ */
+export class EventProvider {
+    register(app) {
+        const container = app.resolve(Container);
+        const bus = new EventBus();
+        container.singleton(EventBus, () => bus);
+    }
+}
+//# sourceMappingURL=provider.js.map

package/dist/provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.js","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAC;AACtD,OAAO,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AAEpC;;;;;GAKG;AACH,MAAM,OAAO,aAAa;IACtB,QAAQ,CAAC,GAAgB;QACrB,MAAM,SAAS,GAAG,GAAG,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;QACzC,MAAM,GAAG,GAAG,IAAI,QAAQ,EAAE,CAAC;QAC3B,SAAS,CAAC,SAAS,CAAC,QAAQ,EAAE,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC;IAC7C,CAAC;CACJ"}

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@wild-framework/events",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT",
+  "author": "Sphah",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/KhandaSoftware/wild-framework.git"
+  },
+  "description": "Typed event bus for Wild Framework.",
+  "keywords": [
+    "wild",
+    "framework",
+    "events",
+    "event-bus",
+    "listeners"
+  ],
+  "dependencies": {
+    "@wild-framework/core": "0.1.0",
+    "@wild-framework/container": "0.1.0"
+  },
+  "scripts": {
+    "build": "tsc",
+    "clean": "rm -rf dist",
+    "test": "vitest run"
+  }
+}