@smounters/imperium-events 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+
+## 0.1.0 - 2026-03-30
+
+- Initial release.
+- `@OnEvent(pattern)` method decorator with wildcard support.
+- `EventModule.register({ listeners })` dynamic module.
+- `EventService` with `emit()` and `getHandlers()`.
+- Concurrent handler execution with per-handler error isolation.
+- Zero runtime dependencies.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sergio (@smounters)
+
+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,77 @@
+# @smounters/imperium-events
+
+Typed in-process event emitter for [`@smounters/imperium`](https://www.npmjs.com/package/@smounters/imperium). Decorate methods with `@OnEvent()` and emit from any service. Supports wildcard patterns.
+
+Part of the [Imperium monorepo](https://github.com/smounters/imperium).
+
+## Install
+
+```bash
+pnpm add @smounters/imperium-events
+```
+
+## Usage
+
+```ts
+import { Injectable, Module } from "@smounters/imperium/decorators";
+import { OnEvent, EventModule, EventService } from "@smounters/imperium-events";
+
+// --- Listener ---
+
+@Injectable()
+class TradeNotifier {
+  @OnEvent("trade.opened")
+  async onTradeOpened(payload: { symbol: string; price: number }) {
+    // push notification, log, update stats
+  }
+
+  @OnEvent("trade.*") // wildcard — matches trade.opened, trade.closed, etc.
+  async auditLog(payload: unknown) {
+    // write to audit log
+  }
+}
+
+// --- Emitter ---
+
+@Injectable()
+class TradingEngine {
+  constructor(private readonly events: EventService) {}
+
+  async executeTrade(symbol: string, price: number) {
+    // ... execute trade logic
+    await this.events.emit("trade.opened", { symbol, price });
+  }
+}
+
+// --- Module ---
+
+@Module({
+  imports: [EventModule.register({ listeners: [TradeNotifier] })],
+  providers: [TradingEngine],
+})
+class TradingModule {}
+```
+
+## API
+
+### `@OnEvent(pattern)`
+
+Method decorator. Registers the method as a handler for events matching the pattern.
+
+- `"trade.opened"` — exact match
+- `"trade.*"` — wildcard, matches any single segment
+
+### `EventModule.register({ listeners })`
+
+Dynamic module. Pass providers that contain `@OnEvent()` methods.
+
+### `EventService`
+
+Injectable service:
+
+- `emit(event, payload?)` — emit an event. All matching handlers run concurrently. Errors in individual handlers are caught and logged without blocking others.
+- `getHandlers()` — returns registered handlers (for introspection/testing)
+
+## License
+
+MIT

package/dist/event.decorators.d.ts

@@ -0,0 +1,14 @@
+import "reflect-metadata";
+export declare const ON_EVENT_KEY: unique symbol;
+export interface EventHandlerMeta {
+    pattern: string;
+    methodName: string;
+}
+/**
+ * Mark a method to handle events matching the given pattern.
+ *
+ * Supports exact match (`"trade.opened"`) and wildcard (`"trade.*"`).
+ *
+ * @param pattern - Event name or wildcard pattern
+ */
+export declare function OnEvent(pattern: string): MethodDecorator;

package/dist/event.decorators.js

@@ -0,0 +1,19 @@
+import "reflect-metadata";
+export const ON_EVENT_KEY = Symbol("events:handlers");
+/**
+ * Mark a method to handle events matching the given pattern.
+ *
+ * Supports exact match (`"trade.opened"`) and wildcard (`"trade.*"`).
+ *
+ * @param pattern - Event name or wildcard pattern
+ */
+export function OnEvent(pattern) {
+    return (target, propertyKey) => {
+        const existing = Reflect.getMetadata(ON_EVENT_KEY, target.constructor) ?? [];
+        existing.push({
+            pattern,
+            methodName: propertyKey,
+        });
+        Reflect.defineMetadata(ON_EVENT_KEY, existing, target.constructor);
+    };
+}

package/dist/event.module.d.ts

@@ -0,0 +1,26 @@
+import "reflect-metadata";
+import type { Constructor } from "@smounters/imperium/core";
+import type { DependencyContainer } from "tsyringe";
+import { EventService } from "./event.service.js";
+export interface EventModuleOptions {
+    /**
+     * Providers that contain @OnEvent() decorated methods.
+     * Automatically registered as DI providers and scanned for event handlers.
+     */
+    listeners: Constructor[];
+}
+export declare class EventModule {
+    static register(options: EventModuleOptions): {
+        module: typeof EventModule;
+        providers: (Constructor | {
+            provide: symbol;
+            useValue: Constructor[];
+            useFactory?: undefined;
+        } | {
+            provide: string;
+            useFactory: (container: DependencyContainer) => DependencyContainer;
+            useValue?: undefined;
+        })[];
+        exports: (typeof EventService)[];
+    };
+}

package/dist/event.module.js

@@ -0,0 +1,59 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+var EventModule_1;
+import "reflect-metadata";
+import { Module, Injectable, Inject } from "@smounters/imperium/decorators";
+import { EventService } from "./event.service.js";
+const EVENT_LISTENERS_TOKEN = Symbol("events:listeners");
+let EventBootstrap = class EventBootstrap {
+    constructor(eventService, listeners, container) {
+        this.eventService = eventService;
+        this.listeners = listeners;
+        this.container = container;
+    }
+    onModuleInit() {
+        for (const listener of this.listeners) {
+            const instance = this.container.resolve(listener);
+            this.eventService.registerListener(instance, listener.name);
+        }
+    }
+};
+EventBootstrap = __decorate([
+    Injectable(),
+    __param(1, Inject(EVENT_LISTENERS_TOKEN)),
+    __param(2, Inject("events:container")),
+    __metadata("design:paramtypes", [EventService, Array, Object])
+], EventBootstrap);
+let EventModule = EventModule_1 = class EventModule {
+    static register(options) {
+        const eventListeners = options.listeners.filter((l) => EventService.hasEventHandlers(l));
+        return {
+            module: EventModule_1,
+            providers: [
+                EventService,
+                EventBootstrap,
+                ...eventListeners,
+                { provide: EVENT_LISTENERS_TOKEN, useValue: eventListeners },
+                {
+                    provide: "events:container",
+                    useFactory: (container) => container,
+                },
+            ],
+            exports: [EventService],
+        };
+    }
+};
+EventModule = EventModule_1 = __decorate([
+    Module({})
+], EventModule);
+export { EventModule };

package/dist/event.service.d.ts

@@ -0,0 +1,31 @@
+import "reflect-metadata";
+export declare class EventService {
+    private readonly handlers;
+    private logger;
+    setLogger(logger: {
+        error: (...args: unknown[]) => void;
+    }): void;
+    /**
+     * Register an event listener instance. Scans @OnEvent() metadata
+     * and binds methods as handlers.
+     */
+    registerListener(instance: object, listenerName: string): void;
+    /**
+     * Check if a class has any @OnEvent() decorated methods.
+     */
+    static hasEventHandlers(target: Function): boolean;
+    /**
+     * Emit an event. All matching handlers are called concurrently.
+     * Errors in individual handlers are caught and logged — they don't
+     * block other handlers or the caller.
+     */
+    emit(event: string, payload?: unknown): Promise<void>;
+    /**
+     * Get all registered handlers (for introspection/testing).
+     */
+    getHandlers(): readonly {
+        pattern: string;
+        listenerName: string;
+        methodName: string;
+    }[];
+}

package/dist/event.service.js

@@ -0,0 +1,87 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+import "reflect-metadata";
+import { injectable } from "tsyringe";
+import { ON_EVENT_KEY } from "./event.decorators.js";
+function patternToRegex(pattern) {
+    const escaped = pattern
+        .replace(/[.+^${}()|[\]\\]/g, "\\$&")
+        .replace(/\*/g, "[^.]+");
+    return new RegExp(`^${escaped}$`);
+}
+let EventService = class EventService {
+    constructor() {
+        this.handlers = [];
+        this.logger = console;
+    }
+    setLogger(logger) {
+        this.logger = logger;
+    }
+    /**
+     * Register an event listener instance. Scans @OnEvent() metadata
+     * and binds methods as handlers.
+     */
+    registerListener(instance, listenerName) {
+        const constructor = instance.constructor;
+        const metas = Reflect.getMetadata(ON_EVENT_KEY, constructor) ?? [];
+        for (const meta of metas) {
+            const method = instance[meta.methodName];
+            if (typeof method !== "function") {
+                throw new Error(`@OnEvent() target ${listenerName}.${meta.methodName} is not a function`);
+            }
+            this.handlers.push({
+                pattern: meta.pattern,
+                regex: patternToRegex(meta.pattern),
+                callback: method.bind(instance),
+                listenerName,
+                methodName: meta.methodName,
+            });
+        }
+    }
+    /**
+     * Check if a class has any @OnEvent() decorated methods.
+     */
+    static hasEventHandlers(target) {
+        const metas = Reflect.getMetadata(ON_EVENT_KEY, target);
+        return (metas?.length ?? 0) > 0;
+    }
+    /**
+     * Emit an event. All matching handlers are called concurrently.
+     * Errors in individual handlers are caught and logged — they don't
+     * block other handlers or the caller.
+     */
+    async emit(event, payload) {
+        const matching = this.handlers.filter((h) => h.regex.test(event));
+        if (matching.length === 0) {
+            return;
+        }
+        const promises = matching.map(async (h) => h.callback(payload));
+        const results = await Promise.allSettled(promises);
+        for (let i = 0; i < results.length; i++) {
+            const result = results[i];
+            const handler = matching[i];
+            if (result?.status === "rejected" && handler) {
+                this.logger.error(`[imperium-events] Handler ${handler.listenerName}.${handler.methodName} ` +
+                    `failed for event "${event}":`, result.reason);
+            }
+        }
+    }
+    /**
+     * Get all registered handlers (for introspection/testing).
+     */
+    getHandlers() {
+        return this.handlers.map((h) => ({
+            pattern: h.pattern,
+            listenerName: h.listenerName,
+            methodName: h.methodName,
+        }));
+    }
+};
+EventService = __decorate([
+    injectable()
+], EventService);
+export { EventService };

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { OnEvent } from "./event.decorators.js";
+export type { EventHandlerMeta } from "./event.decorators.js";
+export { EventService } from "./event.service.js";
+export { EventModule } from "./event.module.js";
+export type { EventModuleOptions } from "./event.module.js";

package/dist/index.js

@@ -0,0 +1,3 @@
+export { OnEvent } from "./event.decorators.js";
+export { EventService } from "./event.service.js";
+export { EventModule } from "./event.module.js";

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@smounters/imperium-events",
+  "version": "0.1.0",
+  "description": "Typed event emitter for @smounters/imperium",
+  "keywords": [
+    "events",
+    "event-emitter",
+    "imperium",
+    "nestjs-like",
+    "typescript"
+  ],
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/smounters/imperium.git",
+    "directory": "packages/imperium-events"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "peerDependencies": {
+    "@smounters/imperium": "^1.1.0",
+    "reflect-metadata": "^0.2.2",
+    "tsyringe": "^4.10.0"
+  },
+  "devDependencies": {
+    "@smounters/imperium": "1.1.2"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "lint": "eslint \"src/**/*.ts\"",
+    "lint:fix": "eslint \"src/**/*.ts\" --fix",
+    "test": "vitest run",
+    "clean": "rm -rf dist"
+  }
+}