@blixis-io/events 0.0.0 → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Michael Voeten
+
+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

@@ -1 +1,33 @@
-placeholder
+# `@blixis-io/events`
+
+An in-process domain event bus (`defineEventsModule`, `EventBus.emit`/`on`). Depends only on `@blixis-io/core` — usable in any app, HTTP or not.
+
+```bash
+npm install @blixis-io/events @blixis-io/core @blixis-io/di
+```
+
+```ts
+// events.ts
+type AppEvents = {
+  "post.created": { postId: string; title: string };
+};
+
+export const { EventsModule, EVENT_BUS } = defineEventsModule<AppEvents>();
+```
+
+```ts
+@Injectable()
+class PostsService {
+  constructor(@Inject(EVENT_BUS) private readonly events: EventBus<AppEvents>) {}
+
+  async create(input: CreatePostInput) {
+    const post = await this.repo.insert(input);
+    await this.events.emit("post.created", { postId: post.id, title: post.title });
+    return post;
+  }
+}
+```
+
+Runs every handler for an event concurrently, in-process — no persistence, no delivery guarantee across a crash. Deliberately the only implementation for now; see the docs for why a transactional outbox was deferred rather than built ahead of a real need.
+
+Part of [Blixis Framework](https://github.com/blixis-io/framework) — full docs: [Events](https://blixis-io.github.io/framework/concepts/events/) · [API reference](https://blixis-io.github.io/framework/reference/blixis-events/).

package/dist/index.d.ts

@@ -0,0 +1,34 @@
+import { DynamicModule } from "@blixis-io/core";
+import { InjectionToken } from "@blixis-io/di";
+//#region src/module.d.ts
+type EventHandler<Payload> = (payload: Payload) => void | Promise<void>;
+interface EventBus<Events extends Record<string, unknown>> {
+  emit<K extends keyof Events & string>(type: K, payload: Events[K]): Promise<void>;
+  /** Registers `handler` for `type`, returning a function that unsubscribes just this handler. */
+  on<K extends keyof Events & string>(type: K, handler: EventHandler<Events[K]>): () => void;
+}
+interface EventsForRootOptions {
+  /** Makes `EVENT_BUS` visible to every module without each one importing this one directly. Defaults to `false`. */
+  global?: boolean;
+}
+/**
+ * Builds an `EVENT_BUS` token typed to one app's event map. Same
+ * factory-closure shape as `defineConfigModule`/`defineAuthModule` — the
+ * event-name-to-payload map is app-specific, so it's a generic parameter
+ * fixed once per app, not baked into the package.
+ */
+export declare function defineEventsModule<Events extends Record<string, unknown>>(): {
+  EventsModule: {
+    forRoot(options?: EventsForRootOptions): DynamicModule;
+  };
+  EVENT_BUS: InjectionToken<EventBus<Events>>;
+  /**
+   * Subscribes the decorated method to `type`. The compiler checks the method accepts that event's
+   * payload. Works on any singleton provider (or controller) in the application; the handlers are
+   * attached once the app has booted, so an event emitted from `onModuleInit` is not seen yet.
+   */
+  OnEvent: <K extends keyof Events & string>(type: K) => <T extends (payload: Events[K]) => void | Promise<void>>(target: object, method: string | symbol, descriptor: TypedPropertyDescriptor<T>) => void;
+};
+//#endregion
+export type { EventBus, EventHandler, EventsForRootOptions };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/module.ts"],"mappings":";;;KASY,aAAa,YAAY,SAAS,mBAAmB;UAEhD,SAAS,eAAe;EACvC,KAAK,gBAAgB,iBAAiB,MAAM,GAAG,SAAS,OAAO,KAAK;;EAEpE,GAAG,gBAAgB,iBAAiB,MAAM,GAAG,SAAS,aAAa,OAAO;;UAG3D;;EAEf;;;;;;;;wBA4Dc,mBAAmB,eAAe;EAChD;IAAgB,QAAQ,UAAU,uBAAuB;;EACzD,WAAW,eAAe,SAAS;;;;;;EAMnC,UAAU,gBAAgB,iBACxB,MAAM,OACF,WAAW,SAAS,OAAO,cAAc,eAC7C,gBACA,yBACA,YAAY,wBAAwB"}

package/dist/index.js

@@ -0,0 +1,127 @@
+import { Module } from "@blixis-io/core";
+import { Inject, Injectable, InjectionToken, defineMetadata, getOwnMetadata } from "@blixis-io/di";
+//#region \0@oxc-project+runtime@0.151.0/helpers/esm/decorate.js
+function __decorate(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;
+}
+//#endregion
+//#region \0@oxc-project+runtime@0.151.0/helpers/esm/decorateMetadata.js
+function __decorateMetadata(k, v) {
+	if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+}
+//#endregion
+//#region \0@oxc-project+runtime@0.151.0/helpers/esm/decorateParam.js
+function __decorateParam(paramIndex, decorator) {
+	return function(target, key) {
+		decorator(target, key, paramIndex);
+	};
+}
+//#endregion
+//#region src/module.ts
+/**
+* Runs every handler for an event concurrently and in-process — no
+* persistence, no delivery guarantee across a crash. Deliberately the only
+* implementation for now; see `concepts/events.md` for why a transactional
+* outbox was deferred rather than built ahead of a real consumer.
+*/
+let InProcessEventBus = class InProcessEventBus {
+	#handlers = /* @__PURE__ */ new Map();
+	on(type, handler) {
+		let handlers = this.#handlers.get(type);
+		if (!handlers) {
+			handlers = /* @__PURE__ */ new Set();
+			this.#handlers.set(type, handlers);
+		}
+		handlers.add(handler);
+		return () => handlers.delete(handler);
+	}
+	async emit(type, payload) {
+		const handlers = this.#handlers.get(type);
+		if (!handlers || handlers.size === 0) return;
+		await Promise.all([...handlers].map(async (handler) => {
+			try {
+				await handler(payload);
+			} catch (error) {
+				console.error(`event handler for "${type}" failed:`, error);
+			}
+		}));
+	}
+};
+InProcessEventBus = __decorate([Injectable()], InProcessEventBus);
+/**
+* Builds an `EVENT_BUS` token typed to one app's event map. Same
+* factory-closure shape as `defineConfigModule`/`defineAuthModule` — the
+* event-name-to-payload map is app-specific, so it's a generic parameter
+* fixed once per app, not baked into the package.
+*/
+function defineEventsModule() {
+	var _EventsModule;
+	const EVENT_BUS = new InjectionToken("blixis.events.bus");
+	const HANDLERS = Symbol("blixis.events.handlers");
+	function OnEvent(type) {
+		return (target, method, _descriptor) => {
+			const own = getOwnMetadata(HANDLERS, target) ?? [];
+			defineMetadata(HANDLERS, [...own, {
+				type,
+				method
+			}], target);
+		};
+	}
+	/** Every `@OnEvent` handler declared on `instance`'s class or any of its base classes. */
+	function handlersOf(instance) {
+		const records = [];
+		for (let proto = Object.getPrototypeOf(instance); typeof proto === "object" && proto !== null; proto = Object.getPrototypeOf(proto)) records.push(...getOwnMetadata(HANDLERS, proto) ?? []);
+		return records;
+	}
+	/** Finds the `@OnEvent` methods across the whole application after boot and subscribes them. */
+	let EventSubscriber = class EventSubscriber {
+		#unsubscribe = [];
+		constructor(bus) {
+			this.bus = bus;
+		}
+		onApplicationBootstrap(app) {
+			for (const [, instance] of app.resolved()) {
+				if (typeof instance !== "object" || instance === null) continue;
+				for (const { type, method } of handlersOf(instance)) {
+					const handle = Reflect.get(instance, method);
+					if (typeof handle !== "function") throw new TypeError(`${instance.constructor.name}.${String(method)} is decorated with @OnEvent("${type}") but is not a method.`);
+					this.#unsubscribe.push(this.bus.on(type, (payload) => Reflect.apply(handle, instance, [payload])));
+				}
+			}
+		}
+		onApplicationShutdown() {
+			for (const off of this.#unsubscribe.splice(0)) off();
+		}
+	};
+	EventSubscriber = __decorate([
+		Injectable(),
+		__decorateParam(0, Inject(EVENT_BUS)),
+		__decorateMetadata("design:paramtypes", [Object])
+	], EventSubscriber);
+	let EventsModule = _EventsModule = class EventsModule {
+		static forRoot(options = {}) {
+			return {
+				module: _EventsModule,
+				providers: [{
+					provide: EVENT_BUS,
+					useClass: InProcessEventBus
+				}, EventSubscriber],
+				exports: [EVENT_BUS],
+				global: options.global ?? false
+			};
+		}
+	};
+	EventsModule = _EventsModule = __decorate([Module()], EventsModule);
+	return {
+		EventsModule,
+		EVENT_BUS,
+		OnEvent
+	};
+}
+//#endregion
+export { defineEventsModule };
+
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../src/module.ts"],"sourcesContent":["import {\n  Module,\n  type BootstrapContext,\n  type DynamicModule,\n  type OnApplicationBootstrap,\n  type OnApplicationShutdown,\n} from \"@blixis-io/core\";\nimport { defineMetadata, getOwnMetadata, Inject, Injectable, InjectionToken } from \"@blixis-io/di\";\n\nexport type EventHandler<Payload> = (payload: Payload) => void | Promise<void>;\n\nexport interface EventBus<Events extends Record<string, unknown>> {\n  emit<K extends keyof Events & string>(type: K, payload: Events[K]): Promise<void>;\n  /** Registers `handler` for `type`, returning a function that unsubscribes just this handler. */\n  on<K extends keyof Events & string>(type: K, handler: EventHandler<Events[K]>): () => void;\n}\n\nexport interface EventsForRootOptions {\n  /** Makes `EVENT_BUS` visible to every module without each one importing this one directly. Defaults to `false`. */\n  global?: boolean;\n}\n\n/**\n * Runs every handler for an event concurrently and in-process — no\n * persistence, no delivery guarantee across a crash. Deliberately the only\n * implementation for now; see `concepts/events.md` for why a transactional\n * outbox was deferred rather than built ahead of a real consumer.\n */\n@Injectable()\nclass InProcessEventBus<Events extends Record<string, unknown>> implements EventBus<Events> {\n  readonly #handlers = new Map<string, Set<EventHandler<never>>>();\n\n  on<K extends keyof Events & string>(type: K, handler: EventHandler<Events[K]>): () => void {\n    let handlers = this.#handlers.get(type);\n    if (!handlers) {\n      handlers = new Set();\n      this.#handlers.set(type, handlers);\n    }\n    handlers.add(handler);\n    return () => handlers.delete(handler);\n  }\n\n  async emit<K extends keyof Events & string>(type: K, payload: Events[K]): Promise<void> {\n    const handlers = this.#handlers.get(type);\n    if (!handlers || handlers.size === 0) {\n      return;\n    }\n\n    await Promise.all(\n      [...handlers].map(async (handler) => {\n        try {\n          // Handlers for every event type share one Set<EventHandler<never>>\n          // collection (indexed by the string `type`, not a type-level key),\n          // so there's no way for TS to correlate a specific handler back to\n          // the K it was registered with — this cast is the one place that\n          // trusts `type` actually matches, same as `on()`'s own erasure.\n          await handler(payload as never);\n        } catch (error) {\n          // A handler's own failure never blocks sibling handlers or the\n          // caller — same self-contained fallback @blixis-io/logging's own\n          // transport-failure handling already uses.\n          console.error(`event handler for \"${type}\" failed:`, error);\n        }\n      }),\n    );\n  }\n}\n\ninterface HandlerRecord {\n  type: string;\n  method: string | symbol;\n}\n\n/**\n * Builds an `EVENT_BUS` token typed to one app's event map. Same\n * factory-closure shape as `defineConfigModule`/`defineAuthModule` — the\n * event-name-to-payload map is app-specific, so it's a generic parameter\n * fixed once per app, not baked into the package.\n */\nexport function defineEventsModule<Events extends Record<string, unknown>>(): {\n  EventsModule: { forRoot(options?: EventsForRootOptions): DynamicModule };\n  EVENT_BUS: InjectionToken<EventBus<Events>>;\n  /**\n   * Subscribes the decorated method to `type`. The compiler checks the method accepts that event's\n   * payload. Works on any singleton provider (or controller) in the application; the handlers are\n   * attached once the app has booted, so an event emitted from `onModuleInit` is not seen yet.\n   */\n  OnEvent: <K extends keyof Events & string>(\n    type: K,\n  ) => <T extends (payload: Events[K]) => void | Promise<void>>(\n    target: object,\n    method: string | symbol,\n    descriptor: TypedPropertyDescriptor<T>,\n  ) => void;\n} {\n  const EVENT_BUS = new InjectionToken<EventBus<Events>>(\"blixis.events.bus\");\n  // One metadata key per factory, so two event maps in one app never pick up each other's handlers.\n  const HANDLERS = Symbol(\"blixis.events.handlers\");\n\n  function OnEvent<K extends keyof Events & string>(type: K) {\n    return <T extends (payload: Events[K]) => void | Promise<void>>(\n      target: object,\n      method: string | symbol,\n      _descriptor: TypedPropertyDescriptor<T>,\n    ): void => {\n      const own = getOwnMetadata<HandlerRecord[]>(HANDLERS, target) ?? [];\n      defineMetadata(HANDLERS, [...own, { type, method }], target);\n    };\n  }\n\n  /** Every `@OnEvent` handler declared on `instance`'s class or any of its base classes. */\n  function handlersOf(instance: object): HandlerRecord[] {\n    const records: HandlerRecord[] = [];\n    for (let proto: unknown = Object.getPrototypeOf(instance); typeof proto === \"object\" && proto !== null; proto = Object.getPrototypeOf(proto)) {\n      records.push(...(getOwnMetadata<HandlerRecord[]>(HANDLERS, proto) ?? []));\n    }\n    return records;\n  }\n\n  /** Finds the `@OnEvent` methods across the whole application after boot and subscribes them. */\n  @Injectable()\n  class EventSubscriber implements OnApplicationBootstrap, OnApplicationShutdown {\n    readonly #unsubscribe: (() => void)[] = [];\n\n    constructor(@Inject(EVENT_BUS) private readonly bus: EventBus<Events>) {}\n\n    onApplicationBootstrap(app: BootstrapContext): void {\n      for (const [, instance] of app.resolved()) {\n        if (typeof instance !== \"object\" || instance === null) {\n          continue;\n        }\n        for (const { type, method } of handlersOf(instance)) {\n          const handle: unknown = Reflect.get(instance, method);\n          if (typeof handle !== \"function\") {\n            throw new TypeError(`${instance.constructor.name}.${String(method)} is decorated with @OnEvent(\"${type}\") but is not a method.`);\n          }\n          this.#unsubscribe.push(this.bus.on(type, (payload) => Reflect.apply(handle, instance, [payload]) as void | Promise<void>));\n        }\n      }\n    }\n\n    onApplicationShutdown(): void {\n      for (const off of this.#unsubscribe.splice(0)) {\n        off();\n      }\n    }\n  }\n\n  @Module()\n  class EventsModule {\n    static forRoot(options: EventsForRootOptions = {}): DynamicModule {\n      return {\n        module: EventsModule,\n        providers: [{ provide: EVENT_BUS, useClass: InProcessEventBus }, EventSubscriber],\n        exports: [EVENT_BUS],\n        global: options.global ?? false,\n      };\n    }\n  }\n\n  return { EventsModule, EVENT_BUS, OnEvent };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA4BA,IACM,oBADN,MACM,kBAAsF;CAC1F,4BAAqB,IAAI,IAAsC;CAE/D,GAAoC,MAAS,SAA8C;EACzF,IAAI,WAAW,KAAK,UAAU,IAAI,IAAI;EACtC,IAAI,CAAC,UAAU;GACb,2BAAW,IAAI,IAAI;GACnB,KAAK,UAAU,IAAI,MAAM,QAAQ;EACnC;EACA,SAAS,IAAI,OAAO;EACpB,aAAa,SAAS,OAAO,OAAO;CACtC;CAEA,MAAM,KAAsC,MAAS,SAAmC;EACtF,MAAM,WAAW,KAAK,UAAU,IAAI,IAAI;EACxC,IAAI,CAAC,YAAY,SAAS,SAAS,GACjC;EAGF,MAAM,QAAQ,IACZ,CAAC,GAAG,QAAQ,CAAC,CAAC,IAAI,OAAO,YAAY;GACnC,IAAI;IAMF,MAAM,QAAQ,OAAgB;GAChC,SAAS,OAAO;IAId,QAAQ,MAAM,sBAAsB,KAAK,YAAY,KAAK;GAC5D;EACF,CAAC,CACH;CACF;AACF;AAtCC,oBAAA,WAAA,CAAA,WAAW,CAAA,GAAA,iBAAA;;;;;;;AAmDZ,SAAgB,qBAed;;CACA,MAAM,YAAY,IAAI,eAAiC,mBAAmB;CAE1E,MAAM,WAAW,OAAO,wBAAwB;CAEhD,SAAS,QAAyC,MAAS;EACzD,QACE,QACA,QACA,gBACS;GACT,MAAM,MAAM,eAAgC,UAAU,MAAM,KAAK,CAAC;GAClE,eAAe,UAAU,CAAC,GAAG,KAAK;IAAE;IAAM;GAAO,CAAC,GAAG,MAAM;EAC7D;CACF;;CAGA,SAAS,WAAW,UAAmC;EACrD,MAAM,UAA2B,CAAC;EAClC,KAAK,IAAI,QAAiB,OAAO,eAAe,QAAQ,GAAG,OAAO,UAAU,YAAY,UAAU,MAAM,QAAQ,OAAO,eAAe,KAAK,GACzI,QAAQ,KAAK,GAAI,eAAgC,UAAU,KAAK,KAAK,CAAC,CAAE;EAE1E,OAAO;CACT;;CAGA,IACM,kBADN,MACM,gBAAyE;EAC7E,eAAwC,CAAC;EAEzC,YAAY,KAA2D;GAAvB,KAAA,MAAA;EAAwB;EAExE,uBAAuB,KAA6B;GAClD,KAAK,MAAM,GAAG,aAAa,IAAI,SAAS,GAAG;IACzC,IAAI,OAAO,aAAa,YAAY,aAAa,MAC/C;IAEF,KAAK,MAAM,EAAE,MAAM,YAAY,WAAW,QAAQ,GAAG;KACnD,MAAM,SAAkB,QAAQ,IAAI,UAAU,MAAM;KACpD,IAAI,OAAO,WAAW,YACpB,MAAM,IAAI,UAAU,GAAG,SAAS,YAAY,KAAK,GAAG,OAAO,MAAM,EAAE,+BAA+B,KAAK,wBAAwB;KAEjI,KAAK,aAAa,KAAK,KAAK,IAAI,GAAG,OAAO,YAAY,QAAQ,MAAM,QAAQ,UAAU,CAAC,OAAO,CAAC,CAAyB,CAAC;IAC3H;GACF;EACF;EAEA,wBAA8B;GAC5B,KAAK,MAAM,OAAO,KAAK,aAAa,OAAO,CAAC,GAC1C,IAAI;EAER;CACF;;EA1BC,WAAW;EAIG,gBAAA,GAAA,OAAO,SAAS,CAAA;;;CAwB/B,IACM,eAAA,gBADN,MACM,aAAa;EACjB,OAAO,QAAQ,UAAgC,CAAC,GAAkB;GAChE,OAAO;IACL,QAAA;IACA,WAAW,CAAC;KAAE,SAAS;KAAW,UAAU;IAAkB,GAAG,eAAe;IAChF,SAAS,CAAC,SAAS;IACnB,QAAQ,QAAQ,UAAU;GAC5B;EACF;CACF;CAVC,eAAA,gBAAA,WAAA,CAAA,OAAO,CAAA,GAAA,YAAA;CAYR,OAAO;EAAE;EAAc;EAAW;CAAQ;AAC5C"}

package/package.json

@@ -1 +1,44 @@
-{ "name": "@blixis-io/events", "version": "0.0.0", "description": "placeholder" }
+{
+  "name": "@blixis-io/events",
+  "version": "0.2.0",
+  "description": "An in-process domain event bus (defineEventsModule, EventBus.emit/on). Depends only on @blixis-io/core — usable in any app, HTTP or not.",
+  "license": "MIT",
+  "author": "Michael Voeten <michael@voeten.online>",
+  "homepage": "https://blixis-io.github.io/framework/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/blixis-io/framework.git",
+    "directory": "packages/events"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=24"
+  },
+  "keywords": [
+    "events",
+    "pub-sub",
+    "event-bus",
+    "typescript"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "@blixis-io/source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "@blixis-io/core": "0.3.0",
+    "@blixis-io/di": "0.1.1"
+  },
+  "scripts": {
+    "typecheck": "tsc -p tsconfig.json",
+    "build": "rolldown -c"
+  }
+}