zod-nest 1.1.1 → 1.3.0

package/dist/index.d.mts

@@ -38,6 +38,9 @@ interface ZodNestRegistry {
      * 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.
+     *
+     * Includes ids discovered transitively via `.meta({ id })` on descendants
+     * of explicitly-registered schemas.
      */
     ids(): readonly string[];
 }
@@ -540,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
@@ -552,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.
@@ -565,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

@@ -38,6 +38,9 @@ interface ZodNestRegistry {
      * 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.
+     *
+     * Includes ids discovered transitively via `.meta({ id })` on descendants
+     * of explicitly-registered schemas.
      */
     ids(): readonly string[];
 }
@@ -540,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
@@ -552,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.
@@ -565,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

@@ -345,20 +345,146 @@ var toOpenApi = /* @__PURE__ */ __name((schema, opts) => {
   }
   return result;
 }, "toOpenApi");
+var INNER_TYPE_WRAPPERS = /* @__PURE__ */ new Set([
+  "optional",
+  "nullable",
+  "default",
+  "prefault",
+  "catch",
+  "nonoptional",
+  "success",
+  "readonly",
+  "promise"
+]);
+var readId = /* @__PURE__ */ __name((schema) => {
+  const meta = zod.z.globalRegistry.get(schema);
+  if (meta === void 0) {
+    return void 0;
+  }
+  const id = meta.id;
+  return typeof id === "string" ? id : void 0;
+}, "readId");
+var collectChildren = /* @__PURE__ */ __name((schema) => {
+  const def = schema._zod.def;
+  if (def.type === "object") {
+    const out = [];
+    const shape = def.shape;
+    if (shape !== void 0) {
+      for (const value of Object.values(shape)) {
+        out.push(value);
+      }
+    }
+    if (def.catchall !== void 0) {
+      out.push(def.catchall);
+    }
+    return out;
+  }
+  if (def.type === "array") {
+    return [
+      def.element
+    ];
+  }
+  if (def.type === "union") {
+    return def.options.map((opt) => opt);
+  }
+  if (def.type === "intersection") {
+    return [
+      def.left,
+      def.right
+    ];
+  }
+  if (def.type === "tuple") {
+    const out = def.items.map((it) => it);
+    if (def.rest !== null) {
+      out.push(def.rest);
+    }
+    return out;
+  }
+  if (def.type === "record" || def.type === "map") {
+    return [
+      def.keyType,
+      def.valueType
+    ];
+  }
+  if (def.type === "set") {
+    return [
+      def.valueType
+    ];
+  }
+  if (def.type === "pipe") {
+    return [
+      def.in,
+      def.out
+    ];
+  }
+  if (def.type === "lazy") {
+    return [
+      def.getter()
+    ];
+  }
+  if (INNER_TYPE_WRAPPERS.has(def.type)) {
+    return [
+      def.innerType
+    ];
+  }
+  return [];
+}, "collectChildren");
+var discoverDependents = /* @__PURE__ */ __name((schema) => {
+  const visited = /* @__PURE__ */ new WeakSet();
+  const out = [];
+  const stack = [
+    schema
+  ];
+  while (stack.length > 0) {
+    const current = stack.pop();
+    if (visited.has(current)) {
+      continue;
+    }
+    visited.add(current);
+    for (const child of collectChildren(current)) {
+      if (visited.has(child)) {
+        continue;
+      }
+      const id = readId(child);
+      if (id !== void 0) {
+        out.push([
+          child,
+          id
+        ]);
+      }
+      stack.push(child);
+    }
+  }
+  return out;
+}, "discoverDependents");
+
+// src/schema/registry.ts
 var createRegistry = /* @__PURE__ */ __name(() => {
   const seen = /* @__PURE__ */ new Map();
+  const recordOnce = /* @__PURE__ */ __name((schema, id) => {
+    let set = seen.get(id);
+    if (set === void 0) {
+      set = /* @__PURE__ */ new Set();
+      seen.set(id, set);
+    }
+    if (set.has(schema)) {
+      return false;
+    }
+    set.add(schema);
+    return true;
+  }, "recordOnce");
   return {
     zodRegistry: zod.z.globalRegistry,
     register: /* @__PURE__ */ __name((schema, id) => {
       zod.z.globalRegistry.add(schema, {
         id
       });
-      let set = seen.get(id);
-      if (set === void 0) {
-        set = /* @__PURE__ */ new Set();
-        seen.set(id, set);
+      if (!recordOnce(schema, id)) {
+        return;
+      }
+      for (const [child, childId] of discoverDependents(schema)) {
+        recordOnce(child, childId);
       }
-      set.add(schema);
     }, "register"),
     hasCollision: /* @__PURE__ */ __name((id) => {
       const set = seen.get(id);
@@ -1147,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;
@@ -1300,6 +1437,164 @@ 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,
+  inputExposedIds: closeOverRefs(collected.inputExposedIds, inputSchemas),
+  outputExposedIds: closeOverRefs(collected.outputExposedIds, outputSchemas)
+}), "extendExposureViaRefs");
+var closeOverRefs = /* @__PURE__ */ __name((seed, bodies) => {
+  const out = new Set(seed);
+  const queue = [
+    ...seed
+  ];
+  while (queue.length > 0) {
+    const id = queue.shift();
+    const body = bodies.get(id);
+    if (body === void 0) {
+      continue;
+    }
+    walkRefs(body, (ref) => {
+      if (!ref.startsWith(COMPONENTS_SCHEMAS_PREFIX)) {
+        return void 0;
+      }
+      const target = ref.slice(COMPONENTS_SCHEMAS_PREFIX.length);
+      if (out.has(target)) {
+        return void 0;
+      }
+      out.add(target);
+      queue.push(target);
+      return void 0;
+    });
+  }
+  return out;
+}, "closeOverRefs");
+
 // src/document/constants.ts
 var OUTPUT_SUFFIX = "Output";
 
@@ -1457,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;
@@ -1483,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);
@@ -1491,13 +1817,19 @@ var applyZodNest = /* @__PURE__ */ __name((doc, opts) => {
     override: opts.override,
     strict: opts.strict
   });
+  const extended = extendExposureViaRefs(collected, inputSchemas, outputSchemas);
   const { divergentOutputIds, renames } = mergeSchemas({
     doc,
     inputSchemas,
     outputSchemas,
-    collected,
+    collected: extended,
     collisions: registry.getCollisions()
   });
+  expandParamMarkers({
+    doc,
+    inputSchemas,
+    outputSchemas
+  });
   rewriteRefs2({
     doc,
     renames,
@@ -1506,8 +1838,9 @@ var applyZodNest = /* @__PURE__ */ __name((doc, opts) => {
   stripMarkers(doc);
   assertNoDanglingRefs({
     doc,
-    collected
+    collected: extended
   });
+  doc.openapi = OPENAPI_VERSION;
   return doc;
 }, "applyZodNest");