zod-nest 1.3.1 → 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);