zod-nest 0.7.0 → 0.8.1

package/README.md

@@ -0,0 +1,474 @@
+# zod-nest
+
+> Modern **Zod v4** ↔ **NestJS** ↔ **OpenAPI 3.1** integration.
+
+[![npm](https://img.shields.io/npm/v/zod-nest)](https://www.npmjs.com/package/zod-nest)
+[![CI](https://github.com/rodrigowbazevedo/zod-nest/actions/workflows/ci.yml/badge.svg)](https://github.com/rodrigowbazevedo/zod-nest/actions/workflows/ci.yml)
+[![codecov](https://codecov.io/gh/rodrigowbazevedo/zod-nest/branch/main/graph/badge.svg)](https://codecov.io/gh/rodrigowbazevedo/zod-nest)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+Define your DTOs once with Zod, get validated request bodies, validated response bodies, and a correct OpenAPI 3.1 document — without the dual-codepath, post-process, or `@ts-ignore` baggage that comes with bolting Zod onto class-validator-shaped tooling.
+
+## Why this exists
+
+`zod-nest` is a fresh take on the idea pioneered by [`nestjs-zod`](https://github.com/BenLorantfy/nestjs-zod) — many thanks to that project and its maintainers; this library would not exist without it.
+
+The difference is that `zod-nest` is Zod v4 only and OpenAPI 3.1 only. It drops `class-validator` / `class-transformer` coexistence, drops Zod v3 codepaths, drops `cleanupOpenApiDoc` as a separate post-process, and drops the 20-odd `@ts-ignore`s that the dual-version approach required. The result is a smaller surface, fully type-safe end to end, with extension points where you actually need them — exception factories, response status resolution, custom emission overrides.
+
+For the long-form motivation, see [`docs/why-this-exists.md`](docs/why-this-exists.md).
+
+## Features
+
+- **Zod v4 only** — no v3 dual codepath, no compatibility shim.
+- **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.
+- **`ZodSerializerInterceptor`** — response validation with a `passthroughOnError` escape hatch for untrusted upstream shapes.
+- **`applyZodNest`** — one call after `SwaggerModule.createDocument(...)` replaces the entire `cleanupOpenApiDoc` ritual.
+- **`ZodNestModule.forRoot`** — global pipe + interceptor + logging configuration in one place; optional (everything works standalone).
+- **Validation logging** — opt-in, per-side (input/output), with case-insensitive deep-key redaction and oversize-value truncation.
+- **Composition** — `extend` + `getLineage` emit OpenAPI `allOf` for derived schemas (`@experimental` — see [Composition](#composition-experimental)).
+- **Custom registry support** — `createRegistry()` for explicit isolation, `defaultRegistry` for the common process-wide case.
+- **Doc-build error reporting** — `ZodNestDocumentError` with codes `AMBIGUOUS_RENAME` and `DANGLING_REF` so registry mis-configurations fail in CI, not at runtime.
+- **Strict-mode unrepresentable detection** — `ZodNestUnrepresentableError` surfaces bigint/date/transform constructs that JSON Schema can't represent (opt-out via `strict: false`).
+- **Custom emission overrides** — `Override` callback for file uploads, opaque blobs, or anything else Zod doesn't model.
+
+## Differences from `nestjs-zod`
+
+A short list of behavioural differences you'll hit on day one. Full migration table is in [`MIGRATION.md`](MIGRATION.md).
+
+- **Multi-status `@ZodResponse`** — stack the decorator per status code. In `nestjs-zod`, multi-status required mixing `@ZodSerializerDto` with hand-rolled `@ApiResponse({ status: ... })` calls.
+- **No internal `@HttpCode`** — `@ZodResponse` does **not** call `@HttpCode` under the hood. Status resolution precedence: `@ZodResponse({ status })` → `@HttpCode(...)` on the handler → method default (`POST → 201`, others → `200`). The caller controls `201` vs `200` vs `204` via standard NestJS decorators.
+- **I/O suffix only when needed** — `<Id>Output` is only emitted when the input and output JSON Schemas actually differ. `nestjs-zod` always emitted `_Output`.
+- **OpenAPI 3.1 only** — no `3.0` fallback. `$ref`s emit to the final location; `cleanupOpenApiDoc` is unnecessary.
+- **Validation-failure logging out of the box** — `nestjs-zod` has none.
+- **Customizable serialization exception** — both `ZodValidationPipe` and `ZodSerializerInterceptor` accept a factory. `nestjs-zod` only customized the input side.
+- **DTO discriminator** — `Symbol.for('zod-nest.dto')` (cross-realm safe), not `MyDto.isZodDto`.
+- **Codec mode in the schema** — express transforms via `z.pipe` / `z.transform`. No `{ codec: true }` flag.
+- **Markers stripped** — the final document has zero `x-zod-nest-*` extensions. `nestjs-zod` left ~10 `x-nestjs_zod-*` keys behind.
+
+## Non-goals (v0)
+
+- **Zod v3 support** — Zod v4 only. Migrate first.
+- **`class-validator` / `class-transformer` coexistence** — `zod-nest` is Zod-native. Mixing class-validator decorators on a `createZodDto` result is not supported.
+- **Status wildcards** in `@ZodResponse` (`'2XX'`, `'default'`) — deferred to v1.
+- **Hybrid DTO projects** — mixing `createZodDto` DTOs with plain `@ApiProperty` classes in the same controller is not tested.
+- **Non-HTTP contexts** — WebSocket gateways, GraphQL resolvers, microservice handlers are out of scope.
+
+## Quickstart
+
+```bash
+npm i zod-nest zod @nestjs/swagger
+```
+
+```ts
+// user.dto.ts
+import { z } from 'zod';
+import { createZodDto } from 'zod-nest';
+
+const userSchema = z
+  .object({
+    id: z.string(),
+    email: z.email().transform((v) => v.toLowerCase()),
+  })
+  .meta({ id: 'User' });
+
+export class UserDto extends createZodDto(userSchema) {}
+```
+
+```ts
+// users.controller.ts
+import { Body, Controller, Get, Post } from '@nestjs/common';
+import { ZodResponse } from 'zod-nest';
+import { UserDto } from './user.dto';
+
+@Controller('users')
+export class UsersController {
+  @Get('single')
+  @ZodResponse({ type: UserDto })
+  single(): UserDto {
+    return { id: 'u1', email: 'A@B.COM' } as UserDto; // transform lowercases on the way out
+  }
+
+  @Post()
+  @ZodResponse({ type: UserDto })
+  create(@Body() body: UserDto): UserDto {
+    // body is already validated + parsed by ZodValidationPipe
+    return body;
+  }
+}
+```
+
+```ts
+// app.module.ts
+import { Module } from '@nestjs/common';
+import { ZodNestModule } from 'zod-nest';
+import { UsersController } from './users.controller';
+
+@Module({
+  imports: [ZodNestModule.forRoot({ validationLogs: true })],
+  controllers: [UsersController],
+})
+export class AppModule {}
+```
+
+```ts
+// main.ts
+import { NestFactory } from '@nestjs/core';
+import { DocumentBuilder, SwaggerModule } from '@nestjs/swagger';
+import { applyZodNest } from 'zod-nest';
+import { AppModule } from './app.module';
+
+async function bootstrap() {
+  const app = await NestFactory.create(AppModule);
+
+  const raw = SwaggerModule.createDocument(
+    app,
+    new DocumentBuilder().setTitle('Users').setVersion('1').build(),
+  );
+  const doc = applyZodNest(raw, { app });
+  SwaggerModule.setup('docs', app, doc);
+
+  await app.listen(3000);
+}
+
+bootstrap();
+```
+
+That's the whole loop. Validation, response serialization, and a correct OpenAPI 3.1 document — all driven from one Zod schema per DTO.
+
+## Core concepts
+
+### Schema is the source of truth
+
+Every DTO is one Zod schema wrapped in a class. The class exists so NestJS' introspection (parameter metatype, `@nestjs/swagger`) can find it; the validation and the OpenAPI emission both come from the schema directly. You don't repeat the shape with decorators.
+
+### `createZodDto` is a thin bridge
+
+The class returned by `createZodDto(schema)` carries `schema`, `id`, `io: 'input'`, and a lazy `Output` sibling. `parse` / `safeParse` are static methods on the class. The class is tagged with `Symbol.for('zod-nest.dto')` so `ZodValidationPipe` and `ZodSerializerInterceptor` can discriminate it from plain constructors. The id comes from `schema.meta({ id })` when present (preferred) or from the second-argument options.
+
+See [`docs/dto.md`](docs/dto.md) for the full surface.
+
+### I/O suffix rules
+
+If a schema's input and output JSON Schemas are byte-equal (the common case), the OpenAPI doc emits a single `components.schemas[Id]`. If they differ (e.g. a `transform`, a `pipe`, an `.optional().default(x)` field), the doc emits two: `Id` for input, `IdOutput` for output. Response refs are rewritten to `IdOutput` automatically.
+
+You don't pick the behaviour with a flag — `applyZodNest` compares the emitted bodies and decides per DTO.
+
+### Multi-status responses + status resolution
+
+Stack `@ZodResponse` to declare multiple status codes on one handler:
+
+```ts
+@Get(':id')
+@ZodResponse({ type: UserDto })                       // success variant — status inferred (200 for GET)
+@ZodResponse({ status: 404, type: ErrorDto })
+@ZodResponse({ status: 500, type: FatalDto })
+getUser(): void {}
+```
+
+**Recommended style:** omit `status` for the success variant and let it infer from the route, then set `status` explicitly only for the off-happy-path variants. Keeps the signal-to-noise high — the explicit numbers in the snippet above are the ones the reader actually needs to scan for.
+
+At request time, `ZodSerializerInterceptor` looks at `response.statusCode` and picks the matching variant. If you don't pass `status`, the variant matches on the handler's default (computed once at request time, in this order: `@HttpCode(n)` → `POST → 201`, everything else → `200`). `@ZodResponse` does **not** internally apply `@HttpCode` — you stay in charge of the actual HTTP status.
+
+See [`docs/responses.md`](docs/responses.md) for the precedence chain and `passthroughOnError`.
+
+## Usage
+
+### Creating DTOs
+
+```ts
+import { z } from 'zod';
+import { createZodDto } from 'zod-nest';
+
+const userSchema = z.object({ id: z.uuid(), name: z.string() }).meta({ id: 'User' });
+class UserDto extends createZodDto(userSchema) {}
+
+UserDto.parse({ id: '00000000-0000-0000-0000-000000000000', name: 'Ada' });
+// → { id: '...', name: 'Ada' }
+```
+
+### Setting the OpenAPI schema id
+
+The id is what appears as the `components.schemas` key in the OpenAPI document and what `$ref`s point at. You can set it in two equivalent ways:
+
+```ts
+// Preferred — on the schema, via Zod's metadata
+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({ /* ... */ }),
+  { id: 'User' },
+) {}
+```
+
+Both produce the same OpenAPI output. `.meta({ id })` is preferred when the schema is hoisted into its own `const`, because the id stays with the schema — composition (`extend(parent, ...)`), shared input/output via `.meta({ id })` on the same schema reference, and any non-DTO use of the schema all pick up the same id without an extra hop through `createZodDto`'s options. Use the `createZodDto(schema, { id })` form when you don't own the schema (e.g. it comes from a third-party module) or when defining a small DTO with an inline schema, where chaining `.meta()` on the inline expression hurts readability.
+
+If you pass neither, the class name is used as a fallback. Under minification — where class names become single mangled characters — `zod-nest` falls back to an `_AnonZodDto_N` id and prints a one-time console warning. Set an explicit id either way for production builds.
+
+### Input validation
+
+```ts
+import { ZodValidationPipe } from 'zod-nest';
+import { APP_PIPE } from '@nestjs/core';
+
+@Controller('things')
+class ThingsController {
+  @Post()
+  create(@Body() body: CreateThingDto) {
+    return { received: body };
+  }
+}
+
+@Module({
+  controllers: [ThingsController],
+  providers: [{ provide: APP_PIPE, useClass: ZodValidationPipe }],
+})
+class AppModule {}
+```
+
+Or use `ZodNestModule.forRoot()` — see [Module options](#module-options) below — to wire the pipe globally along with the response interceptor.
+
+On failure the pipe throws `ZodValidationException` (HTTP 400, body `{ statusCode, message: 'Validation failed', errors: z.treeifyError(zodError) }`).
+
+### Custom validation exception
+
+```ts
+import { HttpException, HttpStatus } from '@nestjs/common';
+import { ZodValidationPipe } from 'zod-nest';
+
+class UnprocessableEntityException extends HttpException {
+  constructor(issuesCount: number) {
+    super({ message: 'invalid input', issuesCount }, HttpStatus.UNPROCESSABLE_ENTITY);
+  }
+}
+
+const pipe = new ZodValidationPipe({
+  schema: CreateThingDto,
+  createValidationException: (zodError) => new UnprocessableEntityException(zodError.issues.length),
+});
+```
+
+The factory receives `(zodError, argMetadata)` and returns anything `throw`-able. Wire it module-wide via `ZodNestModule.forRoot({ createValidationException: ... })`.
+
+### Single-status response
+
+```ts
+@Controller('users')
+class UsersController {
+  @Get('single')
+  @ZodResponse({ type: UserDto })
+  single(): UserDto {
+    return { id: 'u1', email: 'A@B.COM' };
+  }
+}
+```
+
+The interceptor validates the return value against `UserDto.schema` and applies any `transform` / `pipe` Zod stages — in the example above, `email` is lowercased to `a@b.com` before the response leaves.
+
+### Multi-status responses
+
+Stack `@ZodResponse` per status code:
+
+```ts
+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 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({ status: HttpStatus.INTERNAL_SERVER_ERROR, type: FatalDto })
+  getUser(): void {}
+}
+```
+
+At runtime the interceptor matches `response.statusCode` against each variant's `status`. The OpenAPI doc emits three `responses[200|404|500]` entries with the right DTO ref under each. See [`docs/responses.md`](docs/responses.md) for the full mechanism.
+
+### `passthroughOnError`
+
+For an upstream shape you don't fully trust, set `passthroughOnError: true` on the variant. Validation failures are logged (if logging is on) but the original value passes through untouched:
+
+```ts
+@Get('proxied')
+@ZodResponse({ type: ProxyDto, passthroughOnError: true })
+proxied(): unknown {
+  return { upstream: 'value', extra: ['raw', 'shape'] };
+}
+```
+
+Use this sparingly — it bypasses the contract you declared. Logging at `warn` severity makes the deviation visible without breaking the request.
+
+### Array and tuple responses
+
+```ts
+@Get('list')   @ZodResponse({ type: [UserDto] })          list(): UserDto[] { /* ... */ }
+@Get('pair')  @ZodResponse({ type: [UserDto, TagDto] })  pair(): unknown { /* ... */ }
+```
+
+`[Dto]` validates as `z.array(Dto.schema)` and surfaces as OpenAPI `type: array`. `[A, B, …]` validates as `z.tuple([A.schema, B.schema, …])` and surfaces as `prefixItems`. Empty arrays and non-DTO elements throw `TypeError` at decoration time, so typos surface at module load — not the first request.
+
+### Swagger integration
+
+```ts
+import { applyZodNest } from 'zod-nest';
+
+const raw = SwaggerModule.createDocument(app, config);
+const doc = applyZodNest(raw, { app });
+SwaggerModule.setup('docs', app, doc);
+```
+
+`applyZodNest` walks the doc, replaces every `x-zod-nest-dto` marker with the real Zod-derived JSON Schema, applies the I/O suffix truth table, strips the markers, and validates the final ref graph. Any dangling ref throws `ZodNestDocumentError({ code: 'DANGLING_REF' })` — the spec fails at boot, not at request time.
+
+See [`docs/swagger-integration.md`](docs/swagger-integration.md) for `Override`, custom registries, and strict-mode behaviour.
+
+### Module setup
+
+```ts
+import { ZodNestModule } from 'zod-nest';
+
+@Module({
+  imports: [
+    ZodNestModule.forRoot({
+      validationLogs: { input: true, output: true },
+      redactKeys: ['password', 'token', 'sessionId'],
+      createSerializationException: (err, ctx) =>
+        new MyCustomFiveHundred(err, ctx),
+    }),
+  ],
+  controllers: [UsersController],
+})
+class AppModule {}
+```
+
+`forRoot()` is optional — `ZodValidationPipe` and `ZodSerializerInterceptor` work standalone with safe defaults. Use `forRoot` when you want consistent logging, a custom logger, custom exceptions, or shared redaction across the pipe and the interceptor.
+
+## Module options
+
+| 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 |
+
+`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.
+
+Full reference (with every interaction note) lives in [`docs/module-options.md`](docs/module-options.md).
+
+## Logging
+
+Validation logging fires **only on failure**, with side `'input'` or `'output'`. The default behaviour is off; opt in via `validationLogs: true` (both sides) or `validationLogs: { input: true }` / `{ output: true }` (granular).
+
+A log entry carries:
+
+- `side` — `'input'` or `'output'`
+- `severity` — `'error'` for strict failures, `'warn'` for `passthroughOnError` failures
+- `dto` — the DTO class name
+- `value` — the offending value, redacted and truncated
+- the treeified Zod error from `z.treeifyError(zodError)`
+
+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`:
+
+```ts
+import { DEFAULT_REDACT_KEYS, ZodNestModule } from 'zod-nest';
+
+ZodNestModule.forRoot({
+  validationLogs: true,
+  redactKeys: [...DEFAULT_REDACT_KEYS, 'sessionId'],
+});
+```
+
+See [`docs/logging.md`](docs/logging.md) for custom-logger adapters (pino, winston), structured-logging shape, and performance characteristics.
+
+## Composition (experimental)
+
+> **`@experimental`** — output shape may change as edge cases surface. Pin a minor version if you build on this surface.
+
+`zod-nest` ships an `extend` helper that records a parent → child link and emits OpenAPI `allOf` for derived schemas:
+
+```ts
+import { extend, getLineage } from 'zod-nest';
+
+const Base = z.object({ id: z.string() }).meta({ id: 'Base' });
+const Child = extend(Base, (s) => s.extend({ role: z.string() }).meta({ id: 'Child' }));
+
+getLineage(Child);
+// → { op: 'extend', parent: Base }
+```
+
+The emitted `Child` schema is `allOf: [{ $ref: '#/components/schemas/Base' }, { type: 'object', properties: { role: { type: 'string' } }, required: ['role'] }]`. The parent must be registered (via `.meta({ id })` or `createZodDto`) for the `$ref` to resolve; anonymous parents fall back to flat emission.
+
+See [`docs/composition.md`](docs/composition.md) for the full contract, current limitations, and the roadmap for non-`extend` operators.
+
+## API reference
+
+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`
+
+**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`, `ResponseVariant`, `ZOD_RESPONSES_METADATA_KEY`
+
+**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`, `ZodNestRegistry`, `Override`, `OverrideContext`, `ZodNestError`, `ZodNestUnrepresentableError`, `extend`, `getLineage`, `LineageEntry`
+
+## 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/) |
+
+## Migration from `nestjs-zod`
+
+If you're coming from `nestjs-zod`, the headline changes are:
+
+- Replace `cleanupOpenApiDoc(SwaggerModule.createDocument(app, config))` with `applyZodNest(SwaggerModule.createDocument(app, config), { app })`.
+- Replace `@ApiOkResponse({ type: Dto }) + @ZodSerializerDto(Dto)` pairs with `@ZodResponse({ type: Dto })`.
+- Drop `class-validator` / `class-transformer` if they were installed only for `nestjs-zod` interop.
+- Check any `MyDto.isZodDto` reflection — the discriminator is now `Symbol.for('zod-nest.dto') in MyDto`.
+- Status wildcards (`'2XX'`, `'default'`) aren't supported in v0 — use explicit statuses.
+
+Full guide with side-by-side diffs and a 19-row breaking-changes table in [`MIGRATION.md`](MIGRATION.md).
+
+## Contributing
+
+`zod-nest` is a young, single-maintainer OSS project — contributions and issues are welcome. The codebase is well-tested (>340 tests, full coverage on document/schema layers) and is meant to stay small enough that a first-time contributor can hold the whole surface in their head.
+
+See [`CONTRIBUTING.md`](CONTRIBUTING.md) for local-dev setup, the test layout, and how to add a recipe. Reports and discussions go through [GitHub issues](https://github.com/rodrigowbazevedo/zod-nest/issues).
+
+## License
+
+MIT — see [`LICENSE`](LICENSE).
+
+The names and patterns `createZodDto`, `ZodValidationPipe`, `ZodValidationException`, `ZodSerializerInterceptor`, `ZodSerializationException`, and `ZodResponse` originate in [`nestjs-zod`](https://github.com/BenLorantfy/nestjs-zod) (MIT). Attribution lives in [`NOTICE`](NOTICE).

package/dist/index.d.mts

@@ -12,10 +12,10 @@ declare const ZOD_NEST_ERROR_EXTENSION = "x-zod-nest-error";
 /** Value of `x-zod-nest-error` when a registry id is claimed by more than one schema. */
 declare const ZOD_NEST_ERROR_DUPLICATE_ID = "duplicate-id";
 /**
- * OpenAPI extension key used by `createZodDto` to mark a class for Phase 2e's
- * doc-merger. The marker carries `{ __zodNestDto: true, dtoId, io }` so the
- * merger can locate every zod-nest DTO in the @nestjs/swagger document and
- * inject the real Zod-derived schema.
+ * OpenAPI extension key used by `createZodDto` to mark a class for `applyZodNest`.
+ * The marker carries `{ __zodNestDto: true, dtoId, io }` so `applyZodNest` can
+ * locate every zod-nest DTO in the @nestjs/swagger document and inject the
+ * real Zod-derived schema.
  */
 declare const ZOD_NEST_DTO_EXTENSION = "x-zod-nest-dto";
 
@@ -28,17 +28,34 @@ interface OverrideContext {
 }
 type Override = (ctx: OverrideContext) => void;
 
+interface ZodNestRegistry {
+    readonly zodRegistry: typeof z.globalRegistry;
+    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`. The
+     * underlying Zod registry is `z.globalRegistry`, which may hold third-party
+     * entries — bulk emission filters its output against this snapshot to keep
+     * only zod-nest-known ids.
+     */
+    ids(): readonly string[];
+}
+declare const createRegistry: () => ZodNestRegistry;
+/** Process-wide default registry, used when no explicit `options.registry` is passed. */
+declare const defaultRegistry: ZodNestRegistry;
+
 /**
  * Composition layer — emits OpenAPI `allOf` for schemas derived via `extend`.
  *
- * **EXPERIMENTAL (v0.2)**: output shape may change as edge cases surface.
+ * **EXPERIMENTAL**: output shape may change as edge cases surface.
  */
 
 /**
  * Lineage record for a composition-derived schema. Read by the override to
  * emit `allOf` instead of a flat body.
  *
- * @experimental v0.2 — shape may change.
+ * @experimental — shape may change.
  */
 interface LineageEntry {
     readonly op: 'extend';
@@ -48,7 +65,7 @@ interface LineageEntry {
  * Wraps a derived `z.ZodObject` and records the parent → child link so
  * emission rewrites the body to `allOf: [{ $ref: <parent> }, <delta>]`.
  *
- * @experimental v0.2 — output shape may change as the surface stabilizes.
+ * @experimental — output shape may change as the surface stabilizes.
  *
  * @example
  *   const Base  = z.object({ id: z.string() }).meta({ id: 'Base' });
@@ -58,32 +75,10 @@ declare const extend: <P extends z.ZodObject, S extends z.ZodObject>(parent: P,
 /**
  * Read the lineage entry for a composition-derived schema, or `undefined`.
  *
- * @experimental v0.2 — `LineageEntry` shape may change.
+ * @experimental — `LineageEntry` shape may change.
  */
 declare const getLineage: (schema: z.ZodType) => LineageEntry | undefined;
 
-interface ZodNestRegistry {
-    readonly zodRegistry: typeof z.globalRegistry;
-    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;
-/**
- * Process-wide default registry. `createZodDto` registers schemas here unless
- * the caller passes `options.registry`. Phase 2e's doc merger reads from the
- * same instance for bulk emission. Multi-app WeakMap isolation is deferred
- * to v0.2.
- */
-declare const defaultRegistry: ZodNestRegistry;
-
 interface ToOpenApiOptions {
     io: 'input' | 'output';
     registry: ZodNestRegistry;
@@ -105,11 +100,7 @@ declare class ZodNestUnrepresentableError extends ZodNestError {
     constructor(path: ReadonlyArray<string | number>, zodType: string);
 }
 
-/**
- * Runtime detection marker placed on every class returned by `createZodDto`.
- * Used by the validation pipe (Phase 2c), serializer (2d), and doc merger (2e)
- * to discriminate zod-nest DTO classes from regular constructors.
- */
+/** Runtime tag placed on every class returned by `createZodDto`. */
 declare const ZOD_DTO_SYMBOL: unique symbol;
 
 type Io = 'input' | 'output';
@@ -139,7 +130,7 @@ declare const createZodDto: <TSchema extends z.ZodType>(schema: TSchema, options
 
 /**
  * Payload of the `x-zod-nest-dto` placeholder property that
- * `_OPENAPI_METADATA_FACTORY` returns. Phase 2e's doc merger reads this off
+ * `_OPENAPI_METADATA_FACTORY` returns. `applyZodNest` reads this off
  * each `components.schemas.<DtoName>.properties[x-zod-nest-dto]` entry,
  * uses `dtoId` to look up the schema in the registry, and replaces the
  * synthetic schema body with the real Zod-derived schema.
@@ -147,7 +138,7 @@ declare const createZodDto: <TSchema extends z.ZodType>(schema: TSchema, options
  * `type` and `required` are benign filler that satisfy @nestjs/swagger's
  * property-type guard (without them, the explorer throws "A circular
  * dependency has been detected"). They have no semantic meaning and are
- * stripped along with the rest of the marker by Phase 2e.
+ * stripped along with the rest of the marker by `applyZodNest`.
  */
 interface ZodDtoMarker {
     readonly type: () => typeof Object;
@@ -157,14 +148,13 @@ interface ZodDtoMarker {
     readonly io: Io;
 }
 declare const makeZodDtoMarker: (dtoId: string, io: Io) => ZodDtoMarker;
-/** Phase 2e (and tests) use this to discriminate a marker from a real schema. */
 declare const isZodDtoMarker: (value: unknown) => value is ZodDtoMarker;
 
 /**
  * Runtime guard: is `value` a class returned by `createZodDto`?
  *
- * Used by the validation pipe (Phase 2c), the serializer interceptor (2d),
- * and the doc merger (2e) to discriminate zod-nest DTOs from plain
+ * Used by `ZodValidationPipe`, `ZodSerializerInterceptor`, and `applyZodNest`
+ * to discriminate zod-nest DTOs from plain
  * constructors, class-validator DTOs, primitives, and any other metatypes
  * NestJS exposes via `ArgumentMetadata`.
  */
@@ -180,13 +170,18 @@ declare const isZodDto: (value: unknown) => value is ZodDto;
  * {
  *   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.
+ * The zod error tree is **deliberately not exposed in the response body** —
+ * a serialization failure is a server-side contract violation, and leaking
+ * the schema-shape error tree to clients discloses internal structure. The
+ * full treeified error is logged through `ZodNestModule`'s validation-log
+ * channel (with redaction + truncation) so operators get the diagnostic
+ * information without it reaching the wire.
+ *
+ * Custom exception filters can still introspect the failure: `zodError` and
+ * `executionContext` are kept as own properties on the instance.
  */
 declare class ZodSerializationException extends InternalServerErrorException {
     readonly zodError: z.ZodError;
@@ -328,7 +323,7 @@ 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
+ * `applyZodNest`'s `@ApiResponse(...)` emitter. String form is shorthand for
  * `{ description }`; the object form lets users declare OpenAPI response
  * `headers` / `links` alongside the description.
  */
@@ -339,8 +334,8 @@ type ZodResponseDescription = string | {
 };
 /**
  * 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.
+ * `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 — the
  * effective status is resolved lazily by `resolveEffectiveStatus(variant,
@@ -364,7 +359,7 @@ interface ResponseVariant {
  *   `@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.
+ *   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.
@@ -451,8 +446,7 @@ interface ApplyZodNestOptions {
     /**
      * `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).
+     * Pass an explicit registry for multi-app isolation.
      */
     registry?: ZodNestRegistry;
     /** User override pipe applied on top of the built-in override during emission. */