zod-nest 0.4.0 → 0.6.0

package/dist/index.d.mts

@@ -1,8 +1,9 @@
 import { z } from 'zod';
 import { JSONSchema, $ZodTypes } from 'zod/v4/core';
-import { InternalServerErrorException, ExecutionContext, BadRequestException, ArgumentMetadata, LoggerService, PipeTransform, NestInterceptor, CallHandler, DynamicModule } 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/";
@@ -32,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;
 /**
@@ -399,4 +407,67 @@ declare class ZodNestModule {
     static forRoot(options?: ZodNestModuleOptions): DynamicModule;
 }
 
-export { 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, ZodNestError, ZodNestModule, type ZodNestModuleOptions, type ZodNestRegistry, ZodNestUnrepresentableError, ZodResponse, type ZodResponseDescription, type ZodResponseOptions, type ZodResponseType, ZodSerializationException, ZodSerializerInterceptor, ZodValidationException, ZodValidationPipe, type ZodValidationPipeArg, type ZodValidationPipeOptions, createRegistry, createZodDto, defaultRegistry, defaultStatusFor, isZodDto, isZodDtoMarker, makeZodDtoMarker, resolveEffectiveStatus, toOpenApi };
+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,8 +1,9 @@
 import { z } from 'zod';
 import { JSONSchema, $ZodTypes } from 'zod/v4/core';
-import { InternalServerErrorException, ExecutionContext, BadRequestException, ArgumentMetadata, LoggerService, PipeTransform, NestInterceptor, CallHandler, DynamicModule } 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/";
@@ -32,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;
 /**
@@ -399,4 +407,67 @@ declare class ZodNestModule {
     static forRoot(options?: ZodNestModuleOptions): DynamicModule;
 }
 
-export { 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, ZodNestError, ZodNestModule, type ZodNestModuleOptions, type ZodNestRegistry, ZodNestUnrepresentableError, ZodResponse, type ZodResponseDescription, type ZodResponseOptions, type ZodResponseType, ZodSerializationException, ZodSerializerInterceptor, ZodValidationException, ZodValidationPipe, type ZodValidationPipeArg, type ZodValidationPipeOptions, createRegistry, createZodDto, defaultRegistry, defaultStatusFor, isZodDto, isZodDtoMarker, makeZodDtoMarker, resolveEffectiveStatus, toOpenApi };
+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 };