@venizia/ignis-kernel 0.2.0-5 → 0.2.0-6

package/dist/esm/base/events/event-bus.js

@@ -0,0 +1,93 @@
+import { BaseHelper, executeWithRetry, getError, RetryBackoffStrategies, RetryJitterModes, } from '@venizia/ignis-helpers/core';
+import isEmpty from 'lodash/isEmpty';
+import { EventDispatchRetry } from './common/constants.js';
+/** In-process, fire-and-forget domain event bus. `TPayloadMap` keys the event names, so a wrong name
+ * or payload shape is a compile error. Delivery is always async and retry is fixed - there is no
+ * knob for either, so "published" guarantees the same thing at every call site. Retry makes delivery
+ * at-least-once: handlers must be idempotent, see `IEventHandler`. */
+export class EventBus extends BaseHelper {
+    constructor(opts) {
+        super({ scope: opts.scope ?? EventBus.name });
+        this.container = opts.container;
+        this.handlerBindingKeysByName = new Map();
+    }
+    register(opts) {
+        const { name, handlerBindingKey } = opts;
+        if (isEmpty(name) || isEmpty(handlerBindingKey)) {
+            throw getError({
+                message: `[EventBus][register] Invalid registration | name: ${String(name)} | handlerBindingKey: ${handlerBindingKey}`,
+            });
+        }
+        const existing = this.handlerBindingKeysByName.get(name);
+        if (existing) {
+            existing.push(handlerBindingKey);
+            return;
+        }
+        this.handlerBindingKeysByName.set(name, [handlerBindingKey]);
+    }
+    /**
+     * Never blocks and never throws back to the caller: dispatch runs outside this call's flow via
+     * `queueMicrotask`, and a handler failure is caught and logged where it happens (`dispatch`),
+     * never here.
+     */
+    publish(opts) {
+        const { name, payload, traceId } = opts;
+        const event = {
+            name,
+            payload,
+            occurredAt: new Date().toISOString(),
+            traceId,
+        };
+        const handlerBindingKeys = this.handlerBindingKeysByName.get(name);
+        if (!handlerBindingKeys?.length) {
+            // A typo is already a compile error, so at runtime this only means nobody is listening yet -
+            // a legitimate state on a fire-and-forget bus, not an incident.
+            this.logger.debug('[publish] No handler registered | name: %s | traceId: %s', name, traceId);
+            return;
+        }
+        for (const handlerBindingKey of handlerBindingKeys) {
+            queueMicrotask(() => {
+                // `dispatch` catches every failure path itself and never rejects - this `.catch` is an
+                // unreachable backstop, kept (and logged) rather than left floating, for the day it isn't.
+                this.dispatch({ event, handlerBindingKey }).catch((error) => {
+                    this.logger.error('[publish] Unexpected dispatch failure | name: %s | Error: %s', event.name, error);
+                });
+            });
+        }
+    }
+    /**
+     * Fixed 3 attempts / ~100ms exponential backoff, no jitter - see `EventDispatchRetry`. The
+     * handler is resolved fresh from the container on every attempt rather than once up front, so a
+     * rebind takes effect on the very next attempt of a dispatch already in flight.
+     *
+     * `executeWithRetry` is used without its own `logger` - its internal per-attempt/exhaustion
+     * logging knows nothing about the event name or `traceId`, so it cannot be the trace anyone
+     * relies on. The one line below, logged only on final failure, is.
+     */
+    async dispatch(opts) {
+        const { event, handlerBindingKey } = opts;
+        let lastAttempt = 0;
+        try {
+            await executeWithRetry({
+                operation: `EventBus.dispatch:${event.name}`,
+                maxAttempts: EventDispatchRetry.MAX_ATTEMPTS,
+                backoff: {
+                    strategy: RetryBackoffStrategies.EXPONENTIAL,
+                    initialDelayMs: EventDispatchRetry.BASE_DELAY_MS,
+                    jitter: RetryJitterModes.NONE,
+                },
+                execution: async ({ attempt }) => {
+                    lastAttempt = attempt;
+                    const handler = this.container.get({ key: handlerBindingKey });
+                    await handler.handle({ event });
+                },
+            });
+        }
+        catch (error) {
+            // The only trace this failure leaves: it is caught here and never reaches the publisher, so
+            // the event name, traceId and attempt count all have to be on this one line.
+            this.logger.error('[dispatch] Handler exhausted retries | name: %s | traceId: %s | attempts: %d | handlerBindingKey: %s | Error: %s', event.name, event.traceId, lastAttempt, handlerBindingKey, error);
+        }
+    }
+}
+//# sourceMappingURL=event-bus.js.map

package/dist/esm/base/events/event-bus.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-bus.js","sourceRoot":"","sources":["../../../../src/base/events/event-bus.ts"],"names":[],"mappings":"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"}

package/dist/esm/base/events/index.d.ts

@@ -0,0 +1,3 @@
+export * from './common/index.js';
+export * from './event-bus.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/esm/base/events/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/base/events/index.ts"],"names":[],"mappings":"AAAA,cAAc,UAAU,CAAC;AACzB,cAAc,aAAa,CAAC"}

package/dist/esm/base/events/index.js

@@ -0,0 +1,3 @@
+export * from './common/index.js';
+export * from './event-bus.js';
+//# sourceMappingURL=index.js.map

package/dist/esm/base/events/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/base/events/index.ts"],"names":[],"mappings":"AAAA,cAAc,UAAU,CAAC;AACzB,cAAc,aAAa,CAAC"}

package/dist/esm/base/index.d.ts

@@ -3,6 +3,7 @@ export * from './auth/index.js';
 export * from './components/index.js';
 export * from './controllers/index.js';
 export * from './datasources/index.js';
+export * from './events/index.js';
 export * from './metadata/index.js';
 export * from './middlewares/index.js';
 export * from './mixins/index.js';

package/dist/esm/base/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/base/index.ts"],"names":[],"mappings":"AAAA,cAAc,gBAAgB,CAAC;AAC/B,cAAc,QAAQ,CAAC;AACvB,cAAc,cAAc,CAAC;AAC7B,cAAc,eAAe,CAAC;AAC9B,cAAc,eAAe,CAAC;AAC9B,cAAc,YAAY,CAAC;AAM3B,cAAc,eAAe,CAAC;AAC9B,cAAc,UAAU,CAAC;AACzB,cAAc,UAAU,CAAC;AACzB,cAAc,aAAa,CAAC;AAC5B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,mBAAmB,CAAC;AAClC,cAAc,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/base/index.ts"],"names":[],"mappings":"AAAA,cAAc,gBAAgB,CAAC;AAC/B,cAAc,QAAQ,CAAC;AACvB,cAAc,cAAc,CAAC;AAC7B,cAAc,eAAe,CAAC;AAC9B,cAAc,eAAe,CAAC;AAC9B,cAAc,UAAU,CAAC;AACzB,cAAc,YAAY,CAAC;AAC3B,cAAc,eAAe,CAAC;AAC9B,cAAc,UAAU,CAAC;AACzB,cAAc,UAAU,CAAC;AACzB,cAAc,aAAa,CAAC;AAC5B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,mBAAmB,CAAC;AAClC,cAAc,YAAY,CAAC"}

package/dist/esm/base/index.js

@@ -3,12 +3,8 @@ export * from './auth/index.js';
 export * from './components/index.js';
 export * from './controllers/index.js';
 export * from './datasources/index.js';
+export * from './events/index.js';
 export * from './metadata/index.js';
-// Deliberately public, not an accidental leak: core's own `base/applications/base.ts` (registers
-// `emojiFavicon`/`notFoundHandler`) and `base/middlewares/request-spy/request-spy.middleware.ts`
-// (reads `REQUEST_ID_KEY`, registers `RequestErrors`) both need these across the package boundary
-// the split introduced - core did not export this barrel before the move, but two of its own files
-// now depend on symbols that only live here.
 export * from './middlewares/index.js';
 export * from './mixins/index.js';
 export * from './models/index.js';

package/dist/esm/base/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/base/index.ts"],"names":[],"mappings":"AAAA,cAAc,gBAAgB,CAAC;AAC/B,cAAc,QAAQ,CAAC;AACvB,cAAc,cAAc,CAAC;AAC7B,cAAc,eAAe,CAAC;AAC9B,cAAc,eAAe,CAAC;AAC9B,cAAc,YAAY,CAAC;AAC3B,iGAAiG;AACjG,iGAAiG;AACjG,kGAAkG;AAClG,mGAAmG;AACnG,6CAA6C;AAC7C,cAAc,eAAe,CAAC;AAC9B,cAAc,UAAU,CAAC;AACzB,cAAc,UAAU,CAAC;AACzB,cAAc,aAAa,CAAC;AAC5B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,mBAAmB,CAAC;AAClC,cAAc,YAAY,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/base/index.ts"],"names":[],"mappings":"AAAA,cAAc,gBAAgB,CAAC;AAC/B,cAAc,QAAQ,CAAC;AACvB,cAAc,cAAc,CAAC;AAC7B,cAAc,eAAe,CAAC;AAC9B,cAAc,eAAe,CAAC;AAC9B,cAAc,UAAU,CAAC;AACzB,cAAc,YAAY,CAAC;AAC3B,cAAc,eAAe,CAAC;AAC9B,cAAc,UAAU,CAAC;AACzB,cAAc,UAAU,CAAC;AACzB,cAAc,aAAa,CAAC;AAC5B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,mBAAmB,CAAC;AAClC,cAAc,YAAY,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@venizia/ignis-kernel",
-  "version": "0.2.0-5",
+  "version": "0.2.0-6",
   "description": "Browser-pure kernel of the IGNIS framework: dependency injection, lifecycle, REST controllers, repository and datasource abstractions, and the authentication and authorization seams. No node builtin and no server-only peer, so the same kernel serves a Bun server and a browser Worker.",
   "keywords": [
     "authentication",
@@ -79,9 +79,9 @@
     "prepublishOnly": "bun run rebuild"
   },
   "dependencies": {
-    "@venizia/ignis-filter": "^0.2.0-1",
-    "@venizia/ignis-helpers": "^0.2.0-4",
-    "@venizia/ignis-inversion": "^0.2.0-0",
+    "@venizia/ignis-filter": "^0.2.0-2",
+    "@venizia/ignis-helpers": "^0.2.0-5",
+    "@venizia/ignis-inversion": "^0.2.0-1",
     "lodash": "^4.18.1",
     "reflect-metadata": "^0.2.2",
     "zod": "^4.4.3"
@@ -107,7 +107,7 @@
   "devDependencies": {
     "@types/bun": "^1.3.14",
     "@types/lodash": "^4.17.23",
-    "@venizia/dev-configs": "^0.2.0-0",
+    "@venizia/dev-configs": "^0.2.0-1",
     "casbin": "^5.51.1",
     "eslint": "^10.7.0",
     "prettier": "^3.9.5",