zod-nest 0.3.0 → 0.5.0

package/dist/index.d.mts

@@ -1,6 +1,9 @@
 import { z } from 'zod';
 import { JSONSchema, $ZodTypes } from 'zod/v4/core';
-import { BadRequestException, ArgumentMetadata, PipeTransform } from '@nestjs/common';
+import { InternalServerErrorException, ExecutionContext, BadRequestException, ArgumentMetadata, LoggerService, PipeTransform, NestInterceptor, CallHandler, DynamicModule, INestApplication } from '@nestjs/common';
+import { Reflector } from '@nestjs/core';
+import { Observable } from 'rxjs';
+import { OpenAPIObject } from '@nestjs/swagger';
 
 /** OpenAPI 3.1 `$ref` prefix for entries in `components.schemas`. */
 declare const COMPONENTS_SCHEMAS_PREFIX = "#/components/schemas/";
@@ -30,6 +33,13 @@ interface ZodNestRegistry {
     register(schema: z.ZodType, id: string): void;
     hasCollision(id: string): boolean;
     getCollisions(): ReadonlyMap<string, ReadonlySet<z.ZodType>>;
+    /**
+     * Snapshot of every id registered through this `ZodNestRegistry`. Phase 2e's
+     * bulk-mode emitter uses it to filter `z.toJSONSchema(registry.zodRegistry,
+     * ...)` output to zod-nest-known ids only (the underlying Zod registry is
+     * `z.globalRegistry`, which can hold third-party entries).
+     */
+    ids(): readonly string[];
 }
 declare const createRegistry: () => ZodNestRegistry;
 /**
@@ -126,6 +136,30 @@ declare const isZodDtoMarker: (value: unknown) => value is ZodDtoMarker;
  */
 declare const isZodDto: (value: unknown) => value is ZodDto;
 
+/**
+ * Default exception thrown by `ZodSerializerInterceptor` in strict mode
+ * (i.e. when `@ZodResponse({ passthroughOnError: true })` is NOT set) on
+ * response-validation failure.
+ *
+ * Body shape (returned by `getResponse()`):
+ * ```
+ * {
+ *   statusCode: 500,
+ *   message: 'Response validation failed',
+ *   errors: z.treeifyError(zodError),
+ * }
+ * ```
+ *
+ * Carries `zodError` and `executionContext` so custom exception filters
+ * can introspect the original validation failure and the request that
+ * produced it.
+ */
+declare class ZodSerializationException extends InternalServerErrorException {
+    readonly zodError: z.ZodError;
+    readonly executionContext?: ExecutionContext;
+    constructor(zodError: z.ZodError, executionContext?: ExecutionContext);
+}
+
 /**
  * Default exception thrown by `ZodValidationPipe` when input fails to parse.
  *
@@ -147,6 +181,78 @@ declare class ZodValidationException extends BadRequestException {
     constructor(zodError: z.ZodError, argMetadata?: ArgumentMetadata);
 }
 
+interface ValidationLogContext {
+    /** Which side of the request emitted the failure. */
+    side: 'input' | 'output';
+    /** Severity to log at; the formatter does not decide this. */
+    severity: 'warn' | 'error';
+    /** Pre-formatted DTO label, e.g. `'UserDto'`, `'[UserDto]'`, `'[A, B]'`. */
+    dto: string;
+    /** Output side only — HTTP response status code. */
+    status?: number;
+    /** Output side only — `Controller.method` best-effort. */
+    handler?: string;
+    /** Input side only — `body` / `query` / `param` / `custom`. */
+    argType?: string;
+}
+type LogValidationFailure = (err: z.ZodError, value: unknown, ctx: ValidationLogContext) => void;
+
+/**
+ * Module-scope factory for the exception thrown by `ZodValidationPipe` on
+ * input validation failure. Mirrors the existing per-pipe option but lives
+ * at module scope; per-instance constructor arg wins.
+ */
+type CreateValidationException$1 = (err: z.ZodError, argMetadata: ArgumentMetadata) => unknown;
+/**
+ * Module-scope factory for the exception thrown by `ZodSerializerInterceptor`
+ * on output validation failure (strict mode only). Soft mode never calls
+ * this factory.
+ */
+type CreateSerializationException = (err: z.ZodError, executionContext: ExecutionContext) => unknown;
+/** Public options accepted by `ZodNestModule.forRoot()`. */
+interface ZodNestModuleOptions {
+    createValidationException?: CreateValidationException$1;
+    createSerializationException?: CreateSerializationException;
+    /**
+     * Failure-only validation logging. `true` enables both input and output;
+     * the granular form lets each side be toggled independently. Default: off.
+     */
+    validationLogs?: boolean | {
+        input?: boolean;
+        output?: boolean;
+    };
+    /** Override Nest's built-in `Logger` (e.g. pino/winston adapter). */
+    logger?: LoggerService;
+    /**
+     * Keys whose values get scrubbed from logged input/response objects.
+     * Matched case-insensitively at any depth. Supplying this option
+     * REPLACES the default list (no merge).
+     */
+    redactKeys?: readonly string[];
+    /**
+     * Maximum size in bytes (UTF-8) for any single logged value. Oversized
+     * values become `{ _truncated: true, _originalBytes, _preview }`.
+     */
+    maxLoggedValueBytes?: number;
+}
+/**
+ * Resolved options consumed by pipe + interceptor. `forRoot()` builds this
+ * once and stuffs it into a provider for the `ZOD_NEST_OPTIONS` injection
+ * token; downstream code never re-checks the raw `validationLogs` flag.
+ */
+interface NormalizedZodNestOptions {
+    createValidationException: CreateValidationException$1 | undefined;
+    createSerializationException: CreateSerializationException | undefined;
+    /** No-op when `validationLogs.input` resolved to false. */
+    logInputFailure: LogValidationFailure;
+    /** No-op when `validationLogs.output` resolved to false. */
+    logOutputFailure: LogValidationFailure;
+}
+declare const DEFAULT_REDACT_KEYS: readonly string[];
+declare const DEFAULT_MAX_LOGGED_VALUE_BYTES = 4096;
+/** DI token for `NormalizedZodNestOptions`. */
+declare const ZOD_NEST_OPTIONS: unique symbol;
+
 /**
  * Build the exception thrown by `ZodValidationPipe` on validation failure.
  * Receives Zod's error and the NestJS argument metadata; returns anything
@@ -168,11 +274,200 @@ type ZodValidationPipeArg = z.ZodType | ZodDto | ZodValidationPipeOptions;
 
 declare class ZodValidationPipe implements PipeTransform {
     private readonly explicitSchema;
+    private readonly explicitDtoName;
     private readonly createValidationException;
-    constructor(arg?: ZodValidationPipeArg);
+    private readonly logInputFailure;
+    constructor(arg?: ZodValidationPipeArg, moduleOptions?: NormalizedZodNestOptions);
     transform(value: unknown, metadata: ArgumentMetadata): Promise<unknown>;
     private resolveSchema;
+    private resolveDtoLabel;
     private static parseArg;
 }
 
-export { COMPONENTS_SCHEMAS_PREFIX, type CreateValidationException, type CreateZodDtoOptions, type Io, type Override, type OverrideContext, type SchemaObject, type ToOpenApiOptions, type ToOpenApiResult, ZOD_DTO_SYMBOL, ZOD_NEST_DTO_EXTENSION, ZOD_NEST_ERROR_DUPLICATE_ID, ZOD_NEST_ERROR_EXTENSION, type ZodDto, type ZodDtoMarker, ZodNestError, type ZodNestRegistry, ZodNestUnrepresentableError, ZodValidationException, ZodValidationPipe, type ZodValidationPipeArg, type ZodValidationPipeOptions, createRegistry, createZodDto, defaultRegistry, isZodDto, isZodDtoMarker, makeZodDtoMarker, toOpenApi };
+/**
+ * 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';
+/**
+ * Description payload accepted by `@ZodResponse(...)` and passed through to
+ * Phase 2e'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 Phase 2e 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 — 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.
+ */
+interface ResponseVariant {
+    status: number | undefined;
+    kind: ResponseVariantKind;
+    dto: ZodDto | readonly ZodDto[];
+    validationSchema: z.ZodType;
+    description?: ZodResponseDescription;
+    passthroughOnError: boolean;
+}
+
+/**
+ * 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
+ *   `@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 in Phase 2e.
+ *
+ * Empty arrays and non-DTO elements throw `TypeError` at decoration time
+ * so typos surface at module load, not the first request.
+ */
+type ZodResponseType = ZodDto | readonly [ZodDto, ...ZodDto[]];
+interface ZodResponseOptions {
+    status?: number;
+    type: ZodResponseType;
+    description?: ZodResponseDescription;
+    passthroughOnError?: boolean;
+}
+/**
+ * Method-only decorator. Declares a typed response variant for the handler.
+ * Stack multiple decorations to declare per-status types; lookup at runtime
+ * is by `response.statusCode === variant.status`.
+ *
+ * The wrapped Zod schema (array / tuple) is built once at decoration time
+ * and stored on the variant record — no per-request schema construction.
+ */
+declare const ZodResponse: (opts: ZodResponseOptions) => MethodDecorator;
+
+declare class ZodSerializerInterceptor implements NestInterceptor {
+    private readonly reflector;
+    private readonly logOutputFailure;
+    private readonly createSerializationException;
+    constructor(reflector: Reflector, options?: NormalizedZodNestOptions);
+    intercept(context: ExecutionContext, next: CallHandler): Observable<unknown>;
+    private transform;
+}
+
+/**
+ * Compute the default HTTP status code for a handler when `@ZodResponse(...)`
+ * is invoked without an explicit `status`. Lookup order (highest → lowest):
+ *
+ * 1. `@HttpCode(n)` on the handler — explicit per-handler status override.
+ *    NestJS sets `HTTP_CODE_METADATA` to the numeric status when present.
+ * 2. HTTP method default — `POST` → `201`, everything else → `200`.
+ *
+ * The method default itself falls back to `200` when `METHOD_METADATA` is
+ * absent — pinned by tests so a future NestJS rename surfaces as a test
+ * failure rather than a silent regression.
+ */
+declare const defaultStatusFor: (handler: object) => number;
+/**
+ * Resolve the effective status code for a variant. Precedence chain:
+ *
+ * 1. Explicit `@ZodResponse({ status })` on the decorator call — `variant.status`.
+ * 2. `@HttpCode(n)` on the handler — read via `defaultStatusFor()` at runtime.
+ * 3. HTTP method default (POST → 201, others → 200) — also via `defaultStatusFor()`.
+ *
+ * Resolution is deferred to request time because `@ZodResponse` runs before
+ * NestJS' route + `@HttpCode` decorators — none of their metadata is set
+ * when the decorator evaluates.
+ */
+declare const resolveEffectiveStatus: (variant: ResponseVariant, handler: object) => number;
+
+/**
+ * Central wiring for the zod-nest pipe + interceptor. Call
+ * `ZodNestModule.forRoot(options?)` from your root `AppModule` to register
+ * `APP_PIPE` (`ZodValidationPipe`) and `APP_INTERCEPTOR`
+ * (`ZodSerializerInterceptor`) globally, with shared options for
+ * validation logging, redaction, and exception factories.
+ *
+ * `forRoot()` is optional — the pipe and interceptor also work as
+ * regular `APP_PIPE` / `APP_INTERCEPTOR` providers if you prefer to
+ * wire them manually; `@Optional()` injection of `ZOD_NEST_OPTIONS`
+ * falls through to safe defaults.
+ *
+ * Marked `global` so the `ZOD_NEST_OPTIONS` token is injectable from
+ * feature modules (e.g. a custom pipe that wants the same logger /
+ * redact list as the module-wired one).
+ */
+declare class ZodNestModule {
+    static forRoot(options?: ZodNestModuleOptions): DynamicModule;
+}
+
+interface ApplyZodNestOptions {
+    /**
+     * The NestJS app instance. Required so `applyZodNest` can walk controllers
+     * via `DiscoveryService` to pick up `@ZodResponse` output-side DTO usage —
+     * `@nestjs/swagger` is currently anemic on response shapes.
+     */
+    app: INestApplication;
+    /**
+     * `ZodNestRegistry` instance that holds the zod-nest DTOs. Defaults to
+     * `defaultRegistry` (the process-wide singleton populated by `createZodDto`).
+     * Pass an explicit registry for multi-app isolation (planned formalization
+     * in v0.2).
+     */
+    registry?: ZodNestRegistry;
+    /** User override pipe applied on top of the built-in override during emission. */
+    override?: Override;
+    /**
+     * Strict mode (default `true`) throws `ZodNestUnrepresentableError` on
+     * unrepresentable Zod constructs (bigint / date / symbol / transform / ...).
+     * Set to `false` to emit `{}` for those instead.
+     */
+    strict?: boolean;
+}
+/**
+ * Post-processor over the OpenAPI document emitted by
+ * `SwaggerModule.createDocument`. Mutates the doc in place AND returns it for
+ * compositional convenience. After this runs:
+ *
+ * - Every `components.schemas[<DtoClassName>]` placeholder with an
+ *   `x-zod-nest-dto` marker is replaced by the Zod-derived JSON Schema body,
+ *   keyed by the marker's `dtoId` (renaming as needed).
+ * - The I/O suffix truth table is applied — equal input/output bodies collapse
+ *   to one `components.schemas[id]`; divergent bodies split as
+ *   `id` (input) + `idOutput` (output), with response-side refs rewritten.
+ * - Every `$ref` whose target is missing throws `ZodNestDocumentError(DANGLING_REF)`.
+ *
+ * Composable with other doc-transform passes — apply other mutations before
+ * or after this function. The `app` argument is required because the
+ * output-side DTO usage lives on controller-method metadata that the doc
+ * doesn't surface; `DiscoveryService` resolves it.
+ */
+declare const applyZodNest: (doc: OpenAPIObject, opts: ApplyZodNestOptions) => OpenAPIObject;
+
+type ZodNestDocumentErrorCode = 'AMBIGUOUS_RENAME' | 'DANGLING_REF';
+/**
+ * Thrown by `applyZodNest` when the doc cannot be processed cleanly. Surfaces
+ * at doc-build time so typos / mis-registrations fail in CI, not at runtime.
+ *
+ * `AMBIGUOUS_RENAME`: two distinct DTO classes target the same registry id
+ * with differing bodies — the rename pass can't write `components.schemas[id]`
+ * unambiguously.
+ *
+ * `DANGLING_REF`: a `$ref` in the doc points at a `components.schemas` key
+ * that no longer exists after `applyZodNest`. Usually means a marker was
+ * stripped but its rename target wasn't populated, or a user-supplied pre-pass
+ * left a stale ref.
+ */
+declare class ZodNestDocumentError extends ZodNestError {
+    readonly code: ZodNestDocumentErrorCode;
+    readonly details: Readonly<Record<string, unknown>>;
+    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 NormalizedZodNestOptions, type Override, type OverrideContext, type ResponseVariant, type ResponseVariantKind, type 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, type ZodDto, type ZodDtoMarker, ZodNestDocumentError, type ZodNestDocumentErrorCode, ZodNestError, ZodNestModule, type ZodNestModuleOptions, type ZodNestRegistry, ZodNestUnrepresentableError, ZodResponse, type ZodResponseDescription, type ZodResponseOptions, type ZodResponseType, ZodSerializationException, ZodSerializerInterceptor, ZodValidationException, ZodValidationPipe, type ZodValidationPipeArg, type ZodValidationPipeOptions, applyZodNest, createRegistry, createZodDto, defaultRegistry, defaultStatusFor, isZodDto, isZodDtoMarker, makeZodDtoMarker, resolveEffectiveStatus, toOpenApi };

package/dist/index.d.ts

@@ -1,6 +1,9 @@
 import { z } from 'zod';
 import { JSONSchema, $ZodTypes } from 'zod/v4/core';
-import { BadRequestException, ArgumentMetadata, PipeTransform } from '@nestjs/common';
+import { InternalServerErrorException, ExecutionContext, BadRequestException, ArgumentMetadata, LoggerService, PipeTransform, NestInterceptor, CallHandler, DynamicModule, INestApplication } from '@nestjs/common';
+import { Reflector } from '@nestjs/core';
+import { Observable } from 'rxjs';
+import { OpenAPIObject } from '@nestjs/swagger';
 
 /** OpenAPI 3.1 `$ref` prefix for entries in `components.schemas`. */
 declare const COMPONENTS_SCHEMAS_PREFIX = "#/components/schemas/";
@@ -30,6 +33,13 @@ interface ZodNestRegistry {
     register(schema: z.ZodType, id: string): void;
     hasCollision(id: string): boolean;
     getCollisions(): ReadonlyMap<string, ReadonlySet<z.ZodType>>;
+    /**
+     * Snapshot of every id registered through this `ZodNestRegistry`. Phase 2e's
+     * bulk-mode emitter uses it to filter `z.toJSONSchema(registry.zodRegistry,
+     * ...)` output to zod-nest-known ids only (the underlying Zod registry is
+     * `z.globalRegistry`, which can hold third-party entries).
+     */
+    ids(): readonly string[];
 }
 declare const createRegistry: () => ZodNestRegistry;
 /**
@@ -126,6 +136,30 @@ declare const isZodDtoMarker: (value: unknown) => value is ZodDtoMarker;
  */
 declare const isZodDto: (value: unknown) => value is ZodDto;
 
+/**
+ * Default exception thrown by `ZodSerializerInterceptor` in strict mode
+ * (i.e. when `@ZodResponse({ passthroughOnError: true })` is NOT set) on
+ * response-validation failure.
+ *
+ * Body shape (returned by `getResponse()`):
+ * ```
+ * {
+ *   statusCode: 500,
+ *   message: 'Response validation failed',
+ *   errors: z.treeifyError(zodError),
+ * }
+ * ```
+ *
+ * Carries `zodError` and `executionContext` so custom exception filters
+ * can introspect the original validation failure and the request that
+ * produced it.
+ */
+declare class ZodSerializationException extends InternalServerErrorException {
+    readonly zodError: z.ZodError;
+    readonly executionContext?: ExecutionContext;
+    constructor(zodError: z.ZodError, executionContext?: ExecutionContext);
+}
+
 /**
  * Default exception thrown by `ZodValidationPipe` when input fails to parse.
  *
@@ -147,6 +181,78 @@ declare class ZodValidationException extends BadRequestException {
     constructor(zodError: z.ZodError, argMetadata?: ArgumentMetadata);
 }
 
+interface ValidationLogContext {
+    /** Which side of the request emitted the failure. */
+    side: 'input' | 'output';
+    /** Severity to log at; the formatter does not decide this. */
+    severity: 'warn' | 'error';
+    /** Pre-formatted DTO label, e.g. `'UserDto'`, `'[UserDto]'`, `'[A, B]'`. */
+    dto: string;
+    /** Output side only — HTTP response status code. */
+    status?: number;
+    /** Output side only — `Controller.method` best-effort. */
+    handler?: string;
+    /** Input side only — `body` / `query` / `param` / `custom`. */
+    argType?: string;
+}
+type LogValidationFailure = (err: z.ZodError, value: unknown, ctx: ValidationLogContext) => void;
+
+/**
+ * Module-scope factory for the exception thrown by `ZodValidationPipe` on
+ * input validation failure. Mirrors the existing per-pipe option but lives
+ * at module scope; per-instance constructor arg wins.
+ */
+type CreateValidationException$1 = (err: z.ZodError, argMetadata: ArgumentMetadata) => unknown;
+/**
+ * Module-scope factory for the exception thrown by `ZodSerializerInterceptor`
+ * on output validation failure (strict mode only). Soft mode never calls
+ * this factory.
+ */
+type CreateSerializationException = (err: z.ZodError, executionContext: ExecutionContext) => unknown;
+/** Public options accepted by `ZodNestModule.forRoot()`. */
+interface ZodNestModuleOptions {
+    createValidationException?: CreateValidationException$1;
+    createSerializationException?: CreateSerializationException;
+    /**
+     * Failure-only validation logging. `true` enables both input and output;
+     * the granular form lets each side be toggled independently. Default: off.
+     */
+    validationLogs?: boolean | {
+        input?: boolean;
+        output?: boolean;
+    };
+    /** Override Nest's built-in `Logger` (e.g. pino/winston adapter). */
+    logger?: LoggerService;
+    /**
+     * Keys whose values get scrubbed from logged input/response objects.
+     * Matched case-insensitively at any depth. Supplying this option
+     * REPLACES the default list (no merge).
+     */
+    redactKeys?: readonly string[];
+    /**
+     * Maximum size in bytes (UTF-8) for any single logged value. Oversized
+     * values become `{ _truncated: true, _originalBytes, _preview }`.
+     */
+    maxLoggedValueBytes?: number;
+}
+/**
+ * Resolved options consumed by pipe + interceptor. `forRoot()` builds this
+ * once and stuffs it into a provider for the `ZOD_NEST_OPTIONS` injection
+ * token; downstream code never re-checks the raw `validationLogs` flag.
+ */
+interface NormalizedZodNestOptions {
+    createValidationException: CreateValidationException$1 | undefined;
+    createSerializationException: CreateSerializationException | undefined;
+    /** No-op when `validationLogs.input` resolved to false. */
+    logInputFailure: LogValidationFailure;
+    /** No-op when `validationLogs.output` resolved to false. */
+    logOutputFailure: LogValidationFailure;
+}
+declare const DEFAULT_REDACT_KEYS: readonly string[];
+declare const DEFAULT_MAX_LOGGED_VALUE_BYTES = 4096;
+/** DI token for `NormalizedZodNestOptions`. */
+declare const ZOD_NEST_OPTIONS: unique symbol;
+
 /**
  * Build the exception thrown by `ZodValidationPipe` on validation failure.
  * Receives Zod's error and the NestJS argument metadata; returns anything
@@ -168,11 +274,200 @@ type ZodValidationPipeArg = z.ZodType | ZodDto | ZodValidationPipeOptions;
 
 declare class ZodValidationPipe implements PipeTransform {
     private readonly explicitSchema;
+    private readonly explicitDtoName;
     private readonly createValidationException;
-    constructor(arg?: ZodValidationPipeArg);
+    private readonly logInputFailure;
+    constructor(arg?: ZodValidationPipeArg, moduleOptions?: NormalizedZodNestOptions);
     transform(value: unknown, metadata: ArgumentMetadata): Promise<unknown>;
     private resolveSchema;
+    private resolveDtoLabel;
     private static parseArg;
 }
 
-export { COMPONENTS_SCHEMAS_PREFIX, type CreateValidationException, type CreateZodDtoOptions, type Io, type Override, type OverrideContext, type SchemaObject, type ToOpenApiOptions, type ToOpenApiResult, ZOD_DTO_SYMBOL, ZOD_NEST_DTO_EXTENSION, ZOD_NEST_ERROR_DUPLICATE_ID, ZOD_NEST_ERROR_EXTENSION, type ZodDto, type ZodDtoMarker, ZodNestError, type ZodNestRegistry, ZodNestUnrepresentableError, ZodValidationException, ZodValidationPipe, type ZodValidationPipeArg, type ZodValidationPipeOptions, createRegistry, createZodDto, defaultRegistry, isZodDto, isZodDtoMarker, makeZodDtoMarker, toOpenApi };
+/**
+ * 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';
+/**
+ * Description payload accepted by `@ZodResponse(...)` and passed through to
+ * Phase 2e'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 Phase 2e 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 — 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.
+ */
+interface ResponseVariant {
+    status: number | undefined;
+    kind: ResponseVariantKind;
+    dto: ZodDto | readonly ZodDto[];
+    validationSchema: z.ZodType;
+    description?: ZodResponseDescription;
+    passthroughOnError: boolean;
+}
+
+/**
+ * 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
+ *   `@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 in Phase 2e.
+ *
+ * Empty arrays and non-DTO elements throw `TypeError` at decoration time
+ * so typos surface at module load, not the first request.
+ */
+type ZodResponseType = ZodDto | readonly [ZodDto, ...ZodDto[]];
+interface ZodResponseOptions {
+    status?: number;
+    type: ZodResponseType;
+    description?: ZodResponseDescription;
+    passthroughOnError?: boolean;
+}
+/**
+ * Method-only decorator. Declares a typed response variant for the handler.
+ * Stack multiple decorations to declare per-status types; lookup at runtime
+ * is by `response.statusCode === variant.status`.
+ *
+ * The wrapped Zod schema (array / tuple) is built once at decoration time
+ * and stored on the variant record — no per-request schema construction.
+ */
+declare const ZodResponse: (opts: ZodResponseOptions) => MethodDecorator;
+
+declare class ZodSerializerInterceptor implements NestInterceptor {
+    private readonly reflector;
+    private readonly logOutputFailure;
+    private readonly createSerializationException;
+    constructor(reflector: Reflector, options?: NormalizedZodNestOptions);
+    intercept(context: ExecutionContext, next: CallHandler): Observable<unknown>;
+    private transform;
+}
+
+/**
+ * Compute the default HTTP status code for a handler when `@ZodResponse(...)`
+ * is invoked without an explicit `status`. Lookup order (highest → lowest):
+ *
+ * 1. `@HttpCode(n)` on the handler — explicit per-handler status override.
+ *    NestJS sets `HTTP_CODE_METADATA` to the numeric status when present.
+ * 2. HTTP method default — `POST` → `201`, everything else → `200`.
+ *
+ * The method default itself falls back to `200` when `METHOD_METADATA` is
+ * absent — pinned by tests so a future NestJS rename surfaces as a test
+ * failure rather than a silent regression.
+ */
+declare const defaultStatusFor: (handler: object) => number;
+/**
+ * Resolve the effective status code for a variant. Precedence chain:
+ *
+ * 1. Explicit `@ZodResponse({ status })` on the decorator call — `variant.status`.
+ * 2. `@HttpCode(n)` on the handler — read via `defaultStatusFor()` at runtime.
+ * 3. HTTP method default (POST → 201, others → 200) — also via `defaultStatusFor()`.
+ *
+ * Resolution is deferred to request time because `@ZodResponse` runs before
+ * NestJS' route + `@HttpCode` decorators — none of their metadata is set
+ * when the decorator evaluates.
+ */
+declare const resolveEffectiveStatus: (variant: ResponseVariant, handler: object) => number;
+
+/**
+ * Central wiring for the zod-nest pipe + interceptor. Call
+ * `ZodNestModule.forRoot(options?)` from your root `AppModule` to register
+ * `APP_PIPE` (`ZodValidationPipe`) and `APP_INTERCEPTOR`
+ * (`ZodSerializerInterceptor`) globally, with shared options for
+ * validation logging, redaction, and exception factories.
+ *
+ * `forRoot()` is optional — the pipe and interceptor also work as
+ * regular `APP_PIPE` / `APP_INTERCEPTOR` providers if you prefer to
+ * wire them manually; `@Optional()` injection of `ZOD_NEST_OPTIONS`
+ * falls through to safe defaults.
+ *
+ * Marked `global` so the `ZOD_NEST_OPTIONS` token is injectable from
+ * feature modules (e.g. a custom pipe that wants the same logger /
+ * redact list as the module-wired one).
+ */
+declare class ZodNestModule {
+    static forRoot(options?: ZodNestModuleOptions): DynamicModule;
+}
+
+interface ApplyZodNestOptions {
+    /**
+     * The NestJS app instance. Required so `applyZodNest` can walk controllers
+     * via `DiscoveryService` to pick up `@ZodResponse` output-side DTO usage —
+     * `@nestjs/swagger` is currently anemic on response shapes.
+     */
+    app: INestApplication;
+    /**
+     * `ZodNestRegistry` instance that holds the zod-nest DTOs. Defaults to
+     * `defaultRegistry` (the process-wide singleton populated by `createZodDto`).
+     * Pass an explicit registry for multi-app isolation (planned formalization
+     * in v0.2).
+     */
+    registry?: ZodNestRegistry;
+    /** User override pipe applied on top of the built-in override during emission. */
+    override?: Override;
+    /**
+     * Strict mode (default `true`) throws `ZodNestUnrepresentableError` on
+     * unrepresentable Zod constructs (bigint / date / symbol / transform / ...).
+     * Set to `false` to emit `{}` for those instead.
+     */
+    strict?: boolean;
+}
+/**
+ * Post-processor over the OpenAPI document emitted by
+ * `SwaggerModule.createDocument`. Mutates the doc in place AND returns it for
+ * compositional convenience. After this runs:
+ *
+ * - Every `components.schemas[<DtoClassName>]` placeholder with an
+ *   `x-zod-nest-dto` marker is replaced by the Zod-derived JSON Schema body,
+ *   keyed by the marker's `dtoId` (renaming as needed).
+ * - The I/O suffix truth table is applied — equal input/output bodies collapse
+ *   to one `components.schemas[id]`; divergent bodies split as
+ *   `id` (input) + `idOutput` (output), with response-side refs rewritten.
+ * - Every `$ref` whose target is missing throws `ZodNestDocumentError(DANGLING_REF)`.
+ *
+ * Composable with other doc-transform passes — apply other mutations before
+ * or after this function. The `app` argument is required because the
+ * output-side DTO usage lives on controller-method metadata that the doc
+ * doesn't surface; `DiscoveryService` resolves it.
+ */
+declare const applyZodNest: (doc: OpenAPIObject, opts: ApplyZodNestOptions) => OpenAPIObject;
+
+type ZodNestDocumentErrorCode = 'AMBIGUOUS_RENAME' | 'DANGLING_REF';
+/**
+ * Thrown by `applyZodNest` when the doc cannot be processed cleanly. Surfaces
+ * at doc-build time so typos / mis-registrations fail in CI, not at runtime.
+ *
+ * `AMBIGUOUS_RENAME`: two distinct DTO classes target the same registry id
+ * with differing bodies — the rename pass can't write `components.schemas[id]`
+ * unambiguously.
+ *
+ * `DANGLING_REF`: a `$ref` in the doc points at a `components.schemas` key
+ * that no longer exists after `applyZodNest`. Usually means a marker was
+ * stripped but its rename target wasn't populated, or a user-supplied pre-pass
+ * left a stale ref.
+ */
+declare class ZodNestDocumentError extends ZodNestError {
+    readonly code: ZodNestDocumentErrorCode;
+    readonly details: Readonly<Record<string, unknown>>;
+    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 NormalizedZodNestOptions, type Override, type OverrideContext, type ResponseVariant, type ResponseVariantKind, type 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, type ZodDto, type ZodDtoMarker, ZodNestDocumentError, type ZodNestDocumentErrorCode, ZodNestError, ZodNestModule, type ZodNestModuleOptions, type ZodNestRegistry, ZodNestUnrepresentableError, ZodResponse, type ZodResponseDescription, type ZodResponseOptions, type ZodResponseType, ZodSerializationException, ZodSerializerInterceptor, ZodValidationException, ZodValidationPipe, type ZodValidationPipeArg, type ZodValidationPipeOptions, applyZodNest, createRegistry, createZodDto, defaultRegistry, defaultStatusFor, isZodDto, isZodDtoMarker, makeZodDtoMarker, resolveEffectiveStatus, toOpenApi };