@voznov/zod-dto-nestjs 0.2.2 → 0.3.0

package/README.md

@@ -19,11 +19,16 @@ app.useGlobalPipes(new ZodValidationPipe());
 ```
 
 ```ts
-import { Body, Controller, Post } from '@nestjs/common';
+import { Body, Controller, Get, Param, Post, Query } from '@nestjs/common';
 import { ZodDto } from '@voznov/zod-dto';
 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),
+})) {}
 
 @Controller('users')
 export class UsersController {
@@ -31,6 +36,16 @@ export class UsersController {
   create(@Body() body: CreateUserDto) {
     // already validated; `body` is a CreateUserDto instance.
   }
+
+  // `@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) { /* ... */ }
+
+  // `@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) { /* ... */ }
 }
 ```
 
@@ -52,6 +67,20 @@ Supported shapes: scalars, objects (nested), arrays, tuples, records, enums, lit
 
 `.refine(...)` validators run at request-validation time 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.
+
+### Reference nested DTOs by class, not by raw schema
+
+```ts
+// ❌ Inlines NoteDto's full shape into items[]; codegen produces two separate types for the same data.
+class PaginatedNotes extends ZodDto(z.object({ items: z.array(noteSchema) })) {}
+
+// ✅ Emits `items: { type: 'array', items: { $ref: '#/components/schemas/NoteDto' } }`.
+class PaginatedNotes extends ZodDto(z.object({ items: z.array(NoteDto) })) {}
+```
+
+Both forms parse identically, but only the second one keeps the spec DRY — `$ref` instead of an inlined copy. Use the DTO class itself in nested positions whenever you have one.
+
 ### Recursive schemas (`z.lazy` / `lazyDto`)
 
 For self-referential shapes (comment trees, file trees, ...) wrap the recursion in a DTO and reference it back via `lazyDto` — the Swagger walker emits a proper `$ref` at the cycle, and `lazyDto` keeps TypeScript from tripping over the circular self-reference:
@@ -88,12 +117,102 @@ 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.
+
+- **`@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.
+
+Both come in two overloads:
+
+- **Strict** — schema passed explicitly. The method's return type is constrained at compile time to match the schema's output; `tsc` errors on mismatch.
+- **Loose** — no schema. Resolves from `design:returntype` metadata at runtime (`: NoteDto` annotation suffices). No compile-time check; doesn't work on generic return types (`NoteDto[]`, `Promise<NoteDto>`, unions) since TypeScript erases generics in metadata — pass the schema explicitly in that case.
+
+```ts
+import { Body, Controller, Get, Param, Post } from '@nestjs/common';
+import { ZodResponse } from '@voznov/zod-dto-nestjs';
+import { z } from 'zod';
+
+@Controller('notes')
+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 { /* ... */ }
+
+  // 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[]> { /* ... */ }
+
+  // Override status (default 200) + description for the OpenAPI operation.
+  @Post()
+  @ZodResponse(NoteDto, { status: 201, description: 'note created' })
+  create(@Body() body: CreateNoteDto): NoteDto { /* ... */ }
+}
+```
+
+Runtime-only sibling for layers below the controller — same overloads, no Swagger emission:
+
+```ts
+import { ZodSerialize } from '@voznov/zod-dto-nestjs';
+
+class NotesService {
+  // Throws ZodDtoSerializationError if the return shape doesn't match.
+  @ZodSerialize(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 { /* ... */ }
+}
+```
+
+### 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). The default `errorClass` is `ZodDtoSerializationError` (vs `ZodDtoValidationError` for `toDto`), so an exception filter can split client errors from server bugs (see below).
+
+`@ZodResponse` extends the bag with two Swagger-only fields:
+
+- `status: number` — HTTP status for the OpenAPI response object. Default `200`.
+- `description: string` — description on the OpenAPI response object.
+
+```ts
+@ZodResponse(NoteDto, { status: 201, observers: [(note) => metrics.recordCreate(note)] })
+async create(): Promise<NoteDto> { /* ... */ }
+```
+
+### Differentiating client errors from server errors
+
+`ZodDtoSerializationError extends ZodDtoValidationError`, so a single exception filter can split request-validation failures (client → 400) from response-validation failures (server → 500):
+
+```ts
+import { ZodDtoValidationError } from '@voznov/zod-dto';
+import { ZodDtoSerializationError } from '@voznov/zod-dto-nestjs';
+
+@Catch(ZodDtoValidationError)
+export class ZodExceptionFilter implements ExceptionFilter {
+  catch(error: ZodDtoValidationError, host: ArgumentsHost) {
+    const isServerBug = error instanceof ZodDtoSerializationError;
+    const status = isServerBug ? 500 : 400;
+    // log, format, respond...
+  }
+}
+```
+
 ## API
 
-| Export                           | Description                                                                                                                    |
-| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
-| `ZodValidationPipe`              | `PipeTransform` for `@Body()` / `@Param()` / `@Query()`. Accepts `{ createError?: (issues: string[]) => Error }`.              |
-| `applySwaggerDecorators(schema)` | Low-level: apply `@ApiProperty` metadata to a schema. Auto-invoked via `registerOnCreate`; export is for manual/edge-case use. |
+| 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(schema?, options?)`  | `ZodSerialize` + auto-emits `@ApiResponse` Swagger metadata (and `@ApiExtraModels` for inner DTOs).                                        |
+| `ZodResponseOptions`              | Options type for `ZodResponse` (`ToDtoOptions & { status?, description? }`).                                                               |
+| `ZodDtoSerializationError`        | Subclass of `ZodDtoValidationError` thrown by `@ZodSerialize` / `@ZodResponse` when a method returns an invalid shape.                     |
+| `applySwaggerDecorators(schema)`  | Low-level: apply `@ApiProperty` metadata to a schema. Auto-invoked via `registerOnCreate`; export is for manual/edge-case use.             |
 
 ## License