@fluojs/cqrs - npm Package Compare versions

Comparing version 1.1.1 to 1.1.2

dist/buses/event-bus.d.ts

@@ -52,2 +52,3 @@ import { type EventBus } from '@fluojs/event-bus';
     private runPublishAllPipeline;
+    private assertAcceptingNewWork;
     private trackPublishPipeline;
@@ -54,0 +55,0 @@ private drainActivePublishPipelines;

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

@@ -1,1 +0,1 @@
-{"version":3,"file":"event-bus.d.ts","sourceRoot":"","sources":["../../src/buses/event-bus.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,QAAQ,EAA+B,MAAM,mBAAmB,CAAC;AAC/E,OAAO,KAAK,EAAE,sBAAsB,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAGrF,OAAO,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAG9C,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAGtD,OAAO,KAAK,EAAE,mBAAmB,EAAE,YAAY,EAAyC,MAAM,EAAiB,MAAM,aAAa,CAAC;AACnI,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;;;;;;;;OAQG;IACG,OAAO,CAAC,MAAM,SAAS,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC;IAIjG;;;;;;OAMG;IACG,UAAU,CAAC,MAAM,SAAS,MAAM,EAAE,MAAM,EAAE,SAAS,MAAM,EAAE,EAAE,OAAO,CAAC,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC;YAIlG,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"}
+{"version":3,"file":"event-bus.d.ts","sourceRoot":"","sources":["../../src/buses/event-bus.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,QAAQ,EAA+B,MAAM,mBAAmB,CAAC;AAC/E,OAAO,KAAK,EAAE,sBAAsB,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAGrF,OAAO,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAG9C,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAGtD,OAAO,KAAK,EAAE,mBAAmB,EAAE,YAAY,EAAyC,MAAM,EAAiB,MAAM,aAAa,CAAC;AACnI,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;;;;;;;;OAQG;IACG,OAAO,CAAC,MAAM,SAAS,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC;IAKjG;;;;;;OAMG;IACG,UAAU,CAAC,MAAM,SAAS,MAAM,EAAE,MAAM,EAAE,SAAS,MAAM,EAAE,EAAE,OAAO,CAAC,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC;YAKlG,kBAAkB;YAiBlB,qBAAqB;IAMnC,OAAO,CAAC,sBAAsB;YAMhB,oBAAoB;YAUpB,2BAA2B;YAc3B,kBAAkB;IAiBhC,OAAO,CAAC,6BAA6B;IAUrC,OAAO,CAAC,qBAAqB;YAIf,gBAAgB;YAchB,gBAAgB;IAe9B,OAAO,CAAC,wBAAwB;CA4CjC"}

dist/buses/event-bus.js

@@ -94,2 +94,3 @@ let _initClass;
   async publish(event, context) {
+    this.assertAcceptingNewWork('publish');
     await this.trackPublishPipeline(this.runPublishPipeline(event, context));
@@ -106,2 +107,3 @@ }
   async publishAll(events, context) {
+    this.assertAcceptingNewWork('publishAll');
     await this.trackPublishPipeline(this.runPublishAllPipeline(events, context));
@@ -118,3 +120,5 @@ }
     }
-    await this.sagaService.dispatch(event, context);
+    await this.sagaService.dispatch(event, context, {
+      allowDuringShutdown: true
+    });
     await this.eventBus.publish(event);
@@ -124,5 +128,10 @@ }
     for (const event of events) {
-      await this.publish(event, context);
+      await this.runPublishPipeline(event, context);
     }
   }
+  assertAcceptingNewWork(operation) {
+    if (this.lifecycleState === 'stopping' || this.lifecycleState === 'stopped') {
+      throw new InvariantError(`CQRS event bus cannot ${operation} after shutdown has started.`);
+    }
+  }
   async trackPublishPipeline(pipeline) {
@@ -129,0 +138,0 @@ this.activePublishPipelines.add(pipeline);

dist/buses/saga-bus.d.ts

@@ -5,6 +5,9 @@ import type { OnApplicationBootstrap, OnApplicationShutdown } from '@fluojs/runtime';
 import type { CqrsDispatchContext, IEvent } from '../types.js';
+interface SagaDispatchOptions {
+    readonly allowDuringShutdown?: boolean;
+}
 /**
  * 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
+ * The service prevents re-entrant dispatch loops within the same explicit dispatch context and waits for
  * in-flight saga chains during shutdown so lifecycle guarantees remain predictable.
@@ -42,3 +45,4 @@ */
      */
-    dispatch<TEvent extends IEvent>(event: TEvent, context?: CqrsDispatchContext): Promise<void>;
+    dispatch<TEvent extends IEvent>(event: TEvent, context?: CqrsDispatchContext, options?: SagaDispatchOptions): Promise<void>;
+    private assertAcceptingNewWork;
     private matchSagaDescriptors;
@@ -55,2 +59,3 @@ private dispatchWithOrdering;
 }
+export {};
 //# sourceMappingURL=saga-bus.d.ts.map

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

@@ -1,1 +0,1 @@
-{"version":3,"file":"saga-bus.d.ts","sourceRoot":"","sources":["../../src/buses/saga-bus.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,sBAAsB,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAGrF,OAAO,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAI9C,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAEtD,OAAO,KAAK,EAAE,mBAAmB,EAAiB,MAAM,EAAyB,MAAM,aAAa,CAAC;AAqBrG;;;;;GAKG;AACH,qBACa,wBAAyB,SAAQ,WAAY,YAAW,sBAAsB,EAAE,qBAAqB;IAa9G,OAAO,CAAC,QAAQ,CAAC,aAAa;IAZhC,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,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,EAAE,OAAO,CAAC,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC;IAYlG,OAAO,CAAC,oBAAoB;YAYd,oBAAoB;YAyCpB,mBAAmB;YAmBnB,kBAAkB;IAiBhC,OAAO,CAAC,6BAA6B;IAUrC,OAAO,CAAC,qBAAqB;YAYf,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":"AACA,OAAO,KAAK,EAAE,sBAAsB,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAGrF,OAAO,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAI9C,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAEtD,OAAO,KAAK,EAAE,mBAAmB,EAAiB,MAAM,EAAyB,MAAM,aAAa,CAAC;AAMrG,UAAU,mBAAmB;IAC3B,QAAQ,CAAC,mBAAmB,CAAC,EAAE,OAAO,CAAC;CACxC;AAsCD;;;;;GAKG;AACH,qBACa,wBAAyB,SAAQ,WAAY,YAAW,sBAAsB,EAAE,qBAAqB;IAa9G,OAAO,CAAC,QAAQ,CAAC,aAAa;IAZhC,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,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,EAAE,OAAO,CAAC,EAAE,mBAAmB,EAAE,OAAO,GAAE,mBAAwB,GAAG,OAAO,CAAC,IAAI,CAAC;IAarI,OAAO,CAAC,sBAAsB;IAU9B,OAAO,CAAC,oBAAoB;YAYd,oBAAoB;YA0CpB,mBAAmB;YAmBnB,kBAAkB;IAiBhC,OAAO,CAAC,6BAA6B;IAUrC,OAAO,CAAC,qBAAqB;YAaf,UAAU;YAoBV,gBAAgB;YAchB,gBAAgB;IAiB9B,OAAO,CAAC,uBAAuB;CA+ChC"}

dist/buses/saga-bus.js

@@ -16,2 +16,3 @@ let _initClass;
 const DEFAULT_SHUTDOWN_DRAIN_TIMEOUT_MS = 5000;
+const cqrsDispatchContextStateBrand = Symbol('fluo.cqrs.dispatchContextState');
 function isSaga(value) {
@@ -29,2 +30,8 @@ if (typeof value !== 'object' || value === null) {
 }
+function isCqrsDispatchContextState(context) {
+  if (typeof context !== 'object' || context === null) {
+    return false;
+  }
+  return context[cqrsDispatchContextStateBrand] === true;
+}
 
@@ -34,3 +41,3 @@ /**
  *
- * The service prevents re-entrant dispatch loops within the same async context and waits for
+ * The service prevents re-entrant dispatch loops within the same explicit dispatch context and waits for
  * in-flight saga chains during shutdown so lifecycle guarantees remain predictable.
@@ -96,3 +103,4 @@ */
    */
-  async dispatch(event, context) {
+  async dispatch(event, context, options = {}) {
+    this.assertAcceptingNewWork(options);
     await this.ensureDiscovered();
@@ -105,2 +113,10 @@ const descriptors = this.matchSagaDescriptors(event);
   }
+  assertAcceptingNewWork(options) {
+    if (options.allowDuringShutdown) {
+      return;
+    }
+    if (this.lifecycleState === 'stopping' || this.lifecycleState === 'stopped') {
+      throw new InvariantError('CQRS saga bus cannot dispatch after shutdown has started.');
+    }
+  }
   matchSagaDescriptors(event) {
@@ -116,13 +132,14 @@ const descriptors = [];
   async dispatchWithOrdering(descriptor, event, activeContext) {
+    const activeState = isCqrsDispatchContextState(activeContext) ? activeContext : undefined;
     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;
+    const isActiveRoute = activeState?.activeRoutes.some(route => route.token === descriptor.token && route.eventType === descriptor.eventType);
+    const isActiveToken = activeState?.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(' -> ')}.`);
+      throw new SagaTopologyError(`Saga ${descriptor.targetType.name} re-entered an unsafe cycle while handling ${descriptor.eventType.name}. ` + `Active saga path: ${[...(activeState?.path ?? []), routeLabel].join(' -> ')}.`);
     }
-    if ((activeContext?.depth ?? 0) >= MAX_NESTED_SAGA_DEPTH) {
+    if ((activeState?.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.invokeSaga(descriptor, event, this.createDispatchContext(activeContext, descriptor, routeLabel));
+      await this.invokeSaga(descriptor, event, this.createDispatchContext(activeState, descriptor, routeLabel));
       return;
@@ -132,3 +149,3 @@ }
     const current = previous.then(async () => {
-      await this.invokeSaga(descriptor, event, this.createDispatchContext(activeContext, descriptor, routeLabel));
+      await this.invokeSaga(descriptor, event, this.createDispatchContext(activeState, descriptor, routeLabel));
     });
@@ -178,2 +195,3 @@ this.executionChains.set(descriptor.token, current.catch(() => undefined));
     return {
+      [cqrsDispatchContextStateBrand]: true,
       activeRoutes: [...(activeContext?.activeRoutes ?? []), {
@@ -180,0 +198,0 @@ eventType: descriptor.eventType,

dist/module.d.ts

@@ -1,2 +0,1 @@
-import type { Provider } from '@fluojs/di';
 import { type EventBusModuleOptions } from '@fluojs/event-bus';
@@ -19,9 +18,2 @@ import { type ModuleType } from '@fluojs/runtime';
 }
-/**
- * Creates the providers required for CQRS buses, compatibility aliases, and optional handler registration.
- *
- * @param options CQRS module options including eager handler classes and event-bus configuration.
- * @returns Providers for the command, query, event, and saga runtimes plus compatibility tokens.
- */
-export declare function createCqrsProviders(options?: CqrsModuleOptions): Provider[];
 /** Runtime module entrypoint for CQRS bus registration and handler discovery. */
@@ -28,0 +20,0 @@ export declare class CqrsModule {

dist/module.d.ts.map

@@ -1,1 +0,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,EAEnB,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;AA0CD;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,GAAE,iBAAsB,GAAG,QAAQ,EAAE,CA8C/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":"AACA,OAAO,EAAkB,KAAK,qBAAqB,EAAE,MAAM,mBAAmB,CAAC;AAC/E,OAAO,EAAgB,KAAK,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAOhE,OAAO,KAAK,EACV,mBAAmB,EAEnB,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;AAgGD,iFAAiF;AACjF,qBAAa,UAAU;IACrB;;;;;OAKG;IACH,MAAM,CAAC,OAAO,CAAC,OAAO,GAAE,iBAAsB,GAAG,UAAU;CAiB5D"}

dist/module.js

@@ -49,3 +49,3 @@ import { EventBusModule } from '@fluojs/event-bus';
  */
-export function createCqrsProviders(options = {}) {
+function createCqrsProviders(options = {}) {
   return [{
@@ -52,0 +52,0 @@ provide: CQRS_MODULE_OPTIONS,

dist/types.d.ts

@@ -59,15 +59,8 @@ import type { Token } from '@fluojs/core';
  *
- * Pass this value unchanged from handlers and sagas into nested `execute(...)`, `publish(...)`,
- * or `publishAll(...)` calls. Application code should not inspect or construct it directly.
+ * CQRS passes this value to command handlers, query handlers, event handlers, and sagas when a
+ * nested dispatch chain is active. Application code should pass the value through unchanged to
+ * nested `execute(...)`, `publish(...)`, or `publishAll(...)` calls. The context intentionally
+ * exposes no public topology fields and should not be inspected or constructed by callers.
  */
 export interface CqrsDispatchContext {
-    /** Saga routes currently active in the in-process CQRS dispatch chain. */
-    readonly activeRoutes: readonly Readonly<{
-        eventType: CqrsEventType;
-        token: Token;
-    }>[];
-    /** Current nested saga depth for in-process topology guarding. */
-    readonly depth: number;
-    /** Human-readable saga route labels used when reporting topology failures. */
-    readonly path: readonly string[];
 }
@@ -74,0 +67,0 @@ /** Constructor type used to identify a command message class. */

dist/types.d.ts.map

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

package.json

@@ -12,3 +12,3 @@ {
   ],
-  "version": "1.1.1",
+  "version": "1.1.2",
   "private": false,
@@ -42,4 +42,4 @@ "license": "MIT",
     "@fluojs/di": "^1.1.0",
-    "@fluojs/event-bus": "^1.0.0",
-    "@fluojs/runtime": "^1.1.7"
+    "@fluojs/event-bus": "^1.0.1",
+    "@fluojs/runtime": "^1.1.8"
   },
@@ -46,0 +46,0 @@ "devDependencies": {

README.ko.md

@@ -13,2 +13,3 @@ # @fluojs/cqrs
 - [공통 패턴](#공통-패턴)
+  - [Read Projection](#read-projection)
   - [Saga 프로세스 매니저](#saga-프로세스-매니저)
@@ -83,2 +84,63 @@ - [Event 발행 계약](#event-발행-계약)
 
+### Read Projection
+
+Read projection은 query에 맞춘 데이터를 write model과 분리해서 유지합니다. write가 성공한 뒤 domain event를 publish하고, `@EventHandler(...)`에서 projection을 갱신한 다음, `@QueryHandler(...)`에서 그 denormalized view를 제공합니다.
+
+```typescript
+import { Inject } from '@fluojs/core';
+import {
+  EventHandler,
+  IEvent,
+  IEventHandler,
+  IQuery,
+  IQueryHandler,
+  QueryHandler,
+} from '@fluojs/cqrs';
+
+interface OrderSummaryView {
+  id: string;
+  customerId: string;
+  status: 'placed';
+}
+
+class OrderPlacedEvent implements IEvent {
+  constructor(
+    public readonly orderId: string,
+    public readonly customerId: string,
+  ) {}
+}
+
+class GetOrderSummaryQuery implements IQuery<OrderSummaryView | undefined> {
+  constructor(public readonly orderId: string) {}
+}
+
+@Inject(OrderSummaryProjectionStore)
+@EventHandler(OrderPlacedEvent)
+class OrderSummaryProjectionHandler implements IEventHandler<OrderPlacedEvent> {
+  constructor(private readonly store: OrderSummaryProjectionStore) {}
+
+  async handle(event: OrderPlacedEvent): Promise<void> {
+    await this.store.upsert({
+      id: event.orderId,
+      customerId: event.customerId,
+      status: 'placed',
+    });
+  }
+}
+
+@Inject(OrderSummaryProjectionStore)
+@QueryHandler(GetOrderSummaryQuery)
+class GetOrderSummaryHandler
+  implements IQueryHandler<GetOrderSummaryQuery, OrderSummaryView | undefined>
+{
+  constructor(private readonly store: OrderSummaryProjectionStore) {}
+
+  async execute(query: GetOrderSummaryQuery): Promise<OrderSummaryView | undefined> {
+    return this.store.findById(query.orderId);
+  }
+}
+```
+
+`CqrsModule.forRoot(...)`를 import하는 애플리케이션 모듈에 projection handler, query handler, projection store를 singleton provider로 등록하세요. `CqrsEventBusService.publish(new OrderPlacedEvent(...))`는 일치하는 `@EventHandler(...)` provider를 saga와 위임 `@fluojs/event-bus` 발행보다 먼저 실행하므로, read model은 문서화된 CQRS event pipeline을 통해 write-side fact를 관찰합니다. Event replay, retry, 외부 transport가 같은 business fact를 두 번 이상 전달할 수 있으므로 projection handler는 idempotent하게 유지하세요.
+
 ### Saga 프로세스 매니저
@@ -113,7 +175,7 @@
 
-Saga, command handler, query handler, event handler 안에서 다시 CQRS `execute(...)`, `publish(...)`, `publishAll(...)`를 호출할 때는 optional `CqrsDispatchContext` 인자를 그대로 전달하세요. CQRS는 이 명시적인 runtime-agnostic context로 Node.js async-local API에 의존하지 않고 nested dispatch 전반의 saga topology check를 유지합니다.
+Saga, command handler, query handler, event handler 안에서 다시 CQRS `execute(...)`, `publish(...)`, `publishAll(...)`를 호출할 때는 optional `CqrsDispatchContext` 인자를 그대로 전달하세요. CQRS는 이 명시적인 runtime-agnostic context로 Node.js async-local API에 의존하지 않고 nested dispatch 전반의 saga topology check를 유지합니다. 이 context는 opaque입니다. 직접 생성하거나 검사하거나 topology field에 의존하지 마세요. 해당 field는 내부 runtime state입니다.
 
 ### 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, 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 완료를 의미하지 않습니다.
+`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이 시작되면 새로운 `publish(...)`, `publishAll(...)`, direct saga dispatch 호출은 거부됩니다. 이미 진행 중인 publish와 saga 작업은 bounded shutdown window 안에서 계속 drain됩니다. 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 완료를 의미하지 않습니다.
 
@@ -158,3 +220,3 @@ 각 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를 관찰합니다.
 - `ICommandHandler<C, R>`, `IQueryHandler<Q, R>`, `IEventHandler<E>`, `ISaga<E>`: 핸들러 계약입니다.
-- `CqrsDispatchContext`: handler와 saga에서 nested CQRS dispatch로 그대로 전달하는 opaque optional context 값입니다.
+- `CqrsDispatchContext`: handler와 saga에서 nested CQRS dispatch로 그대로 전달하는 opaque optional context 값입니다. 공개 field를 노출하지 않으며, provider assembly는 공개 `createCqrsProviders(...)` helper가 아니라 `CqrsModule.forRoot(...)` facade 뒤에 유지됩니다.
 
@@ -161,0 +223,0 @@ ### 오류

README.md

@@ -13,2 +13,3 @@ # @fluojs/cqrs
 - [Common Patterns](#common-patterns)
+  - [Read Projections](#read-projections)
   - [Saga Process Managers](#saga-process-managers)
@@ -83,2 +84,63 @@ - [Event Publishing Contracts](#event-publishing-contracts)
 
+### Read Projections
+
+Read projections keep query-shaped data separate from the write model. Publish a domain event after the write succeeds, update the projection from an `@EventHandler(...)`, and serve that denormalized view from a `@QueryHandler(...)`.
+
+```typescript
+import { Inject } from '@fluojs/core';
+import {
+  EventHandler,
+  IEvent,
+  IEventHandler,
+  IQuery,
+  IQueryHandler,
+  QueryHandler,
+} from '@fluojs/cqrs';
+
+interface OrderSummaryView {
+  id: string;
+  customerId: string;
+  status: 'placed';
+}
+
+class OrderPlacedEvent implements IEvent {
+  constructor(
+    public readonly orderId: string,
+    public readonly customerId: string,
+  ) {}
+}
+
+class GetOrderSummaryQuery implements IQuery<OrderSummaryView | undefined> {
+  constructor(public readonly orderId: string) {}
+}
+
+@Inject(OrderSummaryProjectionStore)
+@EventHandler(OrderPlacedEvent)
+class OrderSummaryProjectionHandler implements IEventHandler<OrderPlacedEvent> {
+  constructor(private readonly store: OrderSummaryProjectionStore) {}
+
+  async handle(event: OrderPlacedEvent): Promise<void> {
+    await this.store.upsert({
+      id: event.orderId,
+      customerId: event.customerId,
+      status: 'placed',
+    });
+  }
+}
+
+@Inject(OrderSummaryProjectionStore)
+@QueryHandler(GetOrderSummaryQuery)
+class GetOrderSummaryHandler
+  implements IQueryHandler<GetOrderSummaryQuery, OrderSummaryView | undefined>
+{
+  constructor(private readonly store: OrderSummaryProjectionStore) {}
+
+  async execute(query: GetOrderSummaryQuery): Promise<OrderSummaryView | undefined> {
+    return this.store.findById(query.orderId);
+  }
+}
+```
+
+Register the projection handler, query handler, and projection store as singleton providers in the same application module that imports `CqrsModule.forRoot(...)`. `CqrsEventBusService.publish(new OrderPlacedEvent(...))` runs matching `@EventHandler(...)` providers before sagas and delegated `@fluojs/event-bus` publication, so the read model observes the write-side fact through the documented CQRS event pipeline. Keep projection handlers idempotent because event replay, retries, or external transports can deliver the same business fact more than once.
+
 ### Saga Process Managers
@@ -113,7 +175,7 @@
 
-When a saga, command handler, query handler, or event handler performs another CQRS `execute(...)`, `publish(...)`, or `publishAll(...)` call, pass the optional `CqrsDispatchContext` argument through unchanged. CQRS uses this explicit runtime-agnostic context to keep saga topology checks intact across nested dispatch without relying on Node.js async-local APIs.
+When a saga, command handler, query handler, or event handler performs another CQRS `execute(...)`, `publish(...)`, or `publishAll(...)` call, pass the optional `CqrsDispatchContext` argument through unchanged. CQRS uses this explicit runtime-agnostic context to keep saga topology checks intact across nested dispatch without relying on Node.js async-local APIs. The context is opaque: do not construct it, inspect it, or depend on topology fields because those fields are internal runtime state.
 
 ### 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, `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.
+`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. Once shutdown starts, new `publish(...)`, `publishAll(...)`, and direct saga dispatch calls are rejected; already active publish and saga work continues draining inside the bounded shutdown window. 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.
 
@@ -158,3 +220,3 @@ 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.
 - `ICommandHandler<C, R>`, `IQueryHandler<Q, R>`, `IEventHandler<E>`, `ISaga<E>`: Handler contracts.
-- `CqrsDispatchContext`: Opaque optional context value to pass through nested CQRS dispatch from handlers and sagas.
+- `CqrsDispatchContext`: Opaque optional context value to pass through nested CQRS dispatch from handlers and sagas. It exposes no public fields; provider assembly remains behind `CqrsModule.forRoot(...)` rather than a public `createCqrsProviders(...)` helper.
 
@@ -161,0 +223,0 @@ ### Errors

No alert changes

Improved metrics

Total package byte prevSize

146059

4.23%

Lines of code

2221

0.82%

Number of lines in readme file

241

34.64%

Dependency changes

• Updated

  @fluojs/event-bus@^1.0.1

• Updated

  @fluojs/runtime@^1.1.8