@venizia/ignis-kernel 0.4.3 → 0.4.4

package/dist/cjs/base/datasources/index.js

@@ -1,19 +0,0 @@
-"use strict";
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __exportStar = (this && this.__exportStar) || function(m, exports) {
-    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-__exportStar(require("./abstract"), exports);
-__exportStar(require("./common"), exports);
-//# sourceMappingURL=index.js.map

package/dist/cjs/base/datasources/index.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/base/datasources/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,6CAA2B;AAC3B,2CAAyB","sourcesContent":["export * from './abstract';\nexport * from './common';\n"]}

package/dist/cjs/base/events/common/constants.d.ts

@@ -1,37 +0,0 @@
-import type { TConstValue } from '@venizia/ignis-helpers/common';
-export declare class EventDispatchRetry {
-    static readonly MAX_ATTEMPTS = 3;
-    static readonly BASE_DELAY_MS = 100;
-    /**
-     * Ceiling on `register`'s `retry.maxAttempts`. Dispatch is fire-and-forget - nobody awaits it - so
-     * an attempt count high enough to matter is already high enough to hammer a struggling downstream
-     * resource attempt after attempt. Twice the highest count any known consumer has asked for (5)
-     * leaves room to tune without permitting an attempt storm.
-     */
-    static readonly MAX_ATTEMPTS_CEILING = 10;
-    /**
-     * Ceiling, in ms, on the total backoff window `register`'s `retry` can produce (the sum of every
-     * inter-attempt delay, computed without jitter since jitter only shrinks it). Matches
-     * `RetryHelper`'s own default cap on a SINGLE delay: a dispatch holds a handler's resources - e.g.
-     * a database connection - for its entire retry window, so the sum across every attempt gets the
-     * same "unreasonable beyond this" line the framework already draws for one attempt.
-     */
-    static readonly MAX_TOTAL_WINDOW_MS = 30000;
-}
-/**
- * Tag for `EventBus.register`'s `handler` union (`TEventHandlerReference`). The tag makes the
- * caller's choice explicit at the call site instead of implicit in whichever field is present, so a
- * mismatched `type`/field pair (`BINDING_KEY` with `fn`, or `FUNCTION` with `key`) is a compile
- * error there rather than a runtime surprise later, inside a `queueMicrotask` where nobody is
- * watching.
- */
-export declare class EventHandlerTypes {
-    /** `handler.key` is resolved from the container on every retry attempt - a rebind reaches an attempt already in flight. */
-    static readonly BINDING_KEY = "binding-key";
-    /** `handler.fn` is invoked directly as a captured closure - there is nothing to rebind, so every attempt in a retry window calls the exact function registered here. */
-    static readonly FUNCTION = "function";
-    static readonly SCHEME_SET: Set<string>;
-    static isValid(value: string): value is TEventHandlerType;
-}
-export type TEventHandlerType = TConstValue<typeof EventHandlerTypes>;
-//# sourceMappingURL=constants.d.ts.map

package/dist/cjs/base/events/common/constants.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../../../../src/base/events/common/constants.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,+BAA+B,CAAC;AAEjE,qBAAa,kBAAkB;IAC7B,MAAM,CAAC,QAAQ,CAAC,YAAY,KAAK;IACjC,MAAM,CAAC,QAAQ,CAAC,aAAa,OAAO;IAEpC;;;;;OAKG;IACH,MAAM,CAAC,QAAQ,CAAC,oBAAoB,MAAM;IAE1C;;;;;;OAMG;IACH,MAAM,CAAC,QAAQ,CAAC,mBAAmB,SAAU;CAC9C;AAED;;;;;;GAMG;AACH,qBAAa,iBAAiB;IAC5B,2HAA2H;IAC3H,MAAM,CAAC,QAAQ,CAAC,WAAW,iBAAiB;IAE5C,wKAAwK;IACxK,MAAM,CAAC,QAAQ,CAAC,QAAQ,cAAc;IAEtC,MAAM,CAAC,QAAQ,CAAC,UAAU,cAAsD;IAEhF,MAAM,CAAC,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,iBAAiB;CAG1D;AAED,MAAM,MAAM,iBAAiB,GAAG,WAAW,CAAC,OAAO,iBAAiB,CAAC,CAAC"}

package/dist/cjs/base/events/common/constants.js

@@ -1,42 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.EventHandlerTypes = exports.EventDispatchRetry = void 0;
-class EventDispatchRetry {
-    static { this.MAX_ATTEMPTS = 3; }
-    static { this.BASE_DELAY_MS = 100; }
-    /**
-     * Ceiling on `register`'s `retry.maxAttempts`. Dispatch is fire-and-forget - nobody awaits it - so
-     * an attempt count high enough to matter is already high enough to hammer a struggling downstream
-     * resource attempt after attempt. Twice the highest count any known consumer has asked for (5)
-     * leaves room to tune without permitting an attempt storm.
-     */
-    static { this.MAX_ATTEMPTS_CEILING = 10; }
-    /**
-     * Ceiling, in ms, on the total backoff window `register`'s `retry` can produce (the sum of every
-     * inter-attempt delay, computed without jitter since jitter only shrinks it). Matches
-     * `RetryHelper`'s own default cap on a SINGLE delay: a dispatch holds a handler's resources - e.g.
-     * a database connection - for its entire retry window, so the sum across every attempt gets the
-     * same "unreasonable beyond this" line the framework already draws for one attempt.
-     */
-    static { this.MAX_TOTAL_WINDOW_MS = 30_000; }
-}
-exports.EventDispatchRetry = EventDispatchRetry;
-/**
- * Tag for `EventBus.register`'s `handler` union (`TEventHandlerReference`). The tag makes the
- * caller's choice explicit at the call site instead of implicit in whichever field is present, so a
- * mismatched `type`/field pair (`BINDING_KEY` with `fn`, or `FUNCTION` with `key`) is a compile
- * error there rather than a runtime surprise later, inside a `queueMicrotask` where nobody is
- * watching.
- */
-class EventHandlerTypes {
-    /** `handler.key` is resolved from the container on every retry attempt - a rebind reaches an attempt already in flight. */
-    static { this.BINDING_KEY = 'binding-key'; }
-    /** `handler.fn` is invoked directly as a captured closure - there is nothing to rebind, so every attempt in a retry window calls the exact function registered here. */
-    static { this.FUNCTION = 'function'; }
-    static { this.SCHEME_SET = new Set([this.BINDING_KEY, this.FUNCTION]); }
-    static isValid(value) {
-        return this.SCHEME_SET.has(value);
-    }
-}
-exports.EventHandlerTypes = EventHandlerTypes;
-//# sourceMappingURL=constants.js.map

package/dist/cjs/base/events/common/constants.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"constants.js","sourceRoot":"","sources":["../../../../../src/base/events/common/constants.ts"],"names":[],"mappings":";;;AAEA,MAAa,kBAAkB;aACb,iBAAY,GAAG,CAAC,CAAC;aACjB,kBAAa,GAAG,GAAG,CAAC;IAEpC;;;;;OAKG;aACa,yBAAoB,GAAG,EAAE,CAAC;IAE1C;;;;;;OAMG;aACa,wBAAmB,GAAG,MAAM,CAAC;;AAnB/C,gDAoBC;AAED;;;;;;GAMG;AACH,MAAa,iBAAiB;IAC5B,2HAA2H;aAC3G,gBAAW,GAAG,aAAa,CAAC;IAE5C,wKAAwK;aACxJ,aAAQ,GAAG,UAAU,CAAC;aAEtB,eAAU,GAAG,IAAI,GAAG,CAAS,CAAC,IAAI,CAAC,WAAW,EAAE,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC;IAEhF,MAAM,CAAC,OAAO,CAAC,KAAa;QAC1B,OAAO,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;IACpC,CAAC;;AAXH,8CAYC","sourcesContent":["import type { TConstValue } from '@venizia/ignis-helpers/common';\n\nexport class EventDispatchRetry {\n  static readonly MAX_ATTEMPTS = 3;\n  static readonly BASE_DELAY_MS = 100;\n\n  /**\n   * Ceiling on `register`'s `retry.maxAttempts`. Dispatch is fire-and-forget - nobody awaits it - so\n   * an attempt count high enough to matter is already high enough to hammer a struggling downstream\n   * resource attempt after attempt. Twice the highest count any known consumer has asked for (5)\n   * leaves room to tune without permitting an attempt storm.\n   */\n  static readonly MAX_ATTEMPTS_CEILING = 10;\n\n  /**\n   * Ceiling, in ms, on the total backoff window `register`'s `retry` can produce (the sum of every\n   * inter-attempt delay, computed without jitter since jitter only shrinks it). Matches\n   * `RetryHelper`'s own default cap on a SINGLE delay: a dispatch holds a handler's resources - e.g.\n   * a database connection - for its entire retry window, so the sum across every attempt gets the\n   * same \"unreasonable beyond this\" line the framework already draws for one attempt.\n   */\n  static readonly MAX_TOTAL_WINDOW_MS = 30_000;\n}\n\n/**\n * Tag for `EventBus.register`'s `handler` union (`TEventHandlerReference`). The tag makes the\n * caller's choice explicit at the call site instead of implicit in whichever field is present, so a\n * mismatched `type`/field pair (`BINDING_KEY` with `fn`, or `FUNCTION` with `key`) is a compile\n * error there rather than a runtime surprise later, inside a `queueMicrotask` where nobody is\n * watching.\n */\nexport class EventHandlerTypes {\n  /** `handler.key` is resolved from the container on every retry attempt - a rebind reaches an attempt already in flight. */\n  static readonly BINDING_KEY = 'binding-key';\n\n  /** `handler.fn` is invoked directly as a captured closure - there is nothing to rebind, so every attempt in a retry window calls the exact function registered here. */\n  static readonly FUNCTION = 'function';\n\n  static readonly SCHEME_SET = new Set<string>([this.BINDING_KEY, this.FUNCTION]);\n\n  static isValid(value: string): value is TEventHandlerType {\n    return this.SCHEME_SET.has(value);\n  }\n}\n\nexport type TEventHandlerType = TConstValue<typeof EventHandlerTypes>;\n"]}

package/dist/cjs/base/events/common/index.d.ts

@@ -1,3 +0,0 @@
-export * from './constants';
-export * from './types';
-//# sourceMappingURL=index.d.ts.map

package/dist/cjs/base/events/common/index.d.ts.map

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

package/dist/cjs/base/events/common/index.js

@@ -1,19 +0,0 @@
-"use strict";
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __exportStar = (this && this.__exportStar) || function(m, exports) {
-    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-__exportStar(require("./constants"), exports);
-__exportStar(require("./types"), exports);
-//# sourceMappingURL=index.js.map

package/dist/cjs/base/events/common/index.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../src/base/events/common/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,8CAA4B;AAC5B,0CAAwB","sourcesContent":["export * from './constants';\nexport * from './types';\n"]}

package/dist/cjs/base/events/common/types.d.ts

@@ -1,64 +0,0 @@
-import type { ValueOrPromise } from '@venizia/ignis-helpers/common';
-import { type EventHandlerTypes } from './constants';
-/** One occurrence of a named domain event, decoupled from whatever publishes or handles it. */
-export interface IDomainEvent<TPayload = unknown> {
-    name: string;
-    payload: TPayload;
-    occurredAt: string;
-    traceId?: string;
-}
-/**
- * Per-registration retry override for `EventBus.register`. Both fields must be positive integers,
- * and are bounded by `EventDispatchRetry.MAX_ATTEMPTS_CEILING` / `MAX_TOTAL_WINDOW_MS` - a value
- * outside either throws at `register()`, never clamps.
- */
-export interface IEventHandlerRetryOptions {
-    /** Default `EventDispatchRetry.MAX_ATTEMPTS`. */
-    maxAttempts?: number;
-    /** First backoff delay in ms; exponential growth is computed from it. Default `EventDispatchRetry.BASE_DELAY_MS`. */
-    baseDelayMs?: number;
-}
-/** A handler callback - synchronous or asynchronous, `EventBus` awaits either the same way. */
-export type TEventHandlerFunction<TPayload = unknown> = (opts: {
-    event: IDomainEvent<TPayload>;
-}) => ValueOrPromise<void>;
-/** `register`'s binding-key handler shape: resolved from the container by `key` on every retry attempt. */
-export interface IEventHandlerBindingKeyReference {
-    type: typeof EventHandlerTypes.BINDING_KEY;
-    key: string;
-}
-/** `register`'s function handler shape: `fn` is invoked directly, captured as a closure - see `TEventHandlerReference`. */
-export interface IEventHandlerFunctionReference<TPayload = unknown> {
-    type: typeof EventHandlerTypes.FUNCTION;
-    fn: TEventHandlerFunction<TPayload>;
-}
-/**
- * The two shapes `EventBus.register`'s `handler` accepts, tagged by `type` so the caller states
- * which rather than the bus inferring it from whichever field is present. Only `BINDING_KEY` shares
- * `IEventHandler`'s rebind property; see its doc.
- */
-export type TEventHandlerReference<TPayload = unknown> = IEventHandlerBindingKeyReference | IEventHandlerFunctionReference<TPayload>;
-/**
- * Handles one `IDomainEvent`. Implemented by whatever is bound into the container under
- * `register`'s `{ type: EventHandlerTypes.BINDING_KEY, key }` form - see `TEventHandlerReference`
- * for the `FUNCTION` form, which does not implement this interface and does not share its rebind
- * property.
- *
- * MUST be idempotent. The bus retries a failed handler, so delivery is at-least-once: one that
- * half-succeeds then throws runs again from the top, re-applying whatever already landed. Three
- * shapes break, and only the first looks dangerous: a cumulative write (`count = count + 1`, or a
- * rolling average, which drifts toward the resampled value); several writes batched under one
- * `Promise.all`, where any failure re-runs the ones that succeeded; and a bare INSERT of a log or
- * audit row, which simply gains a duplicate - corrupting the record used to diagnose the retry.
- *
- * Resolved from the container by binding key at dispatch time, never captured as a direct reference,
- * so rebinding the key takes effect on the next attempt - including one already in flight. A
- * `FUNCTION`-form handler does NOT have this property: `fn` is a captured closure, so every attempt
- * in a long retry window calls the exact function registered at startup.
- */
-export interface IEventHandler<TEvent extends IDomainEvent = IDomainEvent> {
-    handle(opts: {
-        event: TEvent;
-    }): ValueOrPromise<void>;
-}
-//# sourceMappingURL=types.d.ts.map

package/dist/cjs/base/events/common/types.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../../src/base/events/common/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AACpE,OAAO,EAAE,KAAK,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAErD,+FAA+F;AAC/F,MAAM,WAAW,YAAY,CAAC,QAAQ,GAAG,OAAO;IAC9C,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,QAAQ,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;GAIG;AACH,MAAM,WAAW,yBAAyB;IACxC,iDAAiD;IACjD,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB,qHAAqH;IACrH,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,+FAA+F;AAC/F,MAAM,MAAM,qBAAqB,CAAC,QAAQ,GAAG,OAAO,IAAI,CAAC,IAAI,EAAE;IAC7D,KAAK,EAAE,YAAY,CAAC,QAAQ,CAAC,CAAC;CAC/B,KAAK,cAAc,CAAC,IAAI,CAAC,CAAC;AAE3B,2GAA2G;AAC3G,MAAM,WAAW,gCAAgC;IAC/C,IAAI,EAAE,OAAO,iBAAiB,CAAC,WAAW,CAAC;IAC3C,GAAG,EAAE,MAAM,CAAC;CACb;AAED,2HAA2H;AAC3H,MAAM,WAAW,8BAA8B,CAAC,QAAQ,GAAG,OAAO;IAChE,IAAI,EAAE,OAAO,iBAAiB,CAAC,QAAQ,CAAC;IACxC,EAAE,EAAE,qBAAqB,CAAC,QAAQ,CAAC,CAAC;CACrC;AAED;;;;GAIG;AACH,MAAM,MAAM,sBAAsB,CAAC,QAAQ,GAAG,OAAO,IACjD,gCAAgC,GAChC,8BAA8B,CAAC,QAAQ,CAAC,CAAC;AAE7C;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,aAAa,CAAC,MAAM,SAAS,YAAY,GAAG,YAAY;IACvE,MAAM,CAAC,IAAI,EAAE;QAAE,KAAK,EAAE,MAAM,CAAA;KAAE,GAAG,cAAc,CAAC,IAAI,CAAC,CAAC;CACvD"}

package/dist/cjs/base/events/common/types.js

@@ -1,3 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-//# sourceMappingURL=types.js.map

package/dist/cjs/base/events/common/types.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../../../src/base/events/common/types.ts"],"names":[],"mappings":"","sourcesContent":["import type { ValueOrPromise } from '@venizia/ignis-helpers/common';\nimport { type EventHandlerTypes } from './constants';\n\n/** One occurrence of a named domain event, decoupled from whatever publishes or handles it. */\nexport interface IDomainEvent<TPayload = unknown> {\n  name: string;\n  payload: TPayload;\n  occurredAt: string;\n  traceId?: string;\n}\n\n/**\n * Per-registration retry override for `EventBus.register`. Both fields must be positive integers,\n * and are bounded by `EventDispatchRetry.MAX_ATTEMPTS_CEILING` / `MAX_TOTAL_WINDOW_MS` - a value\n * outside either throws at `register()`, never clamps.\n */\nexport interface IEventHandlerRetryOptions {\n  /** Default `EventDispatchRetry.MAX_ATTEMPTS`. */\n  maxAttempts?: number;\n\n  /** First backoff delay in ms; exponential growth is computed from it. Default `EventDispatchRetry.BASE_DELAY_MS`. */\n  baseDelayMs?: number;\n}\n\n/** A handler callback - synchronous or asynchronous, `EventBus` awaits either the same way. */\nexport type TEventHandlerFunction<TPayload = unknown> = (opts: {\n  event: IDomainEvent<TPayload>;\n}) => ValueOrPromise<void>;\n\n/** `register`'s binding-key handler shape: resolved from the container by `key` on every retry attempt. */\nexport interface IEventHandlerBindingKeyReference {\n  type: typeof EventHandlerTypes.BINDING_KEY;\n  key: string;\n}\n\n/** `register`'s function handler shape: `fn` is invoked directly, captured as a closure - see `TEventHandlerReference`. */\nexport interface IEventHandlerFunctionReference<TPayload = unknown> {\n  type: typeof EventHandlerTypes.FUNCTION;\n  fn: TEventHandlerFunction<TPayload>;\n}\n\n/**\n * The two shapes `EventBus.register`'s `handler` accepts, tagged by `type` so the caller states\n * which rather than the bus inferring it from whichever field is present. Only `BINDING_KEY` shares\n * `IEventHandler`'s rebind property; see its doc.\n */\nexport type TEventHandlerReference<TPayload = unknown> =\n  | IEventHandlerBindingKeyReference\n  | IEventHandlerFunctionReference<TPayload>;\n\n/**\n * Handles one `IDomainEvent`. Implemented by whatever is bound into the container under\n * `register`'s `{ type: EventHandlerTypes.BINDING_KEY, key }` form - see `TEventHandlerReference`\n * for the `FUNCTION` form, which does not implement this interface and does not share its rebind\n * property.\n *\n * MUST be idempotent. The bus retries a failed handler, so delivery is at-least-once: one that\n * half-succeeds then throws runs again from the top, re-applying whatever already landed. Three\n * shapes break, and only the first looks dangerous: a cumulative write (`count = count + 1`, or a\n * rolling average, which drifts toward the resampled value); several writes batched under one\n * `Promise.all`, where any failure re-runs the ones that succeeded; and a bare INSERT of a log or\n * audit row, which simply gains a duplicate - corrupting the record used to diagnose the retry.\n *\n * Resolved from the container by binding key at dispatch time, never captured as a direct reference,\n * so rebinding the key takes effect on the next attempt - including one already in flight. A\n * `FUNCTION`-form handler does NOT have this property: `fn` is a captured closure, so every attempt\n * in a long retry window calls the exact function registered at startup.\n */\nexport interface IEventHandler<TEvent extends IDomainEvent = IDomainEvent> {\n  handle(opts: { event: TEvent }): ValueOrPromise<void>;\n}\n"]}

package/dist/cjs/base/events/event-bus.d.ts

@@ -1,78 +0,0 @@
-import type { Container } from '../../helpers/inversion/container';
-import { BaseHelper } from '@venizia/ignis-helpers/core';
-import type { IEventHandlerRetryOptions, TEventHandlerReference } from './common/types';
-/** 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. Retry timing is a property of the
- * handler's own failure mode, not of the event, so `register` may tune it per registration. But
- * nobody awaits a fire-and-forget dispatch, so an unbounded window would let one event hold a
- * handler - and whatever it holds open, e.g. a database connection - for an unbounded time with no
- * one to report it. What the bus guarantees instead: a bounded MAXIMUM time a single dispatch can
- * occupy, enforced as a hard ceiling at `register()` - see `EventDispatchRetry`. Retry makes
- * delivery at-least-once: handlers must be idempotent, see `IEventHandler`. */
-export declare class EventBus<TPayloadMap extends object> extends BaseHelper {
-    private readonly container;
-    /** `register` appends, never replaces - two handlers may share an event name, and replacing would
-     * drop the first with no way for the caller to notice. */
-    private readonly registrationsByName;
-    constructor(opts: {
-        scope?: string;
-        container: Container;
-    });
-    /** The pre-jitter total of every inter-attempt delay `maxAttempts`/`baseDelayMs` would produce -
-     * jitter (always on, see `dispatch`) only ever shrinks a delay, so this is a true upper bound. */
-    private static computeTotalWindowMs;
-    /** Loud rejection, never a silent clamp: a caller who believes a number the bus does not honour is
-     * worse off than one who sees the ceiling at boot. */
-    private static assertValidRetry;
-    /**
-     * Turns `handler` into a uniform invoker plus a description for the exhaustion log line.
-     * `BINDING_KEY` resolves through the container INSIDE the returned closure, so every call re-reads
-     * the current binding; `FUNCTION` calls `fn` directly, so the closure IS the resolution - there is
-     * nothing left to re-read on a later attempt. The tag (`handler.type`) is what this switches on,
-     * not which field happens to be present - see `EventHandlerTypes`' doc.
-     */
-    private static buildHandlerInvoker;
-    /**
-     * `retry` is optional and per REGISTRATION, not per publish: the right window belongs to the
-     * handler's own failure mode, and two handlers on the same event name may each pick their own.
-     * Omitting it reproduces today's `EventDispatchRetry` defaults exactly. Both `maxAttempts` and the
-     * total backoff window it implies are bounded - see `EventDispatchRetry` - and exceeding either
-     * throws here, at boot where a human sees it, rather than being silently clamped at dispatch time.
-     */
-    register<K extends keyof TPayloadMap & string>(opts: {
-        name: K;
-        /** A `BINDING_KEY` reference re-resolves through the container on every retry attempt, so a
-         * rebind reaches a dispatch already in flight. A `FUNCTION` reference is captured as-is: a
-         * rebind has nothing to reach, and every attempt in a long retry window calls the exact `fn`
-         * registered here. */
-        handler: TEventHandlerReference<TPayloadMap[K]>;
-        retry?: IEventHandlerRetryOptions;
-    }): void;
-    /**
-     * 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<K extends keyof TPayloadMap & string>(opts: {
-        name: K;
-        payload: TPayloadMap[K];
-        traceId?: string;
-    }): void;
-    /**
-     * Attempts/backoff come from the registration (`EventDispatchRetry`'s defaults when omitted),
-     * always with full jitter - `RetryJitterModes.FULL` decorrelates a shared-resource pile-up hardest,
-     * so many handlers retrying the same lock do not collide on the same instant a second and third
-     * time. `invokeHandler` already encodes whether that re-resolves (`BINDING_KEY`) or was captured
-     * once (`FUNCTION`) - see `buildHandlerInvoker` - so this method calls it uniformly. A handler that
-     * throws synchronously is caught exactly like one that returns a rejected promise: `execution`
-     * here is itself `async`, and JS converts a synchronous throw inside an async function body into a
-     * rejection of that function's own promise - `RetryHelper.executeWithRetry`'s attempt loop never
-     * sees the difference.
-     *
-     * `RetryHelper.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.
-     */
-    private dispatch;
-}
-//# sourceMappingURL=event-bus.d.ts.map

package/dist/cjs/base/events/event-bus.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"event-bus.d.ts","sourceRoot":"","sources":["../../../../src/base/events/event-bus.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,+BAA+B,CAAC;AAE/D,OAAO,EACL,UAAU,EAKX,MAAM,6BAA6B,CAAC;AAErC,OAAO,KAAK,EAGV,yBAAyB,EACzB,sBAAsB,EACvB,MAAM,gBAAgB,CAAC;AAexB;;;;;;;+EAO+E;AAC/E,qBAAa,QAAQ,CAAC,WAAW,SAAS,MAAM,CAAE,SAAQ,UAAU;IAClE,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAY;IAEtC;8DAC0D;IAC1D,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAA4C;gBAEpE,IAAI,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,SAAS,CAAA;KAAE;IAM1D;sGACkG;IAClG,OAAO,CAAC,MAAM,CAAC,oBAAoB;IAkBnC;0DACsD;IACtD,OAAO,CAAC,MAAM,CAAC,gBAAgB;IAiC/B;;;;;;OAMG;IACH,OAAO,CAAC,MAAM,CAAC,mBAAmB;IAkDlC;;;;;;OAMG;IACH,QAAQ,CAAC,CAAC,SAAS,MAAM,WAAW,GAAG,MAAM,EAAE,IAAI,EAAE;QACnD,IAAI,EAAE,CAAC,CAAC;QACR;;;8BAGsB;QACtB,OAAO,EAAE,sBAAsB,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC;QAChD,KAAK,CAAC,EAAE,yBAAyB,CAAC;KACnC,GAAG,IAAI;IAmCR;;;;OAIG;IACH,OAAO,CAAC,CAAC,SAAS,MAAM,WAAW,GAAG,MAAM,EAAE,IAAI,EAAE;QAClD,IAAI,EAAE,CAAC,CAAC;QACR,OAAO,EAAE,WAAW,CAAC,CAAC,CAAC,CAAC;QACxB,OAAO,CAAC,EAAE,MAAM,CAAC;KAClB,GAAG,IAAI;IAiCR;;;;;;;;;;;;;;OAcG;YACW,QAAQ;CAmCvB"}

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

@@ -1,217 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.EventBus = void 0;
-const common_1 = require("@venizia/ignis-helpers/common");
-const core_1 = require("@venizia/ignis-helpers/core");
-const constants_1 = require("./common/constants");
-/** 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. Retry timing is a property of the
- * handler's own failure mode, not of the event, so `register` may tune it per registration. But
- * nobody awaits a fire-and-forget dispatch, so an unbounded window would let one event hold a
- * handler - and whatever it holds open, e.g. a database connection - for an unbounded time with no
- * one to report it. What the bus guarantees instead: a bounded MAXIMUM time a single dispatch can
- * occupy, enforced as a hard ceiling at `register()` - see `EventDispatchRetry`. Retry makes
- * delivery at-least-once: handlers must be idempotent, see `IEventHandler`. */
-class EventBus extends core_1.BaseHelper {
-    constructor(opts) {
-        super({ scope: opts.scope ?? EventBus.name });
-        this.container = opts.container;
-        this.registrationsByName = new Map();
-    }
-    /** The pre-jitter total of every inter-attempt delay `maxAttempts`/`baseDelayMs` would produce -
-     * jitter (always on, see `dispatch`) only ever shrinks a delay, so this is a true upper bound. */
-    static computeTotalWindowMs(opts) {
-        const { maxAttempts, baseDelayMs } = opts;
-        let totalWindowMs = 0;
-        for (let attempt = 1; attempt < maxAttempts; attempt++) {
-            totalWindowMs += core_1.RetryHelper.computeBackoffDelayMs({
-                attempt,
-                backoff: {
-                    strategy: core_1.RetryBackoffStrategies.EXPONENTIAL,
-                    initialDelayMs: baseDelayMs,
-                    jitter: core_1.RetryJitterModes.NONE,
-                },
-            });
-        }
-        return totalWindowMs;
-    }
-    /** Loud rejection, never a silent clamp: a caller who believes a number the bus does not honour is
-     * worse off than one who sees the ceiling at boot. */
-    static assertValidRetry(opts) {
-        const { name, maxAttempts, baseDelayMs } = opts;
-        if (!Number.isInteger(maxAttempts) || maxAttempts < 1) {
-            throw (0, core_1.getError)({
-                message: `[EventBus][register] retry.maxAttempts must be a positive integer | name: ${name} | Got: ${maxAttempts}`,
-            });
-        }
-        if (!Number.isInteger(baseDelayMs) || baseDelayMs < 1) {
-            throw (0, core_1.getError)({
-                message: `[EventBus][register] retry.baseDelayMs must be a positive integer | name: ${name} | Got: ${baseDelayMs}`,
-            });
-        }
-        if (maxAttempts > constants_1.EventDispatchRetry.MAX_ATTEMPTS_CEILING) {
-            throw (0, core_1.getError)({
-                message: `[EventBus][register] retry.maxAttempts exceeds the ceiling | name: ${name} | Got: ${maxAttempts} | Ceiling: ${constants_1.EventDispatchRetry.MAX_ATTEMPTS_CEILING} | Lower retry.maxAttempts`,
-            });
-        }
-        const totalWindowMs = EventBus.computeTotalWindowMs({ maxAttempts, baseDelayMs });
-        if (totalWindowMs > constants_1.EventDispatchRetry.MAX_TOTAL_WINDOW_MS) {
-            throw (0, core_1.getError)({
-                message: `[EventBus][register] retry window exceeds the ceiling | name: ${name} | Got: ${totalWindowMs}ms | Ceiling: ${constants_1.EventDispatchRetry.MAX_TOTAL_WINDOW_MS}ms | Lower retry.maxAttempts or retry.baseDelayMs`,
-            });
-        }
-    }
-    /**
-     * Turns `handler` into a uniform invoker plus a description for the exhaustion log line.
-     * `BINDING_KEY` resolves through the container INSIDE the returned closure, so every call re-reads
-     * the current binding; `FUNCTION` calls `fn` directly, so the closure IS the resolution - there is
-     * nothing left to re-read on a later attempt. The tag (`handler.type`) is what this switches on,
-     * not which field happens to be present - see `EventHandlerTypes`' doc.
-     */
-    static buildHandlerInvoker(opts) {
-        const { container, handler, name } = opts;
-        if ((0, common_1.isEmpty)({ value: handler })) {
-            throw (0, core_1.getError)({
-                message: `[EventBus][register] Invalid handler | name: ${name} | Got: ${handler}`,
-            });
-        }
-        switch (handler.type) {
-            case constants_1.EventHandlerTypes.BINDING_KEY: {
-                const { key } = handler;
-                if ((0, common_1.isEmpty)({ value: key })) {
-                    throw (0, core_1.getError)({
-                        message: `[EventBus][register] Invalid handler.key | name: ${name} | Got: ${key}`,
-                    });
-                }
-                return {
-                    invokeHandler: ({ event }) => container.get({ key }).handle({ event }),
-                    description: `binding-key:${key}`,
-                };
-            }
-            case constants_1.EventHandlerTypes.FUNCTION: {
-                const { fn } = handler;
-                if (typeof fn !== 'function') {
-                    throw (0, core_1.getError)({
-                        message: `[EventBus][register] Invalid handler.fn | name: ${name} | Expected a function | Got: ${typeof fn}`,
-                    });
-                }
-                return {
-                    invokeHandler: ({ event }) => fn({ event }),
-                    description: `function:${fn.name || 'anonymous'}`,
-                };
-            }
-            default: {
-                throw (0, core_1.getError)({
-                    message: `[EventBus][register] Unknown handler.type | name: ${name} | Expected one of: ${[...constants_1.EventHandlerTypes.SCHEME_SET].join(', ')} | Got: ${handler.type}`,
-                });
-            }
-        }
-    }
-    /**
-     * `retry` is optional and per REGISTRATION, not per publish: the right window belongs to the
-     * handler's own failure mode, and two handlers on the same event name may each pick their own.
-     * Omitting it reproduces today's `EventDispatchRetry` defaults exactly. Both `maxAttempts` and the
-     * total backoff window it implies are bounded - see `EventDispatchRetry` - and exceeding either
-     * throws here, at boot where a human sees it, rather than being silently clamped at dispatch time.
-     */
-    register(opts) {
-        const { name, handler, retry } = opts;
-        if ((0, common_1.isEmpty)({ value: name })) {
-            throw (0, core_1.getError)({
-                message: `[EventBus][register] Invalid registration | name: ${String(name)}`,
-            });
-        }
-        const maxAttempts = retry?.maxAttempts ?? constants_1.EventDispatchRetry.MAX_ATTEMPTS;
-        const baseDelayMs = retry?.baseDelayMs ?? constants_1.EventDispatchRetry.BASE_DELAY_MS;
-        EventBus.assertValidRetry({ name, maxAttempts, baseDelayMs });
-        const { invokeHandler, description } = EventBus.buildHandlerInvoker({
-            container: this.container,
-            handler,
-            name,
-        });
-        const registration = {
-            invokeHandler,
-            description,
-            maxAttempts,
-            baseDelayMs,
-        };
-        const existing = this.registrationsByName.get(name);
-        if (existing) {
-            existing.push(registration);
-            return;
-        }
-        this.registrationsByName.set(name, [registration]);
-    }
-    /**
-     * 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 registrations = this.registrationsByName.get(name);
-        if (!registrations?.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 registration of registrations) {
-            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, registration }).catch((error) => {
-                    this.logger.error('[publish] Unexpected dispatch failure | name: %s | Error: %s', event.name, error);
-                });
-            });
-        }
-    }
-    /**
-     * Attempts/backoff come from the registration (`EventDispatchRetry`'s defaults when omitted),
-     * always with full jitter - `RetryJitterModes.FULL` decorrelates a shared-resource pile-up hardest,
-     * so many handlers retrying the same lock do not collide on the same instant a second and third
-     * time. `invokeHandler` already encodes whether that re-resolves (`BINDING_KEY`) or was captured
-     * once (`FUNCTION`) - see `buildHandlerInvoker` - so this method calls it uniformly. A handler that
-     * throws synchronously is caught exactly like one that returns a rejected promise: `execution`
-     * here is itself `async`, and JS converts a synchronous throw inside an async function body into a
-     * rejection of that function's own promise - `RetryHelper.executeWithRetry`'s attempt loop never
-     * sees the difference.
-     *
-     * `RetryHelper.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, registration } = opts;
-        const { invokeHandler, description, maxAttempts, baseDelayMs } = registration;
-        let lastAttempt = 0;
-        try {
-            await core_1.RetryHelper.executeWithRetry({
-                operation: `EventBus.dispatch:${event.name}`,
-                maxAttempts,
-                backoff: {
-                    strategy: core_1.RetryBackoffStrategies.EXPONENTIAL,
-                    initialDelayMs: baseDelayMs,
-                    jitter: core_1.RetryJitterModes.FULL,
-                },
-                execution: async ({ attempt }) => {
-                    lastAttempt = attempt;
-                    await invokeHandler({ 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 | handler: %s | Error: %s', event.name, event.traceId, lastAttempt, description, error);
-        }
-    }
-}
-exports.EventBus = EventBus;
-//# sourceMappingURL=event-bus.js.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"event-bus.js","sourceRoot":"","sources":["../../../../src/base/events/event-bus.ts"],"names":[],"mappings":"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","sourcesContent":["import { isEmpty } from '@venizia/ignis-helpers/common';\nimport type { Container } from '@/helpers/inversion/container';\nimport type { AnyType, ValueOrPromise } from '@venizia/ignis-helpers/common';\nimport {\n  BaseHelper,\n  getError,\n  RetryBackoffStrategies,\n  RetryHelper,\n  RetryJitterModes,\n} from '@venizia/ignis-helpers/core';\nimport { EventDispatchRetry, EventHandlerTypes } from './common/constants';\nimport type {\n  IDomainEvent,\n  IEventHandler,\n  IEventHandlerRetryOptions,\n  TEventHandlerReference,\n} from './common/types';\n\ntype TEventHandlerInvoker = (opts: { event: IDomainEvent<unknown> }) => ValueOrPromise<void>;\n\n/** One `register`ed handler, resolved to concrete retry numbers and a ready-to-call invoker -\n * `EventDispatchRetry`'s defaults already applied and `handler`'s shape already resolved, so\n * `dispatch` never has to branch on either. */\ninterface IResolvedEventRegistration {\n  invokeHandler: TEventHandlerInvoker;\n  /** For the exhaustion log line only - a binding key or `<function fn.name>`. */\n  description: string;\n  maxAttempts: number;\n  baseDelayMs: number;\n}\n\n/** In-process, fire-and-forget domain event bus. `TPayloadMap` keys the event names, so a wrong name\n * or payload shape is a compile error. Delivery is always async. Retry timing is a property of the\n * handler's own failure mode, not of the event, so `register` may tune it per registration. But\n * nobody awaits a fire-and-forget dispatch, so an unbounded window would let one event hold a\n * handler - and whatever it holds open, e.g. a database connection - for an unbounded time with no\n * one to report it. What the bus guarantees instead: a bounded MAXIMUM time a single dispatch can\n * occupy, enforced as a hard ceiling at `register()` - see `EventDispatchRetry`. Retry makes\n * delivery at-least-once: handlers must be idempotent, see `IEventHandler`. */\nexport class EventBus<TPayloadMap extends object> extends BaseHelper {\n  private readonly container: Container;\n\n  /** `register` appends, never replaces - two handlers may share an event name, and replacing would\n   * drop the first with no way for the caller to notice. */\n  private readonly registrationsByName: Map<string, IResolvedEventRegistration[]>;\n\n  constructor(opts: { scope?: string; container: Container }) {\n    super({ scope: opts.scope ?? EventBus.name });\n    this.container = opts.container;\n    this.registrationsByName = new Map();\n  }\n\n  /** The pre-jitter total of every inter-attempt delay `maxAttempts`/`baseDelayMs` would produce -\n   * jitter (always on, see `dispatch`) only ever shrinks a delay, so this is a true upper bound. */\n  private static computeTotalWindowMs(opts: { maxAttempts: number; baseDelayMs: number }): number {\n    const { maxAttempts, baseDelayMs } = opts;\n    let totalWindowMs = 0;\n\n    for (let attempt = 1; attempt < maxAttempts; attempt++) {\n      totalWindowMs += RetryHelper.computeBackoffDelayMs({\n        attempt,\n        backoff: {\n          strategy: RetryBackoffStrategies.EXPONENTIAL,\n          initialDelayMs: baseDelayMs,\n          jitter: RetryJitterModes.NONE,\n        },\n      });\n    }\n\n    return totalWindowMs;\n  }\n\n  /** Loud rejection, never a silent clamp: a caller who believes a number the bus does not honour is\n   * worse off than one who sees the ceiling at boot. */\n  private static assertValidRetry(opts: {\n    name: string;\n    maxAttempts: number;\n    baseDelayMs: number;\n  }): void {\n    const { name, maxAttempts, baseDelayMs } = opts;\n\n    if (!Number.isInteger(maxAttempts) || maxAttempts < 1) {\n      throw getError({\n        message: `[EventBus][register] retry.maxAttempts must be a positive integer | name: ${name} | Got: ${maxAttempts}`,\n      });\n    }\n\n    if (!Number.isInteger(baseDelayMs) || baseDelayMs < 1) {\n      throw getError({\n        message: `[EventBus][register] retry.baseDelayMs must be a positive integer | name: ${name} | Got: ${baseDelayMs}`,\n      });\n    }\n\n    if (maxAttempts > EventDispatchRetry.MAX_ATTEMPTS_CEILING) {\n      throw getError({\n        message: `[EventBus][register] retry.maxAttempts exceeds the ceiling | name: ${name} | Got: ${maxAttempts} | Ceiling: ${EventDispatchRetry.MAX_ATTEMPTS_CEILING} | Lower retry.maxAttempts`,\n      });\n    }\n\n    const totalWindowMs = EventBus.computeTotalWindowMs({ maxAttempts, baseDelayMs });\n    if (totalWindowMs > EventDispatchRetry.MAX_TOTAL_WINDOW_MS) {\n      throw getError({\n        message: `[EventBus][register] retry window exceeds the ceiling | name: ${name} | Got: ${totalWindowMs}ms | Ceiling: ${EventDispatchRetry.MAX_TOTAL_WINDOW_MS}ms | Lower retry.maxAttempts or retry.baseDelayMs`,\n      });\n    }\n  }\n\n  /**\n   * Turns `handler` into a uniform invoker plus a description for the exhaustion log line.\n   * `BINDING_KEY` resolves through the container INSIDE the returned closure, so every call re-reads\n   * the current binding; `FUNCTION` calls `fn` directly, so the closure IS the resolution - there is\n   * nothing left to re-read on a later attempt. The tag (`handler.type`) is what this switches on,\n   * not which field happens to be present - see `EventHandlerTypes`' doc.\n   */\n  private static buildHandlerInvoker(opts: {\n    container: Container;\n    handler: TEventHandlerReference<AnyType>;\n    name: string;\n  }): { invokeHandler: TEventHandlerInvoker; description: string } {\n    const { container, handler, name } = opts;\n\n    if (isEmpty({ value: handler })) {\n      throw getError({\n        message: `[EventBus][register] Invalid handler | name: ${name} | Got: ${handler}`,\n      });\n    }\n\n    switch (handler.type) {\n      case EventHandlerTypes.BINDING_KEY: {\n        const { key } = handler;\n        if (isEmpty({ value: key })) {\n          throw getError({\n            message: `[EventBus][register] Invalid handler.key | name: ${name} | Got: ${key}`,\n          });\n        }\n\n        return {\n          invokeHandler: ({ event }) => container.get<IEventHandler>({ key }).handle({ event }),\n          description: `binding-key:${key}`,\n        };\n      }\n\n      case EventHandlerTypes.FUNCTION: {\n        const { fn } = handler;\n        if (typeof fn !== 'function') {\n          throw getError({\n            message: `[EventBus][register] Invalid handler.fn | name: ${name} | Expected a function | Got: ${typeof fn}`,\n          });\n        }\n\n        return {\n          invokeHandler: ({ event }) => fn({ event }),\n          description: `function:${fn.name || 'anonymous'}`,\n        };\n      }\n\n      default: {\n        throw getError({\n          message: `[EventBus][register] Unknown handler.type | name: ${name} | Expected one of: ${[...EventHandlerTypes.SCHEME_SET].join(', ')} | Got: ${(handler as { type?: unknown }).type}`,\n        });\n      }\n    }\n  }\n\n  /**\n   * `retry` is optional and per REGISTRATION, not per publish: the right window belongs to the\n   * handler's own failure mode, and two handlers on the same event name may each pick their own.\n   * Omitting it reproduces today's `EventDispatchRetry` defaults exactly. Both `maxAttempts` and the\n   * total backoff window it implies are bounded - see `EventDispatchRetry` - and exceeding either\n   * throws here, at boot where a human sees it, rather than being silently clamped at dispatch time.\n   */\n  register<K extends keyof TPayloadMap & string>(opts: {\n    name: K;\n    /** A `BINDING_KEY` reference re-resolves through the container on every retry attempt, so a\n     * rebind reaches a dispatch already in flight. A `FUNCTION` reference is captured as-is: a\n     * rebind has nothing to reach, and every attempt in a long retry window calls the exact `fn`\n     * registered here. */\n    handler: TEventHandlerReference<TPayloadMap[K]>;\n    retry?: IEventHandlerRetryOptions;\n  }): void {\n    const { name, handler, retry } = opts;\n\n    if (isEmpty({ value: name })) {\n      throw getError({\n        message: `[EventBus][register] Invalid registration | name: ${String(name)}`,\n      });\n    }\n\n    const maxAttempts = retry?.maxAttempts ?? EventDispatchRetry.MAX_ATTEMPTS;\n    const baseDelayMs = retry?.baseDelayMs ?? EventDispatchRetry.BASE_DELAY_MS;\n    EventBus.assertValidRetry({ name, maxAttempts, baseDelayMs });\n\n    const { invokeHandler, description } = EventBus.buildHandlerInvoker({\n      container: this.container,\n      handler,\n      name,\n    });\n\n    const registration: IResolvedEventRegistration = {\n      invokeHandler,\n      description,\n      maxAttempts,\n      baseDelayMs,\n    };\n\n    const existing = this.registrationsByName.get(name);\n    if (existing) {\n      existing.push(registration);\n      return;\n    }\n\n    this.registrationsByName.set(name, [registration]);\n  }\n\n  /**\n   * Never blocks and never throws back to the caller: dispatch runs outside this call's flow via\n   * `queueMicrotask`, and a handler failure is caught and logged where it happens (`dispatch`),\n   * never here.\n   */\n  publish<K extends keyof TPayloadMap & string>(opts: {\n    name: K;\n    payload: TPayloadMap[K];\n    traceId?: string;\n  }): void {\n    const { name, payload, traceId } = opts;\n\n    const event: IDomainEvent<TPayloadMap[K]> = {\n      name,\n      payload,\n      occurredAt: new Date().toISOString(),\n      traceId,\n    };\n\n    const registrations = this.registrationsByName.get(name);\n    if (!registrations?.length) {\n      // A typo is already a compile error, so at runtime this only means nobody is listening yet -\n      // a legitimate state on a fire-and-forget bus, not an incident.\n      this.logger.debug('[publish] No handler registered | name: %s | traceId: %s', name, traceId);\n      return;\n    }\n\n    for (const registration of registrations) {\n      queueMicrotask(() => {\n        // `dispatch` catches every failure path itself and never rejects - this `.catch` is an\n        // unreachable backstop, kept (and logged) rather than left floating, for the day it isn't.\n        this.dispatch({ event, registration }).catch((error: unknown) => {\n          this.logger.error(\n            '[publish] Unexpected dispatch failure | name: %s | Error: %s',\n            event.name,\n            error,\n          );\n        });\n      });\n    }\n  }\n\n  /**\n   * Attempts/backoff come from the registration (`EventDispatchRetry`'s defaults when omitted),\n   * always with full jitter - `RetryJitterModes.FULL` decorrelates a shared-resource pile-up hardest,\n   * so many handlers retrying the same lock do not collide on the same instant a second and third\n   * time. `invokeHandler` already encodes whether that re-resolves (`BINDING_KEY`) or was captured\n   * once (`FUNCTION`) - see `buildHandlerInvoker` - so this method calls it uniformly. A handler that\n   * throws synchronously is caught exactly like one that returns a rejected promise: `execution`\n   * here is itself `async`, and JS converts a synchronous throw inside an async function body into a\n   * rejection of that function's own promise - `RetryHelper.executeWithRetry`'s attempt loop never\n   * sees the difference.\n   *\n   * `RetryHelper.executeWithRetry` is used without its own `logger` - its internal per-attempt/exhaustion\n   * logging knows nothing about the event name or `traceId`, so it cannot be the trace anyone\n   * relies on. The one line below, logged only on final failure, is.\n   */\n  private async dispatch(opts: {\n    event: IDomainEvent<unknown>;\n    registration: IResolvedEventRegistration;\n  }): Promise<void> {\n    const { event, registration } = opts;\n    const { invokeHandler, description, maxAttempts, baseDelayMs } = registration;\n    let lastAttempt = 0;\n\n    try {\n      await RetryHelper.executeWithRetry({\n        operation: `EventBus.dispatch:${event.name}`,\n        maxAttempts,\n        backoff: {\n          strategy: RetryBackoffStrategies.EXPONENTIAL,\n          initialDelayMs: baseDelayMs,\n          jitter: RetryJitterModes.FULL,\n        },\n        execution: async ({ attempt }) => {\n          lastAttempt = attempt;\n          await invokeHandler({ event });\n        },\n      });\n    } catch (error) {\n      // The only trace this failure leaves: it is caught here and never reaches the publisher, so\n      // the event name, traceId and attempt count all have to be on this one line.\n      this.logger.error(\n        '[dispatch] Handler exhausted retries | name: %s | traceId: %s | attempts: %d | handler: %s | Error: %s',\n        event.name,\n        event.traceId,\n        lastAttempt,\n        description,\n        error,\n      );\n    }\n  }\n}\n"]}

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

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

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

@@ -1 +0,0 @@
-{"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/cjs/base/events/index.js

@@ -1,19 +0,0 @@
-"use strict";
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __exportStar = (this && this.__exportStar) || function(m, exports) {
-    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-__exportStar(require("./common"), exports);
-__exportStar(require("./event-bus"), exports);
-//# sourceMappingURL=index.js.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/base/events/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,2CAAyB;AACzB,8CAA4B","sourcesContent":["export * from './common';\nexport * from './event-bus';\n"]}

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

@@ -1,16 +0,0 @@
-export * from './applications';
-export * from './auth';
-export * from './components';
-export * from './configurations';
-export * from './controllers';
-export * from './datasources';
-export * from './events';
-export * from './metadata';
-export * from './middlewares';
-export * from './mixins';
-export * from './models';
-export * from './providers';
-export * from './repositories';
-export * from './request-context';
-export * from './services';
-//# sourceMappingURL=index.d.ts.map