@cqrs-ddd/pipeline-zod
Validates and sanitizes inputs using Zod schemas before operations execute. Unknown properties are stripped, coercions and defaults applied, and invalid payloads rejected with structured validation errors.
Supports two integration patterns:
- Explicit schema decoration via
validated(schema)at the call site or handler. - Class-embedded schemas via
createCommand(schema)andcreateQuery(schema)validated globally byZodValidationBehavior.
Installation
Section titled “Installation”Requires Node.js 22.12 or later and Zod 4.3 or later.
Usage Patterns
Section titled “Usage Patterns”Pattern 1: Call-Site Decoration (validated)
Section titled “Pattern 1: Call-Site Decoration (validated)”The wrapped function or handler receives a sanitized, parsed copy. The original input argument is never mutated:
Multi-Argument Functions
Section titled “Multi-Argument Functions”Functions accepting multiple arguments are validated using z.tuple():
Pattern 2: Request Classes with Embedded Schemas
Section titled “Pattern 2: Request Classes with Embedded Schemas”Create command and query classes that encapsulate their validation schema:
When ZodValidationBehavior runs globally, it validates any request class bearing an embedded schema:
In-Place Request Validation Semantics
Section titled “In-Place Request Validation Semantics”When validating request class instances:
- Validated values, defaults, and type coercions are reassigned directly to the request instance.
- Unrecognized keys are stripped.
- The request maintains its class identity (
instanceof CreateUserCommand === true).
Updatable Fields & Field-Level Authorization
Section titled “Updatable Fields & Field-Level Authorization”For partial update (PATCH) commands, use updatable to declare allowed mutable fields for field-level authorization with @cqrs-ddd/pipeline-casl:
Pass the fields a command changes to authorizer.authorize('update', user, fields) of CaslAuthorizer, which checks the caller may modify each one. A field without the mark is never listed, so mark every field the handler writes.
Edge HTTP Mapping (createZodMapper)
Section titled “Edge HTTP Mapping (createZodMapper)”Use createZodMapper at the HTTP boundary (Express, Fastify, NestJS controllers) to transform raw HTTP request payloads into strongly typed command or query instances:
CreateUserMapper.map() throws ZodValidationError synchronously on validation failure.
NestJS Integration (@cqrs-ddd/nestjs)
Section titled “NestJS Integration (@cqrs-ddd/nestjs)”In NestJS applications, use @UsePipeline(validated(Schema)) directly on @CommandHandler or @QueryHandler:
The global ErrorFilter translates ZodValidationError into a NestJS BadRequestException formatted to match Nest’s ValidationPipe convention:
Error Handling & HTTP Translation
Section titled “Error Handling & HTTP Translation”When validation fails, ZodValidationError is thrown. Its details property carries flattened issues:
Translating directly to HTTP using @cqrs-ddd/pipeline-zod/http:
Behavior Ordering
Section titled “Behavior Ordering”Always position validation before behaviors that inspect request contents (such as caching, rate limiting, and idempotency). This guarantees that short-circuit keys are generated from validated, sanitized, and canonical data: