@blixis-io/events 0.0.0 → 0.1.2

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,28 @@
+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>>;
+};
+//#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":";;;KAGY,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;;;;;;;;wBAuDc,mBAAmB,eAAe;EAChD;IAAgB,QAAQ,UAAU,uBAAuB;;EACzD,WAAW,eAAe,SAAS"}

package/dist/index.js

@@ -0,0 +1,73 @@
+import { Module } from "@blixis-io/core";
+import { Injectable, InjectionToken } 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 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");
+	let EventsModule = _EventsModule = class EventsModule {
+		static forRoot(options = {}) {
+			return {
+				module: _EventsModule,
+				providers: [{
+					provide: EVENT_BUS,
+					useClass: InProcessEventBus
+				}],
+				exports: [EVENT_BUS],
+				global: options.global ?? false
+			};
+		}
+	};
+	EventsModule = _EventsModule = __decorate([Module()], EventsModule);
+	return {
+		EventsModule,
+		EVENT_BUS
+	};
+}
+//#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 { Module, type DynamicModule } from \"@blixis-io/core\";\nimport { 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\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  const EVENT_BUS = new InjectionToken<EventBus<Events>>(\"blixis.events.bus\");\n\n  @Module()\n  class EventsModule {\n    static forRoot(options: EventsForRootOptions = {}): DynamicModule {\n      return {\n        module: EventsModule,\n        providers: [{ provide: EVENT_BUS, useClass: InProcessEventBus }],\n        exports: [EVENT_BUS],\n        global: options.global ?? false,\n      };\n    }\n  }\n\n  return { EventsModule, EVENT_BUS };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;AAsBA,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;;;;;;;AA8CZ,SAAgB,qBAGd;;CACA,MAAM,YAAY,IAAI,eAAiC,mBAAmB;CAE1E,IACM,eAAA,gBADN,MACM,aAAa;EACjB,OAAO,QAAQ,UAAgC,CAAC,GAAkB;GAChE,OAAO;IACL,QAAA;IACA,WAAW,CAAC;KAAE,SAAS;KAAW,UAAU;IAAkB,CAAC;IAC/D,SAAS,CAAC,SAAS;IACnB,QAAQ,QAAQ,UAAU;GAC5B;EACF;CACF;CAVC,eAAA,gBAAA,WAAA,CAAA,OAAO,CAAA,GAAA,YAAA;CAYR,OAAO;EAAE;EAAc;CAAU;AACnC"}

package/package.json

@@ -1 +1,44 @@
-{ "name": "@blixis-io/events", "version": "0.0.0", "description": "placeholder" }
+{
+  "name": "@blixis-io/events",
+  "version": "0.1.2",
+  "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.2.1",
+    "@blixis-io/di": "0.1.1"
+  },
+  "scripts": {
+    "typecheck": "tsc -p tsconfig.json",
+    "build": "rolldown -c"
+  }
+}