zod-nest 0.6.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";
 
@@ -34,21 +34,50 @@ interface ZodNestRegistry {
     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).
+     * 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;
+
 /**
- * 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.
+ * Composition layer — emits OpenAPI `allOf` for schemas derived via `extend`.
+ *
+ * **EXPERIMENTAL**: output shape may change as edge cases surface.
  */
-declare const defaultRegistry: ZodNestRegistry;
+
+/**
+ * Lineage record for a composition-derived schema. Read by the override to
+ * emit `allOf` instead of a flat body.
+ *
+ * @experimental — shape may change.
+ */
+interface LineageEntry {
+    readonly op: 'extend';
+    readonly parent: z.ZodObject;
+}
+/**
+ * Wraps a derived `z.ZodObject` and records the parent → child link so
+ * emission rewrites the body to `allOf: [{ $ref: <parent> }, <delta>]`.
+ *
+ * @experimental — output shape may change as the surface stabilizes.
+ *
+ * @example
+ *   const Base  = z.object({ id: z.string() }).meta({ id: 'Base' });
+ *   const Child = extend(Base, (s) => s.extend({ role: z.string() }).meta({ id: 'Child' }));
+ */
+declare const extend: <P extends z.ZodObject, S extends z.ZodObject>(parent: P, build: (p: P) => S) => S;
+/**
+ * Read the lineage entry for a composition-derived schema, or `undefined`.
+ *
+ * @experimental — `LineageEntry` shape may change.
+ */
+declare const getLineage: (schema: z.ZodType) => LineageEntry | undefined;
 
 interface ToOpenApiOptions {
     io: 'input' | 'output';
@@ -71,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';
@@ -105,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.
@@ -113,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;
@@ -123,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`.
  */
@@ -146,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;
@@ -294,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.
  */
@@ -305,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,
@@ -330,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.
@@ -417,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. */
@@ -470,4 +498,4 @@ declare class ZodNestDocumentError extends ZodNestError {
     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 };
+export { type ApplyZodNestOptions, COMPONENTS_SCHEMAS_PREFIX, type CreateSerializationException, type CreateValidationException, type CreateZodDtoOptions, DEFAULT_MAX_LOGGED_VALUE_BYTES, DEFAULT_REDACT_KEYS, type Io, type LineageEntry, 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, extend, getLineage, isZodDto, isZodDtoMarker, makeZodDtoMarker, resolveEffectiveStatus, toOpenApi };