zod-nest 3.5.0 → 3.7.0

package/dist/index.js

@@ -624,6 +624,9 @@ var extractDescriptionFields = /* @__PURE__ */ chunkEV5I5HGT_js.__name((desc) =>
   const out = {
     description: desc.description
   };
+  if (desc.summary !== void 0) {
+    out.summary = desc.summary;
+  }
   if (desc.headers !== void 0) {
     out.headers = desc.headers;
   }
@@ -1100,35 +1103,45 @@ var HTTP_METHODS = [
 ];
 var ADDITIONAL_OPERATIONS_KEY = "additionalOperations";
 var isRecord = /* @__PURE__ */ chunkEV5I5HGT_js.__name((value) => value !== null && typeof value === "object", "isRecord");
-var operationsOfPathItem = /* @__PURE__ */ chunkEV5I5HGT_js.__name((pathItem) => {
-  const operations = [];
+var operationEntriesOfPathItem = /* @__PURE__ */ chunkEV5I5HGT_js.__name((pathItem) => {
+  const entries = [];
   for (const method of HTTP_METHODS) {
     const operation = pathItem[method];
     if (isRecord(operation)) {
-      operations.push(operation);
+      entries.push({
+        method,
+        operation
+      });
     }
   }
   const additional = pathItem[ADDITIONAL_OPERATIONS_KEY];
   if (isRecord(additional)) {
-    for (const operation of Object.values(additional)) {
+    for (const [method, operation] of Object.entries(additional)) {
       if (isRecord(operation)) {
-        operations.push(operation);
+        entries.push({
+          method,
+          operation
+        });
       }
     }
   }
-  return operations;
-}, "operationsOfPathItem");
+  return entries;
+}, "operationEntriesOfPathItem");
+var operationsOfPathItem = /* @__PURE__ */ chunkEV5I5HGT_js.__name((pathItem) => operationEntriesOfPathItem(pathItem).map((entry) => entry.operation), "operationsOfPathItem");
 var forEachOperation = /* @__PURE__ */ chunkEV5I5HGT_js.__name((doc, fn) => {
   const paths = doc.paths;
   if (!isRecord(paths)) {
     return;
   }
-  for (const pathItem of Object.values(paths)) {
+  for (const [path, pathItem] of Object.entries(paths)) {
     if (!isRecord(pathItem)) {
       continue;
     }
-    for (const operation of operationsOfPathItem(pathItem)) {
-      fn(operation);
+    for (const { method, operation } of operationEntriesOfPathItem(pathItem)) {
+      fn(operation, {
+        path,
+        method
+      });
     }
   }
 }, "forEachOperation");
@@ -1417,35 +1430,104 @@ var hintFor = /* @__PURE__ */ chunkEV5I5HGT_js.__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
+// src/document/querystring-param.ts
+var QUERYSTRING_MEDIA_TYPE = "application/x-www-form-urlencoded";
 var isPlainRecord3 = /* @__PURE__ */ chunkEV5I5HGT_js.__name((value) => value !== null && typeof value === "object" && !Array.isArray(value), "isPlainRecord");
+var buildQuerystringParam = /* @__PURE__ */ chunkEV5I5HGT_js.__name((params) => {
+  const { dtoId, body } = params;
+  const required = isPlainRecord3(body) && Array.isArray(body.required) && body.required.length > 0;
+  return {
+    name: dtoId,
+    in: "querystring",
+    required,
+    content: {
+      [QUERYSTRING_MEDIA_TYPE]: {
+        schema: {
+          $ref: `${chunkJ2MGUXBB_js.COMPONENTS_SCHEMAS_PREFIX}${dtoId}`
+        }
+      }
+    }
+  };
+}, "buildQuerystringParam");
+var hasQueryConflict = /* @__PURE__ */ chunkEV5I5HGT_js.__name((params) => {
+  const { parameters, pathItemParameters, candidateCount } = params;
+  if (candidateCount > 1) {
+    return true;
+  }
+  return containsQueryParam(parameters) || containsQueryParam(pathItemParameters);
+}, "hasQueryConflict");
+var conflictingQueryNames = /* @__PURE__ */ chunkEV5I5HGT_js.__name((parameters, pathItemParameters) => [
+  ...queryNamesOf(parameters),
+  ...queryNamesOf(pathItemParameters)
+], "conflictingQueryNames");
+var containsQueryParam = /* @__PURE__ */ chunkEV5I5HGT_js.__name((parameters) => Array.isArray(parameters) && parameters.some(isPlainQueryParam), "containsQueryParam");
+var queryNamesOf = /* @__PURE__ */ chunkEV5I5HGT_js.__name((parameters) => {
+  if (!Array.isArray(parameters)) {
+    return [];
+  }
+  const names = [];
+  for (const param of parameters) {
+    if (!isPlainQueryParam(param)) {
+      continue;
+    }
+    names.push(typeof param.name === "string" ? param.name : "<unnamed>");
+  }
+  return names;
+}, "queryNamesOf");
+var isPlainQueryParam = /* @__PURE__ */ chunkEV5I5HGT_js.__name((param) => isPlainRecord3(param) && param.in === "query" && param.__zodNestDto !== true, "isPlainQueryParam");
+
+// src/document/expand-param-markers.ts
+var isPlainRecord4 = /* @__PURE__ */ chunkEV5I5HGT_js.__name((value) => value !== null && typeof value === "object" && !Array.isArray(value), "isPlainRecord");
 var expandParamMarkers = /* @__PURE__ */ chunkEV5I5HGT_js.__name((params) => {
-  const { doc, inputSchemas, outputSchemas } = params;
-  const queryParamStyle = params.queryParamStyle ?? "expand";
+  const { doc, inputSchemas, outputSchemas, queryParamStyle } = params;
+  const emitThirtyTwo = params.emitThirtyTwo ?? false;
   const schemas = doc.components?.schemas;
   const componentIds = schemas !== null && typeof schemas === "object" ? new Set(Object.keys(schemas)) : /* @__PURE__ */ new Set();
+  if (queryParamStyle !== void 0 && emitThirtyTwo) {
+    warnDeprecatedQueryParamStyle();
+  }
+  const context = {
+    inputSchemas,
+    outputSchemas,
+    queryParamStyle,
+    emitThirtyTwo,
+    componentIds
+  };
   let expandedAny = false;
-  forEachOperation(doc, (op) => {
-    const parameters = op.parameters;
-    if (!Array.isArray(parameters)) {
-      return;
+  for (const [path, pathItem] of Object.entries(doc.paths ?? {})) {
+    if (!isPlainRecord4(pathItem)) {
+      continue;
     }
-    const next = expandParameterList(parameters, {
-      inputSchemas,
-      outputSchemas,
-      queryParamStyle,
-      componentIds
-    });
-    if (next !== parameters) {
-      op.parameters = next;
-      expandedAny = true;
+    for (const { method, operation } of operationEntriesOfPathItem(pathItem)) {
+      const parameters = operation.parameters;
+      if (!Array.isArray(parameters)) {
+        continue;
+      }
+      const next = expandParameterList(parameters, context, {
+        path,
+        method,
+        pathItemParameters: pathItem.parameters
+      });
+      if (next !== parameters) {
+        operation.parameters = next;
+        expandedAny = true;
+      }
     }
-  });
+  }
   if (expandedAny) {
     pruneOrphanObjectSchema(doc);
   }
 }, "expandParamMarkers");
-var expandParameterList = /* @__PURE__ */ chunkEV5I5HGT_js.__name((parameters, context) => {
+var expandParameterList = /* @__PURE__ */ chunkEV5I5HGT_js.__name((parameters, context, scope) => {
+  const candidateCount = countCollapseCandidates(parameters, context);
+  const collapseBlocked = context.emitThirtyTwo && candidateCount > 0 && hasQueryConflict({
+    parameters,
+    pathItemParameters: scope.pathItemParameters,
+    candidateCount
+  });
+  if (collapseBlocked) {
+    warnQuerystringDegraded(scope, parameters, candidateCount);
+  }
   let result;
   for (let i = 0; i < parameters.length; i++) {
     const param = parameters[i];
@@ -1459,21 +1541,51 @@ var expandParameterList = /* @__PURE__ */ chunkEV5I5HGT_js.__name((parameters, c
     }
     const map = marker.io === "output" ? context.outputSchemas : context.inputSchemas;
     const body = map.get(marker.dtoId);
-    result.push(...resolveMarker(marker, body, context));
+    result.push(...resolveMarker(marker, body, context, collapseBlocked));
   }
   return result ?? parameters;
 }, "expandParameterList");
-var resolveMarker = /* @__PURE__ */ chunkEV5I5HGT_js.__name((marker, body, context) => {
-  const useRef = marker.ref ?? context.queryParamStyle === "ref";
-  if (marker.in === "query" && useRef && context.componentIds.has(marker.dtoId)) {
+var wouldCollapse = /* @__PURE__ */ chunkEV5I5HGT_js.__name((marker, context) => marker.in === "query" && prefersCollapse(marker, context) && context.componentIds.has(marker.dtoId), "wouldCollapse");
+var prefersCollapse = /* @__PURE__ */ chunkEV5I5HGT_js.__name((marker, context) => {
+  if (marker.ref !== void 0) {
+    return marker.ref;
+  }
+  if (context.queryParamStyle !== void 0) {
+    return context.queryParamStyle === "ref";
+  }
+  return context.emitThirtyTwo;
+}, "prefersCollapse");
+var countCollapseCandidates = /* @__PURE__ */ chunkEV5I5HGT_js.__name((parameters, context) => {
+  let count = 0;
+  for (const param of parameters) {
+    const marker = readMarker2(param);
+    if (marker !== void 0 && wouldCollapse(marker, context)) {
+      count += 1;
+    }
+  }
+  return count;
+}, "countCollapseCandidates");
+var resolveMarker = /* @__PURE__ */ chunkEV5I5HGT_js.__name((marker, body, context, collapseBlocked) => {
+  if (marker.ref !== void 0 && context.emitThirtyTwo) {
+    warnDeprecatedRefOption(marker.dtoId);
+  }
+  if (collapseBlocked || !wouldCollapse(marker, context)) {
+    return expandOne(marker, body);
+  }
+  if (context.emitThirtyTwo) {
     return [
-      buildRefQueryParam(marker, body)
+      buildQuerystringParam({
+        dtoId: marker.dtoId,
+        body
+      })
     ];
   }
-  return expandOne(marker, body);
+  return [
+    buildRefQueryParam(marker, body)
+  ];
 }, "resolveMarker");
 var buildRefQueryParam = /* @__PURE__ */ chunkEV5I5HGT_js.__name((marker, body) => {
-  const required = isPlainRecord3(body) && Array.isArray(body.required) && body.required.length > 0;
+  const required = isPlainRecord4(body) && Array.isArray(body.required) && body.required.length > 0;
   return {
     name: marker.dtoId,
     in: "query",
@@ -1486,7 +1598,7 @@ var buildRefQueryParam = /* @__PURE__ */ chunkEV5I5HGT_js.__name((marker, body)
   };
 }, "buildRefQueryParam");
 var readMarker2 = /* @__PURE__ */ chunkEV5I5HGT_js.__name((value) => {
-  if (!isPlainRecord3(value)) {
+  if (!isPlainRecord4(value)) {
     return void 0;
   }
   if (value.__zodNestDto !== true) {
@@ -1507,7 +1619,7 @@ var readMarker2 = /* @__PURE__ */ chunkEV5I5HGT_js.__name((value) => {
   return value;
 }, "readMarker");
 var expandOne = /* @__PURE__ */ chunkEV5I5HGT_js.__name((marker, body) => {
-  if (!isPlainRecord3(body) || !isPlainRecord3(body.properties)) {
+  if (!isPlainRecord4(body) || !isPlainRecord4(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,
@@ -1518,7 +1630,7 @@ var expandOne = /* @__PURE__ */ chunkEV5I5HGT_js.__name((marker, body) => {
   const requiredSet = collectRequired(body.required);
   const out = [];
   for (const [propName, propSchemaRaw] of Object.entries(properties)) {
-    if (!isPlainRecord3(propSchemaRaw)) {
+    if (!isPlainRecord4(propSchemaRaw)) {
       continue;
     }
     out.push(buildParameter(marker, propName, propSchemaRaw, requiredSet.has(propName)));
@@ -1551,6 +1663,22 @@ var buildParameter = /* @__PURE__ */ chunkEV5I5HGT_js.__name((marker, name, sche
   };
 }, "buildParameter");
 var capitalize = /* @__PURE__ */ chunkEV5I5HGT_js.__name((value) => value.charAt(0).toUpperCase() + value.slice(1), "capitalize");
+var warnQuerystringDegraded = /* @__PURE__ */ chunkEV5I5HGT_js.__name((scope, parameters, candidateCount) => {
+  console.warn(`[zod-nest] Expanded the query DTO on \`${scope.method.toUpperCase()} ${scope.path}\` per-property instead of emitting \`in: 'querystring'\`: ${degradeReason(scope, parameters, candidateCount)} The expanded form is spec-valid, so the document still ships.`);
+}, "warnQuerystringDegraded");
+var degradeReason = /* @__PURE__ */ chunkEV5I5HGT_js.__name((scope, parameters, candidateCount) => {
+  if (candidateCount > 1) {
+    return `OpenAPI 3.2 allows at most one \`querystring\` parameter per operation, and this one has ${candidateCount} query DTOs.`;
+  }
+  const names = conflictingQueryNames(parameters, scope.pathItemParameters);
+  return `OpenAPI 3.2 forbids a \`querystring\` parameter alongside \`in: 'query'\` parameters (${names.map((name) => `\`${name}\``).join(", ")}).`;
+}, "degradeReason");
+var warnDeprecatedQueryParamStyle = /* @__PURE__ */ chunkEV5I5HGT_js.__name(() => {
+  console.warn("[zod-nest] `queryParamStyle` is deprecated and will be removed in the next major: OpenAPI 3.2 emits `in: 'querystring'` for named query DTOs by default, which is what this option approximated. Drop it to take the default.");
+}, "warnDeprecatedQueryParamStyle");
+var warnDeprecatedRefOption = /* @__PURE__ */ chunkEV5I5HGT_js.__name((dtoId) => {
+  console.warn(`[zod-nest] \`@ZodQuery({ ref })\` on \`${dtoId}\` is deprecated and will be removed in the next major: OpenAPI 3.2 emits \`in: 'querystring'\` for named query DTOs by default. Drop the option to take the default.`);
+}, "warnDeprecatedRefOption");
 var pruneOrphanObjectSchema = /* @__PURE__ */ chunkEV5I5HGT_js.__name((doc) => {
   const schemas = doc.components?.schemas;
   if (schemas === void 0 || !Object.prototype.hasOwnProperty.call(schemas, "Object")) {
@@ -1622,7 +1750,7 @@ var inlineAnonymousBodies = /* @__PURE__ */ chunkEV5I5HGT_js.__name(({ doc, regi
       `${anonId}${OUTPUT_SUFFIX}`
     ]) {
       const body = schemas[key];
-      if (isPlainRecord4(body)) {
+      if (isPlainRecord5(body)) {
         bodyByRef.set(`${chunkJ2MGUXBB_js.COMPONENTS_SCHEMAS_PREFIX}${key}`, body);
       }
     }
@@ -1648,7 +1776,7 @@ var refsWithin = /* @__PURE__ */ chunkEV5I5HGT_js.__name((schemas, bodyByRef) =>
   });
   return found;
 }, "refsWithin");
-var isPlainRecord4 = /* @__PURE__ */ chunkEV5I5HGT_js.__name((value) => value !== null && typeof value === "object" && !Array.isArray(value), "isPlainRecord");
+var isPlainRecord5 = /* @__PURE__ */ chunkEV5I5HGT_js.__name((value) => value !== null && typeof value === "object" && !Array.isArray(value), "isPlainRecord");
 var inlineRefs = /* @__PURE__ */ chunkEV5I5HGT_js.__name((node, bodyByRef) => {
   if (Array.isArray(node)) {
     for (const item of node) {
@@ -1656,7 +1784,7 @@ var inlineRefs = /* @__PURE__ */ chunkEV5I5HGT_js.__name((node, bodyByRef) => {
     }
     return;
   }
-  if (!isPlainRecord4(node)) {
+  if (!isPlainRecord5(node)) {
     return;
   }
   const ref = node.$ref;
@@ -1888,7 +2016,7 @@ var applyRefTitles = /* @__PURE__ */ chunkEV5I5HGT_js.__name((doc) => {
   }
   const titleById = /* @__PURE__ */ new Map();
   for (const [id, body] of Object.entries(schemas)) {
-    if (isPlainRecord5(body) && typeof body.title === "string" && body.title !== "") {
+    if (isPlainRecord6(body) && typeof body.title === "string" && body.title !== "") {
       titleById.set(id, body.title);
     }
   }
@@ -1898,7 +2026,7 @@ var applyRefTitles = /* @__PURE__ */ chunkEV5I5HGT_js.__name((doc) => {
   addRefTitles(doc.paths, titleById);
   addRefTitles(schemas, titleById);
 }, "applyRefTitles");
-var isPlainRecord5 = /* @__PURE__ */ chunkEV5I5HGT_js.__name((value) => value !== null && typeof value === "object" && !Array.isArray(value), "isPlainRecord");
+var isPlainRecord6 = /* @__PURE__ */ chunkEV5I5HGT_js.__name((value) => value !== null && typeof value === "object" && !Array.isArray(value), "isPlainRecord");
 var addRefTitles = /* @__PURE__ */ chunkEV5I5HGT_js.__name((node, titleById) => {
   if (Array.isArray(node)) {
     for (const item of node) {
@@ -1906,7 +2034,7 @@ var addRefTitles = /* @__PURE__ */ chunkEV5I5HGT_js.__name((node, titleById) =>
     }
     return;
   }
-  if (!isPlainRecord5(node)) {
+  if (!isPlainRecord6(node)) {
     return;
   }
   const ref = node.$ref;
@@ -1921,6 +2049,30 @@ var addRefTitles = /* @__PURE__ */ chunkEV5I5HGT_js.__name((node, titleById) =>
   }
 }, "addRefTitles");
 
+// src/document/response-summary.ts
+var isRecord4 = /* @__PURE__ */ chunkEV5I5HGT_js.__name((value) => value !== null && typeof value === "object", "isRecord");
+var applyResponseSummary = /* @__PURE__ */ chunkEV5I5HGT_js.__name((doc, opts) => {
+  if (opts.emit) {
+    return;
+  }
+  forEachOperation(doc, (operation, { path, method }) => {
+    const responses = operation.responses;
+    if (!isRecord4(responses)) {
+      return;
+    }
+    for (const [status, response] of Object.entries(responses)) {
+      if (!isRecord4(response) || response.summary === void 0) {
+        continue;
+      }
+      delete response.summary;
+      warnDropped(method, path, status);
+    }
+  });
+}, "applyResponseSummary");
+var warnDropped = /* @__PURE__ */ chunkEV5I5HGT_js.__name((method, path, status) => {
+  console.warn(`[zod-nest] Dropped \`summary\` from \`${method.toUpperCase()} ${path}\` response \`${status}\`: OpenAPI 3.1 has no Response Object \`summary\` field. Declare 3.2 via \`DocumentBuilder.setOpenAPIVersion('3.2.0')\` to emit it.`);
+}, "warnDropped");
+
 // src/document/rewrite-refs.ts
 var rewriteRefs = /* @__PURE__ */ chunkEV5I5HGT_js.__name((params) => {
   const { doc, renames, divergentOutputIds } = params;
@@ -2030,6 +2182,8 @@ var withForcedExposure = /* @__PURE__ */ chunkEV5I5HGT_js.__name((collected, reg
 }, "withForcedExposure");
 var applyZodNest = /* @__PURE__ */ chunkEV5I5HGT_js.__name((doc, opts = {}) => {
   const registry = opts.registry ?? chunkJ2MGUXBB_js.defaultRegistry;
+  const openApiVersion = resolveOpenApiVersion(doc);
+  const emitThirtyTwo = openApiVersion.startsWith("3.2.");
   const collected = collectUsage(doc, registry);
   const exposed = withForcedExposure(collected, registry);
   const { inputSchemas, outputSchemas } = bulkEmit({
@@ -2049,7 +2203,8 @@ var applyZodNest = /* @__PURE__ */ chunkEV5I5HGT_js.__name((doc, opts = {}) => {
     doc,
     inputSchemas,
     outputSchemas,
-    queryParamStyle: opts.queryParamStyle
+    queryParamStyle: opts.queryParamStyle,
+    emitThirtyTwo
   });
   rewriteRefs({
     doc,
@@ -2068,12 +2223,14 @@ var applyZodNest = /* @__PURE__ */ chunkEV5I5HGT_js.__name((doc, opts = {}) => {
     doc,
     collected: extended
   });
-  const openApiVersion = resolveOpenApiVersion(doc);
-  if (openApiVersion.startsWith("3.2.")) {
+  if (emitThirtyTwo) {
     relocateExtensionOperations(doc);
   }
   applyItemSchema(doc, {
-    emit: openApiVersion.startsWith("3.2.")
+    emit: emitThirtyTwo
+  });
+  applyResponseSummary(doc, {
+    emit: emitThirtyTwo
   });
   doc.openapi = openApiVersion;
   return doc;