zod-nest 1.9.0 → 1.11.0

package/README.md

@@ -23,7 +23,7 @@ For the long-form motivation, see [`docs/why-this-exists.md`](docs/why-this-exis
 - **OpenAPI 3.1 emission** — no post-processing, no spec downgrade, no leftover internal extension keys.
 - **`createZodDto`** — class wrapper around a Zod schema with introspectable `schema`, `id`, `io`, and a sibling `Output` class when input/output diverge.
 - **`ZodValidationPipe`** — auto-detects DTO from handler-arg metatype, accepts an explicit DTO or raw Zod schema, customizable exception factory.
-- **`@ZodResponse`** — stackable per status code, accepts a single DTO, an array (`[Dto]`), or a tuple (`[A, B, …]`). No internal `@HttpCode` — caller controls status.
+- **`@ZodResponse`** — stackable per status code; each entry is a DTO **or a raw Zod schema** (single, array `[Entry]`, or tuple `[A, B, …]`, mixable). A raw schema is normalised to an output DTO internally, so a `z.discriminatedUnion` / `z.union` / `z.intersection` that can't be wrapped in `createZodDto` (TS2509) drops straight into a response. No internal `@HttpCode` — caller controls status.
 - **`@ZodBody` / `@ZodQuery` / `@ZodHeaders` / `@ZodCookies`** — method-level decorators that wire OpenAPI docs for schemas whose `z.infer<>` is a union (intersection-of-union, discriminated unions, etc.) — the ones that can't be wrapped in `createZodDto` because TS refuses unions as class bases (TS2509). Schema validation stays via `@Body(new ZodValidationPipe(schema))`; the type at the handler arg stays `z.infer<>`.
 - **`ZodSerializerInterceptor`** — response validation with a `passthroughOnError` escape hatch for untrusted upstream shapes.
 - **`applyZodNest`** — one call after `SwaggerModule.createDocument(...)` replaces the entire `cleanupOpenApiDoc` ritual.
@@ -81,6 +81,7 @@ export class UserDto extends createZodDto(userSchema) {}
 // users.controller.ts
 import { Body, Controller, Get, Post } from '@nestjs/common';
 import { ZodResponse } from 'zod-nest';
+
 import { UserDto } from './user.dto';
 
 @Controller('users')
@@ -104,6 +105,7 @@ export class UsersController {
 // app.module.ts
 import { Module } from '@nestjs/common';
 import { ZodNestModule } from 'zod-nest';
+
 import { UsersController } from './users.controller';
 
 @Module({
@@ -118,6 +120,7 @@ export class AppModule {}
 import { NestFactory } from '@nestjs/core';
 import { DocumentBuilder, SwaggerModule } from '@nestjs/swagger';
 import { applyZodNest } from 'zod-nest';
+
 import { AppModule } from './app.module';
 
 async function bootstrap() {
@@ -154,7 +157,7 @@ See [`docs/dto.md`](docs/dto.md) for the full surface.
 
 ### Schemas that don't fit a class
 
-A schema whose `z.infer<>` is a TypeScript union — `z.union`, `z.discriminatedUnion`, or `z.intersection(obj, union)` — can't be used as a class base because TS rejects unions as constructor return types (TS2509: *Base constructor return type ... is not an object type*). For these, skip `createZodDto` and pair the raw schema with parameter-level decorators that handle OpenAPI emission directly:
+A schema whose `z.infer<>` is a TypeScript union — `z.union`, `z.discriminatedUnion`, or `z.intersection(obj, union)` — can't be used as a class base because TS rejects unions as constructor return types (TS2509: _Base constructor return type ... is not an object type_). For these, skip `createZodDto` and pair the raw schema with parameter-level decorators that handle OpenAPI emission directly:
 
 ```ts
 const IntersectionWithUnion = z
@@ -207,6 +210,18 @@ At request time, `ZodSerializerInterceptor` looks at `response.statusCode` and p
 
 See [`docs/responses.md`](docs/responses.md) for the precedence chain and `passthroughOnError`.
 
+### Streaming responses (SSE, NDJSON, binary)
+
+Streamed bodies are written straight to the response buffer — they shouldn't be validated, and the OpenAPI media type isn't `application/json`. Pass `contentType` (or declare a stream-typed `@Header('Content-Type', …)`) and `@ZodResponse` documents the response under that media type and skips validation:
+
+```ts
+@Sse('events')
+@ZodResponse({ type: NotificationEventDto, contentType: 'text/event-stream' })
+streamEvents(): Observable<MessageEvent> { /* … */ }
+```
+
+`stream` is inferred `true` for known stream types (`text/event-stream`, `application/x-ndjson`, `application/octet-stream`, `application/pdf`, `image/*`, `audio/*`, `video/*`); override with `stream: false`, or extend the set globally via `ZodNestModule.forRoot({ streamContentTypes: [...] })`. See [`docs/recipes/streaming-responses.md`](docs/recipes/streaming-responses.md).
+
 ## Usage
 
 ### Creating DTOs
@@ -228,12 +243,18 @@ The id is what appears as the `components.schemas` key in the OpenAPI document a
 
 ```ts
 // Preferred — on the schema, via Zod's metadata
-const userSchema = z.object({ /* ... */ }).meta({ id: 'User' });
+const userSchema = z
+  .object({
+    /* ... */
+  })
+  .meta({ id: 'User' });
 class UserDto extends createZodDto(userSchema) {}
 
 // Also valid — passed through createZodDto's options
 class UserDto extends createZodDto(
-  z.object({ /* ... */ }),
+  z.object({
+    /* ... */
+  }),
   { id: 'User' },
 ) {}
 ```
@@ -245,8 +266,8 @@ If you pass neither, the class name is used as a fallback. Under minification
 ### Input validation
 
 ```ts
-import { ZodValidationPipe } from 'zod-nest';
 import { APP_PIPE } from '@nestjs/core';
+import { ZodValidationPipe } from 'zod-nest';
 
 @Controller('things')
 class ThingsController {
@@ -310,14 +331,14 @@ Stack `@ZodResponse` per status code:
 import { Get, HttpStatus } from '@nestjs/common';
 import { ZodResponse } from 'zod-nest';
 
-class UserDto  extends createZodDto(z.object({ id: z.string() }),    { id: 'User' })  {}
-class ErrorDto extends createZodDto(z.object({ code: z.number() }),  { id: 'Error' }) {}
+class UserDto extends createZodDto(z.object({ id: z.string() }), { id: 'User' }) {}
+class ErrorDto extends createZodDto(z.object({ code: z.number() }), { id: 'Error' }) {}
 class FatalDto extends createZodDto(z.object({ trace: z.string() }), { id: 'Fatal' }) {}
 
 class UsersController {
   @Get(':id')
-  @ZodResponse({                                           type: UserDto })  // 200 inferred
-  @ZodResponse({ status: HttpStatus.NOT_FOUND,             type: ErrorDto })
+  @ZodResponse({ type: UserDto }) // 200 inferred
+  @ZodResponse({ status: HttpStatus.NOT_FOUND, type: ErrorDto })
   @ZodResponse({ status: HttpStatus.INTERNAL_SERVER_ERROR, type: FatalDto })
   getUser(): void {}
 }
@@ -372,8 +393,7 @@ import { ZodNestModule } from 'zod-nest';
     ZodNestModule.forRoot({
       validationLogs: { input: true, output: true },
       redactKeys: ['password', 'token', 'sessionId'],
-      createSerializationException: (err, ctx) =>
-        new MyCustomFiveHundred(err, ctx),
+      createSerializationException: (err, ctx) => new MyCustomFiveHundred(err, ctx),
     }),
   ],
   controllers: [UsersController],
@@ -385,14 +405,14 @@ class AppModule {}
 
 ## Module options
 
-| Option | Type | Default | What it does |
-|---|---|---|---|
-| `createValidationException` | `(err, argMetadata) => unknown` | uses `ZodValidationException` | Custom 400 exception for input failures |
+| Option                         | Type                                 | Default                          | What it does                                                |
+| ------------------------------ | ------------------------------------ | -------------------------------- | ----------------------------------------------------------- |
+| `createValidationException`    | `(err, argMetadata) => unknown`      | uses `ZodValidationException`    | Custom 400 exception for input failures                     |
 | `createSerializationException` | `(err, executionContext) => unknown` | uses `ZodSerializationException` | Custom 500 exception for output failures (strict mode only) |
-| `validationLogs` | `boolean \| { input?, output? }` | `false` | Opt-in failure-only logging |
-| `logger` | `LoggerService` | NestJS `Logger` | Replace the logger (pino, winston, …) |
-| `redactKeys` | `readonly string[]` | `DEFAULT_REDACT_KEYS` | Keys redacted in logs (replaces default list, no merge) |
-| `maxLoggedValueBytes` | `number` | `4096` | Truncate oversize logged values |
+| `validationLogs`               | `boolean \| { input?, output? }`     | `false`                          | Opt-in failure-only logging                                 |
+| `logger`                       | `LoggerService`                      | NestJS `Logger`                  | Replace the logger (pino, winston, …)                       |
+| `redactKeys`                   | `readonly string[]`                  | `DEFAULT_REDACT_KEYS`            | Keys redacted in logs (replaces default list, no merge)     |
+| `maxLoggedValueBytes`          | `number`                             | `4096`                           | Truncate oversize logged values                             |
 
 `DEFAULT_REDACT_KEYS` includes `password`, `secret`, `apiKey`, `authorization`, `bearer`, `token`, `accessToken`, `refreshToken`, `jwt`, `cookie`, `set-cookie`. Matching is case-insensitive and applied at any depth in the logged value.
 
@@ -412,7 +432,7 @@ A log entry carries:
 
 Redaction is **case-insensitive** at any depth — a key named `Password` deep in a nested object is replaced with `'[REDACTED]'` just like a top-level `password`. Truncation replaces values larger than `maxLoggedValueBytes` (UTF-8 bytes) with `{ _truncated: true, _originalBytes, _preview }` so you keep enough context to debug without flooding the logger.
 
-Supplying `redactKeys` **replaces** the default list — there is no merge. If you want to *add* keys, spread `DEFAULT_REDACT_KEYS`:
+Supplying `redactKeys` **replaces** the default list — there is no merge. If you want to _add_ keys, spread `DEFAULT_REDACT_KEYS`:
 
 ```ts
 import { DEFAULT_REDACT_KEYS, ZodNestModule } from 'zod-nest';
@@ -450,27 +470,35 @@ See [`docs/composition.md`](docs/composition.md) for the full contract, current
 A compact, link-out index. Type signatures and detailed semantics live in the companion docs.
 
 **DTO** — [`docs/dto.md`](docs/dto.md)
-- `createZodDto(schema, options?)`, `isZodDto(value)`, `ZodDto<TSchema>`, `Io`
+
+- `createZodDto(schema, options?)`, `isZodDto(value)`, `isZodSchema(value)`, `ZodDto<TSchema>`, `Io`
 
 **Validation** — [`docs/validation-pipe.md`](docs/validation-pipe.md)
+
 - `ZodValidationPipe`, `ZodValidationException`, `ZodValidationPipeOptions`, `CreateValidationException`
 
 **Response** — [`docs/responses.md`](docs/responses.md)
-- `@ZodResponse({ status?, type, description?, passthroughOnError? })`, `ZodSerializerInterceptor`, `ZodSerializationException`, `defaultStatusFor`, `resolveEffectiveStatus`, `ResponseStatusInput`, `ResponseStatusWildcard`, `ResponseVariant`, `ZOD_RESPONSES_METADATA_KEY`
+
+- `@ZodResponse({ status?, type, description?, passthroughOnError?, contentType?, stream? })` (`type` is a DTO or raw schema, or an array/tuple of either), `ZodSerializerInterceptor`, `ZodSerializationException`, `defaultStatusFor`, `resolveEffectiveStatus`, `ResponseStatusInput`, `ResponseStatusWildcard`, `ResponseVariant`, `ZodResponseEntry`, `ZodResponseType`, `ZOD_RESPONSES_METADATA_KEY`
 
 **Parameter decorators for raw schemas** — [`docs/recipes/intersection-with-union.md`](docs/recipes/intersection-with-union.md)
+
 - `@ZodBody(schema, options?)`, `@ZodQuery(schema, options?)`, `@ZodHeaders(schema, options?)`, `@ZodCookies(schema, options?)`, `ZodBodyOptions`, `ZodQueryOptions`, `ZodHeadersOptions`, `ZodCookiesOptions`
 
 **Document** — [`docs/swagger-integration.md`](docs/swagger-integration.md)
+
 - `applyZodNest(rawDoc, options)`, `ApplyZodNestOptions`, `ZodNestDocumentError`
 
 **Module** — [`docs/module-options.md`](docs/module-options.md) / [`docs/logging.md`](docs/logging.md)
+
 - `ZodNestModule.forRoot(options?)`, `ZodNestModuleOptions`, `DEFAULT_REDACT_KEYS`, `DEFAULT_MAX_LOGGED_VALUE_BYTES`, `ZOD_NEST_OPTIONS`
 
 **Schema engine** — single-schema mode and extension points
+
 - `toOpenApi(schema, opts)`, `createRegistry()`, `defaultRegistry`, `registerSchema(schema, registry?, options?)`, `ZodNestRegistry`, `RegisterSchemaOptions`, `Override`, `OverrideContext`, `overrideJSONSchema(schema, fragment | { input?, output? })`, `OverrideJSONSchemaArg`, `ZodNestError`, `ZodNestUnrepresentableError`, `extend`, `getLineage`, `LineageEntry`
 
 **Helpers** (subpath: `zod-nest/helpers`) — common JSON Schema fragments + presets for assembling overrides
+
 - **Fragment catalog** (frozen consts): `dateTimeFragment`, `dateFragment`, `timeFragment`, `uuidFragment`, `emailFragment`, `uriFragment`, `hostnameFragment`, `ipv4Fragment`, `ipv6Fragment`, `binaryFragment`, `byteFragment`, `int32Fragment`, `int64Fragment`, `floatFragment`, `doubleFragment`, `opaqueFragment`
 - **Sugar functions**: `binary(opts?)`, `opaque(opts?)`
 - **Type-strict composition**: `enrich(base, extras)` — extras are typed per fragment family
@@ -480,31 +508,31 @@ See [`docs/recipes/custom-openapi-overrides.md`](docs/recipes/custom-openapi-ove
 
 ## Documentation
 
-| Topic | Doc |
-|---|---|
-| Why this library exists | [`docs/why-this-exists.md`](docs/why-this-exists.md) |
-| `createZodDto` in depth | [`docs/dto.md`](docs/dto.md) |
-| Input validation | [`docs/validation-pipe.md`](docs/validation-pipe.md) |
-| Responses, multi-status, status resolution | [`docs/responses.md`](docs/responses.md) |
-| Module options reference | [`docs/module-options.md`](docs/module-options.md) |
-| Validation logging | [`docs/logging.md`](docs/logging.md) |
-| Swagger integration & custom emission | [`docs/swagger-integration.md`](docs/swagger-integration.md) |
-| Composition (experimental) | [`docs/composition.md`](docs/composition.md) |
-| Exception classes | [`docs/exceptions.md`](docs/exceptions.md) |
-| Recipes | [`docs/recipes/`](docs/recipes/) |
+| Topic                                      | Doc                                                          |
+| ------------------------------------------ | ------------------------------------------------------------ |
+| Why this library exists                    | [`docs/why-this-exists.md`](docs/why-this-exists.md)         |
+| `createZodDto` in depth                    | [`docs/dto.md`](docs/dto.md)                                 |
+| Input validation                           | [`docs/validation-pipe.md`](docs/validation-pipe.md)         |
+| Responses, multi-status, status resolution | [`docs/responses.md`](docs/responses.md)                     |
+| Module options reference                   | [`docs/module-options.md`](docs/module-options.md)           |
+| Validation logging                         | [`docs/logging.md`](docs/logging.md)                         |
+| Swagger integration & custom emission      | [`docs/swagger-integration.md`](docs/swagger-integration.md) |
+| Composition (experimental)                 | [`docs/composition.md`](docs/composition.md)                 |
+| Exception classes                          | [`docs/exceptions.md`](docs/exceptions.md)                   |
+| Recipes                                    | [`docs/recipes/`](docs/recipes/)                             |
 
 ## Compatibility matrix
 
 `zod-nest` declares explicit min + max peer-dep ranges in `package.json`: `zod >=4.4.0 <5.0.0`, `@nestjs/common >=11.0.1 <12.0.0`, `@nestjs/core >=11.0.1 <12.0.0`, `@nestjs/swagger >=11.0.0 <12.0.0`, `rxjs >=7.6.0 <8.0.0`, `reflect-metadata >=0.2.0 <0.3.0`, Node `>=22`. CI validates those claims by running the full test suite against the cells below; a red cell is a real blocker. Upper bounds are deliberate — a new peer major has to land in a real PR with a `/check-upstream-updates` audit before consumers can install it against this library.
 
-| Cell | `zod` | `@nestjs/common` | `@nestjs/core` | `@nestjs/swagger` | `rxjs` | `reflect-metadata` |
-|---|---|---|---|---|---|---|
-| `floor` | 4.4.0 | 11.0.1 | 11.0.1 | 11.0.0 | 7.6.0 | 0.2.0 |
-| `zod-latest` | latest | 11.0.1 | 11.0.1 | 11.0.0 | 7.6.0 | 0.2.0 |
-| `nest-latest` | 4.4.0 | latest | latest | latest | 7.6.0 | 0.2.0 |
-| `rxjs-latest` | 4.4.0 | 11.0.1 | 11.0.1 | 11.0.0 | latest | 0.2.0 |
-| `reflect-metadata-latest` | 4.4.0 | 11.0.1 | 11.0.1 | 11.0.0 | 7.6.0 | latest |
-| `all-latest` | latest | latest | latest | latest | latest | latest |
+| Cell                      | `zod`  | `@nestjs/common` | `@nestjs/core` | `@nestjs/swagger` | `rxjs` | `reflect-metadata` |
+| ------------------------- | ------ | ---------------- | -------------- | ----------------- | ------ | ------------------ |
+| `floor`                   | 4.4.0  | 11.0.1           | 11.0.1         | 11.0.0            | 7.6.0  | 0.2.0              |
+| `zod-latest`              | latest | 11.0.1           | 11.0.1         | 11.0.0            | 7.6.0  | 0.2.0              |
+| `nest-latest`             | 4.4.0  | latest           | latest         | latest            | 7.6.0  | 0.2.0              |
+| `rxjs-latest`             | 4.4.0  | 11.0.1           | 11.0.1         | 11.0.0            | latest | 0.2.0              |
+| `reflect-metadata-latest` | 4.4.0  | 11.0.1           | 11.0.1         | 11.0.0            | 7.6.0  | latest             |
+| `all-latest`              | latest | latest           | latest         | latest            | latest | latest             |
 
 Cell definitions live in [`.github/compat-matrix.json`](.github/compat-matrix.json). The CI workflow ([`.github/workflows/compat-matrix.yml`](.github/workflows/compat-matrix.yml)) runs on every push to `main` and weekly on Monday — when a cell fails, the workflow opens (or comments on) a GitHub issue labelled `compat-matrix-failure` so the regression is tracked outside the Actions UI. Editing the JSON is the formal way to extend or shrink supported ranges. Node is not matrixed — the `>=22` floor is enforced by `engines`.
 

package/dist/index.d.mts

@@ -225,6 +225,16 @@ declare const isZodDtoMarker: (value: unknown) => value is ZodDtoMarker;
  * NestJS exposes via `ArgumentMetadata`.
  */
 declare const isZodDto: (value: unknown) => value is ZodDto;
+/**
+ * Runtime guard: is `value` a Zod schema (any `z.*` type)?
+ *
+ * Used by `@ZodResponse` to accept a raw schema in place of a DTO — including
+ * `z.discriminatedUnion` / `z.union` / `z.intersection`, which can't be wrapped
+ * with `createZodDto` (their `z.infer` is a union, so `class … extends
+ * createZodDto(schema)` fails to typecheck with TS2509). `instanceof z.ZodType`
+ * holds for every schema built through the same `zod` module instance.
+ */
+declare const isZodSchema: (value: unknown) => value is z.ZodType;
 
 /**
  * Default exception thrown by `ZodSerializerInterceptor` in strict mode
@@ -292,6 +302,93 @@ interface ValidationLogContext {
 }
 type LogValidationFailure = (err: z.ZodError, value: unknown, ctx: ValidationLogContext) => void;
 
+/**
+ * Public metadata key for the array of `ResponseVariant` records attached
+ * to handler methods by `@ZodResponse(...)`. Symbol.for() so external
+ * consumers (e.g. custom interceptors or doc builders) can read the same
+ * registry across realms.
+ */
+declare const ZOD_RESPONSES_METADATA_KEY: unique symbol;
+type ResponseVariantKind = 'single' | 'array' | 'tuple';
+/**
+ * OpenAPI 3.1 range keys accepted by `@ZodResponse({ status })`. Matched
+ * by `ZodSerializerInterceptor` after exact numeric matches fail —
+ * `'2XX'` covers 200–299, `'4XX'` covers 400–499, and so on.
+ */
+type ResponseStatusWildcard = '1XX' | '2XX' | '3XX' | '4XX' | '5XX';
+/**
+ * Description payload accepted by `@ZodResponse(...)` and passed through to
+ * `applyZodNest`'s `@ApiResponse(...)` emitter. String form is shorthand for
+ * `{ description }`; the object form lets users declare OpenAPI response
+ * `headers` / `links` alongside the description.
+ */
+type ZodResponseDescription = string | {
+    description: string;
+    headers?: Record<string, unknown>;
+    links?: Record<string, unknown>;
+};
+/**
+ * One variant record per `@ZodResponse(...)` call. `dto` is kept alongside
+ * `validationSchema` so `applyZodNest` can emit `@ApiResponse({ type })`
+ * without unwrapping the runtime-only `z.array(...)` / `z.tuple([...])` wrapper.
+ *
+ * `status` is `undefined` when the user didn't pass one explicitly OR when
+ * the user wrote `'default'` (the decorator collapses both to `undefined` —
+ * they mean the same thing: "resolve to the method's default status at
+ * request time"). The effective status is resolved lazily by
+ * `resolveEffectiveStatus(variant, handler)` because `@ZodResponse` runs
+ * *before* NestJS' route decorators (`@Get`, `@Post`, ...) under
+ * TypeScript's bottom-up application order, so `METHOD_METADATA` is not
+ * yet set when the decorator evaluates.
+ *
+ * A wildcard string (`'2XX'` / `'4XX'` / ...) is kept verbatim — the
+ * matcher in `ZodSerializerInterceptor` handles range comparison.
+ */
+interface ResponseVariant {
+    status: number | ResponseStatusWildcard | undefined;
+    kind: ResponseVariantKind;
+    dto: ZodDto | readonly ZodDto[];
+    validationSchema: z.ZodType;
+    description?: ZodResponseDescription;
+    passthroughOnError: boolean;
+    /**
+     * Raw `contentType` option from `@ZodResponse`, if set. `undefined` means
+     * "resolve lazily" — `resolveContentType` falls back to a stream-typed
+     * `@Header('Content-Type', …)` or `application/json`. Drives the OpenAPI
+     * media-type key.
+     */
+    contentType?: string;
+    /**
+     * Raw `stream` option from `@ZodResponse`, if set. `undefined` means
+     * "infer" — `isStreamResponse` treats the response as a stream when the
+     * effective content type is a known stream type. Streams skip validation.
+     */
+    stream?: boolean;
+}
+
+/**
+ * Content types whose bodies zod-nest treats as streams by default: the
+ * handler writes them straight to the response buffer (SSE, NDJSON, raw
+ * binary, files), so `ZodSerializerInterceptor` skips validation and the
+ * OpenAPI media-type key becomes the stream type rather than `application/json`.
+ *
+ * A trailing `/*` marks a family prefix — `image/*` matches `image/png`,
+ * `image/jpeg`, … — everything else matches exactly. Consumers extend this set
+ * *additively* via `ZodNestModuleOptions.streamContentTypes`; the defaults are
+ * always retained so SSE / NDJSON detection can't be accidentally dropped.
+ */
+declare const DEFAULT_STREAM_CONTENT_TYPES: readonly string[];
+/**
+ * Normalised stream-content-type matcher: exact media types in a `Set` for
+ * O(1) lookup, family prefixes (`image/`, …) checked with `startsWith`. Built
+ * once by `normalizeStreamMatcher` from the default list (decoration time) or
+ * the default ∪ module-configured list (runtime).
+ */
+interface StreamContentTypeMatcher {
+    exact: ReadonlySet<string>;
+    prefixes: readonly string[];
+}
+
 /**
  * Module-scope factory for the exception thrown by `ZodValidationPipe` on
  * input validation failure. Mirrors the existing per-pipe option but lives
@@ -329,6 +426,14 @@ interface ZodNestModuleOptions {
      * values become `{ _truncated: true, _originalBytes, _preview }`.
      */
     maxLoggedValueBytes?: number;
+    /**
+     * Additional response content types treated as streams — written directly
+     * to the response buffer and never validated by `ZodSerializerInterceptor`.
+     * MERGED with the built-in `DEFAULT_STREAM_CONTENT_TYPES` (SSE, NDJSON,
+     * octet-stream, pdf, `image/*`, `audio/*`, `video/*`), so the defaults are
+     * always retained. A trailing `/*` entry matches a media-type family.
+     */
+    streamContentTypes?: readonly string[];
 }
 /**
  * Resolved options consumed by pipe + interceptor. `forRoot()` builds this
@@ -342,6 +447,8 @@ interface NormalizedZodNestOptions {
     logInputFailure: LogValidationFailure;
     /** No-op when `validationLogs.output` resolved to false. */
     logOutputFailure: LogValidationFailure;
+    /** Built-in defaults ∪ `streamContentTypes`, used by the interceptor's stream check. */
+    streamMatcher: StreamContentTypeMatcher;
 }
 declare const DEFAULT_REDACT_KEYS: readonly string[];
 declare const DEFAULT_MAX_LOGGED_VALUE_BYTES = 4096;
@@ -380,69 +487,28 @@ declare class ZodValidationPipe implements PipeTransform {
 }
 
 /**
- * Public metadata key for the array of `ResponseVariant` records attached
- * to handler methods by `@ZodResponse(...)`. Symbol.for() so external
- * consumers (e.g. custom interceptors or doc builders) can read the same
- * registry across realms.
- */
-declare const ZOD_RESPONSES_METADATA_KEY: unique symbol;
-type ResponseVariantKind = 'single' | 'array' | 'tuple';
-/**
- * OpenAPI 3.1 range keys accepted by `@ZodResponse({ status })`. Matched
- * by `ZodSerializerInterceptor` after exact numeric matches fail —
- * `'2XX'` covers 200–299, `'4XX'` covers 400–499, and so on.
- */
-type ResponseStatusWildcard = '1XX' | '2XX' | '3XX' | '4XX' | '5XX';
-/**
- * Description payload accepted by `@ZodResponse(...)` and passed through to
- * `applyZodNest`'s `@ApiResponse(...)` emitter. String form is shorthand for
- * `{ description }`; the object form lets users declare OpenAPI response
- * `headers` / `links` alongside the description.
- */
-type ZodResponseDescription = string | {
-    description: string;
-    headers?: Record<string, unknown>;
-    links?: Record<string, unknown>;
-};
-/**
- * One variant record per `@ZodResponse(...)` call. `dto` is kept alongside
- * `validationSchema` so `applyZodNest` can emit `@ApiResponse({ type })`
- * without unwrapping the runtime-only `z.array(...)` / `z.tuple([...])` wrapper.
- *
- * `status` is `undefined` when the user didn't pass one explicitly OR when
- * the user wrote `'default'` (the decorator collapses both to `undefined` —
- * they mean the same thing: "resolve to the method's default status at
- * request time"). The effective status is resolved lazily by
- * `resolveEffectiveStatus(variant, handler)` because `@ZodResponse` runs
- * *before* NestJS' route decorators (`@Get`, `@Post`, ...) under
- * TypeScript's bottom-up application order, so `METHOD_METADATA` is not
- * yet set when the decorator evaluates.
- *
- * A wildcard string (`'2XX'` / `'4XX'` / ...) is kept verbatim — the
- * matcher in `ZodSerializerInterceptor` handles range comparison.
+ * One entry in `@ZodResponse({ type })` — either a zod-nest DTO or a raw Zod
+ * schema. A raw schema is normalised internally to `createZodDto(schema).Output`
+ * (output IO, since a response body is output-only), so schemas that can't be
+ * wrapped with `createZodDto` — `z.discriminatedUnion` / `z.union` /
+ * `z.intersection`, whose `z.infer` is a union and so trip TS2509 in an
+ * `extends` clause — can be passed straight to a response. See `toResponseDto`.
  */
-interface ResponseVariant {
-    status: number | ResponseStatusWildcard | undefined;
-    kind: ResponseVariantKind;
-    dto: ZodDto | readonly ZodDto[];
-    validationSchema: z.ZodType;
-    description?: ZodResponseDescription;
-    passthroughOnError: boolean;
-}
-
+type ZodResponseEntry = ZodDto | z.ZodType;
 /**
- * Accepted shapes for `@ZodResponse({ type })`:
- * - `Dto` → validates as `Dto.schema` (single-DTO response).
- * - `[Dto]` (length 1) → validates as `z.array(Dto.schema)`; matches Nest's
+ * Accepted shapes for `@ZodResponse({ type })`. Each slot is a `ZodResponseEntry`
+ * (DTO or raw schema), and the two may be mixed within an array:
+ * - `Dto` / `Schema` → validates as the entry's schema (single response).
+ * - `[Entry]` (length 1) → validates as `z.array(entry.schema)`; matches Nest's
  *   `@ApiResponse({ isArray: true })` convention without minting a separate
  *   `*sDto` id.
  * - `[A, B, ...]` (length ≥ 2) → validates as `z.tuple([A.schema, B.schema, ...])`;
  *   surfaces as an OpenAPI 3.1 `prefixItems` tuple via `applyZodNest`.
  *
- * Empty arrays and non-DTO elements throw `TypeError` at decoration time
- * so typos surface at module load, not the first request.
+ * Empty arrays and entries that are neither a DTO nor a schema throw `TypeError`
+ * at decoration time so typos surface at module load, not the first request.
  */
-type ZodResponseType = ZodDto | readonly [ZodDto, ...ZodDto[]];
+type ZodResponseType = ZodResponseEntry | readonly [ZodResponseEntry, ...ZodResponseEntry[]];
 /**
  * Accepted shapes for `@ZodResponse({ status })`:
  * - `number` — exact match against `response.statusCode` (most common case).
@@ -462,6 +528,20 @@ interface ZodResponseOptions {
     type: ZodResponseType;
     description?: ZodResponseDescription;
     passthroughOnError?: boolean;
+    /**
+     * Response content type, used as the OpenAPI media-type key (`@ApiResponse`
+     * `content`). Defaults to `'application/json'`. Set a stream type
+     * (`'text/event-stream'`, `'application/x-ndjson'`, …) to document a streamed
+     * body; combined with `stream` it also turns off response validation.
+     */
+    contentType?: string;
+    /**
+     * When `true`, the response is written directly to the buffer and
+     * `ZodSerializerInterceptor` skips validation. When unset, it is inferred:
+     * a stream-typed `contentType` (or a stream-typed `@Header('Content-Type', …)`)
+     * implies `true`. See `DEFAULT_STREAM_CONTENT_TYPES`.
+     */
+    stream?: boolean;
 }
 /**
  * Method-only decorator. Declares a typed response variant for the handler
@@ -474,16 +554,16 @@ interface ZodResponseOptions {
  * `'NXX'` wildcard). The wrapped Zod schema (array / tuple) is built once
  * at decoration time — no per-request schema construction.
  *
- * **Decorator-ordering note (implicit `status` only).** TypeScript decorators
- * apply bottom-up, so `@ZodResponse` (typically written above `@Get` /
- * `@HttpCode`) executes its factory body *first* — before sibling
- * decorators have written their `HTTP_CODE_METADATA` / `METHOD_METADATA`.
- * When `opts.status` is explicit, the `@ApiResponse(...)` call is applied
- * synchronously — there's nothing to wait for. When `opts.status` is
- * implicit (resolves to `@HttpCode` or the HTTP-method default), the
- * `@ApiResponse(...)` call is deferred via `queueMicrotask` so the sibling
- * metadata has settled by the time we read it. See `docs/responses.md →
- * "Decorator ordering & the microtask trick"`.
+ * **Decorator-ordering note.** TypeScript decorators apply bottom-up, so
+ * `@ZodResponse` (typically written above `@Get` / `@HttpCode` /
+ * `@Header(...)`) runs *before* those siblings have written their
+ * `HTTP_CODE_METADATA` / `METHOD_METADATA` / `HEADERS_METADATA`. The
+ * `@ApiResponse(...)` call is therefore always deferred via `queueMicrotask`,
+ * so by the time it reads sibling metadata — the effective status *and* the
+ * effective content type (including `@Header('Content-Type', …)` inference) —
+ * everything has settled. The document is built much later
+ * (`SwaggerModule.createDocument`), so the deferral is invisible to output.
+ * See `docs/responses.md → "Decorator ordering & the microtask trick"`.
  */
 declare const ZodResponse: (opts: ZodResponseOptions) => MethodDecorator;
 
@@ -586,6 +666,7 @@ declare class ZodSerializerInterceptor implements NestInterceptor {
     private readonly reflector;
     private readonly logOutputFailure;
     private readonly createSerializationException;
+    private readonly streamMatcher;
     constructor(reflector: Reflector, options?: NormalizedZodNestOptions);
     intercept(context: ExecutionContext, next: CallHandler): Observable<unknown>;
     private transform;
@@ -714,4 +795,4 @@ declare class ZodNestDocumentError extends ZodNestError {
     constructor(code: ZodNestDocumentErrorCode, message: string, details?: Record<string, unknown>);
 }
 
-export { type ApplyZodNestOptions, COMPONENTS_SCHEMAS_PREFIX, type CreateSerializationException, type CreateValidationException, type CreateZodDtoOptions, DEFAULT_MAX_LOGGED_VALUE_BYTES, DEFAULT_REDACT_KEYS, type Io, type LineageEntry, type NormalizedZodNestOptions, type Override, type OverrideContext, type OverrideJSONSchemaArg, type RegisterSchemaOptions, type ResponseStatusInput, type ResponseStatusWildcard, type ResponseVariant, type ResponseVariantKind, SchemaObject, type ToOpenApiOptions, type ToOpenApiResult, ZOD_DTO_SYMBOL, ZOD_NEST_DTO_EXTENSION, ZOD_NEST_ERROR_DUPLICATE_ID, ZOD_NEST_ERROR_EXTENSION, ZOD_NEST_OPTIONS, ZOD_RESPONSES_METADATA_KEY, ZodBody, type ZodBodyOptions, ZodCookies, type ZodCookiesOptions, type ZodDto, type ZodDtoMarker, ZodHeaders, type ZodHeadersOptions, ZodNestDocumentError, type ZodNestDocumentErrorCode, ZodNestError, ZodNestModule, type ZodNestModuleOptions, type ZodNestRegistry, ZodNestUnrepresentableError, ZodQuery, type ZodQueryOptions, ZodResponse, type ZodResponseDescription, type ZodResponseOptions, type ZodResponseType, ZodSerializationException, ZodSerializerInterceptor, ZodValidationException, ZodValidationPipe, type ZodValidationPipeArg, type ZodValidationPipeOptions, applyZodNest, createRegistry, createZodDto, defaultRegistry, defaultStatusFor, extend, getLineage, isZodDto, isZodDtoMarker, makeZodDtoMarker, overrideJSONSchema, registerSchema, resolveEffectiveStatus, toOpenApi };
+export { type ApplyZodNestOptions, COMPONENTS_SCHEMAS_PREFIX, type CreateSerializationException, type CreateValidationException, type CreateZodDtoOptions, DEFAULT_MAX_LOGGED_VALUE_BYTES, DEFAULT_REDACT_KEYS, DEFAULT_STREAM_CONTENT_TYPES, type Io, type LineageEntry, type NormalizedZodNestOptions, type Override, type OverrideContext, type OverrideJSONSchemaArg, type RegisterSchemaOptions, type ResponseStatusInput, type ResponseStatusWildcard, type ResponseVariant, type ResponseVariantKind, SchemaObject, type ToOpenApiOptions, type ToOpenApiResult, ZOD_DTO_SYMBOL, ZOD_NEST_DTO_EXTENSION, ZOD_NEST_ERROR_DUPLICATE_ID, ZOD_NEST_ERROR_EXTENSION, ZOD_NEST_OPTIONS, ZOD_RESPONSES_METADATA_KEY, ZodBody, type ZodBodyOptions, ZodCookies, type ZodCookiesOptions, type ZodDto, type ZodDtoMarker, ZodHeaders, type ZodHeadersOptions, ZodNestDocumentError, type ZodNestDocumentErrorCode, ZodNestError, ZodNestModule, type ZodNestModuleOptions, type ZodNestRegistry, ZodNestUnrepresentableError, ZodQuery, type ZodQueryOptions, ZodResponse, type ZodResponseDescription, type ZodResponseEntry, type ZodResponseOptions, type ZodResponseType, ZodSerializationException, ZodSerializerInterceptor, ZodValidationException, ZodValidationPipe, type ZodValidationPipeArg, type ZodValidationPipeOptions, applyZodNest, createRegistry, createZodDto, defaultRegistry, defaultStatusFor, extend, getLineage, isZodDto, isZodDtoMarker, isZodSchema, makeZodDtoMarker, overrideJSONSchema, registerSchema, resolveEffectiveStatus, toOpenApi };