@fluojs/cqrs 1.0.0-beta.5 → 1.0.0-beta.6

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를 발행하므로 입력 순서를 보존합니다. `CqrsModule.forRoot({ eventBus: { publish: { waitForHandlers: false } } })`로 설정한 경우 위임 발행 호출은 일치하는 `@OnEvent(...)` subscriber가 완료되기 전에 resolve될 수 있으므로, 이 모드에서 `publish(...)`와 `publishAll(...)`는 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가 settle될 때까지 기다린 뒤 stopped 상태로 전환합니다. `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를 관찰합니다.
 
@@ -153,7 +153,8 @@ class TokenInjectedService {
 
 ### 오류
 - `CommandHandlerNotFoundException`, `QueryHandlerNotFoundException`: bus에 일치하는 handler가 없을 때 발생합니다.
-- `DuplicateCommandHandlerError`, `DuplicateQueryHandlerError`, `DuplicateEventHandlerError`: 중복 handler registration에서 발생합니다.
+- `DuplicateCommandHandlerError`, `DuplicateQueryHandlerError`: 서로 다른 singleton provider가 같은 command 또는 query type을 claim할 때 발생합니다.
+- `DuplicateEventHandlerError`: 충돌하는 event-handler discovery 실패를 위해 export됩니다. 일반적으로 같은 event에 여러 `@EventHandler(...)` provider를 등록하는 것은 유효하며 discovery 순서대로 fan-out됩니다.
 - `SagaExecutionError`: 예상하지 못한 non-Fluo saga 실패를 감쌉니다.
 - `SagaTopologyError`: 자기 트리거, 순환, 또는 과도하게 깊은 in-process saga graph를 감지했을 때 발생합니다.
 

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. When `CqrsModule.forRoot({ eventBus: { publish: { waitForHandlers: false } } })` is configured, the delegated publication call can resolve before matching `@OnEvent(...)` subscribers finish, so `publish(...)` and `publishAll(...)` 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 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.
 
 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.
 
@@ -153,7 +153,8 @@ class TokenInjectedService {
 
 ### Errors
 - `CommandHandlerNotFoundException`, `QueryHandlerNotFoundException`: Raised when a bus has no matching handler.
-- `DuplicateCommandHandlerError`, `DuplicateQueryHandlerError`, `DuplicateEventHandlerError`: Raised for duplicate handler registrations.
+- `DuplicateCommandHandlerError`, `DuplicateQueryHandlerError`: Raised when different singleton providers claim the same command or query type.
+- `DuplicateEventHandlerError`: Exported for conflicting event-handler discovery failures; ordinary multiple `@EventHandler(...)` providers for the same event are valid and fan out in discovery order.
 - `SagaExecutionError`: Wraps unexpected non-Fluo saga failures.
 - `SagaTopologyError`: Raised when saga orchestration detects a self-triggering, cyclic, or over-deep in-process saga graph.
 

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

@@ -15,6 +15,7 @@ export declare class CqrsEventBusService extends CqrsBusBase implements CqrsEven
     private descriptors;
     private discoveryPromise;
     private discovered;
+    private readonly activePublishPipelines;
     private lifecycleState;
     constructor(eventBus: EventBus, sagaService: CqrsSagaLifecycleService, runtimeContainer: ConstructorParameters<typeof CqrsBusBase>[0], compiledModules: ConstructorParameters<typeof CqrsBusBase>[1], logger: ConstructorParameters<typeof CqrsBusBase>[2]);
     onApplicationBootstrap(): Promise<void>;
@@ -41,6 +42,9 @@ export declare class CqrsEventBusService extends CqrsBusBase implements CqrsEven
      * @returns A promise that resolves once all events are published.
      */
     publishAll<TEvent extends IEvent>(events: readonly TEvent[]): Promise<void>;
+    private runPublishPipeline;
+    private runPublishAllPipeline;
+    private trackPublishPipeline;
     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;IAOvH,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,WAAW;IAP9B,OAAO,CAAC,WAAW,CAAgC;IACnD,OAAO,CAAC,gBAAgB,CAA4B;IACpD,OAAO,CAAC,UAAU,CAAS;IAC3B,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;IAK5C;;;;OAIG;IACH,4BAA4B;IAY5B;;;;;;;OAOG;IACG,OAAO,CAAC,MAAM,SAAS,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAiBlE;;;;;OAKG;IACG,UAAU,CAAC,MAAM,SAAS,MAAM,EAAE,MAAM,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAMjF,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;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"}

package/dist/buses/event-bus.js

@@ -33,6 +33,7 @@ class CqrsEventBusService extends CqrsBusBase {
   descriptors = [];
   discoveryPromise;
   discovered = false;
+  activePublishPipelines = new Set();
   lifecycleState = 'created';
   constructor(eventBus, sagaService, runtimeContainer, compiledModules, logger) {
     super(runtimeContainer, compiledModules, logger);
@@ -51,6 +52,9 @@ class CqrsEventBusService extends CqrsBusBase {
   }
   async onApplicationShutdown() {
     this.lifecycleState = 'stopping';
+    while (this.activePublishPipelines.size > 0) {
+      await Promise.allSettled(Array.from(this.activePublishPipelines));
+    }
     this.lifecycleState = 'stopped';
   }
 
@@ -79,6 +83,19 @@ class CqrsEventBusService extends CqrsBusBase {
    * @throws {InvariantError} When a discovered provider does not implement `handle(event)`.
    */
   async publish(event) {
+    await this.trackPublishPipeline(this.runPublishPipeline(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) {
+    await this.trackPublishPipeline(this.runPublishAllPipeline(events));
+  }
+  async runPublishPipeline(event) {
     await this.ensureDiscovered();
     for (const descriptor of this.matchEventDescriptors(event)) {
       const instance = await this.resolveHandlerInstance(descriptor.token);
@@ -90,18 +107,19 @@ class CqrsEventBusService extends CqrsBusBase {
     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) {
+  async runPublishAllPipeline(events) {
     for (const event of events) {
       await this.publish(event);
     }
   }
+  async trackPublishPipeline(pipeline) {
+    this.activePublishPipelines.add(pipeline);
+    try {
+      await pipeline;
+    } finally {
+      this.activePublishPipelines.delete(pipeline);
+    }
+  }
   matchEventDescriptors(event) {
     return this.descriptors.filter(descriptor => event instanceof descriptor.eventType);
   }

package/dist/errors.d.ts

@@ -35,7 +35,11 @@ export declare class DuplicateQueryHandlerError extends FluoError {
      */
     constructor(message: string);
 }
-/** Raised when conflicting event-handler registrations break the CQRS discovery contract. */
+/**
+ * Raised when conflicting event-handler registrations break CQRS discovery invariants.
+ *
+ * Ordinary multiple `@EventHandler(...)` providers for the same event are valid and fan out.
+ */
 export declare class DuplicateEventHandlerError extends FluoError {
     /**
      * Creates a duplicate-event-handler error.

package/dist/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAEzC,wFAAwF;AACxF,qBAAa,+BAAgC,SAAQ,SAAS;IAC5D;;;;OAIG;gBACS,OAAO,EAAE,MAAM;CAG5B;AAED,iFAAiF;AACjF,qBAAa,4BAA6B,SAAQ,SAAS;IACzD;;;;OAIG;gBACS,OAAO,EAAE,MAAM;CAG5B;AAED,oFAAoF;AACpF,qBAAa,6BAA8B,SAAQ,SAAS;IAC1D;;;;OAIG;gBACS,OAAO,EAAE,MAAM;CAG5B;AAED,+EAA+E;AAC/E,qBAAa,0BAA2B,SAAQ,SAAS;IACvD;;;;OAIG;gBACS,OAAO,EAAE,MAAM;CAG5B;AAED,6FAA6F;AAC7F,qBAAa,0BAA2B,SAAQ,SAAS;IACvD;;;;OAIG;gBACS,OAAO,EAAE,MAAM;CAG5B;AAED,0EAA0E;AAC1E,qBAAa,kBAAmB,SAAQ,SAAS;IAC/C;;;;OAIG;gBACS,OAAO,EAAE,MAAM;CAG5B;AAED,8EAA8E;AAC9E,qBAAa,iBAAkB,SAAQ,SAAS;IAC9C;;;;OAIG;gBACS,OAAO,EAAE,MAAM;CAG5B"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAEzC,wFAAwF;AACxF,qBAAa,+BAAgC,SAAQ,SAAS;IAC5D;;;;OAIG;gBACS,OAAO,EAAE,MAAM;CAG5B;AAED,iFAAiF;AACjF,qBAAa,4BAA6B,SAAQ,SAAS;IACzD;;;;OAIG;gBACS,OAAO,EAAE,MAAM;CAG5B;AAED,oFAAoF;AACpF,qBAAa,6BAA8B,SAAQ,SAAS;IAC1D;;;;OAIG;gBACS,OAAO,EAAE,MAAM;CAG5B;AAED,+EAA+E;AAC/E,qBAAa,0BAA2B,SAAQ,SAAS;IACvD;;;;OAIG;gBACS,OAAO,EAAE,MAAM;CAG5B;AAED;;;;GAIG;AACH,qBAAa,0BAA2B,SAAQ,SAAS;IACvD;;;;OAIG;gBACS,OAAO,EAAE,MAAM;CAG5B;AAED,0EAA0E;AAC1E,qBAAa,kBAAmB,SAAQ,SAAS;IAC/C;;;;OAIG;gBACS,OAAO,EAAE,MAAM;CAG5B;AAED,8EAA8E;AAC9E,qBAAa,iBAAkB,SAAQ,SAAS;IAC9C;;;;OAIG;gBACS,OAAO,EAAE,MAAM;CAG5B"}

package/dist/errors.js

@@ -56,7 +56,11 @@ export class DuplicateQueryHandlerError extends FluoError {
   }
 }
 
-/** Raised when conflicting event-handler registrations break the CQRS discovery contract. */
+/**
+ * Raised when conflicting event-handler registrations break CQRS discovery invariants.
+ *
+ * Ordinary multiple `@EventHandler(...)` providers for the same event are valid and fan out.
+ */
 export class DuplicateEventHandlerError extends FluoError {
   /**
    * Creates a duplicate-event-handler error.

package/package.json

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