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

package/src/adapters/terminal-logger/terminal-logger.ts

@@ -1,13 +1,19 @@
 import colors from "ansi-colors";
 import type { DebugGroup, Logger } from "../../application/ports/logger.js";
+import { terminalSafeText } from "../../domain/terminal-text.js";
 import { redactUrlSecrets } from "../../domain/url-secrets.js";
 
 /**
  * The Logger port on a terminal, with the original output format: ` ⚠  ` warnings, ` ✘  `
  * errors, and `openapi-ts:<group>` debug lines filtered by `DEBUG` (ENGINEERING_PLAN 4.5). No
- * line shows the user info of a URL.
+ * line shows the secrets of a URL, and each message prints as one line: a message quotes the
+ * document, whose control characters could forge CI commands (terminal-text.ts).
  */
 
+function shownText(message: string): string {
+  return terminalSafeText(redactUrlSecrets(message));
+}
+
 /** Where the lines go: `console` in production, a recording sink in tests. */
 export interface TerminalSink {
   debug(line: string): void;
@@ -84,19 +90,19 @@ class TerminalLogger implements Logger {
     // The original wrote no space without a duration (`openapi-ts:lintIgnored …`).
     const time =
       durationMs === undefined ? " " : this.#palette.green(` ${formatDuration(durationMs)} `);
-    const text = redactUrlSecrets(message);
+    const text = shownText(message);
     this.#options.sink.debug(`  ${this.#palette.bold(name)}${time}${text}`);
   }
 
   warn(message: string): void {
     if (!this.#options.silent) {
-      this.#options.sink.warn(this.#palette.yellow(` ⚠  ${redactUrlSecrets(message)}`));
+      this.#options.sink.warn(this.#palette.yellow(` ⚠  ${shownText(message)}`));
     }
   }
 
   error(message: string): void {
     if (!this.#options.silent) {
-      this.#options.sink.error(this.#palette.red(` ✘  ${redactUrlSecrets(message)}`));
+      this.#options.sink.error(this.#palette.red(` ✘  ${shownText(message)}`));
     }
   }
 }

package/src/api/document-refs.ts

@@ -16,6 +16,34 @@ function isObject(value: unknown): value is Record<string, unknown> {
   return typeof value === "object" && value !== null;
 }
 
+/**
+ * The child of a node under a pointer key. A pointer may pass through a `$ref`
+ * (`#/components/schemas/Wrap/properties/o/properties/v`, where `o` is a `$ref`): a key the node
+ * does not have is read from the node's target, as the generated types index it (ADR-026). A key
+ * the node has is read from it, so a pointer to a sibling of a `$ref` (OpenAPI 3.1) stays as
+ * written.
+ */
+function childOf(
+  schema: unknown,
+  node: unknown,
+  key: string,
+  options: ResolveRefOptions & { logger: Logger },
+): unknown {
+  if (!isObject(node)) {
+    return undefined;
+  }
+  const { visited = [] } = options;
+  const target = node.$ref;
+  if (node[key] || typeof target !== "string" || visited.includes(target)) {
+    return node[key];
+  }
+  const resolved = resolveDocumentRef(schema, target, {
+    ...options,
+    visited: [...visited, target],
+  });
+  return isObject(resolved) ? resolved[key] : undefined;
+}
+
 /** Resolve a `$ref` in a document; warns and returns undefined when it cannot. */
 export function resolveDocumentRef<T>(
   schema: unknown,
@@ -30,7 +58,7 @@ export function resolveDocumentRef<T>(
   }
   let node: unknown = schema;
   for (const key of pointer) {
-    const child = isObject(node) ? node[key] : undefined;
+    const child = childOf(schema, node, key, { ...options, logger });
     if (!child) {
       logger.warn(warningText(`Could not resolve $ref "${$ref}"`, WARNING_CODES.REF_NOT_FOUND));
       return undefined;

package/src/api/document-run.ts

@@ -1,10 +1,10 @@
 import path from "node:path";
-import { fileURLToPath, pathToFileURL } from "node:url";
+import { pathToFileURL } from "node:url";
 import type { Config as RedoclyConfig } from "@redocly/openapi-core";
 import { sourceEmptyError } from "../adapters/redocly-loader/schema-load-errors.js";
 import type { DeprecationReporter } from "../application/ports/deprecation-reporter.js";
 import type { Logger } from "../application/ports/logger.js";
-import type { RefAccess, SchemaLoader } from "../application/ports/schema-loader.js";
+import type { SchemaLoader } from "../application/ports/schema-loader.js";
 import { withStackOverflowReported } from "../application/stack-overflow.js";
 import {
   ineffectiveFixNotices,
@@ -19,6 +19,7 @@ import { warnDiscriminatorValueConflicts } from "./discriminator-conflict-warnin
 import { findDiscriminators } from "./discriminator-scan.js";
 import { resolveDocumentRef } from "./document-refs.js";
 import { warnIdenticalPathTemplates } from "./path-template-warnings.js";
+import { refAccessOf } from "./ref-limit-options.js";
 import type { RunContext } from "./run-context.js";
 import { warnUnsupportedFeatures } from "./unsupported-feature-warnings.js";
 
@@ -68,19 +69,6 @@ function sourceCwd(options: GeneratorOptions): URL {
   return pathToFileURL(path.join(directory, path.sep));
 }
 
-/** The `$ref` limits of the options; a relative local root resolves against the cwd. */
-function refAccessOf(options: GeneratorOptions, cwd: URL): RefAccess {
-  const { localRefRoot, remoteRefHosts } = options;
-  const localRoot =
-    typeof localRefRoot === "string"
-      ? pathToFileURL(path.resolve(fileURLToPath(cwd), localRefRoot))
-      : localRefRoot;
-  return {
-    ...(localRoot === undefined ? {} : { localRoot }),
-    ...(remoteRefHosts === undefined ? {} : { remoteHosts: remoteRefHosts }),
-  };
-}
-
 function callbackOptions(options: GeneratorOptions) {
   return {
     irCallbacks: options.irCallbacks === true,
@@ -126,7 +114,9 @@ function contextFlags(options: GeneratorOptions): ContextFlags {
  */
 function outputFixesOf(options: GeneratorOptions, logger: Logger): readonly OutputFix[] {
   const names = outputFixNamesOf(options.fix ?? []);
-  for (const notice of ineffectiveFixNotices(names, (option) => options[option] === true)) {
+  // The options with their defaults: `defaultNonNullable` is on unless set to false.
+  const flags = contextFlags(options);
+  for (const notice of ineffectiveFixNotices(names, (option) => flags[option])) {
     logger.warn(warningText(notice, WARNING_CODES.FIX_NEEDS_OPTION));
   }
   return [...resolveOutputFixes(names)];

package/src/api/openapi-ts.ts

@@ -1,4 +1,5 @@
 import { createRedoclySchemaLoader } from "../adapters/redocly-loader/redocly-schema-loader.js";
+import type { Logger } from "../application/ports/logger.js";
 import { withStackOverflowReported } from "../application/stack-overflow.js";
 import type { IrDeclaration } from "../domain/ir/nodes.js";
 import type { GeneratorOptions, SchemaSource } from "../types.js";
@@ -52,10 +53,12 @@ export async function generateDeclarations(
 
 /**
  * The default ports: the terminal logger, Node.js deprecation warnings, the given or default
- * Redocly config, Redocly loading.
+ * Redocly config, Redocly loading. A given `logger` takes every line, the loader's included.
  */
-export async function defaultGeneratorPorts(options: GeneratorOptions): Promise<GeneratorPorts> {
-  const logger = defaultLogger(options.silent ?? false);
+export async function defaultGeneratorPorts(
+  options: GeneratorOptions,
+  logger: Logger = defaultLogger(options.silent ?? false),
+): Promise<GeneratorPorts> {
   const redoc = options.redocly ?? (await defaultRedoclyConfig());
   const loader = createRedoclySchemaLoader({
     redoc,

package/src/api/ref-limit-options.ts

@@ -0,0 +1,76 @@
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import type { RefAccess } from "../application/ports/schema-loader.js";
+import { ERROR_CODES, OpenAPITypesafeError } from "../domain/errors.js";
+import { hasUrlScheme } from "../domain/location-text.js";
+import type { GeneratorOptions } from "../types.js";
+
+/**
+ * The `$ref` limits of the options (threat model R1, R2, ADR-017), checked before anything loads.
+ * A value of another type from JavaScript (`remoteRefHosts: "a.com"`, `localRefRoot: new
+ * URL("https://…")`) used to fail later as an error of the document.
+ */
+
+const FILE_PROTOCOL = "file:";
+
+/** What a value is, for the error; a URL is named by its protocol only, as it may hold secrets. */
+function kindOf(value: unknown): string {
+  if (value instanceof URL) {
+    return `a ${value.protocol} URL`;
+  }
+  if (Array.isArray(value)) {
+    return "a list";
+  }
+  return value === null ? "null" : `a ${typeof value}`;
+}
+
+function optionInvalid(option: string, expected: string, got: string): OpenAPITypesafeError {
+  return new OpenAPITypesafeError({
+    code: ERROR_CODES.OPTION_INVALID,
+    message: `The ${option} option must be ${expected}; got ${got}.`,
+    details: { option },
+  });
+}
+
+const LOCAL_ROOT_EXPECTED = "a directory path or a file: URL";
+
+/**
+ * A string as the CLI reads `--local-ref-root`: a URL when it has a scheme (`file:///specs/`),
+ * else a path that resolves against the cwd. Undefined when it does not parse as a URL.
+ */
+function localRootUrlOf(value: string, cwd: URL): URL | undefined {
+  if (!hasUrlScheme(value)) {
+    return pathToFileURL(path.resolve(fileURLToPath(cwd), value));
+  }
+  return URL.parse(value, cwd.href) ?? undefined;
+}
+
+/** The local root as a `file:` URL; the option is set, so it is not undefined. */
+function localRootOf(value: unknown, cwd: URL): URL {
+  const root = typeof value === "string" ? localRootUrlOf(value, cwd) : value;
+  if (root instanceof URL && root.protocol === FILE_PROTOCOL) {
+    return root;
+  }
+  const got = root === undefined ? "a string that is no valid URL" : kindOf(root);
+  throw optionInvalid("localRefRoot", LOCAL_ROOT_EXPECTED, got);
+}
+
+function remoteHostsOf(value: unknown): readonly string[] {
+  if (!Array.isArray(value)) {
+    throw optionInvalid("remoteRefHosts", "a list of hosts", kindOf(value));
+  }
+  const other = value.find((entry) => typeof entry !== "string");
+  if (other !== undefined) {
+    throw optionInvalid("remoteRefHosts", "a list of hosts", `a list with ${kindOf(other)}`);
+  }
+  return value;
+}
+
+/** The limits of the options; fails with `OPTION_INVALID` for a value of another type. */
+export function refAccessOf(options: GeneratorOptions, cwd: URL): RefAccess {
+  const { localRefRoot, remoteRefHosts } = options;
+  return {
+    ...(localRefRoot === undefined ? {} : { localRoot: localRootOf(localRefRoot, cwd) }),
+    ...(remoteRefHosts === undefined ? {} : { remoteHosts: remoteHostsOf(remoteRefHosts) }),
+  };
+}

package/src/api/transform-schema.ts

@@ -6,6 +6,10 @@ import {
   withEnumsRenamed,
 } from "../application/transform/document/enum-names-given-back.js";
 import { operationKeysWritten } from "../application/transform/document/operation-keys-written.js";
+import {
+  unmatchedTemplateKeys,
+  withTemplatePathRefs,
+} from "../application/transform/document/path-template-refs.js";
 import { renameTakenAliases } from "../application/transform/document/root-type-aliases.js";
 import { RunFooter, type RunFooterNames } from "../application/transform/footer/document-footer.js";
 import { EnumNameClaims } from "../application/transform/footer/enum-name-claims.js";
@@ -144,6 +148,20 @@ function enumValuesChecked(
   return checked.footer;
 }
 
+/** The document with its references into templated paths indexed by their templates. */
+function withTemplateRefs(
+  { body, footer, closing }: TransformedDocument,
+  keys: ReadonlyMap<string, string>,
+): TransformedDocument {
+  return {
+    body: withTemplatePathRefs(body, keys),
+    footer: footer.map((entry) =>
+      isIrDeclaration(entry) ? (withTemplatePathRefs([entry], keys)[0] ?? entry) : entry,
+    ),
+    closing: withTemplatePathRefs(closing, keys),
+  };
+}
+
 /** @internal Root types, the footer, then the closing declarations (Phase 5, step 6). */
 export function transformDocument(schema: OpenAPI3, ctx: RunContext): TransformedDocument {
   const document = schema as DocumentObject;
@@ -160,11 +178,8 @@ export function transformDocument(schema: OpenAPI3, ctx: RunContext): Transforme
   const rawClosing = documentClosing(document, context, rawFooter.some(isOperations));
   const parts = { body: rawBody, footer: rawFooter, closing: rawClosing };
   const { body, footer, closing } = withEnumNamesGivenBack(parts, names);
-  return {
-    body: renameTakenAliases(body, footer.filter(isIrDeclaration), closing),
-    footer,
-    closing,
-  };
+  const named = { body: renameTakenAliases(body, footer.filter(isIrDeclaration), closing), footer };
+  return withTemplateRefs({ ...named, closing }, unmatchedTemplateKeys(document.paths, context));
 }
 
 /**

package/src/application/ports/file-system.ts

@@ -29,6 +29,14 @@ export interface DirectoryCheck {
   isDirectory(file: URL): boolean;
 }
 
+/**
+ * Whether a `file:` location is an existing file. A schema argument with a `*` is a glob pattern
+ * only when no file has that name.
+ */
+export interface FileCheck {
+  isFile(file: URL): boolean;
+}
+
 /**
  * An output file that exists before its content is written: the claim created it, empty, when it
  * was missing, so the file system has given it its own identity.

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

@@ -0,0 +1,42 @@
+import { irKeyword, irReference } from "../../domain/ir/constructors.js";
+import type { IrMember, IrType } from "../../domain/ir/nodes.js";
+import { HELPER_TYPES } from "./helper-types.js";
+import type { FooterDeclarations } from "./schema/schema-context.js";
+
+/** The footer part that declares the `PropertyValues` helper type. */
+export type PropertyValuesFooter = Pick<FooterDeclarations, "requirePropertyValues">;
+
+function memberValueTypes(member: IrMember): IrType[] {
+  if (member.kind === "indexSignature") {
+    return [member.type];
+  }
+  return member.isOptional ? [member.type, irKeyword("undefined")] : [member.type];
+}
+
+/**
+ * The value types a key of the type can have, read from its IR: the members of object types,
+ * through unions and intersections. A reference (a `$ref`, `Omit`, `WithRequired`) or a raw
+ * type is read with `PropertyValues`. Primitives, literals and arrays declare no keys.
+ */
+export function declaredValueTypes(type: IrType, footer: PropertyValuesFooter): IrType[] {
+  switch (type.kind) {
+    case "object":
+      return type.members.flatMap(memberValueTypes);
+    case "union":
+    case "intersection":
+      return type.types.flatMap((member) => declaredValueTypes(member, footer));
+    case "reference":
+    case "indexedAccess":
+    case "raw":
+      footer.requirePropertyValues();
+      return [irReference(HELPER_TYPES.propertyValues.name, [type])];
+    case "keyword":
+    case "stringLiteral":
+    case "numberLiteral":
+    case "booleanLiteral":
+    case "array":
+    case "tuple":
+    case "readonly":
+      return [];
+  }
+}

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

@@ -9,13 +9,14 @@ import type {
 } from "../../../domain/ir/nodes.js";
 import type { ComponentsObject } from "../../../domain/openapi/components-object.js";
 import type { DocumentObject } from "../../../domain/openapi/document-object.js";
-import type { PathsObject } from "../../../domain/openapi/path-item-object.js";
+import type { OperationEntry, 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 { isIncludedOperation } from "./path-item.js";
 import { pathMembers, pathsObjectType } from "./paths.js";
 import { apiPathsEnumDeclaration } from "./paths-enum.js";
 import { webhooksType } from "./webhooks.js";
@@ -210,7 +211,8 @@ export function documentClosing(
     declarations.push(emptyAlias(OPERATIONS_NAME));
   }
   if (context.options.makePathsEnum && document.paths) {
-    declarations.push(apiPathsEnumDeclaration(document.paths));
+    const isIncluded = (operation: OperationEntry) => isIncludedOperation(operation, context);
+    declarations.push(apiPathsEnumDeclaration(document.paths, isIncluded));
   }
   return declarations;
 }

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/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/parameter.ts

@@ -13,7 +13,7 @@ import { contentEntryType } from "./media-type.js";
 /**
  * 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-content` fix, any other parameter with `content`
+ * 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 contentParameterType(
@@ -34,14 +34,14 @@ function isTypedByContent(parameter: ParameterObject, context: SchemaContext): b
     return true;
   }
   const hasContent = parameter.schema === undefined && parameter.content !== undefined;
-  return hasContent && context.options.fixes.has(FIX.PARAMETER_CONTENT);
+  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 for
- * `in: querystring`, and with the `parameter-content` fix for every parameter; without the fix
- * other parameters with `content` keep the original's `string`.
+ * `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,

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

@@ -16,10 +16,12 @@ import {
   QUERYSTRING_LOCATION,
 } from "../../../domain/openapi/parameter-object.js";
 import { FIX } from "../../../domain/output-fixes.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,
@@ -126,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. */
@@ -153,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;
     }
@@ -165,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. */

package/src/application/transform/document/path-item.ts

@@ -29,7 +29,7 @@ export function operationKeyOf(operationId: string): string {
 }
 
 /** Whether the method has an operation, not removed by `--exclude-deprecated`. */
-function isIncluded(
+export function isIncludedOperation(
   operation: OperationEntry | undefined,
   context: TransformContext,
 ): operation is OperationEntry {
@@ -94,7 +94,7 @@ function methodMember(
   context: TransformContext,
 ): IrPropertySignature {
   const operation = pathItem[method];
-  if (!isIncluded(operation, context)) {
+  if (!isIncludedOperation(operation, context)) {
     const isReadonly = context.options.immutable;
     return irProperty(toPropertyName(method), irKeyword("never"), { isOptional: true, isReadonly });
   }
@@ -113,7 +113,7 @@ function additionalOperationsMember(
 ): IrPropertySignature | null {
   const entries = documentEntries(pathItem.additionalOperations ?? {}, context.options);
   const members = entries
-    .filter(([, operation]) => isIncluded(operation, context))
+    .filter(([, operation]) => isIncludedOperation(operation, context))
     .map(([method, operation]) => {
       const path = appendPointer(location.path, [ADDITIONAL_OPERATIONS_KEY, method]);
       return operationMember({ name: method, operation, path }, pathItem, location, context);