@orpc/openapi 2.0.0-beta.4 → 2.0.0-beta.41

package/dist/index.mjs

@@ -1,393 +1,222 @@
-export { B as BracketNotationSerializer } from './shared/openapi.Bt87OzTt.mjs';
-import { createContractCaller, getEventIteratorSchemaDetails, ProcedureContract, resolveMetaPlugins } from '@orpc/contract';
-import { O as OpenAPISerializer, D as DEFAULT_OPENAPI_METHOD, g as getDynamicPathParams, a as DEFAULT_OPENAPI_INPUT_STRUCTURE, c as DEFAULT_OPENAPI_SUCCESS_DESCRIPTION, b as DEFAULT_OPENAPI_OUTPUT_STRUCTURE } from './shared/openapi.DmAa7YPO.mjs';
-export { d as OpenAPIJsonSerializer } from './shared/openapi.DmAa7YPO.mjs';
+export { B as BracketNotationSerializer } from './shared/openapi.B2G-HeFn.mjs';
+import { createContractClientFactory, getAsyncIteratorObjectSchemaDetails, ProcedureContract, resolveMetaPlugins } from '@orpc/contract';
+import { D as DEFAULT_OPENAPI_METHOD, a as DEFAULT_OPENAPI_INPUT_STRUCTURE, c as DEFAULT_OPENAPI_SUCCESS_DESCRIPTION, b as DEFAULT_OPENAPI_OUTPUT_STRUCTURE, i as isBodylessMethod, O as OpenAPISerializer, g as getDynamicPathParams } from './shared/openapi.Bu_PfTtX.mjs';
+export { d as OpenAPIJsonSerializer } from './shared/openapi.Bu_PfTtX.mjs';
 import { g as getOpenAPIMeta, o as openapi } from './shared/openapi.B9PQzqBn.mjs';
+import { downgradeSpecV32ToV31, downgradeSpecV31ToV30 } from '@openapi-spec/downgrader';
 import { COMMON_ERROR_STATUS_MAP } from '@orpc/client';
 export { COMMON_ERROR_STATUS_MAP } from '@orpc/client';
-import { DelegatingJsonSchemaConverter, StandardJsonSchemaConverter, combineJsonSchemasWithComposition, isUnconstrainedSchema, extractJsonObjectSchemaEntries, combineJsonObjectSchemaEntries, flattenJsonUnionSchema, isJsonPrimitiveSchema, matchArrayableJsonSchema, ensureJsonSchemaObject, isJsonFileSchema, mapJsonSchemaRefs, encodeJsonPointerSegment, decodeJsonPointerSegment } from '@orpc/json-schema';
-import { walkProcedureContractsAsync, DEFAULT_SUCCESS_STATUS, DEFAULT_ERROR_STATUS } from '@orpc/server';
-import { toArray, clone, value, pathToHttpPath, mergeHttpPath, stringifyJSON, findDeepMatches, isPlainObject, isDeepEqual, isTypescriptObject } from '@orpc/shared';
-import '@standardserver/core';
+import { encodeJsonPointerSegment, ensureJsonSchemaObject, mapJsonSchemaRefs, decodeJsonPointerSegment, isUnconstrainedSchema, combineJsonSchemasWithComposition, extractJsonObjectSchemaEntries, combineJsonObjectSchemaEntries, flattenJsonUnionSchema, isJsonPrimitiveSchema, matchArrayableJsonSchema, isJsonFileSchema, DelegatingJsonSchemaConverter, StandardJsonSchemaConverter, hoistRecursiveRefToDef } from '@orpc/json-schema';
+import { DEFAULT_SUCCESS_STATUS, DEFAULT_ERROR_STATUS, walkProcedureContractsAsync } from '@orpc/server';
+import { setOwn, getOwn, isDeepEqual, value, findDeepMatches, isPlainObject, stringifyJSON, toArray, clone, pathToHttpPath, mergeHttpPath, isTypescriptObject } from '@orpc/shared';
+import '@standard-server/core';
 
-function createContractJsonifiedCaller(link, options = {}) {
-  return createContractCaller(link, options);
+function createContractJsonifiedClientFactory(link, options = {}) {
+  return createContractClientFactory(link, options);
 }
 
-class OpenAPIGeneratorError extends TypeError {
-}
-class OpenAPIGenerator {
-  serializer;
-  converter;
-  constructor(options = {}) {
-    this.serializer = options.serializer ?? new OpenAPISerializer();
-    this.converter = new DelegatingJsonSchemaConverter([
-      ...toArray(options.converters),
-      new StandardJsonSchemaConverter()
-    ]);
-  }
-  async generate(router, options = {}) {
-    const doc = {
-      ...clone(options.base),
-      openapi: options.base?.openapi ?? "3.1.2",
-      info: options.base?.info ?? { title: "API Reference", version: "0.0.0" }
-    };
-    const errors = [];
-    await walkProcedureContractsAsync(router, async (contract, path) => {
-      if (value(options.filter, contract, path) === false) {
-        return;
-      }
-      try {
-        const def = contract["~orpc"];
-        const meta = getOpenAPIMeta(contract);
-        const method = (meta?.method ?? DEFAULT_OPENAPI_METHOD).toLowerCase();
-        const postPath = meta?.path ?? pathToHttpPath(path);
-        const httpPath = meta?.prefix ? mergeHttpPath(meta.prefix, postPath) : postPath;
-        const dynamicPathParams = getDynamicPathParams(httpPath);
-        const openApiPath = toOpenAPIPath(httpPath, dynamicPathParams);
-        let operationRef;
-        if (meta?.spec !== void 0 && typeof meta.spec !== "function") {
-          operationRef = meta.spec;
-        } else {
-          operationRef = {
-            operationId: meta?.operationId ?? path.join("."),
-            summary: meta?.summary,
-            description: meta?.description,
-            deprecated: meta?.deprecated,
-            tags: meta?.tags?.map((tag) => tag)
-          };
-          await this.request(doc, operationRef, def, meta, dynamicPathParams, options, path);
-          await this.successResponse(doc, operationRef, def, meta, options, path);
-          await this.errorResponse(doc, operationRef, def, meta, options);
-        }
-        if (typeof meta?.spec === "function") {
-          operationRef = meta.spec(operationRef);
-        }
-        doc.paths ??= {};
-        doc.paths[openApiPath] ??= {};
-        doc.paths[openApiPath][method] = operationRef;
-      } catch (e) {
-        if (!(e instanceof OpenAPIGeneratorError)) {
-          throw e;
-        }
-        errors.push(
-          `[OpenAPIGenerator] Error occurred while generating OpenAPI for procedure at path: ${path.join(".")}
-${e.message}`
-        );
+const DEFS_REF_PREFIX = "#/$defs/";
+const COMPONENTS_REF_PREFIX = "#/components/schemas/";
+class OpenAPIComponentRegistry {
+  constructor(doc, customComponentName) {
+    this.doc = doc;
+    this.customComponentName = customComponentName;
+  }
+  /**
+   * Registers `schema` as a component under `preferredName` (or an equivalent/postfixed name)
+   * and returns a `$ref` to it.
+   */
+  register(preferredName, schema) {
+    const { $defs, ...body } = schema;
+    let defName = preferredName;
+    if ($defs) {
+      for (let i = 2; Object.hasOwn($defs, defName); i++) {
+        defName = `${preferredName}${i}`;
       }
-    });
-    if (errors.length) {
-      throw new OpenAPIGeneratorError(
-        `Some error occurred during OpenAPI generation:
-
-${errors.join("\n\n")}`
-      );
     }
-    return this.serializer.serialize(doc, { asFormData: false, useFormDataForBlobFields: false });
-  }
-  async convertSchema(schema, direction) {
-    const [jsonSchema, optional] = await this.converter.convert(schema, direction);
-    return [strip$schemaField(jsonSchema), optional];
+    return this.hoistDefs({
+      $defs: { ...$defs, [defName]: body },
+      $ref: `${DEFS_REF_PREFIX}${encodeJsonPointerSegment(defName)}`
+    });
   }
-  async convertSchemas(schemas, direction) {
-    if (!schemas || schemas.length <= 1) {
-      return this.convertSchema(schemas?.[0], direction);
-    }
-    const results = await Promise.all(schemas.map((s) => this.convertSchema(s, direction)));
-    const allOfSchemas = [];
-    let optional = true;
-    for (const [jsonSchema, opt] of results) {
-      allOfSchemas.push(jsonSchema);
-      if (!opt) {
-        optional = false;
+  /**
+   * Moves a schema's root-level `$defs` into `doc.components.schemas` and rewrites
+   * its refs accordingly.
+   */
+  hoistDefs(schema, direction) {
+    if (typeof schema !== "object" || !schema.$defs) {
+      return schema;
+    }
+    const { $defs, ...rest } = schema;
+    const defs = /* @__PURE__ */ new Map();
+    for (const defName of Object.keys($defs)) {
+      const defSchema = $defs[defName];
+      if (defSchema !== void 0) {
+        defs.set(defName, ensureJsonSchemaObject(defSchema));
       }
     }
-    return [combineJsonSchemasWithComposition("allOf", allOfSchemas), optional];
-  }
-  async request(doc, ref, def, meta, dynamicPathParams, options, path) {
-    const method = meta?.method ?? DEFAULT_OPENAPI_METHOD;
-    const inputStructure = meta?.inputStructure ?? DEFAULT_OPENAPI_INPUT_STRUCTURE;
-    const inputSchemas = def.inputSchemas;
-    if (inputStructure === "compact") {
-      const eventIteratorDetails = getEventIteratorDetails(inputSchemas);
-      if (eventIteratorDetails) {
-        const [yieldSchemas, returnSchemas] = eventIteratorDetails;
-        const yieldResult = await this.convertSchemas(yieldSchemas, "input");
-        const returnResult = await this.convertSchemas(returnSchemas, "input");
-        ref.requestBody = {
-          required: true,
-          content: toEventIteratorContent(yieldResult, returnResult, doc, options)
-        };
-        return;
+    if (defs.size === 0) {
+      return schema;
+    }
+    this.doc.components ??= {};
+    this.doc.components.schemas ??= {};
+    const componentsSchemas = this.doc.components.schemas;
+    const renameMap = /* @__PURE__ */ new Map();
+    const pendingSchemas = [];
+    for (const [defName, cleanSchema] of defs) {
+      const [componentName, reuseExisting] = resolveComponentName(
+        componentsSchemas,
+        new Set(renameMap.values()),
+        defName,
+        this.customComponentName?.(defName, cleanSchema) ?? defName,
+        defs,
+        direction
+      );
+      renameMap.set(defName, componentName);
+      if (!reuseExisting) {
+        pendingSchemas.push({ cleanSchema, componentName });
       }
     }
-    const dynamicParams = dynamicPathParams?.map((v) => v.parameterName);
-    const [schema, optional] = await this.convertSchemas(inputSchemas, "input");
-    if (isUnconstrainedSchema(schema) && !dynamicParams?.length) {
-      return;
-    }
-    const objectSchemaEntries = extractJsonObjectSchemaEntries(schema);
-    if (!objectSchemaEntries) {
-      if (inputStructure === "detailed") {
-        throw new OpenAPIGeneratorError(
-          `Procedure at path "${path.join(".")}" has inputStructure "detailed" but its input schema is not an object.
-  Expected shape: { params?: Record<string, unknown>, query?: Record<string, unknown>, headers?: Record<string, unknown>, body?: unknown }`
-        );
-      }
-      if (method === "GET") {
-        throw new OpenAPIGeneratorError(
-          `Procedure at path "${path.join(".")}" uses method "GET" but its input schema is not an object.
-  GET procedures map all input fields to query parameters, so the schema must be an object.
-  Expected: Record<string, unknown>`
-        );
-      }
+    for (const { cleanSchema, componentName } of pendingSchemas) {
+      setOwn(componentsSchemas, componentName, rewriteComponentSchemaRefs(cleanSchema, renameMap));
     }
-    const paramsObjectSchemaEntries = inputStructure === "compact" ? objectSchemaEntries?.filter(([name]) => dynamicParams?.includes(name)) : extractJsonObjectSchemaEntries(objectSchemaEntries?.find(([name]) => name === "params")?.[1] ?? false);
-    const queryObjectSchemaEntries = inputStructure === "compact" ? method === "GET" ? objectSchemaEntries?.filter(([name]) => !dynamicParams?.includes(name)) : void 0 : extractJsonObjectSchemaEntries(objectSchemaEntries?.find(([name]) => name === "query")?.[1] ?? false);
-    const headersObjectSchemaEntries = inputStructure === "compact" ? void 0 : extractJsonObjectSchemaEntries(objectSchemaEntries?.find(([name]) => name === "headers")?.[1] ?? false);
-    const bodySchema = inputStructure === "compact" ? method === "GET" || method === "HEAD" ? void 0 : !dynamicParams?.length ? schema : objectSchemaEntries ? combineJsonObjectSchemaEntries(objectSchemaEntries?.filter(([name]) => !dynamicParams?.includes(name))) : void 0 : objectSchemaEntries?.find(([name]) => name === "body")?.[1];
-    if (dynamicParams?.length) {
-      if (!paramsObjectSchemaEntries) {
-        throw new OpenAPIGeneratorError(
-          `Procedure at path "${path.join(".")}" has dynamic path params (${dynamicParams.map((p) => p).join(", ")}) but its input schema is not an object.
-  Each dynamic param must appear as a required key in the schema.`
-        );
-      }
-      dynamicParams.forEach((name) => {
-        const entry = paramsObjectSchemaEntries.find(([n]) => n === name);
-        if (!entry) {
-          throw new OpenAPIGeneratorError(
-            `Procedure at path "${path.join(".")}" is missing dynamic param "${name}" in its input schema.
-  Route params: ${dynamicParams.map((p) => `{${p}}`).join(", ")}
-  Schema keys:  ${paramsObjectSchemaEntries.map(([n]) => n).join(", ") || "(none)"}`
-          );
-        }
-        if (entry[2]) {
-          throw new OpenAPIGeneratorError(
-            `Procedure at path "${path.join(".")}" has dynamic param "${name}" marked as optional in its input schema, but path params must always be required in OpenAPI.`
-          );
+    return rewriteComponentSchemaRefs(rest, renameMap);
+  }
+  toOpenAPISchema(schema, direction) {
+    return ensureJsonSchemaObject(this.hoistDefs(schema, direction));
+  }
+}
+function resolveComponentName(componentsSchemas, claimedNames, defName, preferredName, defs, direction) {
+  let mintName;
+  for (let i = 1; ; i++) {
+    const [componentName, mintable, tail] = componentNameCandidate(preferredName, direction, i);
+    const existingSchema = getOwn(componentsSchemas, componentName);
+    if (existingSchema === void 0) {
+      if (mintable && !claimedNames.has(componentName)) {
+        mintName ??= componentName;
+        if (tail) {
+          return [mintName, false];
         }
-        ref.parameters ??= [];
-        ref.parameters.push({
-          in: "path",
-          required: true,
-          name,
-          schema: toOpenAPISchema(entry[1], doc, options)
-        });
-      });
+      }
+      continue;
     }
-    if (queryObjectSchemaEntries) {
-      queryObjectSchemaEntries.forEach(([name, schema2, optional2]) => {
-        const style = meta?.queryStyles?.[name];
-        const parameter = {
-          in: "query",
-          name,
-          schema: toOpenAPISchema(schema2, doc, options),
-          allowEmptyValue: true,
-          allowReserved: true
-        };
-        if (!optional2) {
-          parameter.required = true;
-        }
-        if (style === "comma-delimited-array" || style === "comma-delimited-object") {
-          parameter.explode = false;
-        } else if (style === "pipe-delimited-array" || style === "pipe-delimited-object") {
-          parameter.style = "pipeDelimited";
-        } else if (style === "space-delimited-array" || style === "space-delimited-object") {
-          parameter.style = "spaceDelimited";
-        } else if (style === "json") {
-          parameter.content = {
-            "application/json": { schema: parameter.schema }
-          };
-          delete parameter.schema;
-        } else if (style === void 0) {
-          if (flattenJsonUnionSchema(schema2).some((s) => !isJsonPrimitiveSchema(s))) {
-            const arrayable = matchArrayableJsonSchema(schema2);
-            if (!arrayable || flattenJsonUnionSchema(arrayable[0]).some((s) => !isJsonPrimitiveSchema(s))) {
-              parameter.style = "deepObject";
-              parameter.explode = true;
-            }
-          }
-        } else ;
-        ref.parameters ??= [];
-        ref.parameters.push(parameter);
-      });
+    if (areSchemaRefsEquivalentForReuse(
+      DEFS_REF_PREFIX + encodeJsonPointerSegment(defName),
+      COMPONENTS_REF_PREFIX + encodeJsonPointerSegment(componentName),
+      { defs, componentsSchemas, candidateToExistingKeys: /* @__PURE__ */ new Map(), pairedExistingKeys: /* @__PURE__ */ new Set(), visited: /* @__PURE__ */ new WeakMap() }
+    )) {
+      return [componentName, true];
     }
-    if (headersObjectSchemaEntries) {
-      headersObjectSchemaEntries.forEach(([name, schema2, optional2]) => {
-        ref.parameters ??= [];
-        ref.parameters.push({
-          in: "header",
-          name,
-          required: optional2 ? void 0 : true,
-          schema: toOpenAPISchema(schema2, doc, options)
-        });
-      });
+  }
+}
+function componentNameCandidate(preferredName, direction, attempt) {
+  if (attempt === 1) {
+    return [preferredName, true, false];
+  }
+  if (direction !== void 0) {
+    if (attempt === 2) {
+      return [`${preferredName}${direction === "input" ? "Input" : "Output"}`, true, false];
     }
-    if (bodySchema !== void 0) {
-      const bodyOptional = inputStructure === "compact" ? !dynamicParams?.length ? optional : objectSchemaEntries?.filter(([name]) => !dynamicParams?.includes(name)).every(([, , optional2]) => optional2) : objectSchemaEntries?.find(([name]) => name === "body")?.[2];
-      ref.requestBody = {
-        required: bodyOptional ? void 0 : true,
-        content: toBodyContent(bodySchema, doc, options)
-      };
+    if (attempt === 3) {
+      return [`${preferredName}${direction === "input" ? "Output" : "Input"}`, false, false];
     }
+    return [`${preferredName}${attempt - 2}`, true, true];
   }
-  async successResponse(doc, ref, def, meta, options, path) {
-    const outputSchemas = def.outputSchemas;
-    const status = meta?.successStatus ?? DEFAULT_SUCCESS_STATUS;
-    const description = meta?.successDescription ?? DEFAULT_OPENAPI_SUCCESS_DESCRIPTION;
-    const outputStructure = meta?.outputStructure ?? DEFAULT_OPENAPI_OUTPUT_STRUCTURE;
-    if (outputStructure === "compact") {
-      const eventDetails = getEventIteratorDetails(outputSchemas);
-      if (eventDetails) {
-        const [yieldSchemas, returnSchemas] = eventDetails;
-        const yieldResult = await this.convertSchemas(yieldSchemas, "output");
-        const returnResult = await this.convertSchemas(returnSchemas, "output");
-        ref.responses ??= {};
-        ref.responses[status] = {
-          description,
-          content: toEventIteratorContent(yieldResult, returnResult, doc, options)
-        };
-        return;
-      }
+  return [`${preferredName}${attempt}`, true, true];
+}
+function definedKeysOf(object) {
+  return Object.keys(object).filter((key) => object[key] !== void 0).sort();
+}
+function areSchemasEquivalentForReuse(candidate, existing, ctx) {
+  if (candidate === existing) {
+    return true;
+  }
+  if (typeof candidate !== typeof existing) {
+    return false;
+  }
+  if (candidate === null || existing === null) {
+    return candidate === existing;
+  }
+  if (typeof candidate !== "object" || typeof existing !== "object") {
+    return isDeepEqual(candidate, existing);
+  }
+  const seenExisting = ctx.visited.get(candidate);
+  if (seenExisting?.has(existing)) {
+    return true;
+  }
+  if (seenExisting) {
+    seenExisting.add(existing);
+  } else {
+    ctx.visited.set(candidate, new WeakSet([existing]));
+  }
+  if (Array.isArray(candidate) || Array.isArray(existing)) {
+    if (!Array.isArray(candidate) || !Array.isArray(existing) || candidate.length !== existing.length) {
+      return false;
     }
-    const [schema] = await this.convertSchemas(outputSchemas, "output");
-    if (isUnconstrainedSchema(schema) || outputStructure === "compact") {
-      ref.responses ??= {};
-      ref.responses[status] = {
-        description,
-        content: toBodyContent(schema, doc, options)
-      };
-      return;
+    return candidate.every((item, index) => areSchemasEquivalentForReuse(item, existing[index], ctx));
+  }
+  const candidateObject = candidate;
+  const existingObject = existing;
+  const candidateKeys = definedKeysOf(candidateObject);
+  const existingKeys = definedKeysOf(existingObject);
+  if (!isDeepEqual(candidateKeys, existingKeys)) {
+    return false;
+  }
+  return candidateKeys.every((key) => {
+    const candidateValue = candidateObject[key];
+    const existingValue = existingObject[key];
+    if (key === "$ref" && typeof candidateValue === "string" && typeof existingValue === "string") {
+      return areSchemaRefsEquivalentForReuse(candidateValue, existingValue, ctx);
     }
-    const schemasByStatus = /* @__PURE__ */ new Map();
-    for (const item of flattenJsonUnionSchema(schema)) {
-      const objectSchemaEntries = extractJsonObjectSchemaEntries(item);
-      if (!objectSchemaEntries) {
-        throw new OpenAPIGeneratorError(
-          `Procedure at path "${path.join(".")}" has outputStructure "detailed" but its output schema is not an object.
-  Expected shape: { status: number (200-299), headers?: Record<string, unknown>, body?: unknown }`
-        );
-      }
-      const statusSchema = objectSchemaEntries?.find(([name]) => name === "status")?.[1];
-      if (statusSchema !== void 0 && (typeof statusSchema !== "object" || !Number.isInteger(statusSchema.const) || statusSchema.const < 200 || statusSchema.const >= 300)) {
-        throw new OpenAPIGeneratorError(
-          `Procedure at path "${path.join(".")}" has an invalid "status" field in its outputStructure "detailed" schema.
-  Expected: a const integer in the 200-299 range
-  Received: ${stringifyJSON(statusSchema)}`
-        );
-      }
-      const status2 = (statusSchema?.const || void 0) ?? meta?.successStatus ?? DEFAULT_SUCCESS_STATUS;
-      const description2 = statusSchema?.description;
-      const schemas = schemasByStatus.get(status2);
-      const headersSchema = objectSchemaEntries?.find(([name]) => name === "headers")?.[1];
-      const bodySchema = objectSchemaEntries?.find(([name]) => name === "body")?.[1];
-      if (schemas) {
-        schemas.push({ description: description2, headers: headersSchema, body: bodySchema });
-      } else {
-        schemasByStatus.set(status2, [{ description: description2, headers: headersSchema, body: bodySchema }]);
-      }
+    return areSchemasEquivalentForReuse(candidateValue, existingValue, ctx);
+  });
+}
+function parseRefName(ref, prefix) {
+  if (!ref.startsWith(prefix)) {
+    return void 0;
+  }
+  return ref.slice(prefix.length).split("/").map(decodeJsonPointerSegment).join("/");
+}
+function resolveNamedRef(ref, prefix, getNamed) {
+  const name = parseRefName(ref, prefix);
+  if (name === void 0) {
+    return void 0;
+  }
+  const schema = getNamed(name);
+  return schema === void 0 ? void 0 : { key: prefix + name, schema };
+}
+function areSchemaRefsEquivalentForReuse(candidateRef, existingRef, ctx) {
+  const getComponent = (name) => getOwn(ctx.componentsSchemas, name);
+  const candidate = resolveNamedRef(candidateRef, DEFS_REF_PREFIX, (name) => ctx.defs.get(name)) ?? resolveNamedRef(candidateRef, COMPONENTS_REF_PREFIX, getComponent);
+  const existing = resolveNamedRef(existingRef, COMPONENTS_REF_PREFIX, getComponent);
+  if (candidate === void 0 || existing === void 0) {
+    return !candidate && !existing && candidateRef === existingRef;
+  }
+  const pairedExisting = ctx.candidateToExistingKeys.get(candidate.key);
+  if (pairedExisting !== existing.key) {
+    if (pairedExisting !== void 0 || ctx.pairedExistingKeys.has(existing.key)) {
+      return false;
     }
-    for (const [status2, schemas] of schemasByStatus.entries()) {
-      const descriptions = schemas.map(({ description: description2 }) => description2).filter((d) => d !== void 0);
-      const responseObject = {
-        description: descriptions.length ? descriptions.join(", ") : description
-      };
-      const bodySchemas = schemas.map(({ body }) => body).filter((b) => b !== void 0);
-      if (bodySchemas.length) {
-        responseObject.content = toBodyContent(combineJsonSchemasWithComposition("anyOf", bodySchemas), doc, options);
-      }
-      const headerSchemas = schemas.map(({ headers }) => headers).filter((b) => b !== void 0);
-      if (headerSchemas.length) {
-        const entries = extractJsonObjectSchemaEntries(combineJsonSchemasWithComposition("anyOf", headerSchemas));
-        entries?.forEach(([name, schema2, optional]) => {
-          responseObject.headers ??= {};
-          responseObject.headers[name] = {
-            required: optional ? void 0 : true,
-            schema: toOpenAPISchema(schema2, doc, options)
-          };
-        });
-      }
-      ref.responses ??= {};
-      ref.responses[status2] = responseObject;
-    }
-  }
-  async errorResponse(doc, ref, def, meta, options) {
-    const errorStatusMap = options.errorStatusMap ?? COMMON_ERROR_STATUS_MAP;
-    const errorMap = def.errorMap;
-    const errorDefinitionsByStatus = /* @__PURE__ */ new Map();
-    for (const code in errorMap) {
-      const config = errorMap[code];
-      if (!config) {
-        continue;
-      }
-      const status = errorStatusMap[code] ?? DEFAULT_ERROR_STATUS;
-      const defaultMessage = config.message;
-      const [dataJsonSchema, dataOptional] = await this.convertSchema(config.data, "output");
-      const definitions = errorDefinitionsByStatus.get(status);
-      if (definitions) {
-        definitions.push({ code, dataJsonSchema, dataOptional, defaultMessage });
-      } else {
-        errorDefinitionsByStatus.set(status, [{ code, dataJsonSchema, dataOptional, defaultMessage }]);
-      }
+    ctx.candidateToExistingKeys.set(candidate.key, existing.key);
+    ctx.pairedExistingKeys.add(existing.key);
+  }
+  return areSchemasEquivalentForReuse(candidate.schema, existing.schema, ctx);
+}
+function rewriteComponentSchemaRefs(schema, renameMap) {
+  return mapJsonSchemaRefs(schema, (ref) => {
+    const refName = parseRefName(ref, DEFS_REF_PREFIX);
+    if (refName === void 0) {
+      return ref;
     }
-    if (errorDefinitionsByStatus.size) {
-      const undefinedErrorSchema = hoistDefs({
-        $defs: {
-          UndefinedError: {
-            type: "object",
-            properties: {
-              defined: { const: false },
-              inferable: { type: "boolean" },
-              code: { type: "string" },
-              status: { type: "number" },
-              message: { type: "string" },
-              data: {}
-            },
-            required: ["defined", "inferable", "code", "status", "message"]
-          }
-        },
-        $ref: "#/$defs/UndefinedError"
-      }, doc, options);
-      for (const [status, definitions] of errorDefinitionsByStatus.entries()) {
-        const descriptions = definitions.map(({ defaultMessage }) => defaultMessage).filter((m) => m !== void 0);
-        const customBodySchema = value(
-          options.customErrorResponseBodySchema,
-          definitions.map((def2) => ({ ...def2, dataJsonSchema: hoistDefs(def2.dataJsonSchema, doc, options) })),
-          status
-        );
-        const responseSchema = customBodySchema ?? combineJsonSchemasWithComposition("oneOf", [
-          ...definitions.map(({ code, dataJsonSchema, dataOptional, defaultMessage }) => {
-            return combineJsonObjectSchemaEntries([
-              ["defined", { const: true }, false],
-              ["inferable", { type: "boolean" }, false],
-              ["code", { const: code }, false],
-              ["status", { const: status }, false],
-              ["message", { type: "string", default: defaultMessage }, false],
-              ["data", dataJsonSchema, dataOptional]
-            ]);
-          }),
-          undefinedErrorSchema
-        ]);
-        ref.responses ??= {};
-        ref.responses[status] = {
-          description: descriptions.length ? descriptions.join(", ") : status.toString(),
-          content: {
-            "application/json": {
-              schema: toOpenAPISchema(responseSchema, doc, options)
-            }
-          }
-        };
-      }
+    const renamedName = renameMap.get(refName);
+    if (renamedName === void 0) {
+      return ref;
     }
-  }
+    return COMPONENTS_REF_PREFIX + encodeJsonPointerSegment(renamedName);
+  });
 }
-function toOpenAPISchema(schema, doc, options) {
-  return ensureJsonSchemaObject(hoistDefs(
-    schema,
-    doc,
-    options
-  ));
+
+class OpenAPIGeneratorError extends TypeError {
 }
 function toOpenAPIPath(path, dynamicPathParams) {
   if (!dynamicPathParams?.length) {
@@ -403,21 +232,336 @@ function toOpenAPIPath(path, dynamicPathParams) {
   normalized += path.slice(currentIndex);
   return normalized;
 }
-function strip$schemaField(schema) {
-  if (typeof schema !== "object") {
-    return schema;
+function buildRequest(ctx, operation, def, meta, dynamicPathParams) {
+  const method = meta?.method ?? DEFAULT_OPENAPI_METHOD;
+  const inputStructure = meta?.inputStructure ?? DEFAULT_OPENAPI_INPUT_STRUCTURE;
+  if (inputStructure === "compact") {
+    const iteratorDetails = getAsyncIteratorObjectDetails(def.inputSchemas);
+    if (iteratorDetails) {
+      operation.requestBody = {
+        required: true,
+        content: toAsyncIteratorObjectContent(
+          ctx,
+          "input",
+          ctx.convertSchemas(iteratorDetails[0], "input"),
+          ctx.convertSchemas(iteratorDetails[1], "input")
+        )
+      };
+      return;
+    }
   }
-  const { $schema, ...rest } = schema;
-  return rest;
+  const dynamicParams = dynamicPathParams?.map((v) => v.parameterName);
+  const [schema, optional] = ctx.convertSchemas(def.inputSchemas, "input");
+  if (isUnconstrainedSchema(schema) && !dynamicParams?.length) {
+    return;
+  }
+  const parts = inputStructure === "compact" ? extractCompactRequestParts(schema, optional, method, dynamicParams) : extractDetailedRequestParts(schema);
+  renderPathParameters(ctx, operation, dynamicParams, parts.paramsEntries, meta?.paramsStyles);
+  renderQueryParameters(ctx, operation, parts.queryEntries, meta?.queryStyles);
+  renderHeaderParameters(ctx, operation, parts.headersEntries);
+  if (parts.bodySchema !== void 0) {
+    operation.requestBody = {
+      required: parts.bodyOptional ? void 0 : true,
+      content: toBodyContent(ctx, "input", parts.bodySchema)
+    };
+  }
+}
+function extractCompactRequestParts(schema, optional, method, dynamicParams) {
+  const entries = extractJsonObjectSchemaEntries(schema);
+  if (!entries && isBodylessMethod(method)) {
+    throw new OpenAPIGeneratorError(
+      `method is ${method} but the input schema is not an object.
+  ${method} sends every input field as a query parameter, so the input must be an object schema.
+  Fix: make the input an object, or use a method with a request body (POST, PUT, PATCH, DELETE).`
+    );
+  }
+  const paramsEntries = entries?.filter(([name]) => dynamicParams?.includes(name));
+  const restEntries = entries?.filter(([name]) => !dynamicParams?.includes(name));
+  const hasBody = !isBodylessMethod(method);
+  const bodySchema = !hasBody ? void 0 : !dynamicParams?.length ? schema : restEntries ? combineJsonObjectSchemaEntries(restEntries) : void 0;
+  return {
+    paramsEntries,
+    queryEntries: isBodylessMethod(method) ? restEntries : void 0,
+    headersEntries: void 0,
+    bodySchema,
+    bodyOptional: !dynamicParams?.length ? optional : restEntries?.every(([, , optional2]) => optional2)
+  };
 }
-function getEventIteratorDetails(schemas) {
+function extractDetailedRequestParts(schema) {
+  const entries = extractJsonObjectSchemaEntries(schema);
+  if (!entries) {
+    throw new OpenAPIGeneratorError(
+      `inputStructure is "detailed" but the input schema is not an object.
+  Expected an object shaped like: { params?: object, query?: object, headers?: object, body?: unknown }`
+    );
+  }
+  const section = (name) => entries.find(([entryName]) => entryName === name);
+  return {
+    paramsEntries: extractJsonObjectSchemaEntries(section("params")?.[1] ?? false),
+    queryEntries: extractJsonObjectSchemaEntries(section("query")?.[1] ?? false),
+    headersEntries: extractJsonObjectSchemaEntries(section("headers")?.[1] ?? false),
+    bodySchema: section("body")?.[1],
+    bodyOptional: section("body")?.[2]
+  };
+}
+function renderPathParameters(ctx, operation, dynamicParams, paramsEntries, paramsStyles) {
+  if (!dynamicParams?.length) {
+    return;
+  }
+  if (!paramsEntries) {
+    throw new OpenAPIGeneratorError(
+      `the route declares path params (${dynamicParams.map((p) => `{${p}}`).join(", ")}) but there is no object schema to source them from.
+  compact mode:  the input schema must be an object containing each param.
+  detailed mode: the input's "params" section must be an object containing each param.`
+    );
+  }
+  for (const name of dynamicParams) {
+    const entry = paramsEntries.find(([entryName]) => entryName === name);
+    if (!entry) {
+      throw new OpenAPIGeneratorError(
+        `dynamic param "{${name}}" is missing from the input schema.
+  Route params: ${dynamicParams.map((p) => `{${p}}`).join(", ")}
+  Schema keys:  ${paramsEntries.map(([n]) => n).join(", ") || "(none)"}`
+      );
+    }
+    if (entry[2]) {
+      throw new OpenAPIGeneratorError(
+        `dynamic param "${name}" is optional in the input schema.
+  OpenAPI requires path params to be required. Make "${name}" required.`
+      );
+    }
+    const style = paramsStyles?.[name];
+    const parameter = {
+      in: "path",
+      required: true,
+      name,
+      schema: ctx.registry.toOpenAPISchema(entry[1], "input")
+    };
+    if (style === "comma-delimited-array" || style === "comma-delimited-object") {
+      parameter.style = "simple";
+      parameter.explode = false;
+    }
+    operation.parameters ??= [];
+    operation.parameters.push(parameter);
+  }
+}
+function renderQueryParameters(ctx, operation, queryEntries, queryStyles) {
+  for (const [name, schema, optional] of queryEntries ?? []) {
+    const style = queryStyles?.[name];
+    const parameter = {
+      in: "query",
+      name,
+      schema: ctx.registry.toOpenAPISchema(schema, "input"),
+      allowEmptyValue: true,
+      allowReserved: true
+    };
+    if (!optional) {
+      parameter.required = true;
+    }
+    if (style === "comma-delimited-array" || style === "comma-delimited-object") {
+      parameter.explode = false;
+    } else if (style === "pipe-delimited-array" || style === "pipe-delimited-object") {
+      parameter.style = "pipeDelimited";
+    } else if (style === "space-delimited-array" || style === "space-delimited-object") {
+      parameter.style = "spaceDelimited";
+    } else if (style === "json") {
+      parameter.content = {
+        "application/json": { schema: parameter.schema }
+      };
+      delete parameter.schema;
+    } else if (style === void 0) {
+      if (flattenJsonUnionSchema(schema).some((s) => !isJsonPrimitiveSchema(s))) {
+        const arrayable = matchArrayableJsonSchema(schema);
+        if (!arrayable || flattenJsonUnionSchema(arrayable[0]).some((s) => !isJsonPrimitiveSchema(s))) {
+          parameter.style = "deepObject";
+          parameter.explode = true;
+        }
+      }
+    } else ;
+    operation.parameters ??= [];
+    operation.parameters.push(parameter);
+  }
+}
+function renderHeaderParameters(ctx, operation, headersEntries) {
+  for (const [name, schema, optional] of headersEntries ?? []) {
+    operation.parameters ??= [];
+    operation.parameters.push({
+      in: "header",
+      name,
+      required: optional ? void 0 : true,
+      schema: ctx.registry.toOpenAPISchema(schema, "input")
+    });
+  }
+}
+function buildSuccessResponse(ctx, operation, def, meta) {
+  const status = meta?.successStatus ?? DEFAULT_SUCCESS_STATUS;
+  const description = meta?.successDescription ?? DEFAULT_OPENAPI_SUCCESS_DESCRIPTION;
+  const outputStructure = meta?.outputStructure ?? DEFAULT_OPENAPI_OUTPUT_STRUCTURE;
+  if (outputStructure === "compact") {
+    const iteratorDetails = getAsyncIteratorObjectDetails(def.outputSchemas);
+    if (iteratorDetails) {
+      operation.responses ??= {};
+      operation.responses[toResponseStatusKey(status)] = {
+        description,
+        content: toAsyncIteratorObjectContent(
+          ctx,
+          "output",
+          ctx.convertSchemas(iteratorDetails[0], "output"),
+          ctx.convertSchemas(iteratorDetails[1], "output")
+        )
+      };
+      return;
+    }
+  }
+  const [schema] = ctx.convertSchemas(def.outputSchemas, "output");
+  if (isUnconstrainedSchema(schema) || outputStructure === "compact") {
+    operation.responses ??= {};
+    operation.responses[toResponseStatusKey(status)] = {
+      description,
+      content: toBodyContent(ctx, "output", schema)
+    };
+    return;
+  }
+  for (const [responseStatus, parts] of extractDetailedResponseParts(schema, status)) {
+    const responseObject = {
+      description: parts.descriptions.length ? parts.descriptions.join(", ") : description
+    };
+    if (parts.bodies.length) {
+      responseObject.content = toBodyContent(ctx, "output", combineJsonSchemasWithComposition("anyOf", parts.bodies));
+    }
+    if (parts.headers.length) {
+      const entries = extractJsonObjectSchemaEntries(combineJsonSchemasWithComposition("anyOf", parts.headers));
+      entries?.forEach(([name, schema2, optional]) => {
+        responseObject.headers ??= {};
+        responseObject.headers[name] = {
+          required: optional ? void 0 : true,
+          schema: ctx.registry.toOpenAPISchema(schema2, "output")
+        };
+      });
+    }
+    operation.responses ??= {};
+    operation.responses[toResponseStatusKey(responseStatus)] = responseObject;
+  }
+}
+function toResponseStatusKey(status) {
+  return String(status);
+}
+function extractDetailedResponseParts(schema, defaultStatus) {
+  const partsByStatus = /* @__PURE__ */ new Map();
+  for (const item of flattenJsonUnionSchema(schema)) {
+    const entries = extractJsonObjectSchemaEntries(item);
+    if (!entries) {
+      throw new OpenAPIGeneratorError(
+        `outputStructure is "detailed" but the output schema (or one of its union members) is not an object.
+  Expected each member shaped like: { status?: number (< 400), headers?: object, body?: unknown }`
+      );
+    }
+    const statusSchema = entries.find(([name]) => name === "status")?.[1];
+    if (statusSchema !== void 0 && (typeof statusSchema !== "object" || !Number.isInteger(statusSchema.const) || statusSchema.const >= 400)) {
+      throw new OpenAPIGeneratorError(
+        `invalid "status" field in the detailed output schema.
+  Expected: a literal (const) integer below 400
+  Received: ${stringifyJSON(statusSchema)}`
+      );
+    }
+    const status = (statusSchema?.const || void 0) ?? defaultStatus;
+    let parts = partsByStatus.get(status);
+    if (!parts) {
+      parts = { descriptions: [], bodies: [], headers: [] };
+      partsByStatus.set(status, parts);
+    }
+    if (statusSchema?.description !== void 0) {
+      parts.descriptions.push(statusSchema.description);
+    }
+    const headersSchema = entries.find(([name]) => name === "headers")?.[1];
+    if (headersSchema !== void 0) {
+      parts.headers.push(headersSchema);
+    }
+    const bodySchema = entries.find(([name]) => name === "body")?.[1];
+    if (bodySchema !== void 0) {
+      parts.bodies.push(bodySchema);
+    }
+  }
+  return partsByStatus;
+}
+function buildErrorResponse(ctx, operation, def) {
+  const definitionsByStatus = /* @__PURE__ */ new Map();
+  for (const code of Object.keys(def.errorMap)) {
+    const config = def.errorMap[code];
+    if (!config) {
+      continue;
+    }
+    const status = ctx.errorStatusMap[code] ?? DEFAULT_ERROR_STATUS;
+    const [dataJsonSchema, dataOptional] = ctx.convertSchemas(config.data !== void 0 ? [config.data] : void 0, "output");
+    let definitions = definitionsByStatus.get(status);
+    if (!definitions) {
+      definitions = [];
+      definitionsByStatus.set(status, definitions);
+    }
+    definitions.push({ code, dataJsonSchema, dataOptional, defaultMessage: config.message });
+  }
+  if (!definitionsByStatus.size) {
+    return;
+  }
+  const undefinedErrorSchema = ctx.registry.register("UndefinedError", {
+    title: "UndefinedError",
+    type: "object",
+    properties: {
+      defined: { const: false },
+      code: { type: "string" },
+      message: { type: "string" },
+      data: {}
+    },
+    required: ["defined", "code", "message"]
+  });
+  for (const [status, definitions] of definitionsByStatus.entries()) {
+    const descriptions = definitions.map(({ defaultMessage }) => defaultMessage).filter((m) => m !== void 0);
+    const customBodySchema = value(
+      ctx.customErrorResponseBodySchema,
+      definitions.map((def2) => ({ ...def2, dataJsonSchema: ctx.registry.hoistDefs(def2.dataJsonSchema, "output") })),
+      status
+    );
+    const responseSchema = customBodySchema ?? combineJsonSchemasWithComposition("oneOf", [
+      ...definitions.map(({ code, dataJsonSchema, dataOptional }) => {
+        return ctx.registry.register(toErrorComponentName(code), {
+          title: code,
+          ...combineJsonObjectSchemaEntries([
+            ["defined", { const: true }, false],
+            ["code", { const: code }, false],
+            // avoid using the defaultMessage here to improve component reusability
+            ["message", { type: "string" }, false],
+            ["data", ctx.registry.hoistDefs(dataJsonSchema, "output"), dataOptional]
+          ])
+        });
+      }),
+      undefinedErrorSchema
+    ]);
+    operation.responses ??= {};
+    operation.responses[toResponseStatusKey(status)] = {
+      description: descriptions.length ? descriptions.join(", ") : status.toString(),
+      content: {
+        "application/json": {
+          schema: ctx.registry.toOpenAPISchema(responseSchema, "output")
+        }
+      }
+    };
+  }
+}
+function toErrorComponentName(code) {
+  const name = code.split(/[^a-z0-9]+/i).filter(Boolean).map((part) => {
+    const rest = part.slice(1);
+    return part.charAt(0).toUpperCase() + (rest === rest.toUpperCase() ? rest.toLowerCase() : rest);
+  }).join("");
+  return name || "Error";
+}
+function getAsyncIteratorObjectDetails(schemas) {
   if (!schemas || schemas.length === 0) {
     return void 0;
   }
   const yieldSchemas = [];
   const returnSchemas = [];
   for (const s of schemas) {
-    const details = getEventIteratorSchemaDetails(s);
+    const details = getAsyncIteratorObjectSchemaDetails(s);
     if (!details) {
       return void 0;
     }
@@ -426,9 +570,9 @@ function getEventIteratorDetails(schemas) {
       returnSchemas.push(details.returnSchema);
     }
   }
-  return yieldSchemas.length || returnSchemas.length ? [yieldSchemas, returnSchemas] : void 0;
+  return [yieldSchemas, returnSchemas];
 }
-function toEventIteratorContent([yieldSchema, yieldOptional], [returnSchema, returnOptional], doc, options) {
+function toAsyncIteratorObjectContent(ctx, direction, [yieldSchema, yieldOptional], [returnSchema, returnOptional]) {
   const schema = combineJsonSchemasWithComposition("oneOf", [
     combineJsonObjectSchemaEntries([
       ["event", { const: "message" }, false],
@@ -455,11 +599,11 @@ function toEventIteratorContent([yieldSchema, yieldOptional], [returnSchema, ret
   ]);
   return {
     "text/event-stream": {
-      schema: toOpenAPISchema(schema, doc, options)
+      schema: ctx.registry.toOpenAPISchema(schema, direction)
     }
   };
 }
-function toBodyContent(schema, doc, options) {
+function toBodyContent(ctx, direction, schema) {
   const fileSchemasByMediaType = /* @__PURE__ */ new Map();
   const rest = flattenJsonUnionSchema(schema).filter((s) => {
     if (!isJsonFileSchema(s)) {
@@ -485,416 +629,121 @@ function toBodyContent(schema, doc, options) {
     const fileSchemas = fileSchemasByMediaType.get(contentType);
     fileSchemasByMediaType.delete(contentType);
     content[contentType] = {
-      schema: toOpenAPISchema(combineJsonSchemasWithComposition("anyOf", [restSchema, ...toArray(fileSchemas)]), doc, options)
+      schema: ctx.registry.toOpenAPISchema(combineJsonSchemasWithComposition("anyOf", [restSchema, ...fileSchemas ?? []]), direction)
     };
   }
   for (const [contentType, schemas] of fileSchemasByMediaType.entries()) {
     content[contentType] = {
-      schema: toOpenAPISchema(combineJsonSchemasWithComposition("anyOf", schemas), doc, options)
+      schema: ctx.registry.toOpenAPISchema(combineJsonSchemasWithComposition("anyOf", schemas), direction)
     };
   }
   return content;
 }
-function hoistDefs(schema, doc, options) {
-  if (typeof schema !== "object") {
-    return schema;
-  }
-  if (!schema.$defs) {
-    return schema;
-  }
-  const { $defs, ...rest } = schema;
-  const localDefs = {};
-  const hoistedDefs = {};
-  for (const defName of Object.keys($defs)) {
-    const defSchema = $defs[defName];
-    if (defSchema === void 0) {
-      continue;
-    }
-    const normalized = normalizeHoistedDefSchema(defSchema);
-    if (value(options.shouldHoistDef, defName, normalized) !== false) {
-      hoistedDefs[defName] = normalized;
-    } else {
-      localDefs[defName] = normalized;
-    }
-  }
-  hoistReferencedLocalDefs(hoistedDefs, localDefs);
-  if (Object.keys(hoistedDefs).length === 0) {
-    return schema;
-  }
-  doc.components ??= {};
-  doc.components.schemas ??= {};
-  const componentsSchemas = doc.components.schemas;
-  const identityRenameMap = Object.fromEntries(
-    Object.keys(hoistedDefs).map((defName) => [defName, defName])
-  );
-  const renameMap = {};
-  const pendingSchemas = [];
-  for (const defName of Object.keys(hoistedDefs)) {
-    const cleanSchema = hoistedDefs[defName];
-    const existingSchema = componentsSchemas[defName];
-    const candidateSchemas = Object.fromEntries(
-      Object.keys(hoistedDefs).map((currentDefName) => [
-        currentDefName,
-        rewriteComponentSchemaRefs(
-          withReferencedLocalDefs(hoistedDefs[currentDefName], localDefs),
-          {
-            ...identityRenameMap,
-            ...renameMap
-          }
-        )
-      ])
-    );
-    const prelimSchema = candidateSchemas[defName];
-    if (existingSchema !== void 0) {
-      const reusableComponentName = findReusableComponentName(componentsSchemas, defName, prelimSchema, candidateSchemas);
-      if (reusableComponentName !== void 0) {
-        renameMap[defName] = reusableComponentName;
-        continue;
-      }
-      const componentName = findUniqueComponentName(componentsSchemas, defName);
-      renameMap[defName] = componentName;
-      pendingSchemas.push({ cleanSchema, componentName });
-    } else {
-      const reusableComponentName = findReusableComponentName(componentsSchemas, defName, prelimSchema, candidateSchemas);
-      if (reusableComponentName !== void 0) {
-        renameMap[defName] = reusableComponentName;
-        continue;
-      }
-      renameMap[defName] = defName;
-      pendingSchemas.push({ cleanSchema, componentName: defName });
-    }
-  }
-  for (const { cleanSchema, componentName } of pendingSchemas) {
-    componentsSchemas[componentName] = rewriteComponentSchemaRefs(
-      withReferencedLocalDefs(cleanSchema, localDefs),
-      renameMap
-    );
-  }
-  return rewriteComponentSchemaRefs(withReferencedLocalDefs(rest, localDefs), renameMap);
-}
-function normalizeHoistedDefSchema(schema) {
-  let cleanSchema = typeof schema === "boolean" ? schema ? {} : { not: {} } : { ...schema };
-  if (cleanSchema.additionalProperties === false) {
-    const { additionalProperties: _ignored, ...withoutAdditionalProperties } = cleanSchema;
-    cleanSchema = withoutAdditionalProperties;
-  }
-  return cleanSchema;
-}
-function hoistReferencedLocalDefs(hoistedDefs, localDefs) {
-  const queue = Object.values(hoistedDefs);
-  while (queue.length > 0) {
-    const current = queue.shift();
-    if (current === void 0) {
-      continue;
-    }
-    visitSchemaRefs(current, (refName) => {
-      const referenced = localDefs[refName];
-      if (referenced === void 0) {
-        return;
-      }
-      hoistedDefs[refName] = referenced;
-      delete localDefs[refName];
-      queue.push(referenced);
-    });
-  }
-}
-function withReferencedLocalDefs(schema, localDefs) {
-  const referencedLocalDefs = collectReferencedLocalDefNames(schema, localDefs);
-  if (referencedLocalDefs.length === 0) {
-    return schema;
-  }
-  const mergedDefs = {
-    ...schema.$defs
-  };
-  for (const defName of referencedLocalDefs) {
-    mergedDefs[defName] = localDefs[defName];
+
+class OpenAPIGenerator {
+  serializer;
+  converter;
+  constructor(options = {}) {
+    this.serializer = options.serializer ?? new OpenAPISerializer();
+    this.converter = new DelegatingJsonSchemaConverter([
+      ...toArray(options.converters),
+      new StandardJsonSchemaConverter()
+    ]);
   }
-  return {
-    ...schema,
-    $defs: mergedDefs
-  };
-}
-function collectReferencedLocalDefNames(schema, localDefs) {
-  if (Object.keys(localDefs).length === 0) {
-    return [];
-  }
-  const referenced = /* @__PURE__ */ new Set();
-  const queued = /* @__PURE__ */ new Set();
-  const queue = [schema];
-  while (queue.length > 0) {
-    const current = queue.shift();
-    if (current === void 0) {
-      continue;
-    }
-    visitSchemaRefs(current, (refName) => {
-      if (localDefs[refName] === void 0 || referenced.has(refName)) {
+  async generate(router, options = {}) {
+    const version = options.version ?? "3.2.0";
+    const doc = {
+      ...clone(options.base),
+      openapi: "3.2.0",
+      info: options.base?.info ?? { title: "API Reference", version: "0.0.0" }
+    };
+    const ctx = {
+      registry: new OpenAPIComponentRegistry(doc, options.customComponentName),
+      convertSchemas: (schemas, direction) => this.convertSchemas(schemas, direction),
+      errorStatusMap: options.errorStatusMap ?? COMMON_ERROR_STATUS_MAP,
+      customErrorResponseBodySchema: options.customErrorResponseBodySchema
+    };
+    const errors = [];
+    await walkProcedureContractsAsync(router, (contract, path) => {
+      if (value(options.filter, contract, path) === false) {
         return;
       }
-      referenced.add(refName);
-      if (!queued.has(refName)) {
-        queued.add(refName);
-        queue.push(localDefs[refName]);
+      try {
+        const def = contract["~orpc"];
+        const meta = getOpenAPIMeta(contract);
+        const method = (meta?.method ?? DEFAULT_OPENAPI_METHOD).toLowerCase();
+        if (method === "query" && !version.startsWith("3.2.")) {
+          throw new OpenAPIGeneratorError(
+            `QUERY operations require OpenAPI 3.2, but version "${version}" was requested.`
+          );
+        }
+        const postPath = meta?.path ?? pathToHttpPath(path);
+        const httpPath = meta?.prefix ? mergeHttpPath(meta.prefix, postPath) : postPath;
+        const dynamicPathParams = getDynamicPathParams(httpPath);
+        const openApiPath = toOpenAPIPath(httpPath, dynamicPathParams);
+        let operation;
+        if (meta?.spec !== void 0 && typeof meta.spec !== "function") {
+          operation = meta.spec;
+        } else {
+          operation = {
+            operationId: meta?.operationId ?? path.join("."),
+            summary: meta?.summary,
+            description: meta?.description,
+            deprecated: meta?.deprecated,
+            tags: meta?.tags?.map((tag) => tag)
+          };
+          buildRequest(ctx, operation, def, meta, dynamicPathParams);
+          buildSuccessResponse(ctx, operation, def, meta);
+          buildErrorResponse(ctx, operation, def);
+        }
+        if (typeof meta?.spec === "function") {
+          operation = meta.spec(operation);
+        }
+        doc.paths ??= {};
+        doc.paths[openApiPath] ??= {};
+        doc.paths[openApiPath][method] = operation;
+      } catch (e) {
+        if (!(e instanceof OpenAPIGeneratorError)) {
+          throw e;
+        }
+        errors.push(`Procedure at ${path.join(".") || "(root)"}: ${e.message}`);
       }
     });
-  }
-  return [...referenced];
-}
-function visitSchemaRefs(schema, onRef, seen = /* @__PURE__ */ new Set()) {
-  if (typeof schema !== "object" || schema === null) {
-    return;
-  }
-  if (seen.has(schema)) {
-    return;
-  }
-  seen.add(schema);
-  if (typeof schema.$ref === "string") {
-    const refName = parseLocalDefRefName(schema.$ref);
-    if (refName !== void 0) {
-      onRef(refName);
-    }
-  }
-  for (const keyword of ["allOf", "anyOf", "oneOf"]) {
-    if (Array.isArray(schema[keyword])) {
-      for (const item of schema[keyword]) {
-        visitSchemaRefs(item, onRef, seen);
-      }
-    }
-  }
-  if (schema.properties) {
-    for (const property of Object.values(schema.properties)) {
-      visitSchemaRefs(property, onRef, seen);
-    }
-  }
-  if (schema.items !== void 0) {
-    visitSchemaRefs(schema.items, onRef, seen);
-  }
-  if (typeof schema.additionalProperties === "object" && schema.additionalProperties !== null) {
-    visitSchemaRefs(schema.additionalProperties, onRef, seen);
-  }
-  if (schema.not !== void 0) {
-    visitSchemaRefs(schema.not, onRef, seen);
-  }
-  if (schema.if !== void 0) {
-    visitSchemaRefs(schema.if, onRef, seen);
-  }
-  if (schema.then !== void 0) {
-    visitSchemaRefs(schema.then, onRef, seen);
-  }
-  if (schema.else !== void 0) {
-    visitSchemaRefs(schema.else, onRef, seen);
-  }
-  if (Array.isArray(schema.prefixItems)) {
-    for (const item of schema.prefixItems) {
-      visitSchemaRefs(item, onRef, seen);
-    }
-  }
-  if (schema.$defs) {
-    for (const def of Object.values(schema.$defs)) {
-      if (def !== void 0) {
-        visitSchemaRefs(def, onRef, seen);
-      }
-    }
-  }
-}
-function findUniqueComponentName(componentsSchemas, baseName) {
-  const candidate = `${baseName}`;
-  if (componentsSchemas[candidate] === void 0)
-    return candidate;
-  let i = 2;
-  while (componentsSchemas[`${baseName}${i}`] !== void 0) {
-    i++;
-  }
-  return `${baseName}${i}`;
-}
-function findReusableComponentName(componentsSchemas, defName, schema, candidateSchemas) {
-  const exactMatch = componentsSchemas[defName];
-  if (exactMatch !== void 0 && areSchemasEquivalentForReuse(
-    schema,
-    exactMatch,
-    schema,
-    exactMatch,
-    candidateSchemas,
-    componentsSchemas,
-    /* @__PURE__ */ new Map([[defName, defName]]),
-    /* @__PURE__ */ new Map([[defName, defName]])
-  )) {
-    return defName;
-  }
-  for (const [componentName, componentSchema] of Object.entries(componentsSchemas)) {
-    if (componentName === defName) {
-      continue;
-    }
-    if (areSchemasEquivalentForReuse(
-      schema,
-      componentSchema,
-      schema,
-      componentSchema,
-      candidateSchemas,
-      componentsSchemas,
-      /* @__PURE__ */ new Map([[defName, componentName]]),
-      /* @__PURE__ */ new Map([[componentName, defName]])
-    )) {
-      return componentName;
-    }
-  }
-  return void 0;
-}
-function areSchemasEquivalentForReuse(candidate, existing, candidateRootSchema, existingRootSchema, candidateSchemas, existingSchemas, candidateToExistingComponentNames, existingToCandidateComponentNames, visited = /* @__PURE__ */ new WeakMap()) {
-  if (candidate === existing) {
-    return true;
-  }
-  if (typeof candidate !== typeof existing) {
-    return false;
-  }
-  if (candidate === null || existing === null) {
-    return candidate === existing;
-  }
-  if (typeof candidate !== "object" || typeof existing !== "object") {
-    return isDeepEqual(candidate, existing);
-  }
-  const seenExisting = visited.get(candidate);
-  if (seenExisting?.has(existing)) {
-    return true;
-  }
-  if (seenExisting) {
-    seenExisting.add(existing);
-  } else {
-    visited.set(candidate, new WeakSet([existing]));
-  }
-  if (Array.isArray(candidate) || Array.isArray(existing)) {
-    if (!Array.isArray(candidate) || !Array.isArray(existing) || candidate.length !== existing.length) {
-      return false;
-    }
-    return candidate.every((item, index) => areSchemasEquivalentForReuse(
-      item,
-      existing[index],
-      candidateRootSchema,
-      existingRootSchema,
-      candidateSchemas,
-      existingSchemas,
-      candidateToExistingComponentNames,
-      existingToCandidateComponentNames,
-      visited
-    ));
-  }
-  const candidateObject = candidate;
-  const existingObject = existing;
-  const candidateKeys = Object.keys(candidateObject).sort();
-  const existingKeys = Object.keys(existingObject).sort();
-  if (!isDeepEqual(candidateKeys, existingKeys)) {
-    return false;
-  }
-  return candidateKeys.every((key) => {
-    const candidateValue = candidateObject[key];
-    const existingValue = existingObject[key];
-    if (key === "$ref" && typeof candidateValue === "string" && typeof existingValue === "string") {
-      return areSchemaRefsEquivalentForReuse(
-        candidateValue,
-        existingValue,
-        candidateRootSchema,
-        existingRootSchema,
-        candidateSchemas,
-        existingSchemas,
-        candidateToExistingComponentNames,
-        existingToCandidateComponentNames,
-        visited
+    if (errors.length) {
+      throw new OpenAPIGeneratorError(
+        `[OpenAPIGenerator] Failed to generate the OpenAPI document (${errors.length} error${errors.length === 1 ? "" : "s"}):
+
+${errors.join("\n\n")}`
       );
     }
-    return areSchemasEquivalentForReuse(
-      candidateValue,
-      existingValue,
-      candidateRootSchema,
-      existingRootSchema,
-      candidateSchemas,
-      existingSchemas,
-      candidateToExistingComponentNames,
-      existingToCandidateComponentNames,
-      visited
-    );
-  });
-}
-function parseComponentRefName(ref) {
-  if (!ref.startsWith("#/components/schemas/")) {
-    return void 0;
+    const versioned = toVersionedOpenAPIDocument(doc, version);
+    return this.serializer.serialize(versioned, { asFormData: false, useFormDataForBlobFields: false });
   }
-  return ref.slice("#/components/schemas/".length).split("/").map(decodeJsonPointerSegment).join("/");
-}
-function resolveSchemaComparisonRef(ref, rootSchema, componentsSchemas) {
-  const localDefName = parseLocalDefRefName(ref);
-  if (localDefName !== void 0 && typeof rootSchema === "object" && rootSchema !== null) {
-    const localDef = rootSchema.$defs?.[localDefName];
-    if (localDef !== void 0) {
-      return {
-        schema: localDef,
-        rootSchema
-      };
-    }
+  convertSchema(schema, direction) {
+    const [jsonSchema, optional] = this.converter.convert(schema, direction);
+    return [hoistRecursiveRefToDef(strip$schemaField(jsonSchema)), optional];
   }
-  const componentName = parseComponentRefName(ref);
-  if (componentName !== void 0) {
-    const componentSchema = componentsSchemas[componentName];
-    if (componentSchema !== void 0) {
-      return {
-        schema: componentSchema,
-        rootSchema: componentSchema
-      };
+  convertSchemas(schemas, direction) {
+    if (!schemas || schemas.length <= 1) {
+      return this.convertSchema(schemas?.[0], direction);
     }
+    const results = schemas.map((s) => this.convertSchema(s, direction));
+    return [
+      combineJsonSchemasWithComposition("allOf", results.map(([jsonSchema]) => jsonSchema)),
+      results.every(([, optional]) => optional)
+    ];
   }
-  return void 0;
 }
-function areSchemaRefsEquivalentForReuse(candidateRef, existingRef, candidateRootSchema, existingRootSchema, candidateSchemas, existingSchemas, candidateToExistingComponentNames, existingToCandidateComponentNames, visited) {
-  const candidateComponentName = parseComponentRefName(candidateRef);
-  const existingComponentName = parseComponentRefName(existingRef);
-  if (candidateComponentName === void 0 !== (existingComponentName === void 0)) {
-    return false;
-  }
-  if (candidateComponentName !== void 0 && existingComponentName !== void 0) {
-    const mappedExisting = candidateToExistingComponentNames.get(candidateComponentName);
-    if (mappedExisting !== void 0 && mappedExisting !== existingComponentName) {
-      return false;
-    }
-    const mappedCandidate = existingToCandidateComponentNames.get(existingComponentName);
-    if (mappedCandidate !== void 0 && mappedCandidate !== candidateComponentName) {
-      return false;
-    }
-    candidateToExistingComponentNames.set(candidateComponentName, existingComponentName);
-    existingToCandidateComponentNames.set(existingComponentName, candidateComponentName);
-  }
-  const resolvedCandidate = resolveSchemaComparisonRef(candidateRef, candidateRootSchema, candidateSchemas);
-  const resolvedExisting = resolveSchemaComparisonRef(existingRef, existingRootSchema, existingSchemas);
-  if (resolvedCandidate === void 0 || resolvedExisting === void 0) {
-    return candidateRef === existingRef;
-  }
-  return areSchemasEquivalentForReuse(
-    resolvedCandidate.schema,
-    resolvedExisting.schema,
-    resolvedCandidate.rootSchema,
-    resolvedExisting.rootSchema,
-    candidateSchemas,
-    existingSchemas,
-    candidateToExistingComponentNames,
-    existingToCandidateComponentNames,
-    visited
-  );
+function toVersionedOpenAPIDocument(doc, version) {
+  const downgraded = version.startsWith("3.2.") ? doc : version.startsWith("3.1.") ? downgradeSpecV32ToV31(doc) : downgradeSpecV31ToV30(downgradeSpecV32ToV31(doc));
+  return { ...downgraded, openapi: version };
 }
-function parseLocalDefRefName(ref) {
-  if (!ref.startsWith("#/$defs/")) {
-    return void 0;
+function strip$schemaField(schema) {
+  if (typeof schema !== "object") {
+    return schema;
   }
-  return ref.slice("#/$defs/".length).split("/").map(decodeJsonPointerSegment).join("/");
-}
-function rewriteComponentSchemaRefs(schema, renameMap) {
-  return mapJsonSchemaRefs(schema, (ref) => {
-    const refName = parseLocalDefRefName(ref);
-    if (refName === void 0) {
-      return ref;
-    }
-    const renamedName = renameMap[refName];
-    if (renamedName === void 0) {
-      return ref;
-    }
-    return `#/components/schemas/${encodeJsonPointerSegment(renamedName)}`;
-  });
+  const { $schema, ...rest } = schema;
+  return rest;
 }
 
 function populateRouterContractOpenAPIPaths(router, options = {}) {
@@ -918,7 +767,7 @@ function populateRouterContractOpenAPIPaths(router, options = {}) {
     return router;
   }
   const populated = {};
-  for (const key in router) {
+  for (const key of Object.keys(router)) {
     populated[key] = populateRouterContractOpenAPIPaths(
       router[key],
       { ...options, path: [...path, key] }
@@ -927,4 +776,4 @@ function populateRouterContractOpenAPIPaths(router, options = {}) {
   return populated;
 }
 
-export { DEFAULT_OPENAPI_INPUT_STRUCTURE, DEFAULT_OPENAPI_METHOD, DEFAULT_OPENAPI_OUTPUT_STRUCTURE, DEFAULT_OPENAPI_SUCCESS_DESCRIPTION, OpenAPIGenerator, OpenAPIGeneratorError, OpenAPISerializer, createContractJsonifiedCaller, getDynamicPathParams, getOpenAPIMeta, openapi, populateRouterContractOpenAPIPaths };
+export { DEFAULT_OPENAPI_INPUT_STRUCTURE, DEFAULT_OPENAPI_METHOD, DEFAULT_OPENAPI_OUTPUT_STRUCTURE, DEFAULT_OPENAPI_SUCCESS_DESCRIPTION, OpenAPIGenerator, OpenAPIGeneratorError, OpenAPISerializer, createContractJsonifiedClientFactory, getDynamicPathParams, getOpenAPIMeta, isBodylessMethod, openapi, populateRouterContractOpenAPIPaths };