Pipeline execution model
┌─ global before ──┐ ┌── @UsePipeline ──┐ ┌─ global after ──┐│ LoggingBehavior │ → │ AuditBehavior │ → │ TraceBehavior │ → handler.execute()│ ZodValidation │ │ Idempotency │ │ MetricsBehavior │└──────────────────┘ └──────────────────┘ └─────────────────┘ ← response propagates back through the chain ←Bootstrap and Discovery Lifecycle
Section titled “Bootstrap and Discovery Lifecycle”At application startup (onApplicationBootstrap), PipelineBootstrap (from @cqrs-ddd/nestjs) wires the pipeline:
- Handler Discovery: Discovers all
@nestjs/cqrshandlers registered in the Nest application container using Nest’sDiscoveryService, reading metadata from@CommandHandler,@QueryHandler, and@EventsHandler. - Static Dependency Tree Verification: Verifies
provider.isDependencyTreeStatic()on every handler that runs behaviors. If any handler or its injected dependencies are request-scoped (Scope.REQUEST), bootstrap throws immediately with a descriptive error. Handlers and behaviors must be singletons; per-request context is read throughAsyncLocalStoragevia configuredsources. - Behavior Provider Resolution: Resolves each required behavior instance from the NestJS DI container under its behavior class token (e.g.,
IdempotencyBehavior). Fails fast if a required behavior has no provider or if multiple modules provide conflicting instances. - Plan Compilation: Compiles the execution plan once per handler (
compilePipelinePlan), computing the ordered sequence: globalbefore→@UsePipelinedeclared behaviors → globalafter. - Contract Diagnostics: When
diagnosticsis'strict'(default), runsvalidateBehaviorContractsto enforce architectural invariants (e.g.CaslBehaviormust precedeCacheBehaviorandIdempotencyBehavior). - Execution Wrapping: Wraps the handler instance’s
executemethod (orhandlefor event handlers) with the pre-compiledPipelineRunner. On application shutdown (onModuleDestroy), wrappers are cleanly restored.
Runtime Invocation Lifecycle
Section titled “Runtime Invocation Lifecycle”When a caller dispatches through Nest’s CommandBus, QueryBus, or EventBus:
- Context Creation: The runner instantiates an
IPipelineContextcapturing the request instance, class constructor, handler type, timestamp, and an items bag. - Context Sources: Populates
correlationIdandtenantIdby evaluating the configuredsourcesfunctions within the current async execution context (AsyncLocalStorage). - Onion Chain Execution: Executes each behavior in sequence:
- Outer behaviors run pre-processing logic before calling
next(). - If an outer behavior short-circuits (e.g.,
CacheBehaviorcache hit orIdempotencyBehaviorreplay), it returns the cached result without invoking subsequent behaviors or the handler. - Inner behaviors run, followed by the handler’s business logic.
- Post-processing logic executes in reverse order as responses or errors bubble back up.
- Outer behaviors run pre-processing logic before calling
Execution Order
Section titled “Execution Order”| Phase | Source | Position |
|---|---|---|
Global before |
globalBehaviors.before |
Outermost (first to run) |
| Handler-level | @UsePipeline(...) |
Middle |
Global after |
globalBehaviors.after |
Innermost (closest to handler) |
| Handler | execute() / handle() |
Core business logic |
Deduplication and Same-Class Override
Section titled “Deduplication and Same-Class Override”When both global and handler-level configurations include the same behavior class, the handler’s complete options record wins while the behavior retains its global chain position. Global duplicates are deduplicated automatically.
// Global config in PipelineModule.forRootPipelineModule.forRoot({ globalBehaviors: [ { scope: 'all', before: [ [LoggingBehavior, { metricLogLevel: 'log', requestResponseLogLevel: 'debug' }], ], }, ],})
// Handler overrides LoggingBehavior options@CommandHandler(CreateUserCommand)@UsePipeline( [LoggingBehavior, { requestResponseLogLevel: 'log' }], // ← wins over the global options)export class CreateUserHandler implements ICommandHandler<CreateUserCommand> { // ...}
// Effective chain for CreateUserHandler:// [LoggingBehavior at global-before position, using handler options] → handler.execute()Preserving the outer global position guarantees that mandatory cross-cutting policies (such as authentication or logging) cannot be moved behind caching or idempotency behaviors that might short-circuit before calling next().