@fluojs/cqrs 1.0.0-beta.1

package/dist/buses/event-bus.js

@@ -0,0 +1,165 @@
+let _initClass;
+function _applyDecs(e, t, n, r, o, i) { var a, c, u, s, f, l, p, d = Symbol.metadata || Symbol.for("Symbol.metadata"), m = Object.defineProperty, h = Object.create, y = [h(null), h(null)], v = t.length; function g(t, n, r) { return function (o, i) { n && (i = o, o = e); for (var a = 0; a < t.length; a++) i = t[a].apply(o, r ? [i] : []); return r ? i : o; }; } function b(e, t, n, r) { if ("function" != typeof e && (r || void 0 !== e)) throw new TypeError(t + " must " + (n || "be") + " a function" + (r ? "" : " or undefined")); return e; } function applyDec(e, t, n, r, o, i, u, s, f, l, p) { function d(e) { if (!p(e)) throw new TypeError("Attempted to access private element on non-instance"); } var h = [].concat(t[0]), v = t[3], w = !u, D = 1 === o, S = 3 === o, j = 4 === o, E = 2 === o; function I(t, n, r) { return function (o, i) { return n && (i = o, o = e), r && r(o), P[t].call(o, i); }; } if (!w) { var P = {}, k = [], F = S ? "get" : j || D ? "set" : "value"; if (f ? (l || D ? P = { get: _setFunctionName(function () { return v(this); }, r, "get"), set: function (e) { t[4](this, e); } } : P[F] = v, l || _setFunctionName(P[F], r, E ? "" : F)) : l || (P = Object.getOwnPropertyDescriptor(e, r)), !l && !f) { if ((c = y[+s][r]) && 7 !== (c ^ o)) throw Error("Decorating two elements with the same name (" + P[F].name + ") is not supported yet"); y[+s][r] = o < 3 ? 1 : o; } } for (var N = e, O = h.length - 1; O >= 0; O -= n ? 2 : 1) { var T = b(h[O], "A decorator", "be", !0), z = n ? h[O - 1] : void 0, A = {}, H = { kind: ["field", "accessor", "method", "getter", "setter", "class"][o], name: r, metadata: a, addInitializer: function (e, t) { if (e.v) throw new TypeError("attempted to call addInitializer after decoration was finished"); b(t, "An initializer", "be", !0), i.push(t); }.bind(null, A) }; if (w) c = T.call(z, N, H), A.v = 1, b(c, "class decorators", "return") && (N = c);else if (H.static = s, H.private = f, c = H.access = { has: f ? p.bind() : function (e) { return r in e; } }, j || (c.get = f ? E ? function (e) { return d(e), P.value; } : I("get", 0, d) : function (e) { return e[r]; }), E || S || (c.set = f ? I("set", 0, d) : function (e, t) { e[r] = t; }), N = T.call(z, D ? { get: P.get, set: P.set } : P[F], H), A.v = 1, D) { if ("object" == typeof N && N) (c = b(N.get, "accessor.get")) && (P.get = c), (c = b(N.set, "accessor.set")) && (P.set = c), (c = b(N.init, "accessor.init")) && k.unshift(c);else if (void 0 !== N) throw new TypeError("accessor decorators must return an object with get, set, or init properties or undefined"); } else b(N, (l ? "field" : "method") + " decorators", "return") && (l ? k.unshift(N) : P[F] = N); } return o < 2 && u.push(g(k, s, 1), g(i, s, 0)), l || w || (f ? D ? u.splice(-1, 0, I("get", s), I("set", s)) : u.push(E ? P[F] : b.call.bind(P[F])) : m(e, r, P)), N; } function w(e) { return m(e, d, { configurable: !0, enumerable: !0, value: a }); } return void 0 !== i && (a = i[d]), a = h(null == a ? null : a), f = [], l = function (e) { e && f.push(g(e)); }, p = function (t, r) { for (var i = 0; i < n.length; i++) { var a = n[i], c = a[1], l = 7 & c; if ((8 & c) == t && !l == r) { var p = a[2], d = !!a[3], m = 16 & c; applyDec(t ? e : e.prototype, a, m, d ? "#" + p : _toPropertyKey(p), l, l < 2 ? [] : t ? s = s || [] : u = u || [], f, !!t, d, r, t && d ? function (t) { return _checkInRHS(t) === e; } : o); } } }, p(8, 0), p(0, 0), p(8, 1), p(0, 1), l(u), l(s), c = f, v || w(e), { e: c, get c() { var n = []; return v && [w(e = applyDec(e, [t], r, e.name, 5, n)), g(n, 1)]; } }; }
+function _toPropertyKey(t) { var i = _toPrimitive(t, "string"); return "symbol" == typeof i ? i : i + ""; }
+function _toPrimitive(t, r) { if ("object" != typeof t || !t) return t; var e = t[Symbol.toPrimitive]; if (void 0 !== e) { var i = e.call(t, r || "default"); if ("object" != typeof i) return i; throw new TypeError("@@toPrimitive must return a primitive value."); } return ("string" === r ? String : Number)(t); }
+function _setFunctionName(e, t, n) { "symbol" == typeof t && (t = (t = t.description) ? "[" + t + "]" : ""); try { Object.defineProperty(e, "name", { configurable: !0, value: n ? n + " " + t : t }); } catch (e) {} return e; }
+function _checkInRHS(e) { if (Object(e) !== e) throw TypeError("right-hand side of 'in' should be an object, got " + (null !== e ? typeof e : "null")); return e; }
+import { Inject, InvariantError } from '@fluojs/core';
+import { EVENT_BUS as FLUO_EVENT_BUS } from '@fluojs/event-bus';
+import { APPLICATION_LOGGER, COMPILED_MODULES, RUNTIME_CONTAINER } from '@fluojs/runtime/internal';
+import { CqrsBusBase } from '../discovery.js';
+import { createIsolatedEvent } from '../event-clone.js';
+import { getEventHandlerMetadata } from '../metadata.js';
+import { CqrsSagaLifecycleService } from './saga-bus.js';
+import { createCqrsPlatformStatusSnapshot } from '../status.js';
+function isEventHandler(value) {
+  if (typeof value !== 'object' || value === null) {
+    return false;
+  }
+  return typeof value.handle === 'function';
+}
+
+/**
+ * CQRS-facing event bus that dispatches local event handlers, sagas, and the shared event transport.
+ *
+ * This service keeps CQRS event handlers singleton-only, fans events into saga orchestration,
+ * and delegates the final publication step to `@fluojs/event-bus`.
+ */
+let _CqrsEventBusService;
+class CqrsEventBusService extends CqrsBusBase {
+  static {
+    [_CqrsEventBusService, _initClass] = _applyDecs(this, [Inject(FLUO_EVENT_BUS, CqrsSagaLifecycleService, RUNTIME_CONTAINER, COMPILED_MODULES, APPLICATION_LOGGER)], [], 0, void 0, CqrsBusBase).c;
+  }
+  descriptors = [];
+  discoveryPromise;
+  discovered = false;
+  lifecycleState = 'created';
+  constructor(eventBus, sagaService, runtimeContainer, compiledModules, logger) {
+    super(runtimeContainer, compiledModules, logger);
+    this.eventBus = eventBus;
+    this.sagaService = sagaService;
+  }
+  async onApplicationBootstrap() {
+    this.lifecycleState = 'discovering';
+    try {
+      await this.ensureDiscovered();
+      this.lifecycleState = 'ready';
+    } catch (error) {
+      this.lifecycleState = 'failed';
+      throw error;
+    }
+  }
+  async onApplicationShutdown() {
+    this.lifecycleState = 'stopping';
+    this.lifecycleState = 'stopped';
+  }
+
+  /**
+   * Creates a CQRS runtime status snapshot that includes local handler and saga state.
+   *
+   * @returns A structured snapshot describing CQRS event-handler discovery and saga lifecycle state.
+   */
+  createPlatformStatusSnapshot() {
+    const sagaSnapshot = this.sagaService.getRuntimeSnapshot();
+    return createCqrsPlatformStatusSnapshot({
+      eventHandlersDiscovered: this.descriptors.length,
+      inFlightSagaExecutions: sagaSnapshot.inFlightSagaExecutions,
+      lifecycleState: this.lifecycleState,
+      sagaLifecycleState: sagaSnapshot.lifecycleState,
+      sagasDiscovered: sagaSnapshot.sagasDiscovered
+    });
+  }
+
+  /**
+   * Publishes one event to matching CQRS handlers, sagas, and the shared event bus.
+   *
+   * @param event Event instance to publish.
+   * @returns A promise that resolves once all local CQRS side effects and delegated publication complete.
+   *
+   * @throws {InvariantError} When a discovered provider does not implement `handle(event)`.
+   */
+  async publish(event) {
+    await this.ensureDiscovered();
+    for (const descriptor of this.matchEventDescriptors(event)) {
+      const instance = await this.resolveHandlerInstance(descriptor.token);
+      if (!isEventHandler(instance)) {
+        throw new InvariantError(`Event handler ${descriptor.targetType.name} must implement handle(event).`);
+      }
+      await instance.handle(createIsolatedEvent(descriptor.eventType, event));
+    }
+    await this.sagaService.dispatch(event);
+    await this.eventBus.publish(event);
+  }
+
+  /**
+   * Publishes a batch of events sequentially through the CQRS event pipeline.
+   *
+   * @param events Event instances to publish in order.
+   * @returns A promise that resolves once all events are published.
+   */
+  async publishAll(events) {
+    for (const event of events) {
+      await this.publish(event);
+    }
+  }
+  matchEventDescriptors(event) {
+    return this.descriptors.filter(descriptor => event instanceof descriptor.eventType);
+  }
+  async ensureDiscovered() {
+    if (this.discovered) {
+      return;
+    }
+    if (this.discoveryPromise) {
+      await this.discoveryPromise;
+      return;
+    }
+    this.discoveryPromise = this.discoverHandlers();
+    await this.discoveryPromise;
+  }
+  async discoverHandlers() {
+    try {
+      this.descriptors = this.discoverEventDescriptors();
+      this.handlerInstances.clear();
+      for (const descriptor of this.descriptors) {
+        await this.preloadHandlerInstance(descriptor.token);
+      }
+      this.discovered = true;
+    } finally {
+      this.discoveryPromise = undefined;
+    }
+  }
+  discoverEventDescriptors() {
+    const descriptors = [];
+    const seenByTarget = new WeakMap();
+    for (const candidate of this.discoveryCandidates()) {
+      const metadata = getEventHandlerMetadata(candidate.targetType);
+      if (!metadata) {
+        continue;
+      }
+      if (candidate.scope !== 'singleton') {
+        this.logger.warn(`${candidate.targetType.name} in module ${candidate.moduleName} declares @EventHandler() but is registered with ${candidate.scope} scope. Event handlers are registered only for singleton providers.`, 'CqrsEventBusService');
+        continue;
+      }
+      const seenEventTypes = seenByTarget.get(candidate.targetType) ?? new Set();
+      if (seenEventTypes.has(metadata.eventType)) {
+        continue;
+      }
+      seenEventTypes.add(metadata.eventType);
+      seenByTarget.set(candidate.targetType, seenEventTypes);
+      const alreadyRegistered = descriptors.some(descriptor => descriptor.eventType === metadata.eventType && descriptor.targetType === candidate.targetType);
+      if (!alreadyRegistered) {
+        descriptors.push({
+          eventType: metadata.eventType,
+          moduleName: candidate.moduleName,
+          targetType: candidate.targetType,
+          token: candidate.token
+        });
+      }
+    }
+    return descriptors;
+  }
+  static {
+    _initClass();
+  }
+}
+export { _CqrsEventBusService as CqrsEventBusService };

package/dist/buses/query-bus.d.ts

@@ -0,0 +1,29 @@
+import { type OnApplicationBootstrap } from '@fluojs/runtime';
+import { CqrsBusBase } from '../discovery.js';
+import type { IQuery, QueryBus } from '../types.js';
+/**
+ * Discovers and executes query handlers during bootstrap and runtime dispatch.
+ *
+ * The query bus resolves singleton handlers only, warns on unsupported scopes,
+ * and preserves the one-query-to-one-handler contract used by the CQRS surface.
+ */
+export declare class QueryBusLifecycleService extends CqrsBusBase implements QueryBus, OnApplicationBootstrap {
+    private descriptors;
+    private discoveryPromise;
+    private discovered;
+    onApplicationBootstrap(): Promise<void>;
+    /**
+     * Executes one query by dispatching it to the discovered handler for its constructor.
+     *
+     * @param query Query instance to execute.
+     * @returns The resolved handler result.
+     *
+     * @throws {QueryHandlerNotFoundException} When no handler is registered for the query type.
+     * @throws {InvariantError} When the resolved provider does not implement `execute(query)`.
+     */
+    execute<TQuery extends IQuery<TResult>, TResult = unknown>(query: TQuery): Promise<TResult>;
+    private ensureDiscovered;
+    private discoverHandlers;
+    private discoverQueryDescriptors;
+}
+//# sourceMappingURL=query-bus.d.ts.map

package/dist/buses/query-bus.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"query-bus.d.ts","sourceRoot":"","sources":["../../src/buses/query-bus.ts"],"names":[],"mappings":"AACA,OAAO,EACL,KAAK,sBAAsB,EAC5B,MAAM,iBAAiB,CAAC;AAKzB,OAAO,EAAE,WAAW,EAAiC,MAAM,iBAAiB,CAAC;AAC7E,OAAO,KAAK,EACV,MAAM,EAEN,QAAQ,EAGT,MAAM,aAAa,CAAC;AAUrB;;;;;GAKG;AACH,qBACa,wBAAyB,SAAQ,WAAY,YAAW,QAAQ,EAAE,sBAAsB;IACnG,OAAO,CAAC,WAAW,CAAgD;IACnE,OAAO,CAAC,gBAAgB,CAA4B;IACpD,OAAO,CAAC,UAAU,CAAS;IAErB,sBAAsB,IAAI,OAAO,CAAC,IAAI,CAAC;IAI7C;;;;;;;;OAQG;IACG,OAAO,CAAC,MAAM,SAAS,MAAM,CAAC,OAAO,CAAC,EAAE,OAAO,GAAG,OAAO,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;YAmBnF,gBAAgB;YAchB,gBAAgB;IAe9B,OAAO,CAAC,wBAAwB;CAmDjC"}

package/dist/buses/query-bus.js

@@ -0,0 +1,122 @@
+let _initClass;
+function _applyDecs(e, t, n, r, o, i) { var a, c, u, s, f, l, p, d = Symbol.metadata || Symbol.for("Symbol.metadata"), m = Object.defineProperty, h = Object.create, y = [h(null), h(null)], v = t.length; function g(t, n, r) { return function (o, i) { n && (i = o, o = e); for (var a = 0; a < t.length; a++) i = t[a].apply(o, r ? [i] : []); return r ? i : o; }; } function b(e, t, n, r) { if ("function" != typeof e && (r || void 0 !== e)) throw new TypeError(t + " must " + (n || "be") + " a function" + (r ? "" : " or undefined")); return e; } function applyDec(e, t, n, r, o, i, u, s, f, l, p) { function d(e) { if (!p(e)) throw new TypeError("Attempted to access private element on non-instance"); } var h = [].concat(t[0]), v = t[3], w = !u, D = 1 === o, S = 3 === o, j = 4 === o, E = 2 === o; function I(t, n, r) { return function (o, i) { return n && (i = o, o = e), r && r(o), P[t].call(o, i); }; } if (!w) { var P = {}, k = [], F = S ? "get" : j || D ? "set" : "value"; if (f ? (l || D ? P = { get: _setFunctionName(function () { return v(this); }, r, "get"), set: function (e) { t[4](this, e); } } : P[F] = v, l || _setFunctionName(P[F], r, E ? "" : F)) : l || (P = Object.getOwnPropertyDescriptor(e, r)), !l && !f) { if ((c = y[+s][r]) && 7 !== (c ^ o)) throw Error("Decorating two elements with the same name (" + P[F].name + ") is not supported yet"); y[+s][r] = o < 3 ? 1 : o; } } for (var N = e, O = h.length - 1; O >= 0; O -= n ? 2 : 1) { var T = b(h[O], "A decorator", "be", !0), z = n ? h[O - 1] : void 0, A = {}, H = { kind: ["field", "accessor", "method", "getter", "setter", "class"][o], name: r, metadata: a, addInitializer: function (e, t) { if (e.v) throw new TypeError("attempted to call addInitializer after decoration was finished"); b(t, "An initializer", "be", !0), i.push(t); }.bind(null, A) }; if (w) c = T.call(z, N, H), A.v = 1, b(c, "class decorators", "return") && (N = c);else if (H.static = s, H.private = f, c = H.access = { has: f ? p.bind() : function (e) { return r in e; } }, j || (c.get = f ? E ? function (e) { return d(e), P.value; } : I("get", 0, d) : function (e) { return e[r]; }), E || S || (c.set = f ? I("set", 0, d) : function (e, t) { e[r] = t; }), N = T.call(z, D ? { get: P.get, set: P.set } : P[F], H), A.v = 1, D) { if ("object" == typeof N && N) (c = b(N.get, "accessor.get")) && (P.get = c), (c = b(N.set, "accessor.set")) && (P.set = c), (c = b(N.init, "accessor.init")) && k.unshift(c);else if (void 0 !== N) throw new TypeError("accessor decorators must return an object with get, set, or init properties or undefined"); } else b(N, (l ? "field" : "method") + " decorators", "return") && (l ? k.unshift(N) : P[F] = N); } return o < 2 && u.push(g(k, s, 1), g(i, s, 0)), l || w || (f ? D ? u.splice(-1, 0, I("get", s), I("set", s)) : u.push(E ? P[F] : b.call.bind(P[F])) : m(e, r, P)), N; } function w(e) { return m(e, d, { configurable: !0, enumerable: !0, value: a }); } return void 0 !== i && (a = i[d]), a = h(null == a ? null : a), f = [], l = function (e) { e && f.push(g(e)); }, p = function (t, r) { for (var i = 0; i < n.length; i++) { var a = n[i], c = a[1], l = 7 & c; if ((8 & c) == t && !l == r) { var p = a[2], d = !!a[3], m = 16 & c; applyDec(t ? e : e.prototype, a, m, d ? "#" + p : _toPropertyKey(p), l, l < 2 ? [] : t ? s = s || [] : u = u || [], f, !!t, d, r, t && d ? function (t) { return _checkInRHS(t) === e; } : o); } } }, p(8, 0), p(0, 0), p(8, 1), p(0, 1), l(u), l(s), c = f, v || w(e), { e: c, get c() { var n = []; return v && [w(e = applyDec(e, [t], r, e.name, 5, n)), g(n, 1)]; } }; }
+function _toPropertyKey(t) { var i = _toPrimitive(t, "string"); return "symbol" == typeof i ? i : i + ""; }
+function _toPrimitive(t, r) { if ("object" != typeof t || !t) return t; var e = t[Symbol.toPrimitive]; if (void 0 !== e) { var i = e.call(t, r || "default"); if ("object" != typeof i) return i; throw new TypeError("@@toPrimitive must return a primitive value."); } return ("string" === r ? String : Number)(t); }
+function _setFunctionName(e, t, n) { "symbol" == typeof t && (t = (t = t.description) ? "[" + t + "]" : ""); try { Object.defineProperty(e, "name", { configurable: !0, value: n ? n + " " + t : t }); } catch (e) {} return e; }
+function _checkInRHS(e) { if (Object(e) !== e) throw TypeError("right-hand side of 'in' should be an object, got " + (null !== e ? typeof e : "null")); return e; }
+import { Inject, InvariantError } from '@fluojs/core';
+import { APPLICATION_LOGGER, COMPILED_MODULES, RUNTIME_CONTAINER } from '@fluojs/runtime/internal';
+import { DuplicateQueryHandlerError, QueryHandlerNotFoundException } from '../errors.js';
+import { getQueryHandlerMetadata } from '../metadata.js';
+import { CqrsBusBase, createDuplicateHandlerMessage } from '../discovery.js';
+function isQueryHandler(value) {
+  if (typeof value !== 'object' || value === null) {
+    return false;
+  }
+  return typeof value.execute === 'function';
+}
+
+/**
+ * Discovers and executes query handlers during bootstrap and runtime dispatch.
+ *
+ * The query bus resolves singleton handlers only, warns on unsupported scopes,
+ * and preserves the one-query-to-one-handler contract used by the CQRS surface.
+ */
+let _QueryBusLifecycleSer;
+class QueryBusLifecycleService extends CqrsBusBase {
+  static {
+    [_QueryBusLifecycleSer, _initClass] = _applyDecs(this, [Inject(RUNTIME_CONTAINER, COMPILED_MODULES, APPLICATION_LOGGER)], [], 0, void 0, CqrsBusBase).c;
+  }
+  descriptors = new Map();
+  discoveryPromise;
+  discovered = false;
+  async onApplicationBootstrap() {
+    await this.ensureDiscovered();
+  }
+
+  /**
+   * Executes one query by dispatching it to the discovered handler for its constructor.
+   *
+   * @param query Query instance to execute.
+   * @returns The resolved handler result.
+   *
+   * @throws {QueryHandlerNotFoundException} When no handler is registered for the query type.
+   * @throws {InvariantError} When the resolved provider does not implement `execute(query)`.
+   */
+  async execute(query) {
+    await this.ensureDiscovered();
+    const queryType = query.constructor;
+    const descriptor = this.descriptors.get(queryType);
+    if (!descriptor) {
+      throw new QueryHandlerNotFoundException(`No query handler registered for ${queryType.name}.`);
+    }
+    const instance = await this.resolveHandlerInstance(descriptor.token);
+    if (!isQueryHandler(instance)) {
+      throw new InvariantError(`Query handler ${descriptor.targetType.name} must implement execute(query).`);
+    }
+    return await instance.execute(query);
+  }
+  async ensureDiscovered() {
+    if (this.discovered) {
+      return;
+    }
+    if (this.discoveryPromise) {
+      await this.discoveryPromise;
+      return;
+    }
+    this.discoveryPromise = this.discoverHandlers();
+    await this.discoveryPromise;
+  }
+  async discoverHandlers() {
+    try {
+      this.descriptors = this.discoverQueryDescriptors();
+      this.handlerInstances.clear();
+      for (const descriptor of this.descriptors.values()) {
+        await this.preloadHandlerInstance(descriptor.token);
+      }
+      this.discovered = true;
+    } finally {
+      this.discoveryPromise = undefined;
+    }
+  }
+  discoverQueryDescriptors() {
+    const descriptors = new Map();
+    const seenByTarget = new WeakMap();
+    for (const candidate of this.discoveryCandidates()) {
+      const metadata = getQueryHandlerMetadata(candidate.targetType);
+      if (!metadata) {
+        continue;
+      }
+      if (candidate.scope !== 'singleton') {
+        this.logger.warn(`${candidate.targetType.name} in module ${candidate.moduleName} declares @QueryHandler() but is registered with ${candidate.scope} scope. Query handlers are registered only for singleton providers.`, 'QueryBusLifecycleService');
+        continue;
+      }
+      const seenQueryTypes = seenByTarget.get(candidate.targetType) ?? new Set();
+      if (seenQueryTypes.has(metadata.queryType)) {
+        continue;
+      }
+      seenQueryTypes.add(metadata.queryType);
+      seenByTarget.set(candidate.targetType, seenQueryTypes);
+      const existing = descriptors.get(metadata.queryType);
+      if (existing && existing.targetType !== candidate.targetType) {
+        throw new DuplicateQueryHandlerError(createDuplicateHandlerMessage('query', metadata.queryType, existing, {
+          moduleName: candidate.moduleName,
+          targetType: candidate.targetType
+        }));
+      }
+      if (!existing) {
+        descriptors.set(metadata.queryType, {
+          moduleName: candidate.moduleName,
+          queryType: metadata.queryType,
+          targetType: candidate.targetType,
+          token: candidate.token
+        });
+      }
+    }
+    return descriptors;
+  }
+  static {
+    _initClass();
+  }
+}
+export { _QueryBusLifecycleSer as QueryBusLifecycleService };

package/dist/buses/saga-bus.d.ts

@@ -0,0 +1,46 @@
+import type { OnApplicationBootstrap, OnApplicationShutdown } from '@fluojs/runtime';
+import { CqrsBusBase } from '../discovery.js';
+import type { IEvent } from '../types.js';
+/**
+ * Runtime saga coordinator that discovers `@Saga()` providers and serializes execution per saga token.
+ *
+ * The service prevents re-entrant dispatch loops within the same async context and waits for
+ * in-flight saga chains during shutdown so lifecycle guarantees remain predictable.
+ */
+export declare class CqrsSagaLifecycleService extends CqrsBusBase implements OnApplicationBootstrap, OnApplicationShutdown {
+    private descriptorsByEvent;
+    private discoveryPromise;
+    private discovered;
+    private readonly executionChains;
+    private lifecycleState;
+    private readonly pendingDispatches;
+    private readonly dispatchContext;
+    onApplicationBootstrap(): Promise<void>;
+    onApplicationShutdown(): Promise<void>;
+    /**
+     * Returns an internal runtime snapshot used by the CQRS event bus and diagnostics.
+     *
+     * @returns Current discovery state, in-flight execution count, lifecycle state, and discovered saga count.
+     */
+    getRuntimeSnapshot(): {
+        discovered: boolean;
+        inFlightSagaExecutions: number;
+        lifecycleState: 'created' | 'discovering' | 'ready' | 'stopping' | 'stopped' | 'failed';
+        sagasDiscovered: number;
+    };
+    /**
+     * Dispatches one event to every matching saga descriptor.
+     *
+     * @param event Event instance that may trigger one or more sagas.
+     * @returns A promise that resolves once all matching saga chains for the event complete.
+     */
+    dispatch<TEvent extends IEvent>(event: TEvent): Promise<void>;
+    private matchSagaDescriptors;
+    private dispatchWithOrdering;
+    private runInDispatchContext;
+    private invokeSaga;
+    private ensureDiscovered;
+    private discoverHandlers;
+    private discoverSagaDescriptors;
+}
+//# sourceMappingURL=saga-bus.d.ts.map

package/dist/buses/saga-bus.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"saga-bus.d.ts","sourceRoot":"","sources":["../../src/buses/saga-bus.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,sBAAsB,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAGrF,OAAO,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAI9C,OAAO,KAAK,EAAiB,MAAM,EAAyB,MAAM,aAAa,CAAC;AA0BhF;;;;;GAKG;AACH,qBACa,wBAAyB,SAAQ,WAAY,YAAW,sBAAsB,EAAE,qBAAqB;IAChH,OAAO,CAAC,kBAAkB,CAA8C;IACxE,OAAO,CAAC,gBAAgB,CAA4B;IACpD,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAmC;IACnE,OAAO,CAAC,cAAc,CAAsF;IAC5G,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAA4B;IAC9D,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAgD;IAE1E,sBAAsB,IAAI,OAAO,CAAC,IAAI,CAAC;IAYvC,qBAAqB,IAAI,OAAO,CAAC,IAAI,CAAC;IAiB5C;;;;OAIG;IACH,kBAAkB,IAAI;QACpB,UAAU,EAAE,OAAO,CAAC;QACpB,sBAAsB,EAAE,MAAM,CAAC;QAC/B,cAAc,EAAE,SAAS,GAAG,aAAa,GAAG,OAAO,GAAG,UAAU,GAAG,SAAS,GAAG,QAAQ,CAAC;QACxF,eAAe,EAAE,MAAM,CAAC;KACzB;IASD;;;;;OAKG;IACG,QAAQ,CAAC,MAAM,SAAS,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAYnE,OAAO,CAAC,oBAAoB;YAYd,oBAAoB;YA+CpB,oBAAoB;YAepB,UAAU;YAoBV,gBAAgB;YAchB,gBAAgB;IAiB9B,OAAO,CAAC,uBAAuB;CA+ChC"}

package/dist/buses/saga-bus.js

@@ -0,0 +1,225 @@
+let _initClass;
+function _applyDecs(e, t, n, r, o, i) { var a, c, u, s, f, l, p, d = Symbol.metadata || Symbol.for("Symbol.metadata"), m = Object.defineProperty, h = Object.create, y = [h(null), h(null)], v = t.length; function g(t, n, r) { return function (o, i) { n && (i = o, o = e); for (var a = 0; a < t.length; a++) i = t[a].apply(o, r ? [i] : []); return r ? i : o; }; } function b(e, t, n, r) { if ("function" != typeof e && (r || void 0 !== e)) throw new TypeError(t + " must " + (n || "be") + " a function" + (r ? "" : " or undefined")); return e; } function applyDec(e, t, n, r, o, i, u, s, f, l, p) { function d(e) { if (!p(e)) throw new TypeError("Attempted to access private element on non-instance"); } var h = [].concat(t[0]), v = t[3], w = !u, D = 1 === o, S = 3 === o, j = 4 === o, E = 2 === o; function I(t, n, r) { return function (o, i) { return n && (i = o, o = e), r && r(o), P[t].call(o, i); }; } if (!w) { var P = {}, k = [], F = S ? "get" : j || D ? "set" : "value"; if (f ? (l || D ? P = { get: _setFunctionName(function () { return v(this); }, r, "get"), set: function (e) { t[4](this, e); } } : P[F] = v, l || _setFunctionName(P[F], r, E ? "" : F)) : l || (P = Object.getOwnPropertyDescriptor(e, r)), !l && !f) { if ((c = y[+s][r]) && 7 !== (c ^ o)) throw Error("Decorating two elements with the same name (" + P[F].name + ") is not supported yet"); y[+s][r] = o < 3 ? 1 : o; } } for (var N = e, O = h.length - 1; O >= 0; O -= n ? 2 : 1) { var T = b(h[O], "A decorator", "be", !0), z = n ? h[O - 1] : void 0, A = {}, H = { kind: ["field", "accessor", "method", "getter", "setter", "class"][o], name: r, metadata: a, addInitializer: function (e, t) { if (e.v) throw new TypeError("attempted to call addInitializer after decoration was finished"); b(t, "An initializer", "be", !0), i.push(t); }.bind(null, A) }; if (w) c = T.call(z, N, H), A.v = 1, b(c, "class decorators", "return") && (N = c);else if (H.static = s, H.private = f, c = H.access = { has: f ? p.bind() : function (e) { return r in e; } }, j || (c.get = f ? E ? function (e) { return d(e), P.value; } : I("get", 0, d) : function (e) { return e[r]; }), E || S || (c.set = f ? I("set", 0, d) : function (e, t) { e[r] = t; }), N = T.call(z, D ? { get: P.get, set: P.set } : P[F], H), A.v = 1, D) { if ("object" == typeof N && N) (c = b(N.get, "accessor.get")) && (P.get = c), (c = b(N.set, "accessor.set")) && (P.set = c), (c = b(N.init, "accessor.init")) && k.unshift(c);else if (void 0 !== N) throw new TypeError("accessor decorators must return an object with get, set, or init properties or undefined"); } else b(N, (l ? "field" : "method") + " decorators", "return") && (l ? k.unshift(N) : P[F] = N); } return o < 2 && u.push(g(k, s, 1), g(i, s, 0)), l || w || (f ? D ? u.splice(-1, 0, I("get", s), I("set", s)) : u.push(E ? P[F] : b.call.bind(P[F])) : m(e, r, P)), N; } function w(e) { return m(e, d, { configurable: !0, enumerable: !0, value: a }); } return void 0 !== i && (a = i[d]), a = h(null == a ? null : a), f = [], l = function (e) { e && f.push(g(e)); }, p = function (t, r) { for (var i = 0; i < n.length; i++) { var a = n[i], c = a[1], l = 7 & c; if ((8 & c) == t && !l == r) { var p = a[2], d = !!a[3], m = 16 & c; applyDec(t ? e : e.prototype, a, m, d ? "#" + p : _toPropertyKey(p), l, l < 2 ? [] : t ? s = s || [] : u = u || [], f, !!t, d, r, t && d ? function (t) { return _checkInRHS(t) === e; } : o); } } }, p(8, 0), p(0, 0), p(8, 1), p(0, 1), l(u), l(s), c = f, v || w(e), { e: c, get c() { var n = []; return v && [w(e = applyDec(e, [t], r, e.name, 5, n)), g(n, 1)]; } }; }
+function _toPropertyKey(t) { var i = _toPrimitive(t, "string"); return "symbol" == typeof i ? i : i + ""; }
+function _toPrimitive(t, r) { if ("object" != typeof t || !t) return t; var e = t[Symbol.toPrimitive]; if (void 0 !== e) { var i = e.call(t, r || "default"); if ("object" != typeof i) return i; throw new TypeError("@@toPrimitive must return a primitive value."); } return ("string" === r ? String : Number)(t); }
+function _setFunctionName(e, t, n) { "symbol" == typeof t && (t = (t = t.description) ? "[" + t + "]" : ""); try { Object.defineProperty(e, "name", { configurable: !0, value: n ? n + " " + t : t }); } catch (e) {} return e; }
+function _checkInRHS(e) { if (Object(e) !== e) throw TypeError("right-hand side of 'in' should be an object, got " + (null !== e ? typeof e : "null")); return e; }
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { Inject, InvariantError, FluoError } from '@fluojs/core';
+import { APPLICATION_LOGGER, COMPILED_MODULES, RUNTIME_CONTAINER } from '@fluojs/runtime/internal';
+import { CqrsBusBase } from '../discovery.js';
+import { SagaExecutionError, SagaTopologyError } from '../errors.js';
+import { createIsolatedEvent } from '../event-clone.js';
+import { getSagaMetadata } from '../metadata.js';
+const MAX_NESTED_SAGA_DEPTH = 32;
+function isSaga(value) {
+  if (typeof value !== 'object' || value === null) {
+    return false;
+  }
+  return typeof value.handle === 'function';
+}
+function toErrorMessage(error) {
+  if (error instanceof Error) {
+    return error.message;
+  }
+  return String(error);
+}
+
+/**
+ * Runtime saga coordinator that discovers `@Saga()` providers and serializes execution per saga token.
+ *
+ * The service prevents re-entrant dispatch loops within the same async context and waits for
+ * in-flight saga chains during shutdown so lifecycle guarantees remain predictable.
+ */
+let _CqrsSagaLifecycleSer;
+class CqrsSagaLifecycleService extends CqrsBusBase {
+  static {
+    [_CqrsSagaLifecycleSer, _initClass] = _applyDecs(this, [Inject(RUNTIME_CONTAINER, COMPILED_MODULES, APPLICATION_LOGGER)], [], 0, void 0, CqrsBusBase).c;
+  }
+  descriptorsByEvent = new Map();
+  discoveryPromise;
+  discovered = false;
+  executionChains = new Map();
+  lifecycleState = 'created';
+  pendingDispatches = new Set();
+  dispatchContext = new AsyncLocalStorage();
+  async onApplicationBootstrap() {
+    this.lifecycleState = 'discovering';
+    try {
+      await this.ensureDiscovered();
+      this.lifecycleState = 'ready';
+    } catch (error) {
+      this.lifecycleState = 'failed';
+      throw error;
+    }
+  }
+  async onApplicationShutdown() {
+    this.lifecycleState = 'stopping';
+    while (this.pendingDispatches.size > 0) {
+      await Promise.allSettled(Array.from(this.pendingDispatches));
+    }
+    await Promise.allSettled(this.executionChains.values());
+    this.executionChains.clear();
+    this.handlerInstances.clear();
+    this.descriptorsByEvent.clear();
+    this.discovered = false;
+    this.discoveryPromise = undefined;
+    this.lifecycleState = 'stopped';
+  }
+
+  /**
+   * Returns an internal runtime snapshot used by the CQRS event bus and diagnostics.
+   *
+   * @returns Current discovery state, in-flight execution count, lifecycle state, and discovered saga count.
+   */
+  getRuntimeSnapshot() {
+    return {
+      discovered: this.discovered,
+      inFlightSagaExecutions: this.pendingDispatches.size,
+      lifecycleState: this.lifecycleState,
+      sagasDiscovered: new Set(Array.from(this.descriptorsByEvent.values()).flatMap(descriptors => descriptors.map(d => d.token))).size
+    };
+  }
+
+  /**
+   * Dispatches one event to every matching saga descriptor.
+   *
+   * @param event Event instance that may trigger one or more sagas.
+   * @returns A promise that resolves once all matching saga chains for the event complete.
+   */
+  async dispatch(event) {
+    await this.ensureDiscovered();
+    const descriptors = this.matchSagaDescriptors(event);
+    if (descriptors.length === 0) {
+      return;
+    }
+    await Promise.all(descriptors.map(descriptor => this.dispatchWithOrdering(descriptor, event)));
+  }
+  matchSagaDescriptors(event) {
+    const descriptors = [];
+    for (const [eventType, eventDescriptors] of this.descriptorsByEvent.entries()) {
+      if (event instanceof eventType) {
+        descriptors.push(...eventDescriptors);
+      }
+    }
+    return descriptors;
+  }
+  async dispatchWithOrdering(descriptor, event) {
+    const activeContext = this.dispatchContext.getStore();
+    const routeLabel = `${descriptor.targetType.name}(${descriptor.eventType.name})`;
+    const isActiveRoute = activeContext?.activeRoutes.some(route => route.token === descriptor.token && route.eventType === descriptor.eventType);
+    const isActiveToken = activeContext?.activeRoutes.some(route => route.token === descriptor.token) ?? false;
+    if (isActiveRoute) {
+      throw new SagaTopologyError(`Saga ${descriptor.targetType.name} re-entered an unsafe cycle while handling ${descriptor.eventType.name}. ` + `Active saga path: ${[...(activeContext?.path ?? []), routeLabel].join(' -> ')}.`);
+    }
+    if ((activeContext?.depth ?? 0) >= MAX_NESTED_SAGA_DEPTH) {
+      throw new SagaTopologyError(`Saga ${descriptor.targetType.name} exceeded the maximum nested saga depth of ${MAX_NESTED_SAGA_DEPTH} while handling ${descriptor.eventType.name}. ` + 'Keep in-process saga graphs acyclic and externally bounded.');
+    }
+    if (isActiveToken) {
+      await this.runInDispatchContext(activeContext, descriptor, routeLabel, async () => {
+        await this.invokeSaga(descriptor, event);
+      });
+      return;
+    }
+    const previous = this.executionChains.get(descriptor.token) ?? Promise.resolve();
+    const current = previous.then(async () => {
+      await this.runInDispatchContext(activeContext, descriptor, routeLabel, async () => {
+        await this.invokeSaga(descriptor, event);
+      });
+    });
+    this.executionChains.set(descriptor.token, current.catch(() => undefined));
+    this.pendingDispatches.add(current);
+    try {
+      await current;
+    } finally {
+      this.pendingDispatches.delete(current);
+    }
+  }
+  async runInDispatchContext(activeContext, descriptor, routeLabel, callback) {
+    const nextContext = {
+      activeRoutes: [...(activeContext?.activeRoutes ?? []), {
+        eventType: descriptor.eventType,
+        token: descriptor.token
+      }],
+      depth: (activeContext?.depth ?? 0) + 1,
+      path: [...(activeContext?.path ?? []), routeLabel]
+    };
+    await this.dispatchContext.run(nextContext, callback);
+  }
+  async invokeSaga(descriptor, event) {
+    const instance = await this.resolveHandlerInstance(descriptor.token);
+    if (!isSaga(instance)) {
+      throw new InvariantError(`Saga ${descriptor.targetType.name} must implement handle(event).`);
+    }
+    try {
+      await instance.handle(createIsolatedEvent(descriptor.eventType, event));
+    } catch (error) {
+      if (error instanceof FluoError) {
+        throw error;
+      }
+      throw new SagaExecutionError(`Saga ${descriptor.targetType.name} failed while handling ${descriptor.eventType.name}: ${toErrorMessage(error)}`);
+    }
+  }
+  async ensureDiscovered() {
+    if (this.discovered) {
+      return;
+    }
+    if (this.discoveryPromise) {
+      await this.discoveryPromise;
+      return;
+    }
+    this.discoveryPromise = this.discoverHandlers();
+    await this.discoveryPromise;
+  }
+  async discoverHandlers() {
+    try {
+      this.descriptorsByEvent = this.discoverSagaDescriptors();
+      this.handlerInstances.clear();
+      for (const descriptors of this.descriptorsByEvent.values()) {
+        for (const descriptor of descriptors) {
+          await this.preloadHandlerInstance(descriptor.token);
+        }
+      }
+      this.discovered = true;
+    } finally {
+      this.discoveryPromise = undefined;
+    }
+  }
+  discoverSagaDescriptors() {
+    const descriptorsByEvent = new Map();
+    const seenByTarget = new WeakMap();
+    for (const candidate of this.discoveryCandidates()) {
+      const metadata = getSagaMetadata(candidate.targetType);
+      if (!metadata) {
+        continue;
+      }
+      if (candidate.scope !== 'singleton') {
+        this.logger.warn(`${candidate.targetType.name} in module ${candidate.moduleName} declares @Saga() but is registered with ${candidate.scope} scope. Sagas are registered only for singleton providers.`, 'CqrsSagaLifecycleService');
+        continue;
+      }
+      const seenEventTypes = seenByTarget.get(candidate.targetType) ?? new Set();
+      for (const eventType of metadata.eventTypes) {
+        if (seenEventTypes.has(eventType)) {
+          continue;
+        }
+        seenEventTypes.add(eventType);
+        const descriptors = descriptorsByEvent.get(eventType) ?? [];
+        if (!descriptors.some(descriptor => descriptor.targetType === candidate.targetType)) {
+          descriptors.push({
+            eventType,
+            moduleName: candidate.moduleName,
+            targetType: candidate.targetType,
+            token: candidate.token
+          });
+          descriptorsByEvent.set(eventType, descriptors);
+        }
+      }
+      seenByTarget.set(candidate.targetType, seenEventTypes);
+    }
+    return descriptorsByEvent;
+  }
+  static {
+    _initClass();
+  }
+}
+export { _CqrsSagaLifecycleSer as CqrsSagaLifecycleService };

package/dist/decorators.d.ts

@@ -0,0 +1,48 @@
+import type { CommandType, CqrsEventType, QueryType } from './types.js';
+type ClassDecoratorLike = (value: Function, context: ClassDecoratorContext) => void;
+/**
+ * Associates a singleton provider class with one command type.
+ *
+ * @param commandType Command constructor handled by the decorated class.
+ * @returns A class decorator that stores command-handler metadata for discovery.
+ *
+ * @example
+ * ```ts
+ * import { CommandHandler, type ICommandHandler } from '@fluojs/cqrs';
+ *
+ * class CreateUserCommand {
+ *   constructor(public readonly name: string) {}
+ * }
+ *
+ * @CommandHandler(CreateUserCommand)
+ * export class CreateUserHandler implements ICommandHandler<CreateUserCommand, string> {
+ *   async execute(command: CreateUserCommand) {
+ *     return command.name;
+ *   }
+ * }
+ * ```
+ */
+export declare function CommandHandler(commandType: CommandType): ClassDecoratorLike;
+/**
+ * Associates a singleton provider class with one query type.
+ *
+ * @param queryType Query constructor handled by the decorated class.
+ * @returns A class decorator that stores query-handler metadata for discovery.
+ */
+export declare function QueryHandler(queryType: QueryType): ClassDecoratorLike;
+/**
+ * Associates a singleton provider class with one event type.
+ *
+ * @param eventType Event constructor handled by the decorated class.
+ * @returns A class decorator that stores event-handler metadata for discovery.
+ */
+export declare function EventHandler(eventType: CqrsEventType): ClassDecoratorLike;
+/**
+ * Marks a singleton provider class as a saga listener for one or more event types.
+ *
+ * @param eventTypeOrTypes One event constructor or a list of constructors that should trigger the saga.
+ * @returns A class decorator that stores saga metadata for discovery.
+ */
+export declare function Saga(eventTypeOrTypes: CqrsEventType | readonly CqrsEventType[]): ClassDecoratorLike;
+export {};
+//# sourceMappingURL=decorators.d.ts.map

package/dist/decorators.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"decorators.d.ts","sourceRoot":"","sources":["../src/decorators.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAEV,WAAW,EACX,aAAa,EAGb,SAAS,EAEV,MAAM,YAAY,CAAC;AAEpB,KAAK,kBAAkB,GAAG,CAAC,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE,qBAAqB,KAAK,IAAI,CAAC;AA0DpF;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,cAAc,CAAC,WAAW,EAAE,WAAW,GAAG,kBAAkB,CAU3E;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,SAAS,EAAE,SAAS,GAAG,kBAAkB,CAUrE;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,SAAS,EAAE,aAAa,GAAG,kBAAkB,CAUzE;AAED;;;;;GAKG;AACH,wBAAgB,IAAI,CAAC,gBAAgB,EAAE,aAAa,GAAG,SAAS,aAAa,EAAE,GAAG,kBAAkB,CAYnG"}