openapi-typesafe 1.0.0-rc.0 → 1.0.0-rc.2

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

@@ -23,7 +23,7 @@ import { OutputFix } from "../../../domain/output-fixes.js";
 import { type DeprecatedEntryFilter, documentEntries } from "../document-entries.js";
 import type { SchemaLocation } from "../schema/schema-context.js";
 import { transformSchema } from "../schema/schema-transform.js";
-import { withSchemaComment } from "../schema-comment.js";
+import { schemaCommentOptionsOf, withSchemaComment } from "../schema-comment.js";
 import type { TransformContext } from "../transform-context.js";
 import { headerType } from "./header.js";
 import { contentEntryType } from "./media-type.js";
@@ -31,7 +31,7 @@ import { parameterType } from "./parameter.js";
 import { pathItemType } from "./path-item.js";
 import { requestBodyType } from "./request-body.js";
 import { responseType } from "./response.js";
-import { numberDisplacedAliases, rootTypeAlias } from "./root-type-aliases.js";
+import { rootTypeAlias } from "./root-type-aliases.js";
 
 type ComponentTransform = (
   item: never,
@@ -69,7 +69,7 @@ function componentMember(
     isOptional: custom?.isOptional ?? false,
     isReadonly: context.options.immutable,
   });
-  return withSchemaComment(property, item);
+  return withSchemaComment(property, item, schemaCommentOptionsOf(context.options.fixes));
 }
 
 /**
@@ -112,8 +112,8 @@ function rootTypeName(
  * Add a root alias. When its exported name is taken (two schemas of one PascalCase name without
  * the prefix), the later schema takes the name, as in the original. Without the
  * `root-type-numbering` fix the earlier one then has no alias: that output is valid, so a number
- * for it would change it (backlog 30). With the fix the earlier alias is kept aside and numbered
- * at the end.
+ * for it would change it (backlog 30). With the fix the earlier alias is kept aside and follows
+ * the others under the same name; `renameTakenAliases` numbers it once every name is known.
  */
 function addRootAlias(request: ComponentsRequest, alias: IrTypeAliasDeclaration): void {
   const { aliases, displaced } = request;
@@ -184,6 +184,6 @@ export function componentsType(
   const rootTypes = Object.values(aliases);
   return {
     type: irObject(members),
-    rootTypes: [...rootTypes, ...numberDisplacedAliases(displaced ?? [], rootTypes)],
+    rootTypes: [...rootTypes, ...(displaced ?? [])],
   };
 }

package/src/application/transform/document/declared-types.ts

@@ -0,0 +1,93 @@
+import type { IrDeclaration, IrMember, IrType } from "../../../domain/ir/nodes.js";
+
+/**
+ * The type a reference of the generated file names, read from the file's declarations: the
+ * `--path-params-as-types` overlap check compares two path items through the operations and
+ * components they reference (upstream #1752).
+ */
+
+/** The declared type a reference names, or null when the type is no such reference. */
+export type DeclaredTypeLookup = (type: IrType) => IrType | null;
+
+/** Knows no declaration: every reference stays unresolved. */
+export const NO_DECLARED_TYPES: DeclaredTypeLookup = () => null;
+
+/** A reference without type arguments and the string keys indexing it: `components["schemas"]`. */
+interface IndexedName {
+  readonly name: string;
+  readonly keys: readonly string[];
+}
+
+function indexedNameOf(type: IrType): IndexedName | null {
+  if (type.kind === "reference") {
+    return type.typeArguments.length === 0 ? { name: type.name, keys: [] } : null;
+  }
+  if (type.kind !== "indexedAccess" || type.index.kind !== "stringLiteral") {
+    return null;
+  }
+  const object = indexedNameOf(type.object);
+  return object === null ? null : { ...object, keys: [...object.keys, type.index.value] };
+}
+
+function memberName(member: IrMember): string | null {
+  if (member.kind !== "property") {
+    return null;
+  }
+  return member.name.kind === "string" ? member.name.value : member.name.text;
+}
+
+/**
+ * The type of the required property `key`. An optional one is `T | undefined` when indexed, which
+ * is not the declared type, so it is not followed.
+ */
+function propertyType(type: IrType, key: string): IrType | null {
+  if (type.kind !== "object") {
+    return null;
+  }
+  const member = type.members.find((candidate) => memberName(candidate) === key);
+  return member?.kind === "property" && !member.isOptional ? member.type : null;
+}
+
+function declarationType(declaration: IrDeclaration): IrType | null {
+  switch (declaration.kind) {
+    case "interface":
+      return { kind: "object", members: declaration.members };
+    case "typeAlias":
+      return declaration.type;
+    case "enum":
+    case "constArray":
+    case "rawDeclaration":
+      return null;
+  }
+}
+
+/**
+ * A lookup over the declarations. Only a name declared once is read: a second declaration of an
+ * interface merges with the first, which this lookup does not model.
+ */
+export function declaredTypeLookup(declarations: readonly IrDeclaration[]): DeclaredTypeLookup {
+  const byName = new Map<string, IrType | null>();
+  for (const declaration of declarations) {
+    if ("name" in declaration && declaration.name !== undefined) {
+      const isRepeated = byName.has(declaration.name);
+      byName.set(declaration.name, isRepeated ? null : declarationType(declaration));
+    }
+  }
+  // References being resolved: a reference that indexes into itself names no type.
+  const resolving = new Set<IrType>();
+  const lookup: DeclaredTypeLookup = (type) => {
+    const indexed = indexedNameOf(type);
+    if (indexed === null || indexed.keys.length === 0 || resolving.has(type)) {
+      return null;
+    }
+    resolving.add(type);
+    // A key may index a property whose type is a reference again (`paths["/a"]["get"]`).
+    const declared = indexed.keys.reduce<IrType | null>((object, key) => {
+      const named = object === null || object.kind === "object" ? object : lookup(object);
+      return named === null ? null : propertyType(named, key);
+    }, byName.get(indexed.name) ?? null);
+    resolving.delete(type);
+    return declared;
+  };
+  return lookup;
+}

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

@@ -1,4 +1,4 @@
-import { irKeyword, irRecord } from "../../../domain/ir/constructors.js";
+import { irKeyword, irObject, irRecord } from "../../../domain/ir/constructors.js";
 import type {
   IrDeclaration,
   IrIntersectionType,
@@ -12,9 +12,10 @@ import type { PathsObject } from "../../../domain/openapi/path-item-object.js";
 import { READ_WRITE_MARKER_TYPES } from "../helper-types.js";
 import type { TransformContext, TransformOptions } from "../transform-context.js";
 import { componentsType } from "./components.js";
+import { type DeclaredTypeLookup, declaredTypeLookup } from "./declared-types.js";
 import { defsRootType } from "./defs-root.js";
 import { keptDeprecatedComponents } from "./kept-deprecated.js";
-import { pathsType } from "./paths.js";
+import { pathMembers, pathsObjectType } from "./paths.js";
 import { apiPathsEnumDeclaration } from "./paths-enum.js";
 import { webhooksType } from "./webhooks.js";
 
@@ -30,6 +31,11 @@ const EMPTY_ROOT_TYPE = irRecord(irKeyword("string"), irKeyword("never"));
 interface RootResult {
   readonly type: IrType;
   readonly aliases: readonly IrTypeAliasDeclaration[];
+  /**
+   * The root's final type, for a root that reads the types the whole file declares (`paths`, whose
+   * overlap check follows references). `type` then only tells whether the root has members.
+   */
+  readonly withDeclaredTypes?: (lookup: DeclaredTypeLookup) => IrType;
 }
 
 type RootTransform = (
@@ -46,7 +52,14 @@ function keptDeprecated(document: DocumentObject, context: TransformContext): Re
 }
 
 const ROOT_TRANSFORMS: Readonly<Record<RootKey, RootTransform>> = {
-  paths: (node, context) => ({ type: pathsType(node as PathsObject, context), aliases: [] }),
+  paths: (node, context) => {
+    const members = pathMembers(node as PathsObject, context);
+    return {
+      type: irObject(members.map(({ member }) => member)),
+      aliases: [],
+      withDeclaredTypes: (lookup) => pathsObjectType(members, lookup),
+    };
+  },
   webhooks: (node, context) => ({ type: webhooksType(node as PathsObject, context), aliases: [] }),
   components: (node, context, document) => {
     const kept = keptDeprecated(document, context);
@@ -84,6 +97,15 @@ function rootDeclaration(
     : { kind: "interface", name, isExported: true, members: type.members, comments: [] };
 }
 
+/**
+ * The declarations of one root: its type, then its aliases. `finish` gives the root's declaration
+ * again from the types the whole file declares, for a root with `withDeclaredTypes`.
+ */
+interface RootDeclarations {
+  readonly declarations: readonly IrDeclaration[];
+  readonly finish?: (lookup: DeclaredTypeLookup) => IrDeclaration;
+}
+
 /**
  * The declarations of one root. A root that is missing, or whose type has no members, is
  * `Record<string, never>`. Only an object type (or the `paths` intersection) counts as having
@@ -93,21 +115,51 @@ function rootDeclarations(
   root: RootKey,
   document: DocumentObject,
   context: TransformContext,
-): IrDeclaration[] {
+): RootDeclarations {
   const node: unknown = document[root];
   if (!node || typeof node !== "object") {
     context.diagnostics.debug(`${root} done (skipped)`, 0);
-    return [emptyAlias(root)];
+    return { declarations: [emptyAlias(root)] };
   }
   const startedAt = context.diagnostics.now();
-  const { type, aliases } = ROOT_TRANSFORMS[root](node, context, document);
+  const { type, aliases, withDeclaredTypes } = ROOT_TRANSFORMS[root](node, context, document);
   if (!isRootBody(type)) {
     context.diagnostics.debug(`${root} done (skipped)`, 0);
-    return [emptyAlias(root), ...aliases];
+    return { declarations: [emptyAlias(root), ...aliases] };
   }
   const declaration = rootDeclaration(root, type, context.options);
   context.diagnostics.debug(`${root} done`, context.diagnostics.now() - startedAt);
-  return [declaration, ...aliases];
+  const finish =
+    withDeclaredTypes &&
+    ((lookup: DeclaredTypeLookup) => {
+      const finished = withDeclaredTypes(lookup);
+      return isRootBody(finished) ? rootDeclaration(root, finished, context.options) : declaration;
+    });
+  return { declarations: [declaration, ...aliases], ...(finish ? { finish } : {}) };
+}
+
+/**
+ * Every root's declarations in output order. A root with `finish` gets its declaration from the
+ * types of the other roots and of the footer (the `operations` interface), which exist only once
+ * every root is transformed.
+ */
+function rootsDeclarations(
+  document: DocumentObject,
+  context: TransformContext,
+  footer: () => readonly IrDeclaration[],
+): IrDeclaration[] {
+  const roots = ROOT_KEYS.map((root) => rootDeclarations(root, document, context));
+  const transformed = roots.flatMap(({ declarations }) => declarations);
+  if (roots.every(({ finish }) => finish === undefined)) {
+    return transformed;
+  }
+  const lookup = declaredTypeLookup([...transformed, ...footer()]);
+  return roots.flatMap(({ declarations, finish }) => {
+    const [declaration, ...aliases] = declarations;
+    return finish === undefined || declaration === undefined
+      ? declarations
+      : [finish(lookup), ...aliases];
+  });
 }
 
 /**
@@ -118,11 +170,19 @@ function withoutBlankLinesAround(text: string): string {
   return text.replace(/^(?:[ \t]*\r?\n)+/, "").trimEnd();
 }
 
+/** No footer declarations: the roots' references to `operations` stay unresolved. */
+const NO_FOOTER = (): readonly IrDeclaration[] => [];
+
 /**
  * The document's declarations before the footer: helper types, injected code, then one root type
- * per root key with the aliases that follow it.
+ * per root key with the aliases that follow it. `footer` reads the footer's declarations once the
+ * roots are transformed.
  */
-export function documentBody(document: DocumentObject, context: TransformContext): IrDeclaration[] {
+export function documentBody(
+  document: DocumentObject,
+  context: TransformContext,
+  footer: () => readonly IrDeclaration[] = NO_FOOTER,
+): IrDeclaration[] {
   const declarations: IrDeclaration[] = [];
   if (context.options.readWriteMarkers) {
     declarations.push({ kind: "rawDeclaration", text: READ_WRITE_MARKER_TYPES });
@@ -131,9 +191,7 @@ export function documentBody(document: DocumentObject, context: TransformContext
   if (inject !== "") {
     declarations.push({ kind: "rawDeclaration", text: inject });
   }
-  for (const root of ROOT_KEYS) {
-    declarations.push(...rootDeclarations(root, document, context));
-  }
+  declarations.push(...rootsDeclarations(document, context, footer));
   return declarations;
 }
 

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

@@ -0,0 +1,91 @@
+import type { ParameterObject } from "../../../domain/openapi/parameter-object.js";
+import type { Schema, SchemaObject } from "../../../domain/openapi/schema-object.js";
+import type { RefResolver } from "../schema/schema-context.js";
+
+/**
+ * Exploded object query parameters (OpenAPI 3.2 §4.8.12.4, upstream #2361). A query parameter has
+ * `style: form` and, with it, `explode: true` by default. An object value is then sent as its own
+ * `key=value` pairs, `?page=1&limit=10`: the parameter's name is not in the URL. So with the
+ * `exploded-query-objects` fix, the object's properties are keys of `query`, not one key named
+ * after the parameter.
+ */
+
+const FORM_STYLE = "form";
+
+/** Whether a `$ref` chain has been followed already, so a cycle ends. */
+type SeenRefs = ReadonlySet<string>;
+
+function resolvedSchema(schema: Schema, refs: RefResolver, seen: SeenRefs): SchemaObject | null {
+  if (typeof schema !== "object" || schema === null) {
+    return null;
+  }
+  if (!("$ref" in schema)) {
+    return schema;
+  }
+  if (seen.has(schema.$ref)) {
+    return null;
+  }
+  const target = refs.resolve(schema.$ref) as Schema | undefined;
+  return target === undefined
+    ? null
+    : resolvedSchema(target, refs, new Set([...seen, schema.$ref]));
+}
+
+/** The types of a `type` keyword other than `null`; empty when it has none. */
+function nonNullTypes(schema: SchemaObject): readonly unknown[] {
+  const types = Array.isArray(schema.type) ? schema.type : [schema.type];
+  return types.filter((type) => type !== undefined && type !== null && type !== "null");
+}
+
+/** Whether every member of a composition is an object schema; false for an empty list. */
+function isObjectComposition(
+  members: readonly Schema[] | undefined,
+  refs: RefResolver,
+  seen: SeenRefs,
+): boolean {
+  return (
+    members !== undefined &&
+    members.length > 0 &&
+    members.every((member) => isObjectSchemaWith(member, refs, seen))
+  );
+}
+
+function isObjectSchemaWith(schema: Schema, refs: RefResolver, seen: SeenRefs): boolean {
+  const resolved = resolvedSchema(schema, refs, seen);
+  if (resolved === null) {
+    return false;
+  }
+  const types = nonNullTypes(resolved);
+  if (types.length > 0) {
+    return types.every((type) => type === "object");
+  }
+  return (
+    resolved.properties !== undefined ||
+    resolved.additionalProperties !== undefined ||
+    resolved.patternProperties !== undefined ||
+    isObjectComposition(resolved.allOf, refs, seen) ||
+    isObjectComposition(resolved.oneOf, refs, seen) ||
+    isObjectComposition(resolved.anyOf, refs, seen)
+  );
+}
+
+/**
+ * Whether the schema describes only objects: `type: object` (with `null` or not), or no `type`
+ * and object keywords, or a composition of such schemas. A `$ref` is followed.
+ */
+export function isObjectSchema(schema: Schema, refs: RefResolver): boolean {
+  return isObjectSchemaWith(schema, refs, new Set());
+}
+
+/** Whether an `in: query` parameter sends its object value as the object's own keys. */
+export function isExplodedQueryObject(parameter: ParameterObject, refs: RefResolver): boolean {
+  const style = parameter.style ?? FORM_STYLE;
+  const explode = parameter.explode ?? style === FORM_STYLE;
+  return (
+    parameter.in === "query" &&
+    style === FORM_STYLE &&
+    explode &&
+    parameter.schema !== undefined &&
+    isObjectSchema(parameter.schema, refs)
+  );
+}

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

@@ -0,0 +1,78 @@
+import type { IrDeclaration } from "../../../domain/ir/nodes.js";
+
+/**
+ * The TypeScript global types that generated code can refer to: in references (`Record<string,
+ * never>`, `Omit<…>`, the `Blob` of `--binary-as-blob`) and in the text of footer helpers
+ * (`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([
+  "Array",
+  "Blob",
+  "Exclude",
+  "Extract",
+  "NonNullable",
+  "Omit",
+  "Partial",
+  "Pick",
+  "Readonly",
+  "ReadonlyArray",
+  "Record",
+  "Required",
+]);
+
+const GENERIC_USE = /\b([A-Z][A-Za-z]*)\s*</g;
+
+/** `origin` holds the outside node a raw type was printed from; it is not part of the output. */
+const SKIPPED_KEYS: ReadonlySet<string> = new Set(["origin", "comments"]);
+
+function isObject(value: unknown): value is Readonly<Record<string, unknown>> {
+  return typeof value === "object" && value !== null;
+}
+
+function addTextUses(text: string, used: Set<string>): void {
+  for (const match of text.matchAll(GENERIC_USE)) {
+    const name = match[1] ?? "";
+    if (GLOBAL_TYPE_NAMES.has(name)) {
+      used.add(name);
+    }
+  }
+}
+
+function addNodeUses(node: Readonly<Record<string, unknown>>, used: Set<string>): void {
+  if (node.kind === "reference" && typeof node.name === "string") {
+    if (GLOBAL_TYPE_NAMES.has(node.name)) {
+      used.add(node.name);
+    }
+  } else if (
+    (node.kind === "raw" || node.kind === "rawDeclaration") &&
+    typeof node.text === "string"
+  ) {
+    addTextUses(node.text, used);
+  }
+}
+
+function visit(value: unknown, used: Set<string>): void {
+  if (Array.isArray(value)) {
+    for (const item of value) {
+      visit(item, used);
+    }
+    return;
+  }
+  if (!isObject(value)) {
+    return;
+  }
+  addNodeUses(value, used);
+  for (const [key, child] of Object.entries(value)) {
+    if (!SKIPPED_KEYS.has(key)) {
+      visit(child, used);
+    }
+  }
+}
+
+/** The TypeScript global type names that the declarations refer to. */
+export function globalTypeReferences(declarations: readonly IrDeclaration[]): Set<string> {
+  const used = new Set<string>();
+  visit(declarations, used);
+  return used;
+}

package/src/application/transform/document/list-assignability.ts

@@ -0,0 +1,87 @@
+import type {
+  IrArrayType,
+  IrReadonlyType,
+  IrTupleElement,
+  IrTupleType,
+  IrType,
+} from "../../../domain/ir/nodes.js";
+import { type Assignability, everyOf } from "./assignability.js";
+
+/**
+ * How the `--path-params-as-types` overlap check relates two lists: arrays, tuples and their
+ * `readonly` forms. `relate` compares two item types with the whole check.
+ */
+
+type Relate = (source: IrType, target: IrType) => Assignability;
+
+/** The types of the `list` category of `assignability.ts`. */
+export type IrListType = IrArrayType | IrTupleType | IrReadonlyType;
+
+type IrMutableListType = IrArrayType | IrTupleType;
+
+const UNDEFINED: IrType = { kind: "keyword", keyword: "undefined" };
+
+/**
+ * The type of a tuple element's items: a rest element `...T[]` stands for its items, and an
+ * optional element `T?` may be `undefined` (`[string?]` is no `string[]` under `strict`).
+ */
+function elementType(element: IrTupleElement): IrType {
+  if (element.isRest && element.type.kind === "array") {
+    return element.type.element;
+  }
+  return element.isOptional ? { kind: "union", types: [element.type, UNDEFINED] } : element.type;
+}
+
+function isRequired(element: IrTupleElement): boolean {
+  return !element.isRest && !element.isOptional;
+}
+
+/** A tuple with a required element rejects an array, which may be empty. */
+function arrayToTuple(target: IrTupleType): Assignability {
+  return target.elements.some(isRequired) ? "rejected" : "undecided";
+}
+
+/** Tuples of the same shape compare element by element; fixed lengths must be the same. */
+function relateTuples(source: IrTupleType, target: IrTupleType, relate: Relate): Assignability {
+  if (source.elements.length !== target.elements.length) {
+    const isFixed = source.elements.every(isRequired) && target.elements.every(isRequired);
+    return isFixed ? "rejected" : "undecided";
+  }
+  return everyOf(source.elements, (element, index) => {
+    const other = target.elements[index] as IrTupleElement;
+    if (element.isRest !== other.isRest) {
+      return "undecided";
+    }
+    // An optional element may be missing where the target requires one.
+    if (element.isOptional && !other.isOptional) {
+      return "rejected";
+    }
+    return relate(element.type, other.type);
+  });
+}
+
+function relateMutableLists(
+  source: IrMutableListType,
+  target: IrMutableListType,
+  relate: Relate,
+): Assignability {
+  if (source.kind === "array") {
+    return target.kind === "array" ? relate(source.element, target.element) : arrayToTuple(target);
+  }
+  if (target.kind === "array") {
+    return everyOf(source.elements, (element) => relate(elementType(element), target.element));
+  }
+  return relateTuples(source, target, relate);
+}
+
+/** Whether one list type fits another. */
+export function relateLists(source: IrListType, target: IrListType, relate: Relate): Assignability {
+  if (source.kind === "readonly") {
+    // A readonly array is no mutable array (TS4104); to a readonly target it is the same type.
+    return target.kind === "readonly" ? relate(source.type, target.type) : "rejected";
+  }
+  if (target.kind === "readonly") {
+    return relate(source, target.type);
+  }
+  return relateMutableLists(source, target, relate);
+}

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

@@ -1,4 +1,10 @@
-import { irKeyword, irObject, irProperty } from "../../../domain/ir/constructors.js";
+import {
+  irIntersection,
+  irKeyword,
+  irObject,
+  irProperty,
+  irReference,
+} 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";
@@ -10,13 +16,16 @@ import {
   QUERYSTRING_LOCATION,
 } from "../../../domain/openapi/parameter-object.js";
 import type { SchemaObject } from "../../../domain/openapi/schema-object.js";
+import { OutputFix } from "../../../domain/output-fixes.js";
 import { refType } from "../ref-type.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 { parameterType } from "./parameter.js";
 
-const PATH_TEMPLATE_RE = /\{([^}]+)\}/g;
+/** `[^{}]` 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 {
@@ -154,6 +163,66 @@ function querystringMember(
   return withSchemaComment(property, querystring.resolved);
 }
 
+/** With `exploded-query-objects`, whether the parameter's object keys are keys of `query`. */
+function isExplodedEntry(entry: ResolvedEntry, context: TransformContext): boolean {
+  return (
+    context.options.fixes.has(OutputFix.EXPLODED_QUERY_OBJECTS) &&
+    isExplodedQueryObject(entry.resolved, context.refs)
+  );
+}
+
+/**
+ * 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<…>`.
+ */
+function explodedPart(
+  entry: ResolvedEntry,
+  location: SchemaLocation,
+  context: TransformContext,
+): IrType {
+  const type = entryType(entry, location, context);
+  return entry.resolved.required ? type : irReference("Partial", [type]);
+}
+
+/** A location's parameters as members, and the object types of its exploded parameters. */
+interface LocationParts {
+  readonly members: readonly IrPropertySignature[];
+  readonly exploded: readonly IrType[];
+  readonly isOptional: boolean;
+}
+
+/** Each parameter in document order, so the declarations they add keep their order. */
+function locationParts(
+  entries: readonly ResolvedEntry[],
+  location: SchemaLocation,
+  context: TransformContext,
+): LocationParts {
+  const members: IrPropertySignature[] = [];
+  const exploded: IrType[] = [];
+  let isOptional = true;
+  for (const entry of entries) {
+    if (isExplodedEntry(entry, context)) {
+      exploded.push(explodedPart(entry, location, context));
+      isOptional &&= !entry.resolved.required;
+      continue;
+    }
+    const member = parameterMember(entry, location, context);
+    members.push(member);
+    isOptional &&= member.isOptional;
+  }
+  return { members, exploded, isOptional };
+}
+
+/** The members' object, intersected with the exploded parameters' types; `never` for none. */
+function locationType({ members, exploded }: LocationParts): IrType {
+  const types = [...(members.length > 0 ? [irObject(members)] : []), ...exploded];
+  const [first] = types;
+  if (first === undefined) {
+    return irKeyword("never");
+  }
+  return types.length === 1 ? first : irIntersection(types);
+}
+
 /** One location's parameters; optional when all of them are, and `never` when there are none. */
 function locationMember(
   parameterIn: ParameterLocation,
@@ -161,17 +230,14 @@ function locationMember(
   location: SchemaLocation,
   context: TransformContext,
 ): IrPropertySignature {
-  const members = entries
-    .filter((entry): entry is ResolvedEntry => entry.resolved?.in === parameterIn)
-    .map((entry) => parameterMember(entry, location, context));
-  return irProperty(
-    toPropertyName(parameterIn),
-    members.length > 0 ? irObject(members) : irKeyword("never"),
-    {
-      isOptional: members.every((member) => member.isOptional),
-      isReadonly: context.options.immutable,
-    },
+  const located = entries.filter(
+    (entry): entry is ResolvedEntry => entry.resolved?.in === parameterIn,
   );
+  const parts = locationParts(located, location, context);
+  return irProperty(toPropertyName(parameterIn), locationType(parts), {
+    isOptional: parts.isOptional,
+    isReadonly: context.options.immutable,
+  });
 }
 
 /**