zod-nest 1.2.0 → 1.3.0

package/dist/index.d.mts

@@ -543,10 +543,18 @@ interface ApplyZodNestOptions {
  * - Every `components.schemas[<DtoClassName>]` placeholder with an
  *   `x-zod-nest-dto` marker is replaced by the Zod-derived JSON Schema body,
  *   keyed by the marker's `dtoId` (renaming as needed).
+ * - Every `@Query()` / `@Param()` / `@Headers()` / `@Cookie()` marker
+ *   parameter is expanded into one parameter per top-level property of the
+ *   DTO's schema (`expandParamMarkers`). The synthetic `components.schemas.Object`
+ *   that `@nestjs/swagger` materialises for the marker placeholder is pruned
+ *   when it has no remaining referrers.
  * - The I/O suffix truth table is applied — equal input/output bodies collapse
  *   to one `components.schemas[id]`; divergent bodies split as
  *   `id` (input) + `idOutput` (output), with response-side refs rewritten.
  * - Every `$ref` whose target is missing throws `ZodNestDocumentError(DANGLING_REF)`.
+ * - `doc.openapi` is set to `'3.1.0'` — zod-nest emits OpenAPI 3.1 only; this
+ *   guarantees the version string matches the emitted body regardless of the
+ *   `DocumentBuilder` configuration on the caller side.
  *
  * Composable with other doc-transform passes — apply other mutations before
  * or after this function. The `app` argument is required because the
@@ -555,7 +563,7 @@ interface ApplyZodNestOptions {
  */
 declare const applyZodNest: (doc: OpenAPIObject, opts: ApplyZodNestOptions) => OpenAPIObject;
 
-type ZodNestDocumentErrorCode = 'AMBIGUOUS_RENAME' | 'DANGLING_REF';
+type ZodNestDocumentErrorCode = 'AMBIGUOUS_RENAME' | 'DANGLING_REF' | 'UNEXPANDABLE_PARAM_DTO';
 /**
  * Thrown by `applyZodNest` when the doc cannot be processed cleanly. Surfaces
  * at doc-build time so typos / mis-registrations fail in CI, not at runtime.
@@ -568,6 +576,11 @@ type ZodNestDocumentErrorCode = 'AMBIGUOUS_RENAME' | 'DANGLING_REF';
  * that no longer exists after `applyZodNest`. Usually means a marker was
  * stripped but its rename target wasn't populated, or a user-supplied pre-pass
  * left a stale ref.
+ *
+ * `UNEXPANDABLE_PARAM_DTO`: a `@Query()` / `@Param()` / `@Headers()` /
+ * `@Cookie()` handler argument resolved to a `createZodDto` whose schema is
+ * not an object — the marker parameter can't be expanded into individual
+ * parameters because there's no top-level `properties` record to iterate.
  */
 declare class ZodNestDocumentError extends ZodNestError {
     readonly code: ZodNestDocumentErrorCode;

package/dist/index.d.ts

@@ -543,10 +543,18 @@ interface ApplyZodNestOptions {
  * - Every `components.schemas[<DtoClassName>]` placeholder with an
  *   `x-zod-nest-dto` marker is replaced by the Zod-derived JSON Schema body,
  *   keyed by the marker's `dtoId` (renaming as needed).
+ * - Every `@Query()` / `@Param()` / `@Headers()` / `@Cookie()` marker
+ *   parameter is expanded into one parameter per top-level property of the
+ *   DTO's schema (`expandParamMarkers`). The synthetic `components.schemas.Object`
+ *   that `@nestjs/swagger` materialises for the marker placeholder is pruned
+ *   when it has no remaining referrers.
  * - The I/O suffix truth table is applied — equal input/output bodies collapse
  *   to one `components.schemas[id]`; divergent bodies split as
  *   `id` (input) + `idOutput` (output), with response-side refs rewritten.
  * - Every `$ref` whose target is missing throws `ZodNestDocumentError(DANGLING_REF)`.
+ * - `doc.openapi` is set to `'3.1.0'` — zod-nest emits OpenAPI 3.1 only; this
+ *   guarantees the version string matches the emitted body regardless of the
+ *   `DocumentBuilder` configuration on the caller side.
  *
  * Composable with other doc-transform passes — apply other mutations before
  * or after this function. The `app` argument is required because the
@@ -555,7 +563,7 @@ interface ApplyZodNestOptions {
  */
 declare const applyZodNest: (doc: OpenAPIObject, opts: ApplyZodNestOptions) => OpenAPIObject;
 
-type ZodNestDocumentErrorCode = 'AMBIGUOUS_RENAME' | 'DANGLING_REF';
+type ZodNestDocumentErrorCode = 'AMBIGUOUS_RENAME' | 'DANGLING_REF' | 'UNEXPANDABLE_PARAM_DTO';
 /**
  * Thrown by `applyZodNest` when the doc cannot be processed cleanly. Surfaces
  * at doc-build time so typos / mis-registrations fail in CI, not at runtime.
@@ -568,6 +576,11 @@ type ZodNestDocumentErrorCode = 'AMBIGUOUS_RENAME' | 'DANGLING_REF';
  * that no longer exists after `applyZodNest`. Usually means a marker was
  * stripped but its rename target wasn't populated, or a user-supplied pre-pass
  * left a stale ref.
+ *
+ * `UNEXPANDABLE_PARAM_DTO`: a `@Query()` / `@Param()` / `@Headers()` /
+ * `@Cookie()` handler argument resolved to a `createZodDto` whose schema is
+ * not an object — the marker parameter can't be expanded into individual
+ * parameters because there's no top-level `properties` record to iterate.
  */
 declare class ZodNestDocumentError extends ZodNestError {
     readonly code: ZodNestDocumentErrorCode;

package/dist/index.js

@@ -1273,9 +1273,20 @@ var collectRefsFromOperation = /* @__PURE__ */ __name((operation, classToDtoId,
         continue;
       }
       collectRefFromSchema(param.schema, classToDtoId, ids);
+      collectIdFromMarkerParam(param, ids);
     }
   }
 }, "collectRefsFromOperation");
+var collectIdFromMarkerParam = /* @__PURE__ */ __name((param, ids) => {
+  if (param.__zodNestDto !== true) {
+    return;
+  }
+  const dtoId = param.dtoId;
+  if (typeof dtoId !== "string" || dtoId === "") {
+    return;
+  }
+  ids.add(dtoId);
+}, "collectIdFromMarkerParam");
 var collectRefsFromContent = /* @__PURE__ */ __name((content, classToDtoId, ids) => {
   if (!isPlainRecord2(content)) {
     return;
@@ -1426,6 +1437,131 @@ var hintFor = /* @__PURE__ */ __name((ref, collected) => {
   return "no DTO with this id was registered \u2014 check for a meta.id typo or a DTO used without createZodDto";
 }, "hintFor");
 
+// src/document/expand-param-markers.ts
+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;
+    }
+    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);
+    }
+  }
+  pruneOrphanObjectSchema(doc);
+}, "expandParamMarkers");
+var expandParameterList = /* @__PURE__ */ __name((parameters, inputSchemas, outputSchemas) => {
+  const result = [];
+  for (const param of parameters) {
+    const marker = readMarker2(param);
+    if (marker === void 0) {
+      result.push(param);
+      continue;
+    }
+    const map = marker.io === "output" ? outputSchemas : inputSchemas;
+    const body = map.get(marker.dtoId);
+    result.push(...expandOne(marker, body));
+  }
+  return result;
+}, "expandParameterList");
+var readMarker2 = /* @__PURE__ */ __name((value) => {
+  if (!isPlainRecord3(value)) {
+    return void 0;
+  }
+  if (value.__zodNestDto !== true) {
+    return void 0;
+  }
+  if (typeof value.dtoId !== "string" || value.dtoId === "") {
+    return void 0;
+  }
+  if (value.io !== "input" && value.io !== "output") {
+    return void 0;
+  }
+  if (typeof value.in !== "string" || value.in === "") {
+    return void 0;
+  }
+  return value;
+}, "readMarker");
+var expandOne = /* @__PURE__ */ __name((marker, body) => {
+  if (!isPlainRecord3(body) || !isPlainRecord3(body.properties)) {
+    throw new ZodNestDocumentError("UNEXPANDABLE_PARAM_DTO", `Cannot expand \`@${capitalize(marker.in)}() x: ${marker.dtoId}\` \u2014 the DTO's schema is not an object with \`properties\`. Non-body parameter DTOs must be object schemas; arrays, unions, primitives, etc. cannot be split into individual parameters. Use \`@Body()\` for non-object DTOs, or restructure the schema as an object whose fields become the params.`, {
+      dtoId: marker.dtoId,
+      in: marker.in,
+      io: marker.io
+    });
+  }
+  const properties = body.properties;
+  const requiredSet = collectRequired(body.required);
+  const out = [];
+  for (const [propName, propSchemaRaw] of Object.entries(properties)) {
+    if (!isPlainRecord3(propSchemaRaw)) {
+      continue;
+    }
+    out.push(buildParameter(marker, propName, propSchemaRaw, requiredSet.has(propName)));
+  }
+  return out;
+}, "expandOne");
+var collectRequired = /* @__PURE__ */ __name((value) => {
+  if (!Array.isArray(value)) {
+    return /* @__PURE__ */ new Set();
+  }
+  const out = /* @__PURE__ */ new Set();
+  for (const item of value) {
+    if (typeof item === "string") {
+      out.add(item);
+    }
+  }
+  return out;
+}, "collectRequired");
+var buildParameter = /* @__PURE__ */ __name((marker, name, schema, required) => {
+  let effectiveRequired = required;
+  if (marker.in === "path" && !effectiveRequired) {
+    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 = {
+    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) => {
+  const schemas = doc.components?.schemas;
+  if (schemas === void 0 || !Object.prototype.hasOwnProperty.call(schemas, "Object")) {
+    return;
+  }
+  let referenced = false;
+  const targetRef = `${COMPONENTS_SCHEMAS_PREFIX}Object`;
+  walkRefs(doc, (ref) => {
+    if (ref === targetRef) {
+      referenced = true;
+    }
+    return void 0;
+  });
+  if (!referenced) {
+    delete schemas.Object;
+  }
+}, "pruneOrphanObjectSchema");
+
 // src/document/expose-closure.ts
 var extendExposureViaRefs = /* @__PURE__ */ __name((collected, inputSchemas, outputSchemas) => ({
   ...collected,
@@ -1616,13 +1752,43 @@ var rewriteResponseSubtree = /* @__PURE__ */ __name((pathItem, divergentOutputId
 // src/document/strip-markers.ts
 var stripMarkers = /* @__PURE__ */ __name((doc) => {
   const schemas = doc.components?.schemas;
-  if (schemas === void 0) {
+  if (schemas !== void 0) {
+    for (const schema of Object.values(schemas)) {
+      stripMarkerFromSchema(schema);
+    }
+  }
+  stripMarkerParameters(doc);
+}, "stripMarkers");
+var stripMarkerParameters = /* @__PURE__ */ __name((doc) => {
+  const paths = doc.paths;
+  if (paths === null || typeof paths !== "object") {
     return;
   }
-  for (const schema of Object.values(schemas)) {
-    stripMarkerFromSchema(schema);
+  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));
+    }
+  }
+}, "stripMarkerParameters");
+var isMarkerParam = /* @__PURE__ */ __name((value) => {
+  if (value === null || typeof value !== "object") {
+    return false;
   }
-}, "stripMarkers");
+  return value.__zodNestDto === true;
+}, "isMarkerParam");
 var stripMarkerFromSchema = /* @__PURE__ */ __name((schema) => {
   if (schema === null || typeof schema !== "object") {
     return;
@@ -1642,6 +1808,7 @@ var stripMarkerFromSchema = /* @__PURE__ */ __name((schema) => {
 }, "stripMarkerFromSchema");
 
 // src/document/apply-zod-nest.ts
+var OPENAPI_VERSION = "3.1.0";
 var applyZodNest = /* @__PURE__ */ __name((doc, opts) => {
   const registry = opts.registry ?? defaultRegistry;
   const collected = collectUsage(doc, opts.app);
@@ -1658,6 +1825,11 @@ var applyZodNest = /* @__PURE__ */ __name((doc, opts) => {
     collected: extended,
     collisions: registry.getCollisions()
   });
+  expandParamMarkers({
+    doc,
+    inputSchemas,
+    outputSchemas
+  });
   rewriteRefs2({
     doc,
     renames,
@@ -1668,6 +1840,7 @@ var applyZodNest = /* @__PURE__ */ __name((doc, opts) => {
     doc,
     collected: extended
   });
+  doc.openapi = OPENAPI_VERSION;
   return doc;
 }, "applyZodNest");