@voznov/zod-dto-nestjs 0.3.0 → 0.3.2

package/README.md

@@ -59,13 +59,15 @@ Importing this package side-effect-registers an `onCreate` hook that decorates e
 
 Supported shapes: scalars, objects (nested), arrays, tuples, records, enums, literals, unions (including discriminated), intersections, optional/nullable/default wrappers, and nested DTO references (via `oneOf` + `ApiExtraModels`).
 
+`z.discriminatedUnion(key, [...])` of DTO classes emits a proper OpenAPI `discriminator: { propertyName, mapping }` alongside `oneOf`, so codegen tools (`openapi-typescript`, `openapi-generator`) generate tagged unions instead of structural ones. Falls back to plain `oneOf` if any variant can't be mapped (non-DTO class or non-literal discriminator field).
+
 `.default(value)` is forwarded to the OpenAPI `default` keyword.
 
 > ⚠️ **Lazy defaults are frozen at decoration time.** For `.default(() => ...)`, the thunk is invoked **once** when the swagger metadata is generated, and the resolved value is baked into the spec. Anything non-stable — `Date.now()`, `randomUUID()`, `new Date()` — will freeze at the value the server happened to produce on startup, and every endpoint's example in your docs will show that one stale value. Use a stable thunk, or a literal default.
 
 `.describe(text)` is forwarded to the OpenAPI `description` keyword. Works on the wrapper or on the inner type — `z.string().describe('Login email').optional()` and `z.string().optional().describe('Login email')` both end up with `description: 'Login email'` in the spec.
 
-`.refine(...)` validators run at request-validation time but are **not** reflected in the spec — JSON Schema can't express custom predicates, and a single `description` for a chain of refines (`.refine(...).refine(...).refine(...)`) would be ambiguous. Put human-readable docs in `.describe(...)` instead.
+`.refine(...)` validators run at runtime (in `ZodValidationPipe` for requests, in `@ZodSerialize` / `@ZodResponse` for responses) but are **not** reflected in the spec — JSON Schema can't express custom predicates, and a single `description` for a chain of refines (`.refine(...).refine(...).refine(...)`) would be ambiguous. Put human-readable docs in `.describe(...)` instead.
 
 > ⚠️ **`in` / `out` hooks are runtime-only.** The walker only reads the schema's structure, not the options passed to `ZodDto(schema, { in, out })`. A `out: ({ password, ...rest }) => rest` correctly strips `password` from the response *body*, but the OpenAPI schema still lists `password` as a property — the spec lies about a field that runtime drops. Same for `in`: snake_case→camelCase aliases applied via `in` are invisible in the spec, so docs show only the camelCase shape. If spec-correctness matters, either omit the field from the schema itself (`schema.omit({ password: true })`) or maintain a separate response DTO.
 
@@ -124,9 +126,33 @@ Method decorators that parse the return value of a controller (or any class) met
 - **`@ZodSerialize`** — runtime parsing only. Use on services, repositories, internal methods.
 - **`@ZodResponse`** — `@ZodSerialize` + auto-emit `@ApiResponse` Swagger metadata (and register inner DTOs via `@ApiExtraModels`). Use on controller routes.
 
-Both come in two overloads:
+`ZodDtoSerializationError extends ZodDtoValidationError` — wire up one exception filter to split client errors (400) from server bugs (500):
+
+```ts
+import { ArgumentsHost, Catch, ExceptionFilter, HttpStatus } from '@nestjs/common';
+import { ZodDtoValidationError } from '@voznov/zod-dto';
+import { ZodDtoSerializationError } from '@voznov/zod-dto-nestjs';
+
+@Catch(ZodDtoValidationError)
+export class ZodExceptionFilter implements ExceptionFilter {
+  catch(error: ZodDtoValidationError, host: ArgumentsHost) {
+    const isServerBug = error instanceof ZodDtoSerializationError;
+    const status = isServerBug ? HttpStatus.INTERNAL_SERVER_ERROR : HttpStatus.BAD_REQUEST;
+    host.switchToHttp().getResponse().status(status).json({
+      statusCode: status,
+      message: error.message,
+      issues: isServerBug ? undefined : error.issues,
+    });
+  }
+}
+
+// main.ts
+app.useGlobalFilters(new ZodExceptionFilter());
+```
+
+Both decorators come in two overloads:
 
-- **Strict** — schema passed explicitly. The method's return type is constrained at compile time to match the schema's output; `tsc` errors on mismatch.
+- **Strict** — schema passed explicitly. The method's return type is constrained at compile time to match the schema's output; `tsc` errors on mismatch as `TS1241: Unable to resolve signature of method decorator...` — the actual mismatch is on the deepest line of the message (`Type 'X' is not assignable to type 'NoteDto | Promise<NoteDto>'`).
 - **Loose** — no schema. Resolves from `design:returntype` metadata at runtime (`: NoteDto` annotation suffices). No compile-time check; doesn't work on generic return types (`NoteDto[]`, `Promise<NoteDto>`, unions) since TypeScript erases generics in metadata — pass the schema explicitly in that case.
 
 ```ts
@@ -184,21 +210,15 @@ Both decorators accept the full `ToDtoOptions` bag (`preprocessors`, `observers`
 async create(): Promise<NoteDto> { /* ... */ }
 ```
 
-### Differentiating client errors from server errors
+### Async refines on the response schema
 
-`ZodDtoSerializationError extends ZodDtoValidationError`, so a single exception filter can split request-validation failures (client → 400) from response-validation failures (server → 500):
+When the method returns a Promise, the decorator awaits it and parses through `safeParseAsync` — that's the only signal it uses. So if your schema has async validation (`z.string().refine(async ...)`, async transforms — typical when the same schema is reused for request validation), make the method `async` and you'll get the async parse path; failures still throw `ZodDtoSerializationError` and flow through your exception filter, not raw Zod async errors.
 
 ```ts
-import { ZodDtoValidationError } from '@voznov/zod-dto';
-import { ZodDtoSerializationError } from '@voznov/zod-dto-nestjs';
-
-@Catch(ZodDtoValidationError)
-export class ZodExceptionFilter implements ExceptionFilter {
-  catch(error: ZodDtoValidationError, host: ArgumentsHost) {
-    const isServerBug = error instanceof ZodDtoSerializationError;
-    const status = isServerBug ? 500 : 400;
-    // log, format, respond...
-  }
+class Repo {
+  // Promise return → safeParseAsync. Works with async refines on the schema.
+  @ZodSerialize(SchemaWithAsyncRefine)
+  async findOne(id: string): Promise<...> { /* ... */ }
 }
 ```
 

package/dist/index.cjs

@@ -1311,6 +1311,21 @@ var applyDecoratorsImpl = (schema) => {
       innerSchemas_.forEach((innerSchema) => innerSchemas.add(innerSchema));
       return so.oneOf?.length === 1 ? so.oneOf[0] : so;
     });
+    if (schema instanceof import_zod.z.ZodDiscriminatedUnion) {
+      const propertyName = schema._zod.def.discriminator;
+      const mapping = {};
+      const allMappable = schema.options.every((option, i) => {
+        if (!(option instanceof import_zod.z.ZodObject)) return false;
+        const field = option.shape[propertyName];
+        if (!(field instanceof import_zod.z.ZodLiteral)) return false;
+        if (!("$ref" in oneOf[i])) return false;
+        for (const literalValue of field.values) mapping[String(literalValue)] = oneOf[i].$ref;
+        return true;
+      });
+      if (allMappable) {
+        return { so: { oneOf, discriminator: { propertyName, mapping } }, selfRequired: true, innerSchemas };
+      }
+    }
     return { so: { oneOf }, selfRequired: true, innerSchemas };
   }
   if (schema instanceof import_zod.z.ZodIntersection) {
@@ -1362,6 +1377,9 @@ var import_zod2 = require("zod");
 var ZodDtoSerializationError = class extends import_zod_dto3.ZodDtoValidationError {
 };
 var resolveSchema = (schema, target, propertyKey, decoratorName) => {
+  if (schema !== void 0 && !(schema instanceof import_zod2.z.ZodType) && !(0, import_zod_dto3.isZodDtoClass)(schema)) {
+    throw new Error(`${decoratorName} on ${target.constructor.name}.${String(propertyKey)}: schema argument must be a Zod type or DTO class (got ${typeof schema}).`);
+  }
   if (schema) return schema;
   const rt = Reflect.getMetadata("design:returntype", target, propertyKey);
   if (rt instanceof import_zod2.z.ZodType) return rt;
@@ -1381,7 +1399,7 @@ var wrapMethod = (schema, options, decoratorName) => (target, methodName, descri
     [methodName](...args) {
       const out = originalMethod.apply(this, args);
       if (out instanceof Promise) {
-        return out.then((v) => serialize(resolved, v));
+        return out.then(async (v) => serialize.async(resolved, v));
       }
       return serialize(resolved, out);
     }
@@ -1391,7 +1409,8 @@ var wrapMethod = (schema, options, decoratorName) => (target, methodName, descri
 var wrapApiResponse = (schema, options) => (target, propertyKey, descriptor) => {
   const resolved = resolveSchema(schema, target, propertyKey, "@ZodResponse");
   const { so, innerSchemas } = applySwaggerDecorators(resolved);
-  (0, import_swagger2.ApiResponse)({ status: options?.status ?? 200, description: options?.description, schema: so })(target, propertyKey, descriptor);
+  const schemaForApi = Object.keys(so).length === 1 && Array.isArray(so.oneOf) && so.oneOf.length === 1 ? so.oneOf[0] : so;
+  (0, import_swagger2.ApiResponse)({ status: options?.status ?? 200, description: options?.description, schema: schemaForApi })(target, propertyKey, descriptor);
   if (innerSchemas.size > 0) {
     const classTarget = typeof target === "function" ? target : target.constructor;
     (0, import_swagger2.ApiExtraModels)(...innerSchemas)(classTarget);