zod-nest 1.3.0 → 1.4.0

package/dist/index.d.mts

@@ -446,13 +446,26 @@ interface ZodResponseOptions {
     passthroughOnError?: boolean;
 }
 /**
- * Method-only decorator. Declares a typed response variant for the handler.
- * Stack multiple decorations to declare per-status types; lookup at runtime
- * is by `ZodSerializerInterceptor`'s two-pass matcher (exact numeric, then
- * `'NXX'` wildcard).
+ * Method-only decorator. Declares a typed response variant for the handler
+ * AND applies the equivalent `@ApiResponse(...)` from `@nestjs/swagger` so
+ * the OpenAPI document carries the response shape — no need for consumers
+ * to hand-write `@ApiResponse` alongside `@ZodResponse`.
  *
- * The wrapped Zod schema (array / tuple) is built once at decoration time
- * and stored on the variant record — no per-request schema construction.
+ * Stack multiple decorations to declare per-status types; runtime lookup
+ * is by `ZodSerializerInterceptor`'s two-pass matcher (exact numeric, then
+ * `'NXX'` wildcard). The wrapped Zod schema (array / tuple) is built once
+ * at decoration time — no per-request schema construction.
+ *
+ * **Decorator-ordering note (implicit `status` only).** TypeScript decorators
+ * apply bottom-up, so `@ZodResponse` (typically written above `@Get` /
+ * `@HttpCode`) executes its factory body *first* — before sibling
+ * decorators have written their `HTTP_CODE_METADATA` / `METHOD_METADATA`.
+ * When `opts.status` is explicit, the `@ApiResponse(...)` call is applied
+ * synchronously — there's nothing to wait for. When `opts.status` is
+ * implicit (resolves to `@HttpCode` or the HTTP-method default), the
+ * `@ApiResponse(...)` call is deferred via `queueMicrotask` so the sibling
+ * metadata has settled by the time we read it. See `docs/responses.md →
+ * "Decorator ordering & the microtask trick"`.
  */
 declare const ZodResponse: (opts: ZodResponseOptions) => MethodDecorator;
 

package/dist/index.d.ts

@@ -446,13 +446,26 @@ interface ZodResponseOptions {
     passthroughOnError?: boolean;
 }
 /**
- * Method-only decorator. Declares a typed response variant for the handler.
- * Stack multiple decorations to declare per-status types; lookup at runtime
- * is by `ZodSerializerInterceptor`'s two-pass matcher (exact numeric, then
- * `'NXX'` wildcard).
+ * Method-only decorator. Declares a typed response variant for the handler
+ * AND applies the equivalent `@ApiResponse(...)` from `@nestjs/swagger` so
+ * the OpenAPI document carries the response shape — no need for consumers
+ * to hand-write `@ApiResponse` alongside `@ZodResponse`.
  *
- * The wrapped Zod schema (array / tuple) is built once at decoration time
- * and stored on the variant record — no per-request schema construction.
+ * Stack multiple decorations to declare per-status types; runtime lookup
+ * is by `ZodSerializerInterceptor`'s two-pass matcher (exact numeric, then
+ * `'NXX'` wildcard). The wrapped Zod schema (array / tuple) is built once
+ * at decoration time — no per-request schema construction.
+ *
+ * **Decorator-ordering note (implicit `status` only).** TypeScript decorators
+ * apply bottom-up, so `@ZodResponse` (typically written above `@Get` /
+ * `@HttpCode`) executes its factory body *first* — before sibling
+ * decorators have written their `HTTP_CODE_METADATA` / `METHOD_METADATA`.
+ * When `opts.status` is explicit, the `@ApiResponse(...)` call is applied
+ * synchronously — there's nothing to wait for. When `opts.status` is
+ * implicit (resolves to `@HttpCode` or the HTTP-method default), the
+ * `@ApiResponse(...)` call is deferred via `queueMicrotask` so the sibling
+ * metadata has settled by the time we read it. See `docs/responses.md →
+ * "Decorator ordering & the microtask trick"`.
  */
 declare const ZodResponse: (opts: ZodResponseOptions) => MethodDecorator;
 

package/dist/index.js

@@ -2,10 +2,11 @@
 
 var zod = require('zod');
 var common = require('@nestjs/common');
+var constants_js = require('@nestjs/common/constants.js');
+var swagger = require('@nestjs/swagger');
 var core = require('@nestjs/core');
 var rxjs = require('rxjs');
 var operators = require('rxjs/operators');
-var constants_js = require('@nestjs/common/constants.js');
 var stringify = require('fast-json-stable-stringify');
 
 function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
@@ -924,6 +925,25 @@ exports.ZodValidationPipe = _ts_decorate([
     typeof NormalizedZodNestOptions === "undefined" ? Object : NormalizedZodNestOptions
   ])
 ], exports.ZodValidationPipe);
+var POST_DEFAULT_STATUS = 201;
+var GENERIC_DEFAULT_STATUS = 200;
+var defaultStatusFor = /* @__PURE__ */ __name((handler) => {
+  const httpCode = Reflect.getMetadata(constants_js.HTTP_CODE_METADATA, handler);
+  if (typeof httpCode === "number") {
+    return httpCode;
+  }
+  const method = Reflect.getMetadata(constants_js.METHOD_METADATA, handler);
+  if (method === common.RequestMethod.POST) {
+    return POST_DEFAULT_STATUS;
+  }
+  return GENERIC_DEFAULT_STATUS;
+}, "defaultStatusFor");
+var resolveEffectiveStatus = /* @__PURE__ */ __name((variant, handler) => {
+  if (variant.status !== void 0) {
+    return variant.status;
+  }
+  return defaultStatusFor(handler);
+}, "resolveEffectiveStatus");
 
 // src/response/metadata.ts
 var ZOD_RESPONSES_METADATA_KEY = /* @__PURE__ */ Symbol.for("zod-nest.responses");
@@ -938,6 +958,67 @@ var appendResponseVariant = /* @__PURE__ */ __name((handler, variant) => {
     ...existing
   ], handler);
 }, "appendResponseVariant");
+var extractDescriptionFields = /* @__PURE__ */ __name((desc) => {
+  if (desc === void 0) {
+    return {};
+  }
+  if (typeof desc === "string") {
+    return {
+      description: desc
+    };
+  }
+  const out = {
+    description: desc.description
+  };
+  if (desc.headers !== void 0) {
+    out.headers = desc.headers;
+  }
+  if (desc.links !== void 0) {
+    out.links = desc.links;
+  }
+  return out;
+}, "extractDescriptionFields");
+var asDtoFunction = /* @__PURE__ */ __name((dto) => dto, "asDtoFunction");
+var buildApiResponseOptions = /* @__PURE__ */ __name((base, body) => {
+  return {
+    ...base,
+    ...body
+  };
+}, "buildApiResponseOptions");
+var applySwaggerResponseDecorator = /* @__PURE__ */ __name((variant, effectiveStatus, target, propertyKey, descriptor) => {
+  const base = {
+    status: effectiveStatus,
+    ...extractDescriptionFields(variant.description)
+  };
+  if (variant.kind === "single") {
+    const dto = variant.dto;
+    swagger.ApiResponse(buildApiResponseOptions(base, {
+      type: asDtoFunction(dto)
+    }))(target, propertyKey, descriptor);
+    return;
+  }
+  if (variant.kind === "array") {
+    const dtos2 = variant.dto;
+    const dto = dtos2[0];
+    swagger.ApiResponse(buildApiResponseOptions(base, {
+      type: asDtoFunction(dto),
+      isArray: true
+    }))(target, propertyKey, descriptor);
+    return;
+  }
+  const dtos = variant.dto;
+  swagger.ApiExtraModels(...dtos.map(asDtoFunction))(target, propertyKey, descriptor);
+  const schema = {
+    type: "array",
+    prefixItems: dtos.map((d) => ({
+      $ref: swagger.getSchemaPath(asDtoFunction(d))
+    })),
+    items: false
+  };
+  swagger.ApiResponse(buildApiResponseOptions(base, {
+    schema
+  }))(target, propertyKey, descriptor);
+}, "applySwaggerResponseDecorator");
 
 // src/decorators/zod-response.decorator.ts
 var buildArrayKind = /* @__PURE__ */ __name((dtos) => {
@@ -991,7 +1072,8 @@ var normaliseStatus = /* @__PURE__ */ __name((status) => {
 var ZodResponse = /* @__PURE__ */ __name((opts) => {
   const built = buildKind(opts.type);
   const status = normaliseStatus(opts.status);
-  return (_target, _propertyKey, descriptor) => {
+  const statusExplicit = status !== void 0;
+  return (target, propertyKey, descriptor) => {
     const handler = descriptor.value;
     if (typeof handler !== "function") {
       throw new TypeError("[zod-nest] @ZodResponse can only be applied to methods.");
@@ -1005,29 +1087,17 @@ var ZodResponse = /* @__PURE__ */ __name((opts) => {
       passthroughOnError: opts.passthroughOnError ?? false
     };
     appendResponseVariant(handler, variant);
+    const swaggerDescriptor = descriptor;
+    if (statusExplicit) {
+      applySwaggerResponseDecorator(variant, status, target, propertyKey, swaggerDescriptor);
+      return;
+    }
+    queueMicrotask(() => {
+      const effective = resolveEffectiveStatus(variant, handler);
+      applySwaggerResponseDecorator(variant, effective, target, propertyKey, swaggerDescriptor);
+    });
   };
 }, "ZodResponse");
-var POST_DEFAULT_STATUS = 201;
-var GENERIC_DEFAULT_STATUS = 200;
-var defaultStatusFor = /* @__PURE__ */ __name((handler) => {
-  const httpCode = Reflect.getMetadata(constants_js.HTTP_CODE_METADATA, handler);
-  if (typeof httpCode === "number") {
-    return httpCode;
-  }
-  const method = Reflect.getMetadata(constants_js.METHOD_METADATA, handler);
-  if (method === common.RequestMethod.POST) {
-    return POST_DEFAULT_STATUS;
-  }
-  return GENERIC_DEFAULT_STATUS;
-}, "defaultStatusFor");
-var resolveEffectiveStatus = /* @__PURE__ */ __name((variant, handler) => {
-  if (variant.status !== void 0) {
-    return variant.status;
-  }
-  return defaultStatusFor(handler);
-}, "resolveEffectiveStatus");
-
-// src/interceptors/serializer.interceptor.ts
 function _ts_decorate2(decorators, target, key, desc) {
   var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
   if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
@@ -1199,6 +1269,25 @@ var HTTP_METHODS = [
   "patch",
   "trace"
 ];
+var forEachOperation = /* @__PURE__ */ __name((doc, fn) => {
+  const paths = doc.paths;
+  if (paths === null || typeof paths !== "object") {
+    return;
+  }
+  for (const pathItem of Object.values(paths)) {
+    if (pathItem === null || typeof pathItem !== "object") {
+      continue;
+    }
+    const pathRecord = pathItem;
+    for (const method of HTTP_METHODS) {
+      const op = pathRecord[method];
+      if (op === null || typeof op !== "object") {
+        continue;
+      }
+      fn(op);
+    }
+  }
+}, "forEachOperation");
 
 // src/document/collect-usage.ts
 var isPlainRecord2 = /* @__PURE__ */ __name((value) => value !== null && typeof value === "object" && !Array.isArray(value), "isPlainRecord");
@@ -1441,41 +1530,39 @@ var hintFor = /* @__PURE__ */ __name((ref, collected) => {
 var isPlainRecord3 = /* @__PURE__ */ __name((value) => value !== null && typeof value === "object" && !Array.isArray(value), "isPlainRecord");
 var expandParamMarkers = /* @__PURE__ */ __name((params) => {
   const { doc, inputSchemas, outputSchemas } = params;
-  const paths = doc.paths;
-  if (!isPlainRecord3(paths)) {
-    return;
-  }
-  for (const pathItem of Object.values(paths)) {
-    if (!isPlainRecord3(pathItem)) {
-      continue;
+  let expandedAny = false;
+  forEachOperation(doc, (op) => {
+    const parameters = op.parameters;
+    if (!Array.isArray(parameters)) {
+      return;
     }
-    for (const method of HTTP_METHODS) {
-      const op = pathItem[method];
-      if (!isPlainRecord3(op)) {
-        continue;
-      }
-      const parameters = op.parameters;
-      if (!Array.isArray(parameters)) {
-        continue;
-      }
-      op.parameters = expandParameterList(parameters, inputSchemas, outputSchemas);
+    const next = expandParameterList(parameters, inputSchemas, outputSchemas);
+    if (next !== parameters) {
+      op.parameters = next;
+      expandedAny = true;
     }
+  });
+  if (expandedAny) {
+    pruneOrphanObjectSchema(doc);
   }
-  pruneOrphanObjectSchema(doc);
 }, "expandParamMarkers");
 var expandParameterList = /* @__PURE__ */ __name((parameters, inputSchemas, outputSchemas) => {
-  const result = [];
-  for (const param of parameters) {
+  let result;
+  for (let i = 0; i < parameters.length; i++) {
+    const param = parameters[i];
     const marker = readMarker2(param);
     if (marker === void 0) {
-      result.push(param);
+      result?.push(param);
       continue;
     }
+    if (result === void 0) {
+      result = parameters.slice(0, i);
+    }
     const map = marker.io === "output" ? outputSchemas : inputSchemas;
     const body = map.get(marker.dtoId);
     result.push(...expandOne(marker, body));
   }
-  return result;
+  return result ?? parameters;
 }, "expandParameterList");
 var readMarker2 = /* @__PURE__ */ __name((value) => {
   if (!isPlainRecord3(value)) {
@@ -1532,16 +1619,12 @@ var buildParameter = /* @__PURE__ */ __name((marker, name, schema, required) =>
     console.warn(`[zod-nest] Path parameter \`${name}\` on DTO \`${marker.dtoId}\` is marked optional in the Zod schema; OpenAPI 3.1 requires path parameters to be required. Coercing \`required: true\` so the emitted document is spec-valid. Fix by removing \`.optional()\` / \`.nullish()\` from the field, or by switching the decorator to @Query() / @Headers() if the field is genuinely optional.`);
     effectiveRequired = true;
   }
-  const entry = {
+  return {
     name,
     in: marker.in,
     required: effectiveRequired,
     schema
   };
-  if (typeof schema.description === "string") {
-    entry.description = schema.description;
-  }
-  return entry;
 }, "buildParameter");
 var capitalize = /* @__PURE__ */ __name((value) => value.charAt(0).toUpperCase() + value.slice(1), "capitalize");
 var pruneOrphanObjectSchema = /* @__PURE__ */ __name((doc) => {
@@ -1755,40 +1838,28 @@ var stripMarkers = /* @__PURE__ */ __name((doc) => {
   if (schemas !== void 0) {
     for (const schema of Object.values(schemas)) {
       stripMarkerFromSchema(schema);
+      dropJsonSchemaMetadata(schema);
     }
   }
   stripMarkerParameters(doc);
 }, "stripMarkers");
-var stripMarkerParameters = /* @__PURE__ */ __name((doc) => {
-  const paths = doc.paths;
-  if (paths === null || typeof paths !== "object") {
+var dropJsonSchemaMetadata = /* @__PURE__ */ __name((schema) => {
+  if (schema === null || typeof schema !== "object") {
     return;
   }
-  for (const pathItem of Object.values(paths)) {
-    if (pathItem === null || typeof pathItem !== "object") {
-      continue;
-    }
-    const pathRecord = pathItem;
-    for (const method of HTTP_METHODS) {
-      const op = pathRecord[method];
-      if (op === null || typeof op !== "object") {
-        continue;
-      }
-      const opRecord = op;
-      const parameters = opRecord.parameters;
-      if (!Array.isArray(parameters)) {
-        continue;
-      }
-      opRecord.parameters = parameters.filter((param) => !isMarkerParam(param));
+  const body = schema;
+  delete body.$schema;
+  delete body.$id;
+}, "dropJsonSchemaMetadata");
+var stripMarkerParameters = /* @__PURE__ */ __name((doc) => {
+  forEachOperation(doc, (op) => {
+    const parameters = op.parameters;
+    if (!Array.isArray(parameters)) {
+      return;
     }
-  }
+    op.parameters = parameters.filter((param) => !isZodDtoMarker(param));
+  });
 }, "stripMarkerParameters");
-var isMarkerParam = /* @__PURE__ */ __name((value) => {
-  if (value === null || typeof value !== "object") {
-    return false;
-  }
-  return value.__zodNestDto === true;
-}, "isMarkerParam");
 var stripMarkerFromSchema = /* @__PURE__ */ __name((schema) => {
   if (schema === null || typeof schema !== "object") {
     return;