@voznov/zod-dto-nestjs 0.4.0 → 0.4.2

package/README.md

@@ -5,7 +5,7 @@ NestJS adapter for [`@voznov/zod-dto`](https://www.npmjs.com/package/@voznov/zod
 ## Highlights
 
 - **Auto-Swagger without `@ApiProperty`.** Importing this package registers an `onCreate` hook that decorates every `ZodDto`-derived class with `@ApiProperty` metadata derived from its Zod tree — no manual decorators, no schema duplication. Nested DTOs, discriminated unions, defaults (`z.default`), descriptions (`z.describe`), and recursive cycles (`lazyDto`) all forward into the spec automatically. Import order doesn't matter — DTOs created before the import are retroactively decorated.
-- **`@ZodResponse` with compile-time return-type check.** A single decorator validates the response at runtime *and* emits `@ApiResponse` / `@ApiOperation`. The method's return type is constrained against the schema via TypeScript overloads — `Promise<NoteDto[]>` mismatches surface as `tsc` errors instead of 500s in production. Multi-response (`@ZodResponse([{ schema: A, status: 200 }, { throws: NotFoundError, status: 404 }])`) emits one `ApiResponse` per entry, dispatches `res.status(...)` on the matched return spec, and validates `HttpException` bodies against throws-specs at matching status.
+- **`@ZodResponse` with compile-time return-type check.** A single decorator validates the response at runtime _and_ emits `@ApiResponse` / `@ApiOperation`. The method's return type is constrained against the schema via TypeScript overloads — `Promise<NoteDto[]>` mismatches surface as `tsc` errors instead of 500s in production. Multi-response (`@ZodResponse([{ schema: A, status: 200 }, { throws: NotFoundError, status: 404 }])`) emits one `ApiResponse` per entry, dispatches `res.status(...)` on the matched return spec, and validates `HttpException` bodies against throws-specs at matching status.
 
 ## Install
 
@@ -30,10 +30,12 @@ import { z } from 'zod';
 
 class CreateUserDto extends ZodDto(z.object({ name: z.string(), email: z.email() })) {}
 class UserIdParam extends ZodDto(z.object({ id: z.uuid() })) {}
-class ListUsersQuery extends ZodDto(z.object({
-  page: z.coerce.number().int().min(1).default(1),
-  limit: z.coerce.number().int().min(1).max(100).default(20),
-})) {}
+class ListUsersQuery extends ZodDto(
+  z.object({
+    page: z.coerce.number().int().min(1).default(1),
+    limit: z.coerce.number().int().min(1).max(100).default(20),
+  }),
+) {}
 
 @Controller('users')
 export class UsersController {
@@ -45,12 +47,16 @@ export class UsersController {
   // `@Param() params: UserIdParam` — `id` validated as UUID, format: 'uuid' in the spec.
   // (Cleaner than `@Param('id', ParseUUIDPipe) id: string`, and the spec carries the format.)
   @Get(':id')
-  findOne(@Param() params: UserIdParam) { /* ... */ }
+  findOne(@Param() params: UserIdParam) {
+    /* ... */
+  }
 
   // `@Query() query: ListUsersQuery` — every Zod field becomes one OpenAPI query parameter,
   // with per-field validation, defaults, and descriptions, no extra `@ApiQuery` decorators needed.
   @Get()
-  list(@Query() query: ListUsersQuery) { /* ... */ }
+  list(@Query() query: ListUsersQuery) {
+    /* ... */
+  }
 }
 ```
 
@@ -74,7 +80,7 @@ Supported shapes: scalars, objects (nested), arrays, tuples, records, enums, lit
 
 `.refine(...)` validators run at runtime (in `ZodValidationPipe` for requests, in `@ZodSerialize` / `@ZodResponse` for responses) but are **not** reflected in the spec — JSON Schema can't express custom predicates, and a single `description` for a chain of refines (`.refine(...).refine(...).refine(...)`) would be ambiguous. Put human-readable docs in `.describe(...)` instead.
 
-> ⚠️ **`in` / `out` hooks are runtime-only.** The walker only reads the schema's structure, not the options passed to `ZodDto(schema, { in, out })`. A `out: ({ password, ...rest }) => rest` correctly strips `password` from the response *body*, but the OpenAPI schema still lists `password` as a property — the spec lies about a field that runtime drops. Same for `in`: snake_case→camelCase aliases applied via `in` are invisible in the spec, so docs show only the camelCase shape. If spec-correctness matters, either omit the field from the schema itself (`schema.omit({ password: true })`) or maintain a separate response DTO.
+> ⚠️ **`in` / `out` hooks are runtime-only.** The walker only reads the schema's structure, not the options passed to `ZodDto(schema, { in, out })`. A `out: ({ password, ...rest }) => rest` correctly strips `password` from the response _body_, but the OpenAPI schema still lists `password` as a property — the spec lies about a field that runtime drops. Same for `in`: snake_case→camelCase aliases applied via `in` are invisible in the spec, so docs show only the camelCase shape. If spec-correctness matters, either omit the field from the schema itself (`schema.omit({ password: true })`) or maintain a separate response DTO.
 
 ### Reference nested DTOs by class, not by raw schema
 
@@ -105,7 +111,7 @@ class CategoryDto extends ZodDto(
 // → at the type level, `instance.children[0].name` is `string`, not `unknown`.
 ```
 
-`lazyDto<T>(thunk)` is a thin wrapper over `z.lazy` with two type-level tweaks: the explicit generic carries the *instance type* `T`, and the thunk argument is typed `() => any` so TS skips body return-type inference (the source of the circular-class error). Plain `z.lazy(...)` works at runtime too, but you'd need a separate `type Category = {...}` + `(): z.ZodType<Category>` annotation to keep the inferred field types non-`unknown`.
+`lazyDto<T>(thunk)` is a thin wrapper over `z.lazy` with two type-level tweaks: the explicit generic carries the _instance type_ `T`, and the thunk argument is typed `() => any` so TS skips body return-type inference (the source of the circular-class error). Plain `z.lazy(...)` works at runtime too, but you'd need a separate `type Category = {...}` + `(): z.ZodType<Category>` annotation to keep the inferred field types non-`unknown`.
 
 If the recursive position resolves to an anonymous `ZodObject` (no DTO wrap), the walker emits an empty `{}` placeholder there — it won't crash, but Swagger UI will show `any` instead of the recursive structure. Wrap it in `ZodDto` if you want the cycle visible in your docs.
 
@@ -126,7 +132,7 @@ app.useGlobalPipes(
 
 ## Response validation — `@ZodSerialize` / `@ZodResponse`
 
-Method decorators that parse the return value of a controller (or any class) method through a Zod schema. If the method returns something that doesn't match the schema, a `ZodDtoSerializationError` is thrown — caught at runtime *before* the value reaches the client, so server-side bugs are surfaced as 500s instead of leaking malformed payloads or extra fields.
+Method decorators that parse the return value of a controller (or any class) method through a Zod schema. If the method returns something that doesn't match the schema, a `ZodDtoSerializationError` is thrown — caught at runtime _before_ the value reaches the client, so server-side bugs are surfaced as 500s instead of leaking malformed payloads or extra fields.
 
 - **`@ZodSerialize`** — runtime parsing only. Use on services, repositories, internal methods.
 - **`@ZodResponse`** — `@ZodSerialize` + auto-emit `@ApiResponse` Swagger metadata (and register inner DTOs via `@ApiExtraModels`). Use on controller routes.
@@ -143,11 +149,15 @@ export class ZodExceptionFilter implements ExceptionFilter {
   catch(error: ZodDtoValidationError, host: ArgumentsHost) {
     const isServerBug = error instanceof ZodDtoSerializationError;
     const status = isServerBug ? HttpStatus.INTERNAL_SERVER_ERROR : HttpStatus.BAD_REQUEST;
-    host.switchToHttp().getResponse().status(status).json({
-      statusCode: status,
-      message: error.message,
-      issues: isServerBug ? undefined : error.issues,
-    });
+    host
+      .switchToHttp()
+      .getResponse()
+      .status(status)
+      .json({
+        statusCode: status,
+        message: error.message,
+        issues: isServerBug ? undefined : error.issues,
+      });
   }
 }
 
@@ -169,19 +179,25 @@ export class NotesController {
   // Strict + auto-Swagger: tsc enforces the return type, spec gets `$ref` to NoteDto.
   @Get(':id')
   @ZodResponse(NoteDto)
-  findOne(@Param() p: NoteIdParam): NoteDto { /* ... */ }
+  findOne(@Param() p: NoteIdParam): NoteDto {
+    /* ... */
+  }
 
   // Async + array: tsc enforces `Promise<NoteDto[]>`. Generics erased in design:returntype,
   // so the schema must be passed explicitly here.
   @Get()
   @ZodResponse(z.array(NoteDto))
-  async list(): Promise<NoteDto[]> { /* ... */ }
+  async list(): Promise<NoteDto[]> {
+    /* ... */
+  }
 
   // Override status (default 200) + description via the spec object form. Second argument
   // is the ApiOperation metadata (summary / tags / deprecated / operationId / description).
   @Post()
   @ZodResponse({ schema: NoteDto, status: 201, description: 'note created' }, { summary: 'Create a note' })
-  create(@Body() body: CreateNoteDto): NoteDto { /* ... */ }
+  create(@Body() body: CreateNoteDto): NoteDto {
+    /* ... */
+  }
 
   // Multi-response: 200 returns the note, 404 throws `HttpException(notFoundBody, 404)` and we
   // validate that the thrown body matches `NotFoundDto` (shape drift surfaces as ZodDtoSerializationError).
@@ -194,7 +210,9 @@ export class NotesController {
     ],
     { summary: 'Get a note' },
   )
-  findOneOrThrow(@Param() p: NoteIdParam): NoteDto { /* throws HttpException(..., 404) on miss */ }
+  findOneOrThrow(@Param() p: NoteIdParam): NoteDto {
+    /* throws HttpException(..., 404) on miss */
+  }
 }
 ```
 
@@ -206,17 +224,21 @@ import { ZodSerialize } from '@voznov/zod-dto-nestjs';
 class NotesService {
   // Throws ZodDtoSerializationError if the return shape doesn't match.
   @ZodSerialize(NoteDto)
-  findOne(id: string): NoteDto { /* ... */ }
+  findOne(id: string): NoteDto {
+    /* ... */
+  }
 
   // Loose: schema resolved from `design:returntype` (NoteDto class). Won't work for `Promise<...>` / `NoteDto[]` — generic erased to `Promise` / `Array`. Use the strict overload for those.
   @ZodSerialize()
-  default(): NoteDto { /* ... */ }
+  default(): NoteDto {
+    /* ... */
+  }
 }
 ```
 
 ### Options
 
-Both decorators accept the full `ToDtoOptions` bag (`preprocessors`, `observers`, `errorClass` — same semantics as [`toDto.with`](https://www.npmjs.com/package/@voznov/zod-dto), but applied to the method's *return* value instead of an input). `@ZodSerialize` takes them as its second argument; `@ZodResponse` takes them **inside the `ResponseSpec`** (per-status). The default `errorClass` is `ZodDtoSerializationError` (vs `ZodDtoValidationError` for `toDto`), so an exception filter can split client errors from server bugs (see below).
+Both decorators accept the full `ToDtoOptions` bag (`preprocessors`, `observers`, `errorClass` — same semantics as [`toDto.with`](https://www.npmjs.com/package/@voznov/zod-dto), but applied to the method's _return_ value instead of an input). `@ZodSerialize` takes them as its second argument; `@ZodResponse` takes them **inside the `ResponseSpec`** (per-status). The default `errorClass` is `ZodDtoSerializationError` (vs `ZodDtoValidationError` for `toDto`), so an exception filter can split client errors from server bugs (see below).
 
 `@ZodResponse` takes two arguments:
 
@@ -259,7 +281,51 @@ Key properties:
 
 ### Behind the scenes
 
-`@ZodResponse` doesn't wrap the method; it auto-registers a per-method `ZodResponseInterceptor` via `UseInterceptors`. The interceptor takes over response writing: after a successful return-side parse it calls `res.status(spec.status).json(parsedBody)` directly, then emits `EMPTY` so NestJS's default rendering doesn't run a second `res.status(verbDefault)` over it. This is the only reliable way to dispatch a non-default status (`@Get` defaults 200, `@Post` 201, etc. — Nest writes those after interceptors). Trade-off: upstream interceptors receive `EMPTY` rather than the parsed body, and custom body-renderer chains (msgpack/yaml/...) are bypassed. For typical JSON APIs it's the right default; if you need composability with response transformations, hold off on `@ZodResponse` for those routes.
+`@ZodResponse` doesn't wrap the method; it auto-registers a per-method `ZodResponseInterceptor` via `UseInterceptors`. After a successful return-side parse the interceptor writes the response directly via the platform's native chain (Express `res.status(s).json(b)` or Fastify `reply.code(s).send(b)`, picked by feature detection), then emits `EMPTY` so NestJS's default `applicationRef.reply()` doesn't run a second `res.status(verbDefault)` over the dispatched status. Direct-write is the only reliable way to dispatch a non-default status on a per-spec basis: NestJS's `httpStatusCode` is resolved once at bootstrap from `@HttpCode` metadata or the verb default and re-applied to the response on every request, so a runtime `res.status(...)` from inside `map()` would be clobbered.
+
+### Composition with other interceptors
+
+`@ZodResponse` is a **terminal response contract** — what it declared in `@ApiResponse` (status + body schema) must match what actually goes out, otherwise the Swagger doc lies to clients. So the interceptor owns the write end-to-end and, by design, doesn't cooperate with interceptors that would alter the body or status after it.
+
+What composes and what doesn't:
+
+| Interceptor pattern                                 | Works? | Why                                                                                                                                      |
+| --------------------------------------------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------- |
+| Latency / metrics via `finalize`                    | ✅     | `EMPTY` completes cleanly through `.pipe(...)`, `finalize` fires on completion.                                                          |
+| `tap({ complete })` / `tap({ error })` observers    | ✅     | Same — completion / error propagate; only `next` is suppressed.                                                                          |
+| Body-reading loggers (`tap(body => log(body))`)     | ❌     | `next` never fires; the body has already been written by `@ZodResponse`.                                                                 |
+| Body-transforming wrappers (envelope, msgpack, ...) | ❌     | If inner: their transform never runs (`EMPTY`). If outer: they wrap the value before `@ZodResponse` parses → `ZodDtoSerializationError`. |
+| Header / status mutators outside `@ZodResponse`     | ❌     | The status `@ZodResponse` dispatched is the contract; later mutators would desync it from the Swagger declaration.                       |
+
+Concrete observability — drop in as a class- or global-level interceptor; works on every route, with or without `@ZodResponse`:
+
+```ts
+import { type CallHandler, type ExecutionContext, Injectable, Logger, type NestInterceptor } from '@nestjs/common';
+import { type Observable, tap } from 'rxjs';
+
+@Injectable()
+export class LatencyInterceptor implements NestInterceptor {
+  private readonly logger = new Logger(LatencyInterceptor.name);
+
+  intercept(ctx: ExecutionContext, next: CallHandler): Observable<unknown> {
+    const start = process.hrtime.bigint();
+    const req = ctx.switchToHttp().getRequest<{ method: string; url: string }>();
+
+    return next.handle().pipe(
+      tap({
+        // `complete` fires on the inner Observable's completion. `@ZodResponse` emits `EMPTY` after writing
+        // the response, which completes immediately — so this callback runs for every `@ZodResponse` route.
+        complete: () =>
+          this.logger.log(`${req.method} ${req.url} → ${Number(process.hrtime.bigint() - start) / 1e6} ms`),
+      }),
+    );
+  }
+}
+```
+
+If you need to _read_ the response body downstream (audit logging, response tracing), `@ZodResponse` doesn't expose the parsed value to outer interceptors — use `observers: [...]` on the spec (`@ZodResponse({ schema: Dto, observers: [(parsed) => audit.log(parsed)] })`) or hook on `res.on('finish')` / `reply.then(...)` at the platform layer.
+
+If you need to _transform_ the body (envelope, msgpack), the contract you declared in `@ApiResponse` would no longer match the wire shape — bake the envelope into the schema instead (`z.object({ data: Dto, meta: MetaSchema })`), then `@ZodResponse` documents and validates the _actual_ outgoing shape. That's the only way to keep the Swagger doc honest.
 
 ### Async refines on the response schema
 
@@ -275,16 +341,16 @@ class Repo {
 
 ## API
 
-| Export                            | Description                                                                                                                                |
-| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
-| `ZodValidationPipe`               | `PipeTransform` for `@Body()` / `@Param()` / `@Query()`. Accepts `{ createError?: (issues: string[]) => Error }`.                          |
-| `ZodValidationPipeOptions`        | Options type for `ZodValidationPipe`.                                                                                                      |
-| `ZodSerialize(schema?, options?)` | Method decorator: runtime-parse the return value through `schema` (or via `design:returntype` if omitted). Throws `ZodDtoSerializationError` on mismatch. |
+| Export                              | Description                                                                                                                                                                                                                                                                        |
+| ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `ZodValidationPipe`                 | `PipeTransform` for `@Body()` / `@Param()` / `@Query()`. Accepts `{ createError?: (issues: string[]) => Error }`.                                                                                                                                                                  |
+| `ZodValidationPipeOptions`          | Options type for `ZodValidationPipe`.                                                                                                                                                                                                                                              |
+| `ZodSerialize(schema?, options?)`   | Method decorator: runtime-parse the return value through `schema` (or via `design:returntype` if omitted). Throws `ZodDtoSerializationError` on mismatch.                                                                                                                          |
 | `ZodResponse(response, operation?)` | Auto-registers `ZodResponseInterceptor` for runtime validation + writes `res.status(...).json(...)` directly, emits `@ApiResponse` (and `@ApiExtraModels` for inner DTOs). First arg: schema / `ResponseSpec` / `ResponseSpec[]` / `undefined`. Second arg: `ApiOperationOptions`. |
-| `ResponseSpec<S, T>`              | `{ schema?: S; throws?: T; status?: number; description?: string } & ToDtoOptions` — entry shape for `@ZodResponse`'s first argument. `schema` validates returns, `throws` validates `HttpException.getResponse()` at matching status. |
-| `ZodResponseInterceptor`          | Per-method `NestInterceptor` auto-registered by `@ZodResponse`. Exposed for manual `app.useGlobalInterceptors(...)` use if needed.        |
-| `ZodDtoSerializationError`        | Subclass of `ZodDtoValidationError` thrown when a method's return value or a throws-spec's `HttpException` body fails validation.         |
-| `applySwaggerDecorators(schema)`  | Low-level: apply `@ApiProperty` metadata to a schema. Auto-invoked via `registerOnCreate`; export is for manual/edge-case use.             |
+| `ResponseSpec<S, T>`                | `{ schema?: S; throws?: T; status?: number; description?: string } & ToDtoOptions` — entry shape for `@ZodResponse`'s first argument. `schema` validates returns, `throws` validates `HttpException.getResponse()` at matching status.                                             |
+| `ZodResponseInterceptor`            | Per-method `NestInterceptor` auto-registered by `@ZodResponse`. Exposed for manual `app.useGlobalInterceptors(...)` use if needed.                                                                                                                                                 |
+| `ZodDtoSerializationError`          | Subclass of `ZodDtoValidationError` thrown when a method's return value or a throws-spec's `HttpException` body fails validation.                                                                                                                                                  |
+| `applySwaggerDecorators(schema)`    | Low-level: apply `@ApiProperty` metadata to a schema. Auto-invoked via `registerOnCreate`; export is for manual/edge-case use.                                                                                                                                                     |
 
 ## License