@depup/openapi-typescript 7.13.0-depup.0

package/src/transform/index.ts

@@ -0,0 +1,116 @@
+import { performance } from "node:perf_hooks";
+import ts, { type InterfaceDeclaration, type TypeLiteralNode } from "typescript";
+import { NEVER, STRING, stringToAST, tsModifiers, tsRecord } from "../lib/ts.js";
+import { createRef, debug } from "../lib/utils.js";
+import type { GlobalContext, OpenAPI3 } from "../types.js";
+import transformComponentsObject from "./components-object.js";
+import makeApiPathsEnum from "./paths-enum.js";
+import transformPathsObject from "./paths-object.js";
+import transformSchemaObject from "./schema-object.js";
+import transformWebhooksObject from "./webhooks-object.js";
+
+type SchemaTransforms = keyof Pick<OpenAPI3, "paths" | "webhooks" | "components" | "$defs">;
+
+const transformers: Record<SchemaTransforms, (node: any, options: GlobalContext) => ts.Node | ts.Node[]> = {
+  paths: transformPathsObject,
+  webhooks: transformWebhooksObject,
+  components: transformComponentsObject,
+  $defs: (node, options) => transformSchemaObject(node, { path: createRef(["$defs"]), ctx: options, schema: node }),
+};
+
+// Inline helper types for readOnly/writeOnly markers (when readWriteMarkers is enabled)
+const READ_WRITE_HELPER_TYPES = `
+export type $Read<T> = { readonly $read: T };
+export type $Write<T> = { readonly $write: T };
+export type Readable<T> = T extends $Write<any> ? never : T extends $Read<infer U> ? Readable<U> : T extends (infer E)[] ? Readable<E>[] : T extends object ? { [K in keyof T as NonNullable<T[K]> extends $Write<any> ? never : K]: Readable<T[K]> } : T;
+export type Writable<T> = T extends $Read<any> ? never : T extends $Write<infer U> ? Writable<U> : T extends (infer E)[] ? Writable<E>[] : T extends object ? { [K in keyof T as NonNullable<T[K]> extends $Read<any> ? never : K]: Writable<T[K]> } & { [K in keyof T as NonNullable<T[K]> extends $Read<any> ? K : never]?: never } : T;
+`;
+
+export default function transformSchema(schema: OpenAPI3, ctx: GlobalContext) {
+  const type: ts.Node[] = [];
+
+  // Add inline helper types for readOnly/writeOnly markers
+  if (ctx.readWriteMarkers) {
+    const helperNodes = stringToAST(READ_WRITE_HELPER_TYPES) as ts.Node[];
+    type.push(...helperNodes);
+  }
+
+  if (ctx.inject) {
+    const injectNodes = stringToAST(ctx.inject) as ts.Node[];
+    type.push(...injectNodes);
+  }
+
+  for (const root of Object.keys(transformers) as SchemaTransforms[]) {
+    const emptyObj = ts.factory.createTypeAliasDeclaration(
+      /* modifiers      */ tsModifiers({ export: true }),
+      /* name           */ root,
+      /* typeParameters */ undefined,
+      /* type           */ tsRecord(STRING, NEVER),
+    );
+
+    if (schema[root] && typeof schema[root] === "object") {
+      const rootT = performance.now();
+      const subTypes = ([] as ts.Node[]).concat(transformers[root](schema[root], ctx));
+      for (const subType of subTypes) {
+        if (ts.isTypeNode(subType)) {
+          if ((subType as ts.TypeLiteralNode).members?.length) {
+            type.push(
+              ctx.exportType
+                ? ts.factory.createTypeAliasDeclaration(
+                    /* modifiers      */ tsModifiers({ export: true }),
+                    /* name           */ root,
+                    /* typeParameters */ undefined,
+                    /* type           */ subType,
+                  )
+                : ts.factory.createInterfaceDeclaration(
+                    /* modifiers       */ tsModifiers({ export: true }),
+                    /* name            */ root,
+                    /* typeParameters  */ undefined,
+                    /* heritageClauses */ undefined,
+                    /* members         */ (subType as TypeLiteralNode).members,
+                  ),
+            );
+            debug(`${root} done`, "ts", performance.now() - rootT);
+          } else {
+            type.push(emptyObj);
+            debug(`${root} done (skipped)`, "ts", 0);
+          }
+        } else if (ts.isTypeAliasDeclaration(subType)) {
+          type.push(subType);
+        } else {
+          type.push(emptyObj);
+          debug(`${root} done (skipped)`, "ts", 0);
+        }
+      }
+    } else {
+      type.push(emptyObj);
+      debug(`${root} done (skipped)`, "ts", 0);
+    }
+  }
+
+  // inject
+  let hasOperations = false;
+  for (const injectedType of ctx.injectFooter) {
+    if (!hasOperations && (injectedType as InterfaceDeclaration)?.name?.escapedText === "operations") {
+      hasOperations = true;
+    }
+    type.push(injectedType);
+  }
+  if (!hasOperations) {
+    // if no operations created, inject empty operations type
+    type.push(
+      ts.factory.createTypeAliasDeclaration(
+        /* modifiers      */ tsModifiers({ export: true }),
+        /* name           */ "operations",
+        /* typeParameters */ undefined,
+        /* type           */ tsRecord(STRING, NEVER),
+      ),
+    );
+  }
+
+  if (ctx.makePathsEnum && schema.paths) {
+    type.push(makeApiPathsEnum(schema.paths));
+  }
+
+  return type;
+}

package/src/transform/media-type-object.ts

@@ -0,0 +1,18 @@
+import type ts from "typescript";
+import { UNKNOWN } from "../lib/ts.js";
+import type { MediaTypeObject, TransformNodeOptions } from "../types.js";
+import transformSchemaObject from "./schema-object.js";
+
+/**
+ * Transform MediaTypeObject nodes (4.8.14)
+ * @see https://spec.openapis.org/oas/v3.1.0#media-type-object
+ */
+export default function transformMediaTypeObject(
+  mediaTypeObject: MediaTypeObject,
+  options: TransformNodeOptions,
+): ts.TypeNode {
+  if (!mediaTypeObject.schema) {
+    return UNKNOWN;
+  }
+  return transformSchemaObject(mediaTypeObject.schema, options);
+}

package/src/transform/operation-object.ts

@@ -0,0 +1,104 @@
+import ts from "typescript";
+import { addJSDocComment, NEVER, oapiRef, QUESTION_TOKEN, tsModifiers, tsPropertyIndex } from "../lib/ts.js";
+import { createRef } from "../lib/utils.js";
+import type { OperationObject, RequestBodyObject, TransformNodeOptions } from "../types.js";
+import { transformParametersArray } from "./parameters-array.js";
+import transformRequestBodyObject from "./request-body-object.js";
+import transformResponsesObject from "./responses-object.js";
+
+/**
+ * Transform OperationObject nodes (4.8.10)
+ * @see https://spec.openapis.org/oas/v3.1.0#operation-object
+ */
+export default function transformOperationObject(
+  operationObject: OperationObject,
+  options: TransformNodeOptions,
+): ts.TypeElement[] {
+  const type: ts.TypeElement[] = [];
+
+  // parameters
+  type.push(...transformParametersArray(operationObject.parameters ?? [], options));
+
+  // requestBody
+  if (operationObject.requestBody) {
+    const requestBodyType =
+      "$ref" in operationObject.requestBody
+        ? oapiRef(operationObject.requestBody.$ref)
+        : transformRequestBodyObject(operationObject.requestBody, {
+            ...options,
+            path: createRef([options.path, "requestBody"]),
+          });
+    const required = !!(
+      "$ref" in operationObject.requestBody
+        ? options.ctx.resolve<RequestBodyObject>(operationObject.requestBody.$ref)
+        : operationObject.requestBody
+    )?.required;
+    const property = ts.factory.createPropertySignature(
+      /* modifiers     */ tsModifiers({ readonly: options.ctx.immutable }),
+      /* name          */ tsPropertyIndex("requestBody"),
+      /* questionToken */ required ? undefined : QUESTION_TOKEN,
+      /* type          */ requestBodyType,
+    );
+    addJSDocComment(operationObject.requestBody, property);
+    type.push(property);
+  } else {
+    type.push(
+      ts.factory.createPropertySignature(
+        /* modifiers     */ tsModifiers({ readonly: options.ctx.immutable }),
+        /* name          */ tsPropertyIndex("requestBody"),
+        /* questionToken */ QUESTION_TOKEN,
+        /* type          */ NEVER,
+      ),
+    );
+  }
+
+  // responses
+  type.push(
+    ts.factory.createPropertySignature(
+      /* modifiers     */ tsModifiers({ readonly: options.ctx.immutable }),
+      /* name          */ tsPropertyIndex("responses"),
+      /* questionToken */ undefined,
+      /* type          */ transformResponsesObject(operationObject.responses ?? {}, options),
+    ),
+  );
+
+  return type;
+}
+
+/** inject an operation at the top level */
+export function injectOperationObject(
+  operationId: string,
+  operationObject: OperationObject,
+  options: TransformNodeOptions,
+): void {
+  // find or create top-level operations interface
+  let operations = options.ctx.injectFooter.find(
+    (node) => ts.isInterfaceDeclaration(node) && (node as ts.InterfaceDeclaration).name.text === "operations",
+  ) as unknown as ts.InterfaceDeclaration;
+  if (!operations) {
+    operations = ts.factory.createInterfaceDeclaration(
+      /* modifiers       */ tsModifiers({
+        export: true,
+        // important: do NOT make this immutable
+      }),
+      /* name            */ ts.factory.createIdentifier("operations"),
+      /* typeParameters  */ undefined,
+      /* heritageClauses */ undefined,
+      /* members         */ [],
+    );
+    options.ctx.injectFooter.push(operations);
+  }
+
+  // inject operation object
+  const type = transformOperationObject(operationObject, options);
+  // @ts-expect-error this is OK to mutate
+  operations.members = ts.factory.createNodeArray([
+    ...operations.members,
+    ts.factory.createPropertySignature(
+      /* modifiers     */ tsModifiers({ readonly: options.ctx.immutable }),
+      /* name          */ tsPropertyIndex(operationId),
+      /* questionToken */ undefined,
+      /* type          */ ts.factory.createTypeLiteralNode(type),
+    ),
+  ]);
+}

package/src/transform/parameter-object.ts

@@ -0,0 +1,15 @@
+import type ts from "typescript";
+import { STRING } from "../lib/ts.js";
+import type { ParameterObject, TransformNodeOptions } from "../types.js";
+import transformSchemaObject from "./schema-object.js";
+
+/**
+ * Transform ParameterObject nodes (4.8.12)
+ * @see https://spec.openapis.org/oas/v3.1.0#parameter-object
+ */
+export default function transformParameterObject(
+  parameterObject: ParameterObject,
+  options: TransformNodeOptions,
+): ts.TypeNode {
+  return parameterObject.schema ? transformSchemaObject(parameterObject.schema, options) : STRING; // assume a parameter is a string by default rather than "unknown"
+}

package/src/transform/parameters-array.ts

@@ -0,0 +1,129 @@
+import ts from "typescript";
+import { addJSDocComment, NEVER, oapiRef, QUESTION_TOKEN, tsModifiers, tsPropertyIndex } from "../lib/ts.js";
+import { createRef } from "../lib/utils.js";
+import type { ParameterObject, ReferenceObject, TransformNodeOptions } from "../types.js";
+import transformParameterObject from "./parameter-object.js";
+
+// Regex to match path parameters in URL
+const PATH_PARAM_RE = /\{([^}]+)\}/g;
+
+/**
+ * Create a synthetic path parameter object from a parameter name
+ */
+function createPathParameter(paramName: string): ParameterObject {
+  return {
+    name: paramName,
+    in: "path",
+    required: true,
+    schema: { type: "string" },
+  };
+}
+
+/**
+ * Extract path parameters from a URL
+ */
+function extractPathParamsFromUrl(path: string): ParameterObject[] {
+  const params: ParameterObject[] = [];
+  const matches = path.match(PATH_PARAM_RE);
+  if (matches) {
+    for (const match of matches) {
+      const paramName = match.slice(1, -1);
+      params.push(createPathParameter(paramName));
+    }
+  }
+  return params;
+}
+
+/**
+ * Synthetic type. Array of (ParameterObject | ReferenceObject)s found in OperationObject and PathItemObject.
+ */
+export function transformParametersArray(
+  parametersArray: (ParameterObject | ReferenceObject)[],
+  options: TransformNodeOptions,
+): ts.TypeElement[] {
+  const type: ts.TypeElement[] = [];
+
+  // Create a working copy of parameters array
+  const workingParameters = [...parametersArray];
+
+  // Generate path parameters if enabled
+  if (options.ctx.generatePathParams && options.path) {
+    const pathString = Array.isArray(options.path) ? options.path[0] : options.path;
+    if (typeof pathString === "string") {
+      const pathParams = extractPathParamsFromUrl(pathString);
+      // Only add path parameters that aren't already defined
+      for (const param of pathParams) {
+        const exists = workingParameters.some((p) => {
+          const resolved = "$ref" in p ? options.ctx.resolve<ParameterObject>(p.$ref) : p;
+          return resolved?.in === "path" && resolved?.name === param.name;
+        });
+        if (!exists) {
+          workingParameters.push(param);
+        }
+      }
+    }
+  }
+
+  // parameters
+  const paramType: ts.TypeElement[] = [];
+  for (const paramIn of ["query", "header", "path", "cookie"] as ParameterObject["in"][]) {
+    const paramLocType: ts.TypeElement[] = [];
+    let operationParameters = workingParameters.map((param) => ({
+      original: param,
+      resolved: "$ref" in param ? options.ctx.resolve<ParameterObject>(param.$ref) : param,
+    }));
+
+    // this is the only array type in the spec, so we have to one-off sort here
+    if (options.ctx.alphabetize) {
+      operationParameters.sort((a, b) => (a.resolved?.name ?? "").localeCompare(b.resolved?.name ?? ""));
+    }
+    if (options.ctx.excludeDeprecated) {
+      operationParameters = operationParameters.filter(
+        ({ resolved }) => !resolved?.deprecated && !resolved?.schema?.deprecated,
+      );
+    }
+    for (const { original, resolved } of operationParameters) {
+      if (resolved?.in !== paramIn) {
+        continue;
+      }
+      let optional: ts.QuestionToken | undefined;
+      if (paramIn !== "path" && !(resolved as ParameterObject).required) {
+        optional = QUESTION_TOKEN;
+      }
+      const subType =
+        "$ref" in original
+          ? oapiRef(original.$ref, resolved)
+          : transformParameterObject(resolved as ParameterObject, {
+              ...options,
+              path: createRef([options.path, "parameters", resolved.in, resolved.name]),
+            });
+      const property = ts.factory.createPropertySignature(
+        /* modifiers     */ tsModifiers({ readonly: options.ctx.immutable }),
+        /* name          */ tsPropertyIndex(resolved?.name),
+        /* questionToken */ optional,
+        /* type          */ subType,
+      );
+      addJSDocComment(resolved, property);
+      paramLocType.push(property);
+    }
+    const allOptional = paramLocType.every((node) => !!node.questionToken);
+    paramType.push(
+      ts.factory.createPropertySignature(
+        /* modifiers     */ tsModifiers({ readonly: options.ctx.immutable }),
+        /* name          */ tsPropertyIndex(paramIn),
+        /* questionToken */ allOptional || !paramLocType.length ? QUESTION_TOKEN : undefined,
+        /* type          */ paramLocType.length ? ts.factory.createTypeLiteralNode(paramLocType) : NEVER,
+      ),
+    );
+  }
+  type.push(
+    ts.factory.createPropertySignature(
+      /* modifiers     */ tsModifiers({ readonly: options.ctx.immutable }),
+      /* name          */ tsPropertyIndex("parameters"),
+      /* questionToken */ !paramType.length ? QUESTION_TOKEN : undefined,
+      /* type          */ paramType.length ? ts.factory.createTypeLiteralNode(paramType) : NEVER,
+    ),
+  );
+
+  return type;
+}

package/src/transform/path-item-object.ts

@@ -0,0 +1,102 @@
+import ts from "typescript";
+import { addJSDocComment, NEVER, oapiRef, QUESTION_TOKEN, tsModifiers, tsPropertyIndex } from "../lib/ts.js";
+import { createRef } from "../lib/utils.js";
+import type {
+  OperationObject,
+  ParameterObject,
+  PathItemObject,
+  ReferenceObject,
+  TransformNodeOptions,
+} from "../types.js";
+import transformOperationObject, { injectOperationObject } from "./operation-object.js";
+import { transformParametersArray } from "./parameters-array.js";
+
+export type Method = "get" | "put" | "post" | "delete" | "options" | "head" | "patch" | "trace";
+
+/**
+ * Transform PathItem nodes (4.8.9)
+ * @see https://spec.openapis.org/oas/v3.1.0#path-item-object
+ */
+export default function transformPathItemObject(pathItem: PathItemObject, options: TransformNodeOptions): ts.TypeNode {
+  const type: ts.TypeElement[] = [];
+
+  // parameters
+  type.push(
+    ...transformParametersArray(pathItem.parameters ?? [], {
+      ...options,
+      path: createRef([options.path, "parameters"]),
+    }),
+  );
+
+  // methods
+  for (const method of ["get", "put", "post", "delete", "options", "head", "patch", "trace"] as Method[]) {
+    const operationObject = pathItem[method];
+    if (
+      !operationObject ||
+      (options.ctx.excludeDeprecated &&
+        ("$ref" in operationObject ? options.ctx.resolve<OperationObject>(operationObject.$ref) : operationObject)
+          ?.deprecated)
+    ) {
+      type.push(
+        ts.factory.createPropertySignature(
+          /* modifiers     */ tsModifiers({ readonly: options.ctx.immutable }),
+          /* name          */ tsPropertyIndex(method),
+          /* questionToken */ QUESTION_TOKEN,
+          /* type          */ NEVER,
+        ),
+      );
+      continue;
+    }
+
+    // fold top-level PathItem parameters into method-level, with the latter overriding the former
+    const keyedParameters: Record<string, ParameterObject | ReferenceObject> = {};
+    if (!("$ref" in operationObject)) {
+      // important: OperationObject parameters come last, and will override any conflicts with PathItem parameters
+      for (const parameter of [...(pathItem.parameters ?? []), ...(operationObject.parameters ?? [])]) {
+        // fix: #1798, use unique key
+        const name =
+          "$ref" in parameter
+            ? `${options.ctx.resolve<ParameterObject>(parameter.$ref)?.in}-${options.ctx.resolve<ParameterObject>(parameter.$ref)?.name}`
+            : `${parameter.in}-${parameter.name}`;
+        if (name) {
+          keyedParameters[name] = parameter;
+        }
+      }
+    }
+
+    let operationType: ts.TypeNode;
+    if ("$ref" in operationObject) {
+      operationType = oapiRef(operationObject.$ref);
+    }
+    // if operationId exists, move into an `operations` export and pass the reference in here
+    else if (operationObject.operationId) {
+      // workaround for issue caused by redocly ref parsing: https://github.com/openapi-ts/openapi-typescript/issues/1542
+      const operationId = operationObject.operationId.replace(HASH_RE, "/");
+      operationType = oapiRef(createRef(["operations", operationId]));
+      injectOperationObject(
+        operationId,
+        { ...operationObject, parameters: Object.values(keyedParameters) },
+        { ...options, path: createRef([options.path, method]) },
+      );
+    } else {
+      operationType = ts.factory.createTypeLiteralNode(
+        transformOperationObject(
+          { ...operationObject, parameters: Object.values(keyedParameters) },
+          { ...options, path: createRef([options.path, method]) },
+        ),
+      );
+    }
+    const property = ts.factory.createPropertySignature(
+      /* modifiers     */ tsModifiers({ readonly: options.ctx.immutable }),
+      /* name          */ tsPropertyIndex(method),
+      /* questionToken */ undefined,
+      /* type          */ operationType,
+    );
+    addJSDocComment(operationObject, property);
+    type.push(property);
+  }
+
+  return ts.factory.createTypeLiteralNode(type);
+}
+
+const HASH_RE = /#/g;

package/src/transform/paths-enum.ts

@@ -0,0 +1,43 @@
+import type ts from "typescript";
+import { tsEnum } from "../lib/ts.js";
+import { getEntries } from "../lib/utils.js";
+import type { PathsObject } from "../types.js";
+
+export default function makeApiPathsEnum(pathsObject: PathsObject): ts.EnumDeclaration {
+  const enumKeys = [];
+  const enumMetaData = [];
+
+  for (const [url, pathItemObject] of getEntries(pathsObject)) {
+    for (const [method, operation] of Object.entries(pathItemObject)) {
+      if (!["get", "put", "post", "delete", "options", "head", "patch", "trace"].includes(method)) {
+        continue;
+      }
+
+      // Generate a name from the operation ID
+      let pathName: string;
+      if (operation.operationId) {
+        pathName = operation.operationId;
+      } else {
+        // If the operation ID is not present, construct a name from the method and path
+        pathName = (method + url)
+          .split("/")
+          .map((part) => {
+            const capitalised = part.charAt(0).toUpperCase() + part.slice(1);
+
+            // Remove any characters not allowed as enum keys, and attempt to remove
+            //  named parameters.
+            return capitalised.replace(/{.*}|:.*|[^a-zA-Z\d_]+/, "");
+          })
+          .join("");
+      }
+      enumKeys.push(url);
+      enumMetaData.push({
+        name: pathName,
+      });
+    }
+  }
+
+  return tsEnum("ApiPaths", enumKeys, enumMetaData, {
+    export: true,
+  });
+}

package/src/transform/paths-object.ts

@@ -0,0 +1,134 @@
+import { performance } from "node:perf_hooks";
+import ts from "typescript";
+import { addJSDocComment, oapiRef, stringToAST, tsModifiers, tsPropertyIndex } from "../lib/ts.js";
+import { createRef, debug, getEntries } from "../lib/utils.js";
+import type {
+  GlobalContext,
+  OperationObject,
+  ParameterObject,
+  PathItemObject,
+  PathsObject,
+  ReferenceObject,
+} from "../types.js";
+import transformPathItemObject, { type Method } from "./path-item-object.js";
+
+const PATH_PARAM_RE = /\{[^}]+\}/g;
+
+/**
+ * Transform the PathsObject node (4.8.8)
+ * @see https://spec.openapis.org/oas/v3.1.0#operation-object
+ */
+export default function transformPathsObject(pathsObject: PathsObject, ctx: GlobalContext): ts.TypeNode {
+  const type: ts.TypeElement[] = [];
+  for (const [url, pathItemObject] of getEntries(pathsObject, ctx)) {
+    if (!pathItemObject || typeof pathItemObject !== "object") {
+      continue;
+    }
+
+    const pathT = performance.now();
+
+    // handle $ref
+    if ("$ref" in pathItemObject) {
+      const property = ts.factory.createPropertySignature(
+        /* modifiers     */ tsModifiers({ readonly: ctx.immutable }),
+        /* name          */ tsPropertyIndex(url),
+        /* questionToken */ undefined,
+        /* type          */ oapiRef(pathItemObject.$ref),
+      );
+      addJSDocComment(pathItemObject, property);
+      type.push(property);
+    } else {
+      const pathItemType = transformPathItemObject(pathItemObject, {
+        path: createRef(["paths", url]),
+        ctx,
+      });
+
+      // pathParamsAsTypes
+      if (ctx.pathParamsAsTypes && url.includes("{")) {
+        const pathParams = extractPathParams(pathItemObject, ctx);
+        const matches = url.match(PATH_PARAM_RE);
+        let rawPath = `\`${url}\``;
+        if (matches) {
+          for (const match of matches) {
+            const paramName = match.slice(1, -1);
+            const param = pathParams[paramName];
+            switch (param?.schema?.type) {
+              case "number":
+              case "integer":
+                rawPath = rawPath.replace(match, "${number}");
+                break;
+              case "boolean":
+                rawPath = rawPath.replace(match, "${boolean}");
+                break;
+              default:
+                rawPath = rawPath.replace(match, "${string}");
+                break;
+            }
+          }
+          // note: creating a string template literal’s AST manually is hard!
+          // just pass an arbitrary string to TS
+          const pathType = (stringToAST(rawPath)[0] as any)?.expression;
+          if (pathType) {
+            type.push(
+              ts.factory.createIndexSignature(
+                /* modifiers     */ tsModifiers({ readonly: ctx.immutable }),
+                /* parameters    */ [
+                  ts.factory.createParameterDeclaration(
+                    /* modifiers      */ undefined,
+                    /* dotDotDotToken */ undefined,
+                    /* name           */ "path",
+                    /* questionToken  */ undefined,
+                    /* type           */ pathType,
+                    /* initializer    */ undefined,
+                  ),
+                ],
+                /* type          */ pathItemType,
+              ),
+            );
+            continue;
+          }
+        }
+      }
+
+      type.push(
+        ts.factory.createPropertySignature(
+          /* modifiers     */ tsModifiers({ readonly: ctx.immutable }),
+          /* name          */ tsPropertyIndex(url),
+          /* questionToken */ undefined,
+          /* type          */ pathItemType,
+        ),
+      );
+
+      debug(`Transformed path "${url}"`, "ts", performance.now() - pathT);
+    }
+  }
+
+  return ts.factory.createTypeLiteralNode(type);
+}
+
+function extractPathParams(pathItemObject: PathItemObject, ctx: GlobalContext) {
+  const params: Record<string, ParameterObject> = {};
+  for (const p of pathItemObject.parameters ?? []) {
+    const resolved = "$ref" in p && p.$ref ? ctx.resolve<ParameterObject>(p.$ref) : (p as ParameterObject);
+    if (resolved && resolved.in === "path") {
+      params[resolved.name] = resolved;
+    }
+  }
+  for (const method of ["get", "put", "post", "delete", "options", "head", "patch", "trace"] as Method[]) {
+    if (!(method in pathItemObject)) {
+      continue;
+    }
+    const resolvedMethod = (pathItemObject[method] as ReferenceObject).$ref
+      ? ctx.resolve<OperationObject>((pathItemObject[method] as ReferenceObject).$ref)
+      : (pathItemObject[method] as OperationObject);
+    if (resolvedMethod?.parameters) {
+      for (const p of resolvedMethod.parameters) {
+        const resolvedParam = "$ref" in p && p.$ref ? ctx.resolve<ParameterObject>(p.$ref) : (p as ParameterObject);
+        if (resolvedParam && resolvedParam.in === "path") {
+          params[resolvedParam.name] = resolvedParam;
+        }
+      }
+    }
+  }
+  return params;
+}