openapi-typesafe 1.0.0-rc.3 → 1.0.0-rc.5

package/src/application/transform/document/enum-names-given-back.ts

@@ -0,0 +1,91 @@
+import type { IrDeclaration } from "../../../domain/ir/nodes.js";
+import { HELPER_TYPES, READ_WRITE_MARKER_TYPES } from "../helper-types.js";
+import { typeNamesDeclaredBy, typeNamesInText } from "./declared-type-names.js";
+import { OPERATIONS_NAME, ROOT_KEYS } from "./document.js";
+import { GLOBAL_TYPE_NAMES, globalTypeReferences } from "./global-type-references.js";
+import { API_PATHS_NAME } from "./paths-enum.js";
+import { isRootTypeAlias } from "./root-type-aliases.js";
+
+/**
+ * The second step of naming `--enum` declarations (`EnumNameClaims`): once the output is known,
+ * an enum that gave way to a name the output turned out not to need gets that name back.
+ */
+
+/**
+ * The type names the output of a document may need, besides its enums: the global types it may
+ * refer to and the names the generator declares itself. An enum avoids them until the end.
+ */
+export const NAMES_THE_OUTPUT_MAY_NEED: ReadonlySet<string> = new Set([
+  ...GLOBAL_TYPE_NAMES,
+  ...Object.values(HELPER_TYPES).map(({ name }) => name),
+  ...typeNamesInText(READ_WRITE_MARKER_TYPES),
+  API_PATHS_NAME,
+  ...ROOT_KEYS,
+  OPERATIONS_NAME,
+]);
+
+/** The parts of a transformed document; the footer holds only IR declarations here. */
+export interface DocumentParts {
+  readonly body: readonly IrDeclaration[];
+  readonly footer: readonly IrDeclaration[];
+  readonly closing: readonly IrDeclaration[];
+}
+
+/**
+ * The type names the output needs besides its enums: the globals it refers to, and the names of
+ * its other declarations. Root aliases give way to enums (`renameTakenAliases`), so they count
+ * for nothing.
+ */
+export function namesTheOutputNeeds({ body, footer, closing }: DocumentParts): Set<string> {
+  const others = [
+    ...body.filter((declaration) => !isRootTypeAlias(declaration)),
+    ...footer.filter((declaration) => declaration.kind !== "enum"),
+    ...closing,
+  ];
+  return new Set([
+    ...globalTypeReferences([...body, ...footer, ...closing]),
+    ...typeNamesDeclaredBy(others),
+  ]);
+}
+
+/** `origin` holds the compiler node a raw type was printed from; it is not IR. */
+const SKIPPED_KEYS: ReadonlySet<string> = new Set(["origin"]);
+
+/** The enum references the generator writes: `Name`, `Name.member` and `typeof Name`. */
+const ENUM_REFERENCE_RE = /^(typeof )?([^.]+)(\..*)?$/s;
+
+function renamedReference(name: string, renames: ReadonlyMap<string, string>): string {
+  const match = ENUM_REFERENCE_RE.exec(name);
+  const renamed = match === null ? undefined : renames.get(match[2] ?? "");
+  return renamed === undefined ? name : `${match?.[1] ?? ""}${renamed}${match?.[3] ?? ""}`;
+}
+
+function isNode(value: unknown): value is Readonly<Record<string, unknown>> {
+  return typeof value === "object" && value !== null;
+}
+
+function renamedNode(value: unknown, renames: ReadonlyMap<string, string>): unknown {
+  if (Array.isArray(value)) {
+    return value.map((item) => renamedNode(item, renames));
+  }
+  if (!isNode(value)) {
+    return value;
+  }
+  const node = Object.fromEntries(
+    Object.entries(value).map(([key, child]) => [
+      key,
+      SKIPPED_KEYS.has(key) ? child : renamedNode(child, renames),
+    ]),
+  );
+  const isNamed =
+    (node.kind === "reference" || node.kind === "enum") && typeof node.name === "string";
+  return isNamed ? { ...node, name: renamedReference(node.name as string, renames) } : node;
+}
+
+/** The declarations with each enum in `renames` (old name to new) renamed, references too. */
+export function withEnumsRenamed<T extends IrDeclaration>(
+  declarations: readonly T[],
+  renames: ReadonlyMap<string, string>,
+): T[] {
+  return renames.size === 0 ? [...declarations] : (renamedNode(declarations, renames) as T[]);
+}

package/src/application/transform/document/exploded-query-values.ts

@@ -0,0 +1,88 @@
+import type { IrMember, IrType } from "../../../domain/ir/nodes.js";
+import type { Schema } from "../../../domain/openapi/schema-object.js";
+import { transformSchema } from "../schema/schema-transform.js";
+import type { TransformContext } from "../transform-context.js";
+import { unionOf } from "../type-combinators.js";
+import type { ResolvedEntry } from "./parameter-entries.js";
+
+/**
+ * `exploded-query-objects` and index signatures. The keys of an exploded object are keys of
+ * `query`, next to the other parameters. TypeScript checks an index signature against every key
+ * of a value, so `{ page?: number } & { [key: string]: string }` admits no `page`, and no value
+ * with another parameter at all. An index signature of an exploded object therefore also takes
+ * the value types of the other keys of `query`: those keys carry their own values.
+ */
+
+function refOf(value: unknown): string | undefined {
+  const ref = (value as { $ref?: unknown } | undefined)?.$ref;
+  return typeof ref === "string" ? ref : undefined;
+}
+
+/** A schema `$ref` chain followed to its end, with the pointer where that schema is declared. */
+function declaredSchema(schema: Schema | undefined, ref: string, context: TransformContext) {
+  let declared = { schema, path: ref };
+  const seen = new Set<string>();
+  for (let next = refOf(schema); next !== undefined && !seen.has(next); ) {
+    seen.add(next);
+    declared = { schema: context.refs.resolve(next) as Schema | undefined, path: next };
+    next = refOf(declared.schema);
+  }
+  return declared;
+}
+
+/**
+ * The type of an exploded parameter whose own type is a reference (its `$ref`, or the `$ref` of
+ * its schema), written out where its schema is declared: the index signature of a referenced type
+ * cannot be changed. The location is the one `components` types it at, so the enums it declares
+ * are the ones the reference names. Null when no `$ref` is involved.
+ */
+export function declaredObjectType(entry: ResolvedEntry, context: TransformContext): IrType | null {
+  const { original, resolved } = entry;
+  const schemaRef = refOf(resolved.schema);
+  if (schemaRef !== undefined) {
+    const { schema, path } = declaredSchema(resolved.schema, schemaRef, context);
+    return transformSchema(schema, { path, schema }, context);
+  }
+  const parameterRef = refOf(original);
+  return parameterRef === undefined
+    ? null
+    : transformSchema(resolved.schema, { path: parameterRef, schema: resolved }, context);
+}
+
+function isIndexSignature(member: IrMember): boolean {
+  return member.kind === "indexSignature";
+}
+
+/** Whether the type has an index signature in its objects, through unions and intersections. */
+export function hasIndexSignature(type: IrType): boolean {
+  switch (type.kind) {
+    case "object":
+      return type.members.some(isIndexSignature);
+    case "union":
+    case "intersection":
+      return type.types.some(hasIndexSignature);
+    default:
+      return false;
+  }
+}
+
+function widenedMember(member: IrMember, values: readonly IrType[]): IrMember {
+  // `unknown` takes every value already.
+  const isUnknown = member.type.kind === "keyword" && member.type.keyword === "unknown";
+  return isIndexSignature(member) && !isUnknown
+    ? { ...member, type: unionOf([member.type, ...values]) }
+    : member;
+}
+
+/** The type with the values added to each index signature of its objects. */
+export function withIndexValues(type: IrType, values: readonly IrType[]): IrType {
+  switch (type.kind) {
+    case "object":
+      return { ...type, members: type.members.map((member) => widenedMember(member, values)) };
+    case "union":
+    case "intersection":
+      return { ...type, types: type.types.map((member) => withIndexValues(member, values)) };
+    default:
+      return type;
+  }
+}

package/src/application/transform/document/global-type-references.ts

@@ -6,7 +6,7 @@ import type { IrDeclaration } from "../../../domain/ir/nodes.js";
  * (`Exclude<…>`, `Readonly<…>`). A module declaration of the same name shadows the global: every
  * use of it then fails to compile, or silently names the module's type (`Blob`).
  */
-const GLOBAL_TYPE_NAMES: ReadonlySet<string> = new Set([
+export const GLOBAL_TYPE_NAMES: ReadonlySet<string> = new Set([
   "Array",
   "Blob",
   "Exclude",

package/src/application/transform/document/header.ts

@@ -2,6 +2,8 @@ import { irObject } from "../../../domain/ir/constructors.js";
 import type { IrType } from "../../../domain/ir/nodes.js";
 import type { HeaderObject } from "../../../domain/openapi/header-object.js";
 import { escapePointerSegment } from "../../../domain/openapi/json-pointer.js";
+import type { ContentMap } from "../../../domain/openapi/media-type-object.js";
+import { FIX } from "../../../domain/output-fixes.js";
 import { documentEntries } from "../document-entries.js";
 import type { SchemaContext, SchemaLocation } from "../schema/schema-context.js";
 import { transformSchema } from "../schema/schema-transform.js";
@@ -10,8 +12,10 @@ import { documentMember } from "./document-member.js";
 import { contentEntryType } from "./media-type.js";
 
 /**
- * A header's type (OpenAPI 3.1 §4.8.21): its schema, else an object with one property per media
- * type in `content`, else `unknown`.
+ * A header's type (OpenAPI 3.1 §4.8.21): its schema, else the type of its `content`, else
+ * `unknown`. `content` holds one media type whose schema describes the value; the original typed
+ * it as an object with one property per media type, which the `parameter-header-content` fix
+ * replaces by the media type's type, as for a parameter.
  */
 export function headerType(
   header: HeaderObject,
@@ -24,11 +28,27 @@ export function headerType(
   if (!header.content) {
     return UNKNOWN_TYPE;
   }
+  if (context.options.fixes.has(FIX.PARAMETER_HEADER_CONTENT)) {
+    // The first media type in document order, as for a parameter: `--alphabetize` sorts only
+    // the members it writes.
+    const first = Object.entries(header.content)[0];
+    return first === undefined ? UNKNOWN_TYPE : mediaType(...first, location, context);
+  }
   const members = documentEntries(header.content, context.options).map(([contentType, entry]) => {
-    // Unlike other content maps, the original joins this path by hand: a missing path is `#`.
-    const path = `${location.path ?? "#"}/${escapePointerSegment(contentType)}`;
-    const type = contentEntryType(entry, { ...location, path }, context);
+    const type = mediaType(contentType, entry, location, context);
     return documentMember(contentType, type, entry, { isReadonly: context.options.immutable });
   });
   return irObject(members);
 }
+
+/** The type of one media type of a header, at the path the original gave it. */
+function mediaType(
+  contentType: string,
+  entry: ContentMap[string],
+  location: SchemaLocation,
+  context: SchemaContext,
+): IrType {
+  // Unlike other content maps, the original joins this path by hand: a missing path is `#`.
+  const path = `${location.path ?? "#"}/${escapePointerSegment(contentType)}`;
+  return contentEntryType(entry, { ...location, path }, context);
+}

package/src/application/transform/document/media-type.ts

@@ -1,7 +1,7 @@
 import { irObject, irProperty } from "../../../domain/ir/constructors.js";
 import type { IrPropertySignature, IrType } from "../../../domain/ir/nodes.js";
 import { toPropertyName } from "../../../domain/ir/property-name.js";
-import { createRef } from "../../../domain/openapi/json-pointer.js";
+import { appendPointer, createRef } from "../../../domain/openapi/json-pointer.js";
 import {
   type ContentMap,
   isMediaTypeComponentRef,
@@ -48,9 +48,10 @@ function itemSchemaAt(
     const resolved = isMediaTypeComponentRef(entry.$ref)
       ? (context.refs.resolve(entry.$ref) as MediaTypeObject | undefined)
       : undefined;
+    // `createRef` reads the `$ref` itself as a pointer; only the constant segment is appended.
     return { schema: resolved?.itemSchema, path: createRef([entry.$ref, "itemSchema"]) };
   }
-  return { schema: entry.itemSchema, path: createRef([path, "itemSchema"]) };
+  return { schema: entry.itemSchema, path: appendPointer(path, ["itemSchema"]) };
 }
 
 /**
@@ -64,7 +65,7 @@ export function itemContentMember(
   flags: { readonly isReadonly: boolean },
 ): IrPropertySignature | null {
   const members = documentEntries(content, context.options).flatMap(([mediaType, entry]) => {
-    const contentPath = createRef([location.path, "content", mediaType]);
+    const contentPath = appendPointer(location.path, ["content", mediaType]);
     const item = itemSchemaAt(entry, contentPath, context);
     if (item.schema === undefined) {
       return [];

package/src/application/transform/document/operation-keys-written.ts

@@ -0,0 +1,27 @@
+import { appendAll } from "../../../domain/append-all.js";
+import { operationKeyOf } from "./path-item.js";
+
+/**
+ * Every `operations` key that an `operationId` in the document asks for, so that a repeated ID
+ * never gets a number another operation has as its own ID (`OperationKeys`). Operations can sit
+ * in `paths`, `webhooks`, `components.pathItems` and callbacks, so the whole document is read. A
+ * Link Object's `operationId` is read too; an extra name only makes a number skip it.
+ */
+export function operationKeysWritten(document: object): Set<string> {
+  const keys = new Set<string>();
+  const seen = new WeakSet<object>();
+  const pending: unknown[] = [document];
+  while (pending.length > 0) {
+    const value = pending.pop();
+    if (typeof value !== "object" || value === null || seen.has(value)) {
+      continue;
+    }
+    seen.add(value);
+    const { operationId } = value as { operationId?: unknown };
+    if (typeof operationId === "string") {
+      keys.add(operationKeyOf(operationId));
+    }
+    appendAll(pending, Object.values(value));
+  }
+  return keys;
+}

package/src/application/transform/document/operation.ts

@@ -1,7 +1,7 @@
 import { irKeyword, irProperty } from "../../../domain/ir/constructors.js";
 import type { IrPropertySignature } from "../../../domain/ir/nodes.js";
 import { toPropertyName } from "../../../domain/ir/property-name.js";
-import { createRef } from "../../../domain/openapi/json-pointer.js";
+import { appendPointer } from "../../../domain/openapi/json-pointer.js";
 import type { OperationObject } from "../../../domain/openapi/operation-object.js";
 import type { RequestBodyObject } from "../../../domain/openapi/request-body-object.js";
 import { refType } from "../ref-type.js";
@@ -31,7 +31,7 @@ function requestBodyMember(
     ? refType(body.$ref)
     : requestBodyType(
         body,
-        { ...location, path: createRef([location.path, "requestBody"]) },
+        { ...location, path: appendPointer(location.path, ["requestBody"]) },
         context,
       );
   const resolved = isReference

package/src/application/transform/document/parameter-entries.ts

@@ -0,0 +1,70 @@
+import type { OperationObject } from "../../../domain/openapi/operation-object.js";
+import type {
+  ParameterObject,
+  ParameterOrReference,
+} from "../../../domain/openapi/parameter-object.js";
+import type { PathItemObject } from "../../../domain/openapi/path-item-object.js";
+import type { SchemaObject } from "../../../domain/openapi/schema-object.js";
+import type { RefResolver } from "../schema/schema-context.js";
+import type { TransformContext } from "../transform-context.js";
+
+/** A parameter as written in the document, and the object its `$ref` points to. */
+export interface ParameterEntry {
+  readonly original: ParameterOrReference;
+  readonly resolved: ParameterObject | undefined;
+}
+
+/** An entry whose `$ref` resolved, so its location and name are known. */
+export type ResolvedEntry = ParameterEntry & { readonly resolved: ParameterObject };
+
+/** The parameter object itself, or the one its `$ref` points to. */
+export function resolveParameter(
+  parameter: ParameterOrReference,
+  refs: RefResolver,
+): ParameterObject | undefined {
+  return "$ref" in parameter
+    ? (refs.resolve(parameter.$ref) as ParameterObject | undefined)
+    : parameter;
+}
+
+function isDeprecatedParameter(parameter: ParameterObject | undefined): boolean {
+  const schema = parameter?.schema as SchemaObject | undefined;
+  return Boolean(parameter?.deprecated || schema?.deprecated);
+}
+
+/** Resolved parameters, sorted for `--alphabetize`, without deprecated ones if excluded. */
+export function parameterEntries(
+  parameters: readonly ParameterOrReference[],
+  context: TransformContext,
+): ParameterEntry[] {
+  const entries = parameters.map((original) => ({
+    original,
+    resolved: resolveParameter(original, context.refs),
+  }));
+  if (context.options.alphabetize) {
+    // Unlike map keys, the original sorts parameters with the default locale's `localeCompare`.
+    entries.sort((left, right) =>
+      (left.resolved?.name ?? "").localeCompare(right.resolved?.name ?? ""),
+    );
+  }
+  return context.options.excludeDeprecated
+    ? entries.filter(({ resolved }) => !isDeprecatedParameter(resolved))
+    : entries;
+}
+
+/**
+ * Path item parameters followed by the operation's, keyed by location and name, so an operation
+ * parameter replaces the path item parameter it redefines (upstream issue #1798).
+ */
+export function mergedParameters(
+  pathItem: PathItemObject,
+  operation: OperationObject,
+  refs: RefResolver,
+): ParameterOrReference[] {
+  const byKey = new Map<string, ParameterOrReference>();
+  for (const parameter of [...(pathItem.parameters ?? []), ...(operation.parameters ?? [])]) {
+    const resolved = resolveParameter(parameter, refs);
+    byKey.set(`${resolved?.in}-${resolved?.name}`, parameter);
+  }
+  return [...byKey.values()];
+}

package/src/application/transform/document/parameter.ts

@@ -1,19 +1,22 @@
 import { irKeyword } from "../../../domain/ir/constructors.js";
 import type { IrType } from "../../../domain/ir/nodes.js";
-import { createRef } from "../../../domain/openapi/json-pointer.js";
+import { appendPointer } from "../../../domain/openapi/json-pointer.js";
 import {
   type ParameterObject,
   QUERYSTRING_LOCATION,
 } from "../../../domain/openapi/parameter-object.js";
+import { FIX } from "../../../domain/output-fixes.js";
 import type { SchemaContext, SchemaLocation } from "../schema/schema-context.js";
 import { transformSchema } from "../schema/schema-transform.js";
 import { contentEntryType } from "./media-type.js";
 
 /**
- * An `in: querystring` parameter (OpenAPI 3.2): the whole query string, typed by the schema of its
- * one `content` media type (ADR-020). Without one it is `string`, the query string as text.
+ * A parameter typed by the schema of its one `content` media type. An `in: querystring` parameter
+ * (OpenAPI 3.2) is the whole query string (ADR-020); without a media type it is `string`, the
+ * query string as text. With the `parameter-header-content` fix, any other parameter with `content`
+ * (OpenAPI 3.0 and later, for a JSON value in a query parameter) is typed the same way.
  */
-function querystringType(
+function contentParameterType(
   parameter: ParameterObject,
   location: SchemaLocation,
   context: SchemaContext,
@@ -22,22 +25,31 @@ function querystringType(
   if (mediaType === undefined || entry === undefined) {
     return irKeyword("string");
   }
-  const path = createRef([location.path, "content", mediaType]);
+  const path = appendPointer(location.path, ["content", mediaType]);
   return contentEntryType(entry, { ...location, path }, context);
 }
 
+function isTypedByContent(parameter: ParameterObject, context: SchemaContext): boolean {
+  if (parameter.in === QUERYSTRING_LOCATION) {
+    return true;
+  }
+  const hasContent = parameter.schema === undefined && parameter.content !== undefined;
+  return hasContent && context.options.fixes.has(FIX.PARAMETER_HEADER_CONTENT);
+}
+
 /**
  * A parameter's type (OpenAPI 3.2 §4.8.12). Without a schema it is `string`, not `unknown`:
- * query, path, header and cookie values all arrive as text. `content` is read only for
- * `in: querystring`; other parameters with `content` keep their pre-3.2 type.
+ * query, path, header and cookie values all arrive as text. `content` is read for
+ * `in: querystring`, and with the `parameter-header-content` fix for every parameter; without
+ * the fix other parameters with `content` keep the original's `string`.
  */
 export function parameterType(
   parameter: ParameterObject,
   location: SchemaLocation,
   context: SchemaContext,
 ): IrType {
-  if (parameter.in === QUERYSTRING_LOCATION) {
-    return querystringType(parameter, location, context);
+  if (isTypedByContent(parameter, context)) {
+    return contentParameterType(parameter, location, context);
   }
   return parameter.schema
     ? transformSchema(parameter.schema, location, context)

package/src/application/transform/document/parameters.ts

@@ -7,7 +7,7 @@ import {
 } from "../../../domain/ir/constructors.js";
 import type { IrPropertyName, IrPropertySignature, IrType } from "../../../domain/ir/nodes.js";
 import { toPropertyName } from "../../../domain/ir/property-name.js";
-import { createRef } from "../../../domain/openapi/json-pointer.js";
+import { appendPointer } from "../../../domain/openapi/json-pointer.js";
 import {
   PARAMETER_LOCATIONS,
   type ParameterLocation,
@@ -15,36 +15,25 @@ import {
   type ParameterOrReference,
   QUERYSTRING_LOCATION,
 } from "../../../domain/openapi/parameter-object.js";
-import type { SchemaObject } from "../../../domain/openapi/schema-object.js";
 import { FIX } from "../../../domain/output-fixes.js";
-import { refType } from "../ref-type.js";
+import { declaredValueTypes } from "../declared-value-types.js";
 import type { SchemaLocation } from "../schema/schema-context.js";
 import { withSchemaComment } from "../schema-comment.js";
 import type { TransformContext } from "../transform-context.js";
 import { isExplodedQueryObject } from "./exploded-query.js";
+import { declaredObjectType, hasIndexSignature, withIndexValues } from "./exploded-query-values.js";
 import { parameterType } from "./parameter.js";
+import {
+  type ParameterEntry,
+  parameterEntries,
+  type ResolvedEntry,
+  resolveParameter,
+} from "./parameter-entries.js";
+import { referencedParameterType } from "./referenced-parameter.js";
 
 /** `[^{}]` keeps the scan linear: `[^}]` retried from every `{` of a long run of them. */
 const PATH_TEMPLATE_RE = /\{([^{}]+)\}/g;
 
-/** A parameter as written in the document, and the object its `$ref` points to. */
-interface ParameterEntry {
-  readonly original: ParameterOrReference;
-  readonly resolved: ParameterObject | undefined;
-}
-
-/** An entry whose `$ref` resolved, so its location and name are known. */
-type ResolvedEntry = ParameterEntry & { readonly resolved: ParameterObject };
-
-function resolveParameter(
-  parameter: ParameterOrReference,
-  context: TransformContext,
-): ParameterObject | undefined {
-  return "$ref" in parameter
-    ? (context.refs.resolve(parameter.$ref) as ParameterObject | undefined)
-    : parameter;
-}
-
 /** Required string parameters for every `{name}` in a path template. */
 function pathTemplateParameters(path: string): ParameterObject[] {
   return (path.match(PATH_TEMPLATE_RE) ?? []).map((match) => ({
@@ -67,7 +56,7 @@ function withPathTemplateParameters(
   }
   for (const parameter of pathTemplateParameters(location.path)) {
     const isDefined = result.some((candidate) => {
-      const resolved = resolveParameter(candidate, context);
+      const resolved = resolveParameter(candidate, context.refs);
       return resolved?.in === "path" && resolved.name === parameter.name;
     });
     if (!isDefined) {
@@ -77,31 +66,6 @@ function withPathTemplateParameters(
   return result;
 }
 
-function isDeprecatedParameter(parameter: ParameterObject | undefined): boolean {
-  const schema = parameter?.schema as SchemaObject | undefined;
-  return Boolean(parameter?.deprecated || schema?.deprecated);
-}
-
-/** Resolved parameters, sorted for `--alphabetize`, without deprecated ones if excluded. */
-function parameterEntries(
-  parameters: readonly ParameterOrReference[],
-  context: TransformContext,
-): ParameterEntry[] {
-  const entries = parameters.map((original) => ({
-    original,
-    resolved: resolveParameter(original, context),
-  }));
-  if (context.options.alphabetize) {
-    // Unlike map keys, the original sorts parameters with the default locale's `localeCompare`.
-    entries.sort((left, right) =>
-      (left.resolved?.name ?? "").localeCompare(right.resolved?.name ?? ""),
-    );
-  }
-  return context.options.excludeDeprecated
-    ? entries.filter(({ resolved }) => !isDeprecatedParameter(resolved))
-    : entries;
-}
-
 /** The original quotes a name that is not text (a missing name prints as `"undefined"`). */
 function parameterName(name: unknown): IrPropertyName {
   return typeof name === "string" || typeof name === "number"
@@ -109,21 +73,14 @@ function parameterName(name: unknown): IrPropertyName {
     : { kind: "string", value: String(name) };
 }
 
-function referencedParameterType(ref: string, resolved: ParameterObject): IrType {
-  // A `$ref` that resolves to another `$ref` is not a parameter object yet: index it as a path.
-  const isParameter = !(resolved as { $ref?: unknown }).$ref;
-  const parameter = isParameter ? { in: resolved.in, name: resolved.name } : null;
-  return refType(ref, { parameter });
-}
-
 function entryType(
   { original, resolved }: ResolvedEntry,
   location: SchemaLocation,
   context: TransformContext,
 ): IrType {
-  const path = createRef([location.path, "parameters", resolved.in, resolved.name]);
+  const path = appendPointer(location.path, ["parameters", resolved.in, resolved.name]);
   return "$ref" in original
-    ? referencedParameterType(original.$ref, resolved)
+    ? referencedParameterType(original.$ref, resolved, context)
     : parameterType(resolved, { ...location, path }, context);
 }
 
@@ -171,17 +128,50 @@ function isExplodedEntry(entry: ResolvedEntry, context: TransformContext): boole
   );
 }
 
+/** An exploded object parameter with its type, typed in document order. */
+interface ExplodedEntry {
+  readonly entry: ResolvedEntry;
+  readonly type: IrType;
+}
+
 /**
- * An exploded object parameter's part of `query`: its object type. A parameter that may be left
- * out sends none of its keys then, so they are optional: `Partial<…>`.
+ * The object type of an exploded parameter, written out when it is a reference to a type with an
+ * index signature and `query` has other keys, which that signature must then admit. Without
+ * other keys the reference is kept.
  */
-function explodedPart(
-  entry: ResolvedEntry,
-  location: SchemaLocation,
+function explodedObjectType(
+  { entry, type }: ExplodedEntry,
+  hasOtherKeys: boolean,
   context: TransformContext,
 ): IrType {
-  const type = entryType(entry, location, context);
-  return entry.resolved.required ? type : irReference("Partial", [type]);
+  if (!hasOtherKeys) {
+    return type;
+  }
+  const declared = declaredObjectType(entry, context);
+  return declared !== null && hasIndexSignature(declared) ? declared : type;
+}
+
+/**
+ * The exploded object parameters' parts of `query`: their object types, each index signature
+ * widened by the value types of the other keys (see `exploded-query-values.ts`). A parameter that
+ * may be left out sends none of its keys then, so they are optional: `Partial<…>`.
+ */
+function explodedParts(
+  exploded: readonly ExplodedEntry[],
+  members: readonly IrPropertySignature[],
+  context: TransformContext,
+): IrType[] {
+  const hasOtherKeys = members.length > 0 || exploded.length > 1;
+  const types = exploded.map((part) => explodedObjectType(part, hasOtherKeys, context));
+  const others = (index: number) => [
+    ...(members.length > 0 ? [irObject(members)] : []),
+    ...types.filter((_type, other) => other !== index),
+  ];
+  return types.map((type, index) => {
+    const values = others(index).flatMap((other) => declaredValueTypes(other, context.footer));
+    const widened = withIndexValues(type, values);
+    return exploded[index]?.entry.resolved.required ? widened : irReference("Partial", [widened]);
+  });
 }
 
 /** A location's parameters as members, and the object types of its exploded parameters. */
@@ -198,11 +188,11 @@ function locationParts(
   context: TransformContext,
 ): LocationParts {
   const members: IrPropertySignature[] = [];
-  const exploded: IrType[] = [];
+  const exploded: ExplodedEntry[] = [];
   let isOptional = true;
   for (const entry of entries) {
     if (isExplodedEntry(entry, context)) {
-      exploded.push(explodedPart(entry, location, context));
+      exploded.push({ entry, type: entryType(entry, location, context) });
       isOptional &&= !entry.resolved.required;
       continue;
     }
@@ -210,7 +200,7 @@ function locationParts(
     members.push(member);
     isOptional &&= member.isOptional;
   }
-  return { members, exploded, isOptional };
+  return { members, exploded: explodedParts(exploded, members, context), isOptional };
 }
 
 /** The members' object, intersected with the exploded parameters' types; `never` for none. */