API Reference

Entry Points

nest-zod exports runtime parsing and serialization:

import {
  ZBody,
  ZParam,
  ZQuery,
  ZSerialize,
  ZSerializerInterceptor,
  ZValidationPipe,
} from 'nest-zod';

nest-zod/swagger exports Swagger-aware versions of the four decorators plus the OpenAPI helpers:

import {
  ZBody,
  ZParam,
  ZQuery,
  ZSerialize,
  isZodObjectSchema,
  zodInputObjectSchema,
  zodSchemaForEncodedResponse,
  zodSchemaForInput,
  zodToOpenApiSchema,
} from 'nest-zod/swagger';

Request Decorators

ZBody(schema, options?)

Parses the whole request body.

ZParam(name, schema, options?)

Parses one named route parameter.

ZQuery(schema, options?)

Parses the whole query object.

ZQuery(name, schema, options?)

Parses one named query parameter. The named value may be scalar or object-shaped.

All request decorators accept runtime validation options:

type ZValidationDecoratorOptions = {
  validation?: {
    async?: boolean;
    exceptionFactory?: (error: z.ZodError) => Error;
  };
};

async selects schema.parseAsync() instead of schema.parse(). exceptionFactory replaces the default BadRequestException for Zod failures.

Swagger-aware ZBody and ZParam also forward their corresponding @nestjs/swagger options. Swagger-aware ZQuery adds refId but otherwise keeps the runtime option shape.

Response Decorator

ZSerialize(schema, options?)

Encodes each successful handler result before Nest sends it.

Runtime-only options:

type ZSerializeOptions = {
  serialization?: {
    async?: boolean;
  };
};

Enable serialization.async when the response schema requires schema.encodeAsync().

The Swagger-aware version also accepts ApiResponseOptions fields except schema, plus:

type ZSerializeOptions = {
  refId?: string;
  serialization?: {
    async?: boolean;
  };
};

Its status field controls the documented response status. Use Nest's @HttpCode() to change the runtime HTTP status.

Runtime Classes

ZValidationPipe

new ZValidationPipe(schema, {
  async?: boolean,
  exceptionFactory?: (error) => exception,
});

Synchronous mode returns the schema output directly. Async mode returns a promise. Non-Zod errors thrown by schema logic are rethrown unchanged. When the class's TAsync generic is explicitly true, the constructor also requires { async: true }, keeping the declared promise return type aligned with runtime behavior.

ZSerializerInterceptor

new ZSerializerInterceptor(schema, {
  async?: boolean,
});

Encoding errors become InternalServerErrorException with message Serialization failed; the original error is available as cause.

OpenAPI Helpers

zodToOpenApiSchema(schema, options?)

Converts a Zod schema into an inline OpenAPI 3.0 schema.

options.refId is the internal id used by the temporary schema registry. It does not register a reusable component in the final Nest document.

zodSchemaForInput(schema)

Returns the schema used to describe the incoming wire format. A top-level Zod codec uses its input side.

zodSchemaForEncodedResponse(schema)

Returns the schema used to describe the encoded response wire format. This is also the codec input side because that is what schema.encode() emits.

zodInputObjectSchema(schema)

Returns the underlying input object for whole-query documentation when the schema is an object or an object wrapped in optional, nullable, or default. Otherwise it returns undefined.

isZodObjectSchema(schema)

Narrows schemas accepted as whole-query objects. It uses zodInputObjectSchema() internally.

Default Errors

Invalid input produces:

{
  "message": "Validation failed",
  "statusCode": 400
}

Encoding failures produce:

{
  "message": "Serialization failed",
  "statusCode": 500
}

See Compatibility and Limits for async schemas, custom error envelopes, query parsing, recursive schemas, and supported peer versions.