@fluojs/cqrs 1.0.0-beta.6 → 1.0.0

package/README.ko.md

@@ -110,7 +110,7 @@ Saga 실행은 같은 프로세스 안에서 동일 saga route로 순환 재진
 
 ### Event 발행 계약
 
-`CqrsEventBusService.publish(event)`는 CQRS event pipeline을 고정된 순서로 실행합니다. 먼저 일치하는 `@EventHandler(...)` provider를 실행하고, 그다음 일치하는 `@Saga(...)` provider를 실행한 뒤, 마지막으로 `@fluojs/event-bus`로 위임 발행합니다. `publishAll(events)`는 각 event의 CQRS handler, saga, 위임 발행 호출을 기다린 뒤 다음 event를 발행하므로 입력 순서를 보존합니다. 애플리케이션 shutdown 중에는 CQRS event bus가 진행 중인 `publish(...)` pipeline과 `publishAll(...)` sequence가 settle될 때까지 기다린 뒤 stopped 상태로 전환합니다. `CqrsModule.forRoot({ eventBus: { publish: { waitForHandlers: false } } })`로 설정한 경우 위임 발행 호출은 일치하는 `@OnEvent(...)` subscriber가 완료되기 전에 resolve될 수 있으므로, 이 모드에서 `publish(...)`, `publishAll(...)`, shutdown drain 완료는 subscriber 완료를 의미하지 않습니다.
+`CqrsEventBusService.publish(event)`는 CQRS event pipeline을 고정된 순서로 실행합니다. 먼저 일치하는 `@EventHandler(...)` provider를 실행하고, 그다음 일치하는 `@Saga(...)` provider를 실행한 뒤, 마지막으로 `@fluojs/event-bus`로 위임 발행합니다. `publishAll(events)`는 각 event의 CQRS handler, saga, 위임 발행 호출을 기다린 뒤 다음 event를 발행하므로 입력 순서를 보존합니다. 애플리케이션 shutdown 중에는 CQRS event bus가 진행 중인 `publish(...)` pipeline, `publishAll(...)` sequence, saga execution chain이 settle될 때까지 기다린 뒤 stopped 상태로 전환합니다. Shutdown drain은 기본값이 5000ms인 `CqrsModule.forRoot({ shutdown: { drainTimeoutMs } })`로 제한됩니다. CQRS handler, saga 또는 위임 publish chain이 이 bound 이후에도 멈춰 있으면 CQRS는 degraded status diagnostic을 기록하고 경고를 남긴 뒤 애플리케이션 close를 무기한 hang시키지 않고 계속 진행합니다. `CqrsModule.forRoot({ eventBus: { publish: { waitForHandlers: false } } })`로 설정한 경우 위임 발행 호출은 일치하는 `@OnEvent(...)` subscriber가 완료되기 전에 resolve될 수 있으므로, 이 모드에서 `publish(...)`, `publishAll(...)`, shutdown drain 완료는 subscriber 완료를 의미하지 않습니다.
 
 각 CQRS event handler와 saga는 매칭된 event prototype이 복원된 격리 event 복사본을 받습니다. 이 복사본을 mutate해도 변경은 현재 handler 또는 saga route 안에만 머물며, 다른 CQRS handler, saga, 원본 event 객체, 또는 위임된 `@fluojs/event-bus` subscriber에는 보이지 않습니다. 위임된 event-bus 발행은 CQRS side effect가 끝난 뒤 원본 event를 받으므로, `@OnEvent(...)` projection과 transport는 CQRS handler가 mutate한 복사본이 아니라 호출자가 소유한 payload를 관찰합니다.
 

package/README.md

@@ -110,7 +110,7 @@ Saga execution fails fast with `SagaTopologyError` when an in-process publish ch
 
 ### Event Publishing Contracts
 
-`CqrsEventBusService.publish(event)` runs the CQRS event pipeline in a fixed order: matching `@EventHandler(...)` providers first, matching `@Saga(...)` providers second, and delegated `@fluojs/event-bus` publication last. `publishAll(events)` preserves the input order by awaiting each event's CQRS handlers, sagas, and delegated publication call before publishing the next event. During application shutdown, the CQRS event bus waits for active `publish(...)` pipelines and `publishAll(...)` sequences to settle before marking itself stopped. When `CqrsModule.forRoot({ eventBus: { publish: { waitForHandlers: false } } })` is configured, the delegated publication call can resolve before matching `@OnEvent(...)` subscribers finish, so `publish(...)`, `publishAll(...)`, and shutdown drain completion do not imply subscriber completion in that mode.
+`CqrsEventBusService.publish(event)` runs the CQRS event pipeline in a fixed order: matching `@EventHandler(...)` providers first, matching `@Saga(...)` providers second, and delegated `@fluojs/event-bus` publication last. `publishAll(events)` preserves the input order by awaiting each event's CQRS handlers, sagas, and delegated publication call before publishing the next event. During application shutdown, the CQRS event bus waits for active `publish(...)` pipelines, `publishAll(...)` sequences, and saga execution chains to settle before marking itself stopped. Shutdown drain is bounded by `CqrsModule.forRoot({ shutdown: { drainTimeoutMs } })`, which defaults to 5000ms; if a CQRS handler, saga, or delegated publish chain is still stuck after the bound, CQRS records degraded status diagnostics, logs a warning, and lets application close continue instead of hanging indefinitely. When `CqrsModule.forRoot({ eventBus: { publish: { waitForHandlers: false } } })` is configured, the delegated publication call can resolve before matching `@OnEvent(...)` subscribers finish, so `publish(...)`, `publishAll(...)`, and shutdown drain completion do not imply subscriber completion in that mode.
 
 Each CQRS event handler and saga receives an isolated event copy with the matched event prototype restored. Mutating that copy is local to the current handler or saga route; those mutations are not visible to other CQRS handlers, sagas, the original event object, or delegated `@fluojs/event-bus` subscribers. The delegated event-bus publication receives the original event after CQRS side effects complete, so `@OnEvent(...)` projections and transports observe the caller-owned payload rather than a CQRS handler's mutated copy.
 

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

@@ -1,8 +1,9 @@
 import { type EventBus } from '@fluojs/event-bus';
 import type { OnApplicationShutdown, OnApplicationBootstrap } from '@fluojs/runtime';
 import { CqrsBusBase } from '../discovery.js';
-import { CqrsSagaLifecycleService } from './saga-bus.js';
+import type { CqrsModuleOptions } from '../module.js';
 import type { CqrsEventBus, IEvent } from '../types.js';
+import { CqrsSagaLifecycleService } from './saga-bus.js';
 /**
  * CQRS-facing event bus that dispatches local event handlers, sagas, and the shared event transport.
  *
@@ -12,12 +13,14 @@ import type { CqrsEventBus, IEvent } from '../types.js';
 export declare class CqrsEventBusService extends CqrsBusBase implements CqrsEventBus, OnApplicationBootstrap, OnApplicationShutdown {
     private readonly eventBus;
     private readonly sagaService;
+    private readonly moduleOptions;
     private descriptors;
     private discoveryPromise;
     private discovered;
     private readonly activePublishPipelines;
+    private shutdownDrainTimeouts;
     private lifecycleState;
-    constructor(eventBus: EventBus, sagaService: CqrsSagaLifecycleService, runtimeContainer: ConstructorParameters<typeof CqrsBusBase>[0], compiledModules: ConstructorParameters<typeof CqrsBusBase>[1], logger: ConstructorParameters<typeof CqrsBusBase>[2]);
+    constructor(eventBus: EventBus, sagaService: CqrsSagaLifecycleService, runtimeContainer: ConstructorParameters<typeof CqrsBusBase>[0], compiledModules: ConstructorParameters<typeof CqrsBusBase>[1], logger: ConstructorParameters<typeof CqrsBusBase>[2], moduleOptions?: CqrsModuleOptions);
     onApplicationBootstrap(): Promise<void>;
     onApplicationShutdown(): Promise<void>;
     /**
@@ -45,6 +48,9 @@ export declare class CqrsEventBusService extends CqrsBusBase implements CqrsEven
     private runPublishPipeline;
     private runPublishAllPipeline;
     private trackPublishPipeline;
+    private drainActivePublishPipelines;
+    private awaitShutdownDrain;
+    private resolveShutdownDrainTimeoutMs;
     private matchEventDescriptors;
     private ensureDiscovered;
     private discoverHandlers;

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

@@ -1 +1 @@
-{"version":3,"file":"event-bus.d.ts","sourceRoot":"","sources":["../../src/buses/event-bus.ts"],"names":[],"mappings":"AACA,OAAO,EAA+B,KAAK,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAC/E,OAAO,KAAK,EAAE,qBAAqB,EAAE,sBAAsB,EAAE,MAAM,iBAAiB,CAAC;AAGrF,OAAO,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAG9C,OAAO,EAAE,wBAAwB,EAAE,MAAM,eAAe,CAAC;AAEzD,OAAO,KAAK,EAAE,YAAY,EAAyC,MAAM,EAAiB,MAAM,aAAa,CAAC;AAU9G;;;;;GAKG;AACH,qBACa,mBAAoB,SAAQ,WAAY,YAAW,YAAY,EAAE,sBAAsB,EAAE,qBAAqB;IAQvH,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,WAAW;IAR9B,OAAO,CAAC,WAAW,CAAgC;IACnD,OAAO,CAAC,gBAAgB,CAA4B;IACpD,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,QAAQ,CAAC,sBAAsB,CAA4B;IACnE,OAAO,CAAC,cAAc,CAAsF;gBAGzF,QAAQ,EAAE,QAAQ,EAClB,WAAW,EAAE,wBAAwB,EACtD,gBAAgB,EAAE,qBAAqB,CAAC,OAAO,WAAW,CAAC,CAAC,CAAC,CAAC,EAC9D,eAAe,EAAE,qBAAqB,CAAC,OAAO,WAAW,CAAC,CAAC,CAAC,CAAC,EAC7D,MAAM,EAAE,qBAAqB,CAAC,OAAO,WAAW,CAAC,CAAC,CAAC,CAAC;IAKhD,sBAAsB,IAAI,OAAO,CAAC,IAAI,CAAC;IAYvC,qBAAqB,IAAI,OAAO,CAAC,IAAI,CAAC;IAU5C;;;;OAIG;IACH,4BAA4B;IAY5B;;;;;;;OAOG;IACG,OAAO,CAAC,MAAM,SAAS,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIlE;;;;;OAKG;IACG,UAAU,CAAC,MAAM,SAAS,MAAM,EAAE,MAAM,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;YAInE,kBAAkB;YAiBlB,qBAAqB;YAMrB,oBAAoB;IAUlC,OAAO,CAAC,qBAAqB;YAIf,gBAAgB;YAchB,gBAAgB;IAe9B,OAAO,CAAC,wBAAwB;CA4CjC"}
+{"version":3,"file":"event-bus.d.ts","sourceRoot":"","sources":["../../src/buses/event-bus.ts"],"names":[],"mappings":"AACA,OAAO,EAA+B,KAAK,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAC/E,OAAO,KAAK,EAAE,qBAAqB,EAAE,sBAAsB,EAAE,MAAM,iBAAiB,CAAC;AAGrF,OAAO,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAK9C,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AACtD,OAAO,KAAK,EAAE,YAAY,EAAyC,MAAM,EAAiB,MAAM,aAAa,CAAC;AAC9G,OAAO,EAAE,wBAAwB,EAAE,MAAM,eAAe,CAAC;AAYzD;;;;;GAKG;AACH,qBACa,mBAAoB,SAAQ,WAAY,YAAW,YAAY,EAAE,sBAAsB,EAAE,qBAAqB;IASvH,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,WAAW;IAI5B,OAAO,CAAC,QAAQ,CAAC,aAAa;IAbhC,OAAO,CAAC,WAAW,CAAgC;IACnD,OAAO,CAAC,gBAAgB,CAA4B;IACpD,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,QAAQ,CAAC,sBAAsB,CAA4B;IACnE,OAAO,CAAC,qBAAqB,CAAK;IAClC,OAAO,CAAC,cAAc,CAAsF;gBAGzF,QAAQ,EAAE,QAAQ,EAClB,WAAW,EAAE,wBAAwB,EACtD,gBAAgB,EAAE,qBAAqB,CAAC,OAAO,WAAW,CAAC,CAAC,CAAC,CAAC,EAC9D,eAAe,EAAE,qBAAqB,CAAC,OAAO,WAAW,CAAC,CAAC,CAAC,CAAC,EAC7D,MAAM,EAAE,qBAAqB,CAAC,OAAO,WAAW,CAAC,CAAC,CAAC,CAAC,EACnC,aAAa,GAAE,iBAAsB;IAKlD,sBAAsB,IAAI,OAAO,CAAC,IAAI,CAAC;IAYvC,qBAAqB,IAAI,OAAO,CAAC,IAAI,CAAC;IAU5C;;;;OAIG;IACH,4BAA4B;IAe5B;;;;;;;OAOG;IACG,OAAO,CAAC,MAAM,SAAS,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIlE;;;;;OAKG;IACG,UAAU,CAAC,MAAM,SAAS,MAAM,EAAE,MAAM,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;YAInE,kBAAkB;YAiBlB,qBAAqB;YAMrB,oBAAoB;YAUpB,2BAA2B;YAc3B,kBAAkB;IAiBhC,OAAO,CAAC,6BAA6B;IAUrC,OAAO,CAAC,qBAAqB;YAIf,gBAAgB;YAchB,gBAAgB;IAe9B,OAAO,CAAC,wBAAwB;CA4CjC"}

package/dist/buses/event-bus.js

@@ -10,8 +10,10 @@ import { APPLICATION_LOGGER, COMPILED_MODULES, RUNTIME_CONTAINER } from '@fluojs
 import { CqrsBusBase } from '../discovery.js';
 import { createIsolatedEvent } from '../event-clone.js';
 import { getEventHandlerMetadata } from '../metadata.js';
-import { CqrsSagaLifecycleService } from './saga-bus.js';
+import { CQRS_MODULE_OPTIONS } from '../tokens.js';
 import { createCqrsPlatformStatusSnapshot } from '../status.js';
+import { CqrsSagaLifecycleService } from './saga-bus.js';
+const DEFAULT_SHUTDOWN_DRAIN_TIMEOUT_MS = 5000;
 function isEventHandler(value) {
   if (typeof value !== 'object' || value === null) {
     return false;
@@ -28,17 +30,19 @@ function isEventHandler(value) {
 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;
+    [_CqrsEventBusService, _initClass] = _applyDecs(this, [Inject(FLUO_EVENT_BUS, CqrsSagaLifecycleService, RUNTIME_CONTAINER, COMPILED_MODULES, APPLICATION_LOGGER, CQRS_MODULE_OPTIONS)], [], 0, void 0, CqrsBusBase).c;
   }
   descriptors = [];
   discoveryPromise;
   discovered = false;
   activePublishPipelines = new Set();
+  shutdownDrainTimeouts = 0;
   lifecycleState = 'created';
-  constructor(eventBus, sagaService, runtimeContainer, compiledModules, logger) {
+  constructor(eventBus, sagaService, runtimeContainer, compiledModules, logger, moduleOptions = {}) {
     super(runtimeContainer, compiledModules, logger);
     this.eventBus = eventBus;
     this.sagaService = sagaService;
+    this.moduleOptions = moduleOptions;
   }
   async onApplicationBootstrap() {
     this.lifecycleState = 'discovering';
@@ -52,8 +56,8 @@ class CqrsEventBusService extends CqrsBusBase {
   }
   async onApplicationShutdown() {
     this.lifecycleState = 'stopping';
-    while (this.activePublishPipelines.size > 0) {
-      await Promise.allSettled(Array.from(this.activePublishPipelines));
+    if (this.activePublishPipelines.size > 0) {
+      await this.drainActivePublishPipelines();
     }
     this.lifecycleState = 'stopped';
   }
@@ -70,7 +74,10 @@ class CqrsEventBusService extends CqrsBusBase {
       inFlightSagaExecutions: sagaSnapshot.inFlightSagaExecutions,
       lifecycleState: this.lifecycleState,
       sagaLifecycleState: sagaSnapshot.lifecycleState,
-      sagasDiscovered: sagaSnapshot.sagasDiscovered
+      sagaShutdownDrainTimeouts: sagaSnapshot.shutdownDrainTimeouts,
+      sagasDiscovered: sagaSnapshot.sagasDiscovered,
+      shutdownDrainTimeoutMs: this.resolveShutdownDrainTimeoutMs(),
+      shutdownDrainTimeouts: this.shutdownDrainTimeouts
     });
   }
 
@@ -120,6 +127,36 @@ class CqrsEventBusService extends CqrsBusBase {
       this.activePublishPipelines.delete(pipeline);
     }
   }
+  async drainActivePublishPipelines() {
+    const activePipelines = Array.from(this.activePublishPipelines);
+    const timeoutMs = this.resolveShutdownDrainTimeoutMs();
+    const drained = await this.awaitShutdownDrain(activePipelines, timeoutMs);
+    if (!drained) {
+      this.shutdownDrainTimeouts += 1;
+      this.logger.warn(`CQRS event shutdown drain exceeded ${String(timeoutMs)}ms with ${String(activePipelines.length)} active publish pipeline(s); continuing shutdown.`, 'CqrsEventBusService');
+    }
+  }
+  async awaitShutdownDrain(activePipelines, timeoutMs) {
+    let timeoutId;
+    const timeout = new Promise(resolve => {
+      timeoutId = setTimeout(() => resolve(false), timeoutMs);
+    });
+    const drain = Promise.allSettled(activePipelines).then(() => true);
+    try {
+      return await Promise.race([drain, timeout]);
+    } finally {
+      if (timeoutId) {
+        clearTimeout(timeoutId);
+      }
+    }
+  }
+  resolveShutdownDrainTimeoutMs() {
+    const timeoutMs = this.moduleOptions.shutdown?.drainTimeoutMs;
+    if (typeof timeoutMs !== 'number' || !Number.isFinite(timeoutMs) || timeoutMs <= 0) {
+      return DEFAULT_SHUTDOWN_DRAIN_TIMEOUT_MS;
+    }
+    return Math.floor(timeoutMs);
+  }
   matchEventDescriptors(event) {
     return this.descriptors.filter(descriptor => event instanceof descriptor.eventType);
   }

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

@@ -1,5 +1,6 @@
 import type { OnApplicationBootstrap, OnApplicationShutdown } from '@fluojs/runtime';
 import { CqrsBusBase } from '../discovery.js';
+import type { CqrsModuleOptions } from '../module.js';
 import type { IEvent } from '../types.js';
 /**
  * Runtime saga coordinator that discovers `@Saga()` providers and serializes execution per saga token.
@@ -8,6 +9,7 @@ import type { IEvent } from '../types.js';
  * in-flight saga chains during shutdown so lifecycle guarantees remain predictable.
  */
 export declare class CqrsSagaLifecycleService extends CqrsBusBase implements OnApplicationBootstrap, OnApplicationShutdown {
+    private readonly moduleOptions;
     private descriptorsByEvent;
     private discoveryPromise;
     private discovered;
@@ -15,6 +17,8 @@ export declare class CqrsSagaLifecycleService extends CqrsBusBase implements OnA
     private lifecycleState;
     private readonly pendingDispatches;
     private readonly dispatchContext;
+    private shutdownDrainTimeouts;
+    constructor(runtimeContainer: ConstructorParameters<typeof CqrsBusBase>[0], compiledModules: ConstructorParameters<typeof CqrsBusBase>[1], logger: ConstructorParameters<typeof CqrsBusBase>[2], moduleOptions?: CqrsModuleOptions);
     onApplicationBootstrap(): Promise<void>;
     onApplicationShutdown(): Promise<void>;
     /**
@@ -27,6 +31,7 @@ export declare class CqrsSagaLifecycleService extends CqrsBusBase implements OnA
         inFlightSagaExecutions: number;
         lifecycleState: 'created' | 'discovering' | 'ready' | 'stopping' | 'stopped' | 'failed';
         sagasDiscovered: number;
+        shutdownDrainTimeouts: number;
     };
     /**
      * Dispatches one event to every matching saga descriptor.
@@ -37,6 +42,9 @@ export declare class CqrsSagaLifecycleService extends CqrsBusBase implements OnA
     dispatch<TEvent extends IEvent>(event: TEvent): Promise<void>;
     private matchSagaDescriptors;
     private dispatchWithOrdering;
+    private drainActiveSagaWork;
+    private awaitShutdownDrain;
+    private resolveShutdownDrainTimeoutMs;
     private runInDispatchContext;
     private invokeSaga;
     private ensureDiscovered;

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

@@ -1 +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"}
+{"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;AAK9C,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AACtD,OAAO,KAAK,EAAiB,MAAM,EAAyB,MAAM,aAAa,CAAC;AA2BhF;;;;;GAKG;AACH,qBACa,wBAAyB,SAAQ,WAAY,YAAW,sBAAsB,EAAE,qBAAqB;IAc9G,OAAO,CAAC,QAAQ,CAAC,aAAa;IAbhC,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;IAChF,OAAO,CAAC,qBAAqB,CAAK;gBAGhC,gBAAgB,EAAE,qBAAqB,CAAC,OAAO,WAAW,CAAC,CAAC,CAAC,CAAC,EAC9D,eAAe,EAAE,qBAAqB,CAAC,OAAO,WAAW,CAAC,CAAC,CAAC,CAAC,EAC7D,MAAM,EAAE,qBAAqB,CAAC,OAAO,WAAW,CAAC,CAAC,CAAC,CAAC,EACnC,aAAa,GAAE,iBAAsB;IAKlD,sBAAsB,IAAI,OAAO,CAAC,IAAI,CAAC;IAYvC,qBAAqB,IAAI,OAAO,CAAC,IAAI,CAAC;IAa5C;;;;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;QACxB,qBAAqB,EAAE,MAAM,CAAC;KAC/B;IAUD;;;;;OAKG;IACG,QAAQ,CAAC,MAAM,SAAS,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAYnE,OAAO,CAAC,oBAAoB;YAYd,oBAAoB;YA+CpB,mBAAmB;YAmBnB,kBAAkB;IAiBhC,OAAO,CAAC,6BAA6B;YAUvB,oBAAoB;YAepB,UAAU;YAoBV,gBAAgB;YAchB,gBAAgB;IAiB9B,OAAO,CAAC,uBAAuB;CA+ChC"}

package/dist/buses/saga-bus.js

@@ -11,7 +11,9 @@ import { CqrsBusBase } from '../discovery.js';
 import { SagaExecutionError, SagaTopologyError } from '../errors.js';
 import { createIsolatedEvent } from '../event-clone.js';
 import { getSagaMetadata } from '../metadata.js';
+import { CQRS_MODULE_OPTIONS } from '../tokens.js';
 const MAX_NESTED_SAGA_DEPTH = 32;
+const DEFAULT_SHUTDOWN_DRAIN_TIMEOUT_MS = 5000;
 function isSaga(value) {
   if (typeof value !== 'object' || value === null) {
     return false;
@@ -34,7 +36,7 @@ function toErrorMessage(error) {
 let _CqrsSagaLifecycleSer;
 class CqrsSagaLifecycleService extends CqrsBusBase {
   static {
-    [_CqrsSagaLifecycleSer, _initClass] = _applyDecs(this, [Inject(RUNTIME_CONTAINER, COMPILED_MODULES, APPLICATION_LOGGER)], [], 0, void 0, CqrsBusBase).c;
+    [_CqrsSagaLifecycleSer, _initClass] = _applyDecs(this, [Inject(RUNTIME_CONTAINER, COMPILED_MODULES, APPLICATION_LOGGER, CQRS_MODULE_OPTIONS)], [], 0, void 0, CqrsBusBase).c;
   }
   descriptorsByEvent = new Map();
   discoveryPromise;
@@ -43,6 +45,11 @@ class CqrsSagaLifecycleService extends CqrsBusBase {
   lifecycleState = 'created';
   pendingDispatches = new Set();
   dispatchContext = new AsyncLocalStorage();
+  shutdownDrainTimeouts = 0;
+  constructor(runtimeContainer, compiledModules, logger, moduleOptions = {}) {
+    super(runtimeContainer, compiledModules, logger);
+    this.moduleOptions = moduleOptions;
+  }
   async onApplicationBootstrap() {
     this.lifecycleState = 'discovering';
     try {
@@ -55,10 +62,7 @@ class CqrsSagaLifecycleService extends CqrsBusBase {
   }
   async onApplicationShutdown() {
     this.lifecycleState = 'stopping';
-    while (this.pendingDispatches.size > 0) {
-      await Promise.allSettled(Array.from(this.pendingDispatches));
-    }
-    await Promise.allSettled(this.executionChains.values());
+    await this.drainActiveSagaWork();
     this.executionChains.clear();
     this.handlerInstances.clear();
     this.descriptorsByEvent.clear();
@@ -77,7 +81,8 @@ class CqrsSagaLifecycleService extends CqrsBusBase {
       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
+      sagasDiscovered: new Set(Array.from(this.descriptorsByEvent.values()).flatMap(descriptors => descriptors.map(d => d.token))).size,
+      shutdownDrainTimeouts: this.shutdownDrainTimeouts
     };
   }
 
@@ -135,6 +140,39 @@ class CqrsSagaLifecycleService extends CqrsBusBase {
       this.pendingDispatches.delete(current);
     }
   }
+  async drainActiveSagaWork() {
+    const activeWork = [...this.pendingDispatches, ...this.executionChains.values()];
+    if (activeWork.length === 0) {
+      return;
+    }
+    const timeoutMs = this.resolveShutdownDrainTimeoutMs();
+    const drained = await this.awaitShutdownDrain(activeWork, timeoutMs);
+    if (!drained) {
+      this.shutdownDrainTimeouts += 1;
+      this.logger.warn(`CQRS saga shutdown drain exceeded ${String(timeoutMs)}ms with ${String(activeWork.length)} active saga task(s); continuing shutdown.`, 'CqrsSagaLifecycleService');
+    }
+  }
+  async awaitShutdownDrain(activeWork, timeoutMs) {
+    let timeoutId;
+    const timeout = new Promise(resolve => {
+      timeoutId = setTimeout(() => resolve(false), timeoutMs);
+    });
+    const drain = Promise.allSettled(activeWork).then(() => true);
+    try {
+      return await Promise.race([drain, timeout]);
+    } finally {
+      if (timeoutId) {
+        clearTimeout(timeoutId);
+      }
+    }
+  }
+  resolveShutdownDrainTimeoutMs() {
+    const timeoutMs = this.moduleOptions.shutdown?.drainTimeoutMs;
+    if (typeof timeoutMs !== 'number' || !Number.isFinite(timeoutMs) || timeoutMs <= 0) {
+      return DEFAULT_SHUTDOWN_DRAIN_TIMEOUT_MS;
+    }
+    return Math.floor(timeoutMs);
+  }
   async runInDispatchContext(activeContext, descriptor, routeLabel, callback) {
     const nextContext = {
       activeRoutes: [...(activeContext?.activeRoutes ?? []), {

package/dist/module.d.ts

@@ -11,6 +11,10 @@ export interface CqrsModuleOptions {
     global?: boolean;
     queryHandlers?: readonly QueryHandlerClass[];
     sagas?: readonly SagaClass[];
+    /** Shutdown drain policy for CQRS event pipelines and saga execution. `drainTimeoutMs` defaults to 5000ms. */
+    shutdown?: {
+        drainTimeoutMs?: number;
+    };
 }
 /**
  * Creates the providers required for CQRS buses, compatibility aliases, and optional handler registration.

package/dist/module.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"module.d.ts","sourceRoot":"","sources":["../src/module.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAC3C,OAAO,EAAkB,KAAK,qBAAqB,EAAE,MAAM,mBAAmB,CAAC;AAC/E,OAAO,EAAgB,KAAK,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAOhE,OAAO,KAAK,EACV,mBAAmB,EACnB,iBAAiB,EAIjB,iBAAiB,EACjB,SAAS,EACV,MAAM,YAAY,CAAC;AAEpB,4FAA4F;AAC5F,MAAM,WAAW,iBAAiB;IAChC,eAAe,CAAC,EAAE,SAAS,mBAAmB,EAAE,CAAC;IACjD,QAAQ,CAAC,EAAE,qBAAqB,CAAC;IACjC,aAAa,CAAC,EAAE,SAAS,iBAAiB,EAAE,CAAC;IAC7C,iFAAiF;IACjF,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,aAAa,CAAC,EAAE,SAAS,iBAAiB,EAAE,CAAC;IAC7C,KAAK,CAAC,EAAE,SAAS,SAAS,EAAE,CAAC;CAC9B;AAwBD;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,GAAE,iBAAsB,GAAG,QAAQ,EAAE,CA8B/E;AAED,iFAAiF;AACjF,qBAAa,UAAU;IACrB;;;;;OAKG;IACH,MAAM,CAAC,OAAO,CAAC,OAAO,GAAE,iBAAsB,GAAG,UAAU;CAiB5D"}
+{"version":3,"file":"module.d.ts","sourceRoot":"","sources":["../src/module.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAC3C,OAAO,EAAkB,KAAK,qBAAqB,EAAE,MAAM,mBAAmB,CAAC;AAC/E,OAAO,EAAgB,KAAK,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAOhE,OAAO,KAAK,EACV,mBAAmB,EACnB,iBAAiB,EAIjB,iBAAiB,EACjB,SAAS,EACV,MAAM,YAAY,CAAC;AAEpB,4FAA4F;AAC5F,MAAM,WAAW,iBAAiB;IAChC,eAAe,CAAC,EAAE,SAAS,mBAAmB,EAAE,CAAC;IACjD,QAAQ,CAAC,EAAE,qBAAqB,CAAC;IACjC,aAAa,CAAC,EAAE,SAAS,iBAAiB,EAAE,CAAC;IAC7C,iFAAiF;IACjF,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,aAAa,CAAC,EAAE,SAAS,iBAAiB,EAAE,CAAC;IAC7C,KAAK,CAAC,EAAE,SAAS,SAAS,EAAE,CAAC;IAC7B,8GAA8G;IAC9G,QAAQ,CAAC,EAAE;QACT,cAAc,CAAC,EAAE,MAAM,CAAC;KACzB,CAAC;CACH;AAwBD;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,GAAE,iBAAsB,GAAG,QAAQ,EAAE,CAkC/E;AAED,iFAAiF;AACjF,qBAAa,UAAU;IACrB;;;;;OAKG;IACH,MAAM,CAAC,OAAO,CAAC,OAAO,GAAE,iBAAsB,GAAG,UAAU;CAiB5D"}

package/dist/module.js

@@ -4,7 +4,7 @@ import { CommandBusLifecycleService } from './buses/command-bus.js';
 import { CqrsEventBusService } from './buses/event-bus.js';
 import { QueryBusLifecycleService } from './buses/query-bus.js';
 import { CqrsSagaLifecycleService } from './buses/saga-bus.js';
-import { COMMAND_BUS, EVENT_BUS, QUERY_BUS } from './tokens.js';
+import { COMMAND_BUS, CQRS_MODULE_OPTIONS, EVENT_BUS, QUERY_BUS } from './tokens.js';
 
 /** Module options for registering first-party handler classes and event-bus integration. */
 
@@ -32,7 +32,10 @@ function collectOptionHandlerProviders(options) {
  * @returns Providers for the command, query, event, and saga runtimes plus compatibility tokens.
  */
 export function createCqrsProviders(options = {}) {
-  return [CommandBusLifecycleService, {
+  return [{
+    provide: CQRS_MODULE_OPTIONS,
+    useValue: options
+  }, CommandBusLifecycleService, {
     inject: [CommandBusLifecycleService],
     provide: COMMAND_BUS,
     useFactory: service => ({

package/dist/status.d.ts

@@ -11,7 +11,10 @@ export interface CqrsStatusAdapterInput {
     inFlightSagaExecutions: number;
     lifecycleState: CqrsLifecycleState;
     sagaLifecycleState: CqrsLifecycleState;
+    sagaShutdownDrainTimeouts: number;
     sagasDiscovered: number;
+    shutdownDrainTimeoutMs: number;
+    shutdownDrainTimeouts: number;
 }
 /**
  * Describes the cqrs platform status snapshot contract.

package/dist/status.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"status.d.ts","sourceRoot":"","sources":["../src/status.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,uBAAuB,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAEvG;;GAEG;AACH,MAAM,MAAM,kBAAkB,GAAG,SAAS,GAAG,aAAa,GAAG,OAAO,GAAG,UAAU,GAAG,SAAS,GAAG,QAAQ,CAAC;AAEzG;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC,uBAAuB,EAAE,MAAM,CAAC;IAChC,sBAAsB,EAAE,MAAM,CAAC;IAC/B,cAAc,EAAE,kBAAkB,CAAC;IACnC,kBAAkB,EAAE,kBAAkB,CAAC;IACvC,eAAe,EAAE,MAAM,CAAC;CACzB;AAED;;GAEG;AACH,MAAM,WAAW,0BAA0B;IACzC,SAAS,EAAE,uBAAuB,CAAC;IACnC,MAAM,EAAE,oBAAoB,CAAC;IAC7B,SAAS,EAAE,gBAAgB,CAAC,WAAW,CAAC,CAAC;IACzC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC;AA4ED;;;;;GAKG;AACH,wBAAgB,gCAAgC,CAAC,KAAK,EAAE,sBAAsB,GAAG,0BAA0B,CAiB1G"}
+{"version":3,"file":"status.d.ts","sourceRoot":"","sources":["../src/status.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,uBAAuB,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAEvG;;GAEG;AACH,MAAM,MAAM,kBAAkB,GAAG,SAAS,GAAG,aAAa,GAAG,OAAO,GAAG,UAAU,GAAG,SAAS,GAAG,QAAQ,CAAC;AAEzG;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC,uBAAuB,EAAE,MAAM,CAAC;IAChC,sBAAsB,EAAE,MAAM,CAAC;IAC/B,cAAc,EAAE,kBAAkB,CAAC;IACnC,kBAAkB,EAAE,kBAAkB,CAAC;IACvC,yBAAyB,EAAE,MAAM,CAAC;IAClC,eAAe,EAAE,MAAM,CAAC;IACxB,sBAAsB,EAAE,MAAM,CAAC;IAC/B,qBAAqB,EAAE,MAAM,CAAC;CAC/B;AAED;;GAEG;AACH,MAAM,WAAW,0BAA0B;IACzC,SAAS,EAAE,uBAAuB,CAAC;IACnC,MAAM,EAAE,oBAAoB,CAAC;IAC7B,SAAS,EAAE,gBAAgB,CAAC,WAAW,CAAC,CAAC;IACzC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC;AAmFD;;;;;GAKG;AACH,wBAAgB,gCAAgC,CAAC,KAAK,EAAE,sBAAsB,GAAG,0BAA0B,CAoB1G"}

package/dist/status.js

@@ -57,6 +57,12 @@ function createHealth(input) {
       status: 'degraded'
     };
   }
+  if (input.shutdownDrainTimeouts > 0 || input.sagaShutdownDrainTimeouts > 0) {
+    return {
+      reason: 'CQRS event/saga pipeline reported bounded shutdown drain timeouts.',
+      status: 'degraded'
+    };
+  }
   return {
     status: 'healthy'
   };
@@ -76,7 +82,10 @@ export function createCqrsPlatformStatusSnapshot(input) {
       inFlightSagaExecutions: input.inFlightSagaExecutions,
       lifecycleState: input.lifecycleState,
       sagaLifecycleState: input.sagaLifecycleState,
-      sagasDiscovered: input.sagasDiscovered
+      sagaShutdownDrainTimeouts: input.sagaShutdownDrainTimeouts,
+      sagasDiscovered: input.sagasDiscovered,
+      shutdownDrainTimeoutMs: input.shutdownDrainTimeoutMs,
+      shutdownDrainTimeouts: input.shutdownDrainTimeouts
     },
     health: createHealth(input),
     ownership: {

package/dist/tokens.d.ts

@@ -6,4 +6,6 @@ export declare const COMMAND_BUS: Token<CommandBus>;
 export declare const QUERY_BUS: Token<QueryBus>;
 /** Compatibility injection token for the CQRS event bus facade. */
 export declare const EVENT_BUS: Token<CqrsEventBus>;
+/** Internal injection token for CQRS module options. */
+export declare const CQRS_MODULE_OPTIONS: Token<unknown>;
 //# sourceMappingURL=tokens.d.ts.map

package/dist/tokens.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tokens.d.ts","sourceRoot":"","sources":["../src/tokens.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,cAAc,CAAC;AAE1C,OAAO,KAAK,EAAE,UAAU,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAErE,gEAAgE;AAChE,eAAO,MAAM,WAAW,EAAE,KAAK,CAAC,UAAU,CAAuC,CAAC;AAClF,8DAA8D;AAC9D,eAAO,MAAM,SAAS,EAAE,KAAK,CAAC,QAAQ,CAAqC,CAAC;AAC5E,mEAAmE;AACnE,eAAO,MAAM,SAAS,EAAE,KAAK,CAAC,YAAY,CAAqC,CAAC"}
+{"version":3,"file":"tokens.d.ts","sourceRoot":"","sources":["../src/tokens.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,cAAc,CAAC;AAE1C,OAAO,KAAK,EAAE,UAAU,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAErE,gEAAgE;AAChE,eAAO,MAAM,WAAW,EAAE,KAAK,CAAC,UAAU,CAAuC,CAAC;AAClF,8DAA8D;AAC9D,eAAO,MAAM,SAAS,EAAE,KAAK,CAAC,QAAQ,CAAqC,CAAC;AAC5E,mEAAmE;AACnE,eAAO,MAAM,SAAS,EAAE,KAAK,CAAC,YAAY,CAAqC,CAAC;AAChF,wDAAwD;AACxD,eAAO,MAAM,mBAAmB,EAAE,KAAK,CAAC,OAAO,CAA0C,CAAC"}

package/dist/tokens.js

@@ -3,4 +3,6 @@ export const COMMAND_BUS = Symbol.for('fluo.cqrs.command-bus');
 /** Compatibility injection token for the query bus facade. */
 export const QUERY_BUS = Symbol.for('fluo.cqrs.query-bus');
 /** Compatibility injection token for the CQRS event bus facade. */
-export const EVENT_BUS = Symbol.for('fluo.cqrs.event-bus');
+export const EVENT_BUS = Symbol.for('fluo.cqrs.event-bus');
+/** Internal injection token for CQRS module options. */
+export const CQRS_MODULE_OPTIONS = Symbol.for('fluo.cqrs.module-options');

package/package.json

@@ -9,7 +9,7 @@
     "saga",
     "event-sourcing"
   ],
-  "version": "1.0.0-beta.6",
+  "version": "1.0.0",
   "private": false,
   "license": "MIT",
   "repository": {
@@ -36,10 +36,10 @@
     "dist"
   ],
   "dependencies": {
-    "@fluojs/core": "^1.0.0-beta.5",
-    "@fluojs/di": "^1.0.0-beta.7",
-    "@fluojs/event-bus": "^1.0.0-beta.6",
-    "@fluojs/runtime": "^1.0.0-beta.12"
+    "@fluojs/core": "^1.0.0",
+    "@fluojs/di": "^1.0.0",
+    "@fluojs/event-bus": "^1.0.0",
+    "@fluojs/runtime": "^1.0.0"
   },
   "devDependencies": {
     "vitest": "^3.2.4"