@stlmpp/nestjs-zod 1.0.0

package/dist/index.d.cts

@@ -0,0 +1,228 @@
+import { a as UnknownSchema, i as RequiredBy, n as createZodDto, t as ZodDto } from "./dto-CMhDHMJh.cjs";
+import { input, output } from "zod/v4/core";
+import { BadRequestException, CallHandler, CanActivate, ExecutionContext, InternalServerErrorException, PipeTransform } from "@nestjs/common";
+import { z } from "zod/v3";
+import { OpenAPIObject } from "@nestjs/swagger";
+import { Observable } from "rxjs";
+
+//#region src/config.d.ts
+interface ZodDtoConfig {
+  /**
+   * Default value for `createZodDto`'s `codec` option when it isn't passed
+   * explicitly for a given DTO.
+   */
+  codec: boolean;
+}
+/**
+ * Overrides the library-wide defaults used by `createZodDto`.  Any option
+ * not passed here keeps its previous value.  Call this once, e.g. during
+ * app bootstrap, before any `createZodDto` calls that should observe it.
+ */
+declare function configureZodDto(config: Partial<ZodDtoConfig>): void;
+//#endregion
+//#region src/exception.d.ts
+declare class ZodValidationException extends BadRequestException {
+  private error;
+  constructor(error: unknown);
+  getZodError(): unknown;
+}
+declare class ZodSerializationException extends InternalServerErrorException {
+  private error;
+  constructor(error: unknown);
+  getZodError(): unknown;
+}
+type ZodExceptionCreator = (error: unknown) => Error;
+//#endregion
+//#region src/guard.d.ts
+type Source = 'body' | 'query' | 'params';
+interface ZodBodyGuardOptions {
+  createValidationException?: ZodExceptionCreator;
+}
+type ZodGuardClass = new (source: Source, schemaOrDto: UnknownSchema | ZodDto) => CanActivate;
+/**
+ * @deprecated `createZodGuard` will be removed in a future version, since
+ * guards are not intended for validation purposes.
+ */
+declare function createZodGuard({
+  createValidationException
+}?: ZodBodyGuardOptions): ZodGuardClass;
+/**
+ * @deprecated `ZodGuard` will be removed in a future version, since guards
+ * are not intended for validation purposes.
+ */
+declare const ZodGuard: ZodGuardClass;
+/**
+ * @deprecated `UseZodGuard` will be removed in a future version, since guards
+ * are not intended for validation purposes.
+ */
+declare const UseZodGuard: (source: Source, schemaOrDto: UnknownSchema | ZodDto) => MethodDecorator & ClassDecorator;
+//#endregion
+//#region src/zodV3ToOpenApi.d.ts
+type SchemaObject = Exclude<Exclude<Exclude<OpenAPIObject['components'], undefined>['schemas'], undefined>[string], {
+  $ref: string;
+}>;
+interface ExtendedSchemaObject extends SchemaObject {
+  [key: `x-${string}`]: any;
+}
+/**
+ * @deprecated `zodToOpenAPI` will be removed in a future version, since zod
+ * v4 adds built-in support for generating OpenAPI schemas from zod schemas.
+ */
+declare function zodV3ToOpenAPI(zodType: z.ZodTypeAny, visited?: Set<any>): ExtendedSchemaObject;
+//#endregion
+//#region src/pipe.d.ts
+interface ZodValidationPipeOptions {
+  /**
+   * Use this to customize the exception that is thrown when validation fails
+   */
+  createValidationException?: ZodExceptionCreator;
+  /**
+   * If `true`, then an error will be thrown if the pipe tries to validate a
+   * value that is not typed with a nestjs-zod DTO
+   *
+   * It's recommended to set this to `true`, since it will catch cases where
+   * we're not properly validating data
+   */
+  strictSchemaDeclaration?: boolean;
+}
+type ZodValidationPipeClass = new (schemaOrDto?: UnknownSchema | ZodDto) => PipeTransform;
+declare class ZodSchemaDeclarationException extends InternalServerErrorException {
+  constructor();
+}
+declare function createZodValidationPipe({
+  createValidationException,
+  strictSchemaDeclaration
+}?: ZodValidationPipeOptions): ZodValidationPipeClass;
+declare const ZodValidationPipe: ZodValidationPipeClass;
+//#endregion
+//#region src/serializer.d.ts
+declare function ZodSerializerDto(dto: ZodDto | UnknownSchema | [ZodDto] | [UnknownSchema]): import("@nestjs/common").CustomDecorator<"ZOD_SERIALIZER_DTO_OPTIONS">;
+interface ZodSerializerInterceptorOptions {
+  reportInput?: boolean;
+}
+type ZodSerializerInterceptorClass = new (...args: unknown[]) => {
+  intercept(context: ExecutionContext, next: CallHandler): Observable<unknown>;
+};
+declare function createZodSerializerInterceptor({
+  reportInput
+}?: ZodSerializerInterceptorOptions): ZodSerializerInterceptorClass;
+declare const ZodSerializerInterceptor: ZodSerializerInterceptorClass;
+//#endregion
+//#region src/validate.d.ts
+/**
+ * @deprecated `validate` will be removed in a future version.  It is
+ * recommended to use `.parse` directly
+ */
+declare function validate<TSchema extends UnknownSchema>(value: unknown, schemaOrDto: TSchema | ZodDto<TSchema, boolean>, createValidationException?: ZodExceptionCreator): ReturnType<TSchema['parse']>;
+//#endregion
+//#region src/cleanupOpenApiDoc.d.ts
+/**
+ * This function performs some post-processing on the OpenAPI document.  It
+ * should only touch parts of the document that were generated from nestjs-zod
+ * DTOs.
+ *
+ * Specifically, this function:
+ * 1. Removes empty `type` fields
+ * 2. Renames OpenAPI schemas that have an explicit `id` field to match that
+ *    `id`, instead of using the DTO class name
+ * 3. If the DTO's schema references another zod schema, it adds that zod
+ *    schema's OpenAPI representation to `components.schemas`
+ * 4. If a DTO is created directly with an array zod schema, it ensures the
+ *    OpenAPI schema is generated properly
+ * 5. Handles recursive zod schemas
+ * 6. Handles `null` properly based on the OpenAPI version
+ *
+ * @param doc - The OpenAPI document that is generated by `SwaggerModule.createDocument`
+ * @param options.version - The version of OpenAPI to use.  Defaults to `auto`,
+ * which will use the version of the OpenAPI object passed in.  Note if the
+ * version is `3.1` then it impacts how `null` is handled.  In `3.0`, `nullable:
+ * true` is used, while in `3.1` `anyOf: [..., { type: 'null' }]` is used
+ * instead
+ * @returns A cleaned up OpenAPI document
+ */
+declare function cleanupOpenApiDoc(doc: OpenAPIObject, {
+  version: versionParam
+}?: {
+  version?: '3.1' | '3.0' | 'auto';
+}): OpenAPIObject;
+//#endregion
+//#region src/response.d.ts
+/**
+ * `@ZodResponse` can be used to set the response information for a method.
+ * This is the recommended way to handle responses, since it applies a few
+ * related decorators at once to keep them in sync:
+ *
+ * 1. Uses `@ZodSerializerDto` to serialize the return value of the method.  This
+ *    means the return value of the method will be parsed by the DTO's schema.
+ * 2. Uses `@ApiResponse` to set the response DTO for the method.  This means
+ *    the OpenAPI documentation will be updated to reflect the DTO's schema.
+ *    Note that by default ZodResponse automatically uses the output version of
+ *    the DTO, so there is no need to use DTO.Output.  If the `codec` option is
+ *    set to `true` on the DTO (`createZodDto(z.object({}), { codec: true })`),
+ *    then the response schema will be the input version of the DTO.
+ * 3. Uses `@HttpCode` to set the HTTP status code for the response if `status`
+ *    is provided
+ * 4. Lastly, by default it also throws a typescript error if the return value
+ *    of the method does not match the DTO's input schema.  However, if the
+ *    `codec` option is set to `true` on the DTO, it throws a typescript error
+ *    unless the return value matches the DTO's output schema instead.
+ *
+ * `@ZodResponse` is powerful because it keeps the run-time, compile-time, and
+ * docs-time response representations in sync
+ *
+ *
+ * @example
+ * ```ts
+ * @Get()
+ * @ZodResponse({ status: 200, description: 'Get book', type: BookDto })
+ * getBook() {
+ *   return { id: '1' };
+ * }
+ * ```
+ *
+ * @example
+ * ```ts
+ * @Get()
+ * @ZodResponse({ status: 200, description: 'Get books', type: [BookDto] })
+ * getBooks() {
+ *   return [{ id: '1' }, { id: '2' }];
+ * }
+ */
+declare function ZodResponse<TSchema extends UnknownSchema>({
+  status,
+  description,
+  type
+}: {
+  status?: number;
+  description?: string;
+  type: ZodDto<TSchema, true, 'input' | 'output'>;
+}): (target: object, propertyKey?: string | symbol, descriptor?: Pick<TypedPropertyDescriptor<(...args: any[]) => output<TSchema> | Promise<output<TSchema>>>, 'value'>) => void;
+declare function ZodResponse<TSchema extends RequiredBy<UnknownSchema, 'array'>>({
+  status,
+  description,
+  type
+}: {
+  status?: number;
+  description?: string;
+  type: [ZodDto<TSchema, true, 'input' | 'output'>];
+}): (target: object, propertyKey?: string | symbol, descriptor?: Pick<TypedPropertyDescriptor<(...args: any[]) => Array<output<TSchema>> | Promise<Array<output<TSchema>>>>, 'value'>) => void;
+declare function ZodResponse<TSchema extends UnknownSchema>({
+  status,
+  description,
+  type
+}: {
+  status?: number;
+  description?: string;
+  type: ZodDto<TSchema, false, 'input' | 'output'>;
+}): (target: object, propertyKey?: string | symbol, descriptor?: Pick<TypedPropertyDescriptor<(...args: any[]) => input<TSchema> | Promise<input<TSchema>>>, 'value'>) => void;
+declare function ZodResponse<TSchema extends RequiredBy<UnknownSchema, 'array'>>({
+  status,
+  description,
+  type
+}: {
+  status?: number;
+  description?: string;
+  type: [ZodDto<TSchema, false, 'input' | 'output'>];
+}): (target: object, propertyKey?: string | symbol, descriptor?: Pick<TypedPropertyDescriptor<(...args: any[]) => Array<input<TSchema>> | Promise<Array<input<TSchema>>>>, 'value'>) => void;
+//#endregion
+export { UseZodGuard, type ZodDto, ZodGuard, ZodResponse, ZodSchemaDeclarationException, ZodSerializationException, ZodSerializerDto, ZodSerializerInterceptor, ZodValidationException, ZodValidationPipe, cleanupOpenApiDoc, configureZodDto, createZodDto, createZodGuard, createZodSerializerInterceptor, createZodValidationPipe, validate, zodV3ToOpenAPI };

package/dist/index.d.mts

@@ -0,0 +1,228 @@
+import { a as UnknownSchema, i as RequiredBy, n as createZodDto, t as ZodDto } from "./dto-CMhDHMJh.mjs";
+import { input, output } from "zod/v4/core";
+import { z } from "zod/v3";
+import { BadRequestException, CallHandler, CanActivate, ExecutionContext, InternalServerErrorException, PipeTransform } from "@nestjs/common";
+import { Observable } from "rxjs";
+import { OpenAPIObject } from "@nestjs/swagger";
+
+//#region src/config.d.ts
+interface ZodDtoConfig {
+  /**
+   * Default value for `createZodDto`'s `codec` option when it isn't passed
+   * explicitly for a given DTO.
+   */
+  codec: boolean;
+}
+/**
+ * Overrides the library-wide defaults used by `createZodDto`.  Any option
+ * not passed here keeps its previous value.  Call this once, e.g. during
+ * app bootstrap, before any `createZodDto` calls that should observe it.
+ */
+declare function configureZodDto(config: Partial<ZodDtoConfig>): void;
+//#endregion
+//#region src/exception.d.ts
+declare class ZodValidationException extends BadRequestException {
+  private error;
+  constructor(error: unknown);
+  getZodError(): unknown;
+}
+declare class ZodSerializationException extends InternalServerErrorException {
+  private error;
+  constructor(error: unknown);
+  getZodError(): unknown;
+}
+type ZodExceptionCreator = (error: unknown) => Error;
+//#endregion
+//#region src/guard.d.ts
+type Source = 'body' | 'query' | 'params';
+interface ZodBodyGuardOptions {
+  createValidationException?: ZodExceptionCreator;
+}
+type ZodGuardClass = new (source: Source, schemaOrDto: UnknownSchema | ZodDto) => CanActivate;
+/**
+ * @deprecated `createZodGuard` will be removed in a future version, since
+ * guards are not intended for validation purposes.
+ */
+declare function createZodGuard({
+  createValidationException
+}?: ZodBodyGuardOptions): ZodGuardClass;
+/**
+ * @deprecated `ZodGuard` will be removed in a future version, since guards
+ * are not intended for validation purposes.
+ */
+declare const ZodGuard: ZodGuardClass;
+/**
+ * @deprecated `UseZodGuard` will be removed in a future version, since guards
+ * are not intended for validation purposes.
+ */
+declare const UseZodGuard: (source: Source, schemaOrDto: UnknownSchema | ZodDto) => MethodDecorator & ClassDecorator;
+//#endregion
+//#region src/zodV3ToOpenApi.d.ts
+type SchemaObject = Exclude<Exclude<Exclude<OpenAPIObject['components'], undefined>['schemas'], undefined>[string], {
+  $ref: string;
+}>;
+interface ExtendedSchemaObject extends SchemaObject {
+  [key: `x-${string}`]: any;
+}
+/**
+ * @deprecated `zodToOpenAPI` will be removed in a future version, since zod
+ * v4 adds built-in support for generating OpenAPI schemas from zod schemas.
+ */
+declare function zodV3ToOpenAPI(zodType: z.ZodTypeAny, visited?: Set<any>): ExtendedSchemaObject;
+//#endregion
+//#region src/pipe.d.ts
+interface ZodValidationPipeOptions {
+  /**
+   * Use this to customize the exception that is thrown when validation fails
+   */
+  createValidationException?: ZodExceptionCreator;
+  /**
+   * If `true`, then an error will be thrown if the pipe tries to validate a
+   * value that is not typed with a nestjs-zod DTO
+   *
+   * It's recommended to set this to `true`, since it will catch cases where
+   * we're not properly validating data
+   */
+  strictSchemaDeclaration?: boolean;
+}
+type ZodValidationPipeClass = new (schemaOrDto?: UnknownSchema | ZodDto) => PipeTransform;
+declare class ZodSchemaDeclarationException extends InternalServerErrorException {
+  constructor();
+}
+declare function createZodValidationPipe({
+  createValidationException,
+  strictSchemaDeclaration
+}?: ZodValidationPipeOptions): ZodValidationPipeClass;
+declare const ZodValidationPipe: ZodValidationPipeClass;
+//#endregion
+//#region src/serializer.d.ts
+declare function ZodSerializerDto(dto: ZodDto | UnknownSchema | [ZodDto] | [UnknownSchema]): import("@nestjs/common").CustomDecorator<"ZOD_SERIALIZER_DTO_OPTIONS">;
+interface ZodSerializerInterceptorOptions {
+  reportInput?: boolean;
+}
+type ZodSerializerInterceptorClass = new (...args: unknown[]) => {
+  intercept(context: ExecutionContext, next: CallHandler): Observable<unknown>;
+};
+declare function createZodSerializerInterceptor({
+  reportInput
+}?: ZodSerializerInterceptorOptions): ZodSerializerInterceptorClass;
+declare const ZodSerializerInterceptor: ZodSerializerInterceptorClass;
+//#endregion
+//#region src/validate.d.ts
+/**
+ * @deprecated `validate` will be removed in a future version.  It is
+ * recommended to use `.parse` directly
+ */
+declare function validate<TSchema extends UnknownSchema>(value: unknown, schemaOrDto: TSchema | ZodDto<TSchema, boolean>, createValidationException?: ZodExceptionCreator): ReturnType<TSchema['parse']>;
+//#endregion
+//#region src/cleanupOpenApiDoc.d.ts
+/**
+ * This function performs some post-processing on the OpenAPI document.  It
+ * should only touch parts of the document that were generated from nestjs-zod
+ * DTOs.
+ *
+ * Specifically, this function:
+ * 1. Removes empty `type` fields
+ * 2. Renames OpenAPI schemas that have an explicit `id` field to match that
+ *    `id`, instead of using the DTO class name
+ * 3. If the DTO's schema references another zod schema, it adds that zod
+ *    schema's OpenAPI representation to `components.schemas`
+ * 4. If a DTO is created directly with an array zod schema, it ensures the
+ *    OpenAPI schema is generated properly
+ * 5. Handles recursive zod schemas
+ * 6. Handles `null` properly based on the OpenAPI version
+ *
+ * @param doc - The OpenAPI document that is generated by `SwaggerModule.createDocument`
+ * @param options.version - The version of OpenAPI to use.  Defaults to `auto`,
+ * which will use the version of the OpenAPI object passed in.  Note if the
+ * version is `3.1` then it impacts how `null` is handled.  In `3.0`, `nullable:
+ * true` is used, while in `3.1` `anyOf: [..., { type: 'null' }]` is used
+ * instead
+ * @returns A cleaned up OpenAPI document
+ */
+declare function cleanupOpenApiDoc(doc: OpenAPIObject, {
+  version: versionParam
+}?: {
+  version?: '3.1' | '3.0' | 'auto';
+}): OpenAPIObject;
+//#endregion
+//#region src/response.d.ts
+/**
+ * `@ZodResponse` can be used to set the response information for a method.
+ * This is the recommended way to handle responses, since it applies a few
+ * related decorators at once to keep them in sync:
+ *
+ * 1. Uses `@ZodSerializerDto` to serialize the return value of the method.  This
+ *    means the return value of the method will be parsed by the DTO's schema.
+ * 2. Uses `@ApiResponse` to set the response DTO for the method.  This means
+ *    the OpenAPI documentation will be updated to reflect the DTO's schema.
+ *    Note that by default ZodResponse automatically uses the output version of
+ *    the DTO, so there is no need to use DTO.Output.  If the `codec` option is
+ *    set to `true` on the DTO (`createZodDto(z.object({}), { codec: true })`),
+ *    then the response schema will be the input version of the DTO.
+ * 3. Uses `@HttpCode` to set the HTTP status code for the response if `status`
+ *    is provided
+ * 4. Lastly, by default it also throws a typescript error if the return value
+ *    of the method does not match the DTO's input schema.  However, if the
+ *    `codec` option is set to `true` on the DTO, it throws a typescript error
+ *    unless the return value matches the DTO's output schema instead.
+ *
+ * `@ZodResponse` is powerful because it keeps the run-time, compile-time, and
+ * docs-time response representations in sync
+ *
+ *
+ * @example
+ * ```ts
+ * @Get()
+ * @ZodResponse({ status: 200, description: 'Get book', type: BookDto })
+ * getBook() {
+ *   return { id: '1' };
+ * }
+ * ```
+ *
+ * @example
+ * ```ts
+ * @Get()
+ * @ZodResponse({ status: 200, description: 'Get books', type: [BookDto] })
+ * getBooks() {
+ *   return [{ id: '1' }, { id: '2' }];
+ * }
+ */
+declare function ZodResponse<TSchema extends UnknownSchema>({
+  status,
+  description,
+  type
+}: {
+  status?: number;
+  description?: string;
+  type: ZodDto<TSchema, true, 'input' | 'output'>;
+}): (target: object, propertyKey?: string | symbol, descriptor?: Pick<TypedPropertyDescriptor<(...args: any[]) => output<TSchema> | Promise<output<TSchema>>>, 'value'>) => void;
+declare function ZodResponse<TSchema extends RequiredBy<UnknownSchema, 'array'>>({
+  status,
+  description,
+  type
+}: {
+  status?: number;
+  description?: string;
+  type: [ZodDto<TSchema, true, 'input' | 'output'>];
+}): (target: object, propertyKey?: string | symbol, descriptor?: Pick<TypedPropertyDescriptor<(...args: any[]) => Array<output<TSchema>> | Promise<Array<output<TSchema>>>>, 'value'>) => void;
+declare function ZodResponse<TSchema extends UnknownSchema>({
+  status,
+  description,
+  type
+}: {
+  status?: number;
+  description?: string;
+  type: ZodDto<TSchema, false, 'input' | 'output'>;
+}): (target: object, propertyKey?: string | symbol, descriptor?: Pick<TypedPropertyDescriptor<(...args: any[]) => input<TSchema> | Promise<input<TSchema>>>, 'value'>) => void;
+declare function ZodResponse<TSchema extends RequiredBy<UnknownSchema, 'array'>>({
+  status,
+  description,
+  type
+}: {
+  status?: number;
+  description?: string;
+  type: [ZodDto<TSchema, false, 'input' | 'output'>];
+}): (target: object, propertyKey?: string | symbol, descriptor?: Pick<TypedPropertyDescriptor<(...args: any[]) => Array<input<TSchema>> | Promise<Array<input<TSchema>>>>, 'value'>) => void;
+//#endregion
+export { UseZodGuard, type ZodDto, ZodGuard, ZodResponse, ZodSchemaDeclarationException, ZodSerializationException, ZodSerializerDto, ZodSerializerInterceptor, ZodValidationException, ZodValidationPipe, cleanupOpenApiDoc, configureZodDto, createZodDto, createZodGuard, createZodSerializerInterceptor, createZodValidationPipe, validate, zodV3ToOpenAPI };