@voznov/zod-dto-nestjs 0.3.3 → 0.4.1

package/README.md

@@ -2,6 +2,11 @@
 
 NestJS adapter for [`@voznov/zod-dto`](https://www.npmjs.com/package/@voznov/zod-dto) — validation pipe + automatic Swagger integration.
 
+## 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.
+
 ## Install
 
 ```bash
@@ -25,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 {
@@ -40,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) {
+    /* ... */
+  }
 }
 ```
 
@@ -69,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
 
@@ -100,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.
 
@@ -121,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.
@@ -138,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,
+      });
   }
 }
 
@@ -150,10 +165,9 @@ export class ZodExceptionFilter implements ExceptionFilter {
 app.useGlobalFilters(new ZodExceptionFilter());
 ```
 
-Both decorators come in two overloads:
+`@ZodSerialize` has two overloads — **strict** (schema given explicitly, return-type compile-time-checked against the schema) and **loose** (no schema, resolves from `design:returntype` at runtime). `@ZodResponse` adds two more on top: a `ResponseSpec` object form (`{ schema, status?, description?, throws?, ...ToDtoOptions }`) and a `ResponseSpec[]` array form for multi-response.
 
-- **Strict** — schema passed explicitly. The method's return type is constrained at compile time to match the schema's output; `tsc` errors on mismatch as `TS1241: Unable to resolve signature of method decorator...` — the actual mismatch is on the deepest line of the message (`Type 'X' is not assignable to type 'NoteDto | Promise<NoteDto>'`).
-- **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.
+Common pattern: pass the schema explicitly when the return type isn't a bare DTO class. Loose form sees `Promise` / `Array` constructors stripped of their generic argument, so `: Promise<NoteDto>` / `: NoteDto[]` won't resolve. The strict form errors as `TS1241: Unable to resolve signature of method decorator...` on schema/return mismatch — the actual mismatch is on the deepest line of the message (`Type 'X' is not assignable to type 'NoteDto | Promise<NoteDto>'`).
 
 ```ts
 import { Body, Controller, Get, Param, Post } from '@nestjs/common';
@@ -165,18 +179,40 @@ 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 for the OpenAPI operation.
+  // Override status (default 200) + description via the spec object form. Second argument
+  // is the ApiOperation metadata (summary / tags / deprecated / operationId / description).
   @Post()
-  @ZodResponse(NoteDto, { status: 201, description: 'note created' })
-  create(@Body() body: CreateNoteDto): NoteDto { /* ... */ }
+  @ZodResponse({ schema: NoteDto, status: 201, description: 'note created' }, { summary: 'Create a note' })
+  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).
+  // `throws:` schemas are NOT in the method's return-type union — the method just returns `NoteDto`.
+  @Get('many/:id')
+  @ZodResponse(
+    [
+      { schema: NoteDto, status: 200, description: 'Found' },
+      { throws: NotFoundDto, status: 404, description: 'Not found' },
+    ],
+    { summary: 'Get a note' },
+  )
+  findOneOrThrow(@Param() p: NoteIdParam): NoteDto {
+    /* throws HttpException(..., 404) on miss */
+  }
 }
 ```
 
@@ -188,28 +224,109 @@ 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). 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` extends the bag with two Swagger-only fields:
+`@ZodResponse` takes two arguments:
 
-- `status: number` — HTTP status for the OpenAPI response object. Default `200`.
-- `description: string` — description on the OpenAPI response object.
+1. **Response spec** — what shape the route returns / throws. Accepts one of:
+   - a Zod schema or DTO class — simple form, defaults `status` to 200;
+   - a `ResponseSpec` object — `{ schema?, throws?, status?, description? }` plus `ToDtoOptions` (`preprocessors`, `observers`, `errorClass`);
+   - an array of `ResponseSpec` — multi-response: one `@ApiResponse` per entry, the return value is parsed against the return-specs, thrown `HttpException` bodies are validated against the throws-specs at the matching status (see "throws-marked specs" below);
+   - `undefined` (loose form) — resolves the schema from `design:returntype`.
+2. **Operation metadata** — `ApiOperationOptions` (`summary`, `tags`, `description`, `deprecated`, `operationId`, ...). Forwarded straight to `@ApiOperation` so you don't need a second decorator for the common case. An explicit `@ApiOperation({...})` stacked on top still wins on conflicting keys.
 
 ```ts
-@ZodResponse(NoteDto, { status: 201, observers: [(note) => metrics.recordCreate(note)] })
+@ZodResponse({ schema: NoteDto, status: 201, observers: [(note) => metrics.recordCreate(note)] }, { summary: 'Create a note', tags: ['notes'] })
 async create(): Promise<NoteDto> { /* ... */ }
 ```
 
+> Note on `description`. In the response spec it's the **response description** (the OpenAPI status object's description). In the operation argument it's the **operation description** (the long-form route description). The split is intentional — the previous single `description: string` slot was ambiguous.
+
+### Throws-marked specs — validate `HttpException` body against a schema
+
+In a `ResponseSpec` array, `{ throws: ErrorDto, status: 4xx }` declares that when the method throws an `HttpException` whose status matches, its body must match `ErrorDto`. Shape drift → `ZodDtoSerializationError` (a server-side 500 — your declared error contract no longer matches what the code actually throws). On match the original exception re-throws untouched, so global exception filters still own the wire format.
+
+```ts
+@Get(':id')
+@ZodResponse([
+  { schema: NoteDto, status: 200 },
+  { throws: NotFoundError, status: 404 },              // method throws HttpException({code, message}, 404) on miss
+])
+findOne(@Param() p: NoteIdParam): NoteDto {            // return-type union is just NoteDto — throws-spec doesn't widen it
+  const note = this.svc.find(p.id);
+  if (!note) throw new HttpException({ code: 'NOT_FOUND', message: `note ${p.id} missing` }, 404);
+  return note;
+}
+```
+
+Key properties:
+
+- **`throws:` schemas are excluded from the method's return-type constraint** — `findOne(): NoteDto` compiles even when the array also declares `{throws: NotFoundError, status: 404}`.
+- **HttpException with a status that's not declared as throws passes through** — typical `throw new BadRequestException(...)` (400) won't be touched unless you declared a `{throws: ..., status: 400}` spec.
+- **Non-HttpException throws pass through unchanged** — vanilla `Error` doesn't get validated.
+
+### Behind the scenes
+
+`@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
 
 When the method returns a Promise, the decorator awaits it and parses through `safeParseAsync` — that's the only signal it uses. So if your schema has async validation (`z.string().refine(async ...)`, async transforms — typical when the same schema is reused for request validation), make the method `async` and you'll get the async parse path; failures still throw `ZodDtoSerializationError` and flow through your exception filter, not raw Zod async errors.
@@ -224,15 +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. |
-| `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.             |
+| 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.                                                                                                                                                     |
 
 ## License
 

package/dist/index.cjs

@@ -12,11 +12,11 @@ var __export = (target, all) => {
   for (var name in all)
     __defProp(target, name, { get: all[name], enumerable: true });
 };
-var __copyProps = (to, from, except, desc) => {
-  if (from && typeof from === "object" || typeof from === "function") {
-    for (let key of __getOwnPropNames(from))
+var __copyProps = (to, from2, except, desc) => {
+  if (from2 && typeof from2 === "object" || typeof from2 === "function") {
+    for (let key of __getOwnPropNames(from2))
       if (!__hasOwnProp.call(to, key) && key !== except)
-        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+        __defProp(to, key, { get: () => from2[key], enumerable: !(desc = __getOwnPropDesc(from2, key)) || desc.enumerable });
   }
   return to;
 };
@@ -1129,17 +1129,16 @@ var index_exports = {};
 __export(index_exports, {
   ZodDtoSerializationError: () => ZodDtoSerializationError,
   ZodResponse: () => ZodResponse,
+  ZodResponseInterceptor: () => ZodResponseInterceptor,
   ZodSerialize: () => ZodSerialize,
   ZodValidationPipe: () => ZodValidationPipe,
   applySwaggerDecorators: () => applySwaggerDecorators
 });
 module.exports = __toCommonJS(index_exports);
-var import_zod_dto4 = require("@voznov/zod-dto");
+var import_zod_dto5 = require("@voznov/zod-dto");
 
 // src/swagger.ts
 var import_swagger = require("@nestjs/swagger");
-var import_open_api_spec = require("@nestjs/swagger/dist/interfaces/open-api-spec.interface");
-var import_schema_object_metadata = require("@nestjs/swagger/dist/interfaces/schema-object-metadata.interface");
 var import_zod_dto = require("@voznov/zod-dto");
 var import_zod = require("zod");
 
@@ -1169,6 +1168,7 @@ var schemaObjectToApiPropertyOptions = (so, selfRequired) => {
   }
   return { ...so, required: selfRequired };
 };
+var unwrapSimpleOneOf = (so) => Object.keys(so).length === 1 && Array.isArray(so.oneOf) && so.oneOf.length === 1 ? so.oneOf[0] : so;
 var leaf = (so) => ({
   so,
   selfRequired: true,
@@ -1207,11 +1207,11 @@ var applyDecoratorsImpl = (schema) => {
       (0, import_swagger.ApiExtraModels)(...[...innerSchemas.values()].filter((innerSchema) => innerSchema !== schema))(schema);
       return { so: { oneOf: (0, import_swagger.refs)(schema) }, selfRequired: true, innerSchemas: /* @__PURE__ */ new Set([schema]) };
     }
-    return { so: { type: "object", properties: mapValues(properties, (so) => so.oneOf?.length === 1 ? so.oneOf[0] : so), required }, selfRequired: true, innerSchemas };
+    return { so: { type: "object", properties: mapValues(properties, unwrapSimpleOneOf), required }, selfRequired: true, innerSchemas };
   }
   if (schema instanceof import_zod.z.ZodRecord) {
     const { so } = applySwaggerDecorators(schema._zod.def.valueType);
-    return leaf({ type: "object", additionalProperties: so.oneOf?.length === 1 ? so.oneOf[0] : so });
+    return leaf({ type: "object", additionalProperties: unwrapSimpleOneOf(so) });
   }
   if (schema instanceof import_zod.z.ZodOptional || schema instanceof import_zod.z.ZodExactOptional) {
     return { ...applySwaggerDecorators(schema.unwrap()), selfRequired: false };
@@ -1257,12 +1257,12 @@ var applyDecoratorsImpl = (schema) => {
     if (!selfRequiredElement) {
       throw new Error("Not required array item is not supported in Swagger. Use nullable instead.");
     }
-    return { so: { type: "array", items: so.oneOf?.length === 1 ? so.oneOf[0] : so }, selfRequired: true, innerSchemas };
+    return { so: { type: "array", items: unwrapSimpleOneOf(so) }, selfRequired: true, innerSchemas };
   }
   if (schema instanceof import_zod.z.ZodTuple) {
     const itemSchemas = schema._zod.def.items.map((item) => {
       const { so } = applySwaggerDecorators(item);
-      return so.oneOf?.length === 1 ? so.oneOf[0] : so;
+      return unwrapSimpleOneOf(so);
     });
     const unique = [...new Map(itemSchemas.map((s) => [JSON.stringify(s), s])).values()];
     const items = unique.length === 1 ? unique[0] : { oneOf: unique };
@@ -1318,7 +1318,7 @@ var applyDecoratorsImpl = (schema) => {
         throw new Error("Not required option in oneOf is not supported in Swagger. Use nullable instead.");
       }
       innerSchemas_.forEach((innerSchema) => innerSchemas.add(innerSchema));
-      return so.oneOf?.length === 1 ? so.oneOf[0] : so;
+      return unwrapSimpleOneOf(so);
     });
     if (schema instanceof import_zod.z.ZodDiscriminatedUnion) {
       const propertyName = schema._zod.def.discriminator;
@@ -1341,9 +1341,7 @@ var applyDecoratorsImpl = (schema) => {
     const left = applySwaggerDecorators(schema._zod.def.left);
     const right = applySwaggerDecorators(schema._zod.def.right);
     const innerSchemas = /* @__PURE__ */ new Set([...left.innerSchemas, ...right.innerSchemas]);
-    const leftSo = left.so.oneOf?.length === 1 ? left.so.oneOf[0] : left.so;
-    const rightSo = right.so.oneOf?.length === 1 ? right.so.oneOf[0] : right.so;
-    return { so: { allOf: [leftSo, rightSo] }, selfRequired: true, innerSchemas };
+    return { so: { allOf: [unwrapSimpleOneOf(left.so), unwrapSimpleOneOf(right.so)] }, selfRequired: true, innerSchemas };
   }
   if (schema instanceof import_zod.z.ZodAny || schema instanceof import_zod.z.ZodUnknown) {
     return leaf({});
@@ -1380,67 +1378,149 @@ ZodValidationPipe = __decorateClass([
 
 // src/zod-serialize.ts
 var import_reflect_metadata = __toESM(require_Reflect(), 1);
-var import_swagger2 = require("@nestjs/swagger");
 var import_zod_dto3 = require("@voznov/zod-dto");
 var import_zod2 = require("zod");
+var isSchemaLike = (value) => value instanceof import_zod2.z.ZodType || (0, import_zod_dto3.isZodDtoClass)(value);
 var ZodDtoSerializationError = class extends import_zod_dto3.ZodDtoValidationError {
 };
-var resolveSchema = (schema, target, propertyKey, decoratorName) => {
-  if (schema !== void 0 && !(schema instanceof import_zod2.z.ZodType) && !(0, import_zod_dto3.isZodDtoClass)(schema)) {
-    throw new Error(`${decoratorName} on ${target.constructor.name}.${String(propertyKey)}: schema argument must be a Zod type or DTO class (got ${typeof schema}).`);
-  }
-  if (schema) return schema;
+var resolveDesignReturnType = (target, propertyKey, decoratorName) => {
   const rt = Reflect.getMetadata("design:returntype", target, propertyKey);
-  if (rt instanceof import_zod2.z.ZodType) return rt;
+  if (isSchemaLike(rt)) return rt;
   const rtName = rt instanceof Object && "name" in rt && typeof rt.name === "string" ? rt.name : "unknown";
   throw new Error(
     `${decoratorName} on ${target.constructor.name}.${String(propertyKey)}: no Zod schema provided and design:returntype "${rtName}" is not a Zod schema. Pass it explicitly, e.g. ${decoratorName}(z.array(MySchema)).`
   );
 };
-var wrapMethod = (schema, options, decoratorName) => (target, methodName, descriptor) => {
+var resolveSerializeSchema = (schema, target, propertyKey) => {
+  if (schema !== void 0 && !isSchemaLike(schema)) {
+    throw new Error(`@ZodSerialize on ${target.constructor.name}.${String(propertyKey)}: schema argument must be a Zod type or DTO class (got ${typeof schema}).`);
+  }
+  if (schema) return schema;
+  return resolveDesignReturnType(target, propertyKey, "@ZodSerialize");
+};
+var wrapMethod = (decoratorName, wrapper) => (target, methodName, descriptor) => {
   const originalMethod = descriptor.value;
   if (typeof originalMethod !== "function") {
     throw new Error(`${decoratorName}: ${target.constructor.name}.${String(methodName)} is not a method`);
   }
-  const resolved = resolveSchema(schema, target, methodName, decoratorName);
-  const serialize = import_zod_dto3.toDto.with({ errorClass: ZodDtoSerializationError, ...options });
-  descriptor.value = {
-    [methodName](...args) {
-      const out = originalMethod.apply(this, args);
-      if (out instanceof Promise) {
-        return out.then(async (v) => serialize.async(resolved, v));
-      }
-      return serialize(resolved, out);
-    }
-  }[methodName];
+  descriptor.value = { [methodName]: wrapper(originalMethod) }[methodName];
   redecorateFromReflect(originalMethod, descriptor.value);
 };
-var wrapApiResponse = (schema, options) => (target, propertyKey, descriptor) => {
-  const resolved = resolveSchema(schema, target, propertyKey, "@ZodResponse");
-  const { so, innerSchemas } = applySwaggerDecorators(resolved);
-  const schemaForApi = Object.keys(so).length === 1 && Array.isArray(so.oneOf) && so.oneOf.length === 1 ? so.oneOf[0] : so;
-  (0, import_swagger2.ApiResponse)({ status: options?.status ?? 200, description: options?.description, schema: schemaForApi })(target, propertyKey, descriptor);
-  if (innerSchemas.size > 0) {
-    const classTarget = typeof target === "function" ? target : target.constructor;
-    (0, import_swagger2.ApiExtraModels)(...innerSchemas)(classTarget);
-  }
-};
 function ZodSerialize(schema, options) {
-  return wrapMethod(schema, options, "@ZodSerialize");
+  return (target, methodName, descriptor) => {
+    const resolved = resolveSerializeSchema(schema, target, methodName);
+    const serialize = import_zod_dto3.toDto.with({ errorClass: ZodDtoSerializationError, ...options });
+    wrapMethod(
+      "@ZodSerialize",
+      (originalMethod) => function(...args) {
+        const out = originalMethod.apply(this, args);
+        if (out instanceof Promise) {
+          return out.then(async (v) => serialize.async(resolved, v));
+        }
+        return serialize(resolved, out);
+      }
+    )(target, methodName, descriptor);
+  };
 }
-function ZodResponse(schema, options) {
-  return (target, propertyKey, descriptor) => {
-    wrapMethod(schema, options, "@ZodResponse")(target, propertyKey, descriptor);
-    wrapApiResponse(schema, options)(target, propertyKey, descriptor);
+
+// src/zod-response.ts
+var import_reflect_metadata2 = __toESM(require_Reflect(), 1);
+var import_common2 = require("@nestjs/common");
+var import_swagger2 = require("@nestjs/swagger");
+var import_zod_dto4 = require("@voznov/zod-dto");
+var import_rxjs = require("rxjs");
+var import_zod3 = require("zod");
+var writePlatformResponse = (res, status, body) => {
+  if (typeof res.json === "function" && typeof res.status === "function") {
+    res.status(status).json(body);
+  } else if (typeof res.send === "function" && typeof res.code === "function") {
+    res.code(status).send(body);
+  } else {
+    throw new Error("@ZodResponse: unsupported HTTP platform \u2014 response object has neither Express (.status/.json) nor Fastify (.code/.send) chain.");
+  }
+};
+var ZodResponseInterceptor = class {
+  constructor(returnEntries, throwsEntries) {
+    this.returnEntries = returnEntries;
+    this.throwsEntries = throwsEntries;
+  }
+  intercept(ctx, next) {
+    return next.handle().pipe(
+      (0, import_rxjs.mergeMap)((value) => this.returnEntries.length === 0 ? (0, import_rxjs.of)(value) : this.writeReturn(ctx, value)),
+      (0, import_rxjs.catchError)((err) => (0, import_rxjs.from)(this.handleThrow(err)))
+    );
+  }
+  writeReturn(ctx, value) {
+    return (0, import_rxjs.from)(this.parseReturn(value)).pipe(
+      (0, import_rxjs.mergeMap)(({ status, body }) => {
+        writePlatformResponse(ctx.switchToHttp().getResponse(), status, body);
+        return import_rxjs.EMPTY;
+      })
+    );
+  }
+  async parseReturn(value) {
+    let lastError;
+    for (const entry of this.returnEntries) {
+      try {
+        const body = await entry.serialize(value);
+        return { status: entry.status, body };
+      } catch (error) {
+        lastError = error;
+      }
+    }
+    throw lastError;
+  }
+  async handleThrow(err) {
+    if (!(err instanceof import_common2.HttpException)) throw err;
+    const matched = this.throwsEntries.find((entry) => entry.status === err.getStatus());
+    if (!matched) throw err;
+    await matched.serialize(err.getResponse());
+    throw err;
+  }
+};
+ZodResponseInterceptor = __decorateClass([
+  (0, import_common2.Injectable)()
+], ZodResponseInterceptor);
+function ZodResponse(arg, operation) {
+  return (target, methodName, descriptor) => {
+    const specs = Array.isArray(arg) ? arg : [arg === void 0 || isSchemaLike(arg) ? { schema: arg } : arg];
+    if (specs.length === 0) throw new Error(`@ZodResponse on ${target.constructor.name}.${String(methodName)}: array argument must not be an empty list`);
+    const innerSchemas = /* @__PURE__ */ new Set();
+    const returnEntries = [];
+    const throwsEntries = [];
+    for (const {
+      throws,
+      schema = throws === void 0 ? resolveDesignReturnType(target, methodName, "@ZodResponse") : void 0,
+      status = 200,
+      description,
+      ...toDtoOpts
+    } of specs) {
+      toDtoOpts.errorClass ??= ZodDtoSerializationError;
+      const serializeWith = import_zod_dto4.toDto.with(toDtoOpts);
+      if (schema !== void 0) returnEntries.push({ status, serialize: async (value) => serializeWith.async(schema, value) });
+      if (throws !== void 0) throwsEntries.push({ status, serialize: async (value) => serializeWith.async(throws, value) });
+      const declared = [...new Set([schema, throws].filter(Boolean))].map(applySwaggerDecorators);
+      declared.forEach(({ innerSchemas: iS }) => iS.forEach((inner) => innerSchemas.add(inner)));
+      const variants = declared.map(({ so }) => unwrapSimpleOneOf(so));
+      const schemaForApi = variants.length === 1 ? variants[0] : { oneOf: variants };
+      (0, import_swagger2.ApiResponse)({ status, description, schema: schemaForApi })(target, methodName, descriptor);
+    }
+    if (innerSchemas.size > 0) {
+      const classTarget = typeof target === "function" ? target : target.constructor;
+      (0, import_swagger2.ApiExtraModels)(...innerSchemas)(classTarget);
+    }
+    if (operation) (0, import_swagger2.ApiOperation)(operation)(target, methodName, descriptor);
+    (0, import_common2.UseInterceptors)(new ZodResponseInterceptor(returnEntries, throwsEntries))(target, methodName, descriptor);
   };
 }
 
 // src/index.ts
-(0, import_zod_dto4.registerOnCreate)((dto) => void Promise.resolve().then(() => applySwaggerDecorators(dto)));
+(0, import_zod_dto5.registerOnCreate)((dto) => void Promise.resolve().then(() => applySwaggerDecorators(dto)));
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   ZodDtoSerializationError,
   ZodResponse,
+  ZodResponseInterceptor,
   ZodSerialize,
   ZodValidationPipe,
   applySwaggerDecorators