openapi-typesafe 0.0.0 → 1.0.0-rc.1

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

@@ -0,0 +1,189 @@
+import { irKeyword, irObject, irProperty } from "../../../domain/ir/constructors.js";
+import {
+  hasIdentifierStart,
+  isReservedTypeName,
+  withIdentifierParts,
+} from "../../../domain/ir/identifier-text.js";
+import type {
+  IrPropertySignature,
+  IrType,
+  IrTypeAliasDeclaration,
+} from "../../../domain/ir/nodes.js";
+import { toPropertyName } from "../../../domain/ir/property-name.js";
+import {
+  COMPONENT_KINDS,
+  type ComponentKind,
+  type ComponentsObject,
+  DECLARED_COMPONENT_KINDS,
+  isEnumSchema,
+  singularizeComponentKind,
+} from "../../../domain/openapi/components-object.js";
+import { createRef } from "../../../domain/openapi/json-pointer.js";
+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 { schemaCommentOptionsOf, withSchemaComment } from "../schema-comment.js";
+import type { TransformContext } from "../transform-context.js";
+import { headerType } from "./header.js";
+import { contentEntryType } from "./media-type.js";
+import { parameterType } from "./parameter.js";
+import { pathItemType } from "./path-item.js";
+import { requestBodyType } from "./request-body.js";
+import { responseType } from "./response.js";
+import { rootTypeAlias } from "./root-type-aliases.js";
+
+type ComponentTransform = (
+  item: never,
+  location: SchemaLocation,
+  context: TransformContext,
+) => IrType;
+
+const COMPONENT_TRANSFORMS: Readonly<Record<ComponentKind, ComponentTransform>> = {
+  schemas: transformSchema,
+  responses: responseType,
+  parameters: parameterType,
+  requestBodies: requestBodyType,
+  headers: headerType,
+  pathItems: pathItemType,
+  mediaTypes: contentEntryType,
+};
+
+/** The `components` type and the `--root-types` aliases. */
+export interface ComponentsResult {
+  readonly type: IrType;
+  readonly rootTypes: readonly IrTypeAliasDeclaration[];
+}
+
+/** One component; the `transform` callback may replace its type, as for nested schemas. */
+function componentMember(
+  kind: ComponentKind,
+  name: string,
+  item: unknown,
+  context: TransformContext,
+): IrPropertySignature {
+  const location = { path: createRef(["components", kind, name]), schema: item };
+  const type = COMPONENT_TRANSFORMS[kind](item as never, location, context);
+  const custom = context.callbacks.transform(item, location);
+  const property = irProperty(toPropertyName(name), custom?.type ?? type, {
+    isOptional: custom?.isOptional ?? false,
+    isReadonly: context.options.immutable,
+  });
+  return withSchemaComment(property, item, schemaCommentOptionsOf(context.options.fixes));
+}
+
+/**
+ * The root alias name: `SchemaPet`, `ResponseNotFound`, … A taken name gets `_2`, `_3`, … The
+ * original checks for conflicts before it removes the schema prefix, and so does this; for a clash
+ * of exported names see `addRootAlias`.
+ *
+ * The original could build a name that is no identifier, so the generated file did not parse
+ * (research/legacy-bugs.md, item 16): a kept casing keeps spaces and symbols, which become `_`;
+ * and a name without the prefix can start with a digit, so it keeps the prefix (`Schema1`). A
+ * kept casing without the prefix can also give a reserved name (`void`, `class`), which keeps the
+ * prefix too (`Schemavoid`).
+ */
+function rootTypeName(
+  kind: ComponentKind,
+  name: string,
+  aliases: Readonly<Record<string, IrTypeAliasDeclaration>>,
+  context: TransformContext,
+): string {
+  const { options, casing } = context;
+  const prefix = casing.pascalCase(singularizeComponentKind(kind));
+  const isSchema = kind === "schemas";
+  const base = withIdentifierParts(
+    options.rootTypesKeepCasing && isSchema ? name : casing.pascalCase(name),
+  );
+  const exportedName = (alias: string): string => {
+    const unprefixed = alias.replace(prefix, "");
+    const isUnprefixed = options.rootTypesNoSchemaPrefix && isSchema;
+    const isTypeName = hasIdentifierStart(unprefixed) && !isReservedTypeName(unprefixed);
+    return isUnprefixed && isTypeName ? unprefixed : alias;
+  };
+  let alias = `${prefix}${base}`;
+  for (let counter = 2; aliases[alias] !== undefined; counter++) {
+    alias = `${prefix}${base}_${counter}`;
+  }
+  return exportedName(alias);
+}
+
+/**
+ * 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 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;
+  const previous = aliases[alias.name];
+  if (previous !== undefined && displaced !== null) {
+    displaced.push(previous);
+  }
+  aliases[alias.name] = alias;
+}
+
+/** `--root-types` skips enum schemas under `--enum`: the enum itself is exported. */
+function hasRootType(kind: ComponentKind, item: unknown, context: TransformContext): boolean {
+  const { options } = context;
+  return options.rootTypes && !(options.enum && kind === "schemas" && isEnumSchema(item));
+}
+
+/** The components of one run, and the deprecated ones that kept output still references. */
+interface ComponentsRequest {
+  readonly components: ComponentsObject;
+  readonly isKept: DeprecatedEntryFilter;
+  readonly aliases: Record<string, IrTypeAliasDeclaration>;
+  /** With the `root-type-numbering` fix: the aliases a later schema took the name of, in order. */
+  readonly displaced: IrTypeAliasDeclaration[] | null;
+}
+
+function kindMember(
+  kind: ComponentKind,
+  request: ComponentsRequest,
+  context: TransformContext,
+): IrPropertySignature {
+  const { components, isKept, aliases } = request;
+  const startedAt = context.diagnostics.now();
+  const items: IrPropertySignature[] = [];
+  for (const [name, item] of documentEntries(components[kind] ?? {}, context.options, isKept)) {
+    items.push(componentMember(kind, name, item, context));
+    if (hasRootType(kind, item, context)) {
+      addRootAlias(request, rootTypeAlias(rootTypeName(kind, name, aliases, context), kind, name));
+    }
+  }
+  const type = items.length > 0 ? irObject(items) : irKeyword("never");
+  context.diagnostics.debug(
+    `Transformed components → ${kind}`,
+    context.diagnostics.now() - startedAt,
+  );
+  return irProperty(toPropertyName(kind), type);
+}
+
+/**
+ * The `components` interface body (OpenAPI 3.1 §4.8.7), one member per component kind. With
+ * `--exclude-deprecated`, `kept` holds the deprecated components that kept output references
+ * (`keptDeprecatedComponents`); they stay, so no reference names a missing key.
+ */
+export function componentsType(
+  components: ComponentsObject,
+  context: TransformContext,
+  kept: ReadonlySet<object> = new Set(),
+): ComponentsResult {
+  // A plain object, as in the original: its key order (integer-like names first) is the
+  // output order.
+  const aliases: Record<string, IrTypeAliasDeclaration> = {};
+  const displaced = context.options.fixes.has(OutputFix.ROOT_TYPE_NUMBERING) ? [] : null;
+  const isKept = (item: unknown) => kept.has(item as object);
+  const request = { components, isKept, aliases, displaced };
+  const declaredKinds = DECLARED_COMPONENT_KINDS.filter((kind) => components[kind] !== undefined);
+  const members = [...COMPONENT_KINDS, ...declaredKinds].map((kind) =>
+    kindMember(kind, request, context),
+  );
+  const rootTypes = Object.values(aliases);
+  return {
+    type: irObject(members),
+    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/defs-root.ts

@@ -0,0 +1,25 @@
+import { irObject, irProperty } from "../../../domain/ir/constructors.js";
+import type { IrObjectType } from "../../../domain/ir/nodes.js";
+import { toPropertyName } from "../../../domain/ir/property-name.js";
+import { createRef } from "../../../domain/openapi/json-pointer.js";
+import type { Schema } from "../../../domain/openapi/schema-object.js";
+import { transformSchema } from "../schema/schema-transform.js";
+import type { TransformContext } from "../transform-context.js";
+
+/**
+ * The root `$defs` type: one required member per named subschema, so `#/$defs/<name>` refs
+ * (`$defs["<name>"]`) resolve. The original transformed the whole `$defs` map as one schema,
+ * which gave `Record<string, never>` and made every such ref `never` (research/legacy-bugs.md,
+ * item 18).
+ */
+export function defsRootType(
+  defs: Readonly<Record<string, Schema>>,
+  context: TransformContext,
+): IrObjectType {
+  const members = Object.entries(defs).map(([name, schema]) => {
+    const location = { path: createRef(["$defs", name]), schema };
+    const type = transformSchema(schema, location, context);
+    return irProperty(toPropertyName(name), type, { isReadonly: context.options.immutable });
+  });
+  return irObject(members);
+}

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

@@ -0,0 +1,20 @@
+import { irProperty } from "../../../domain/ir/constructors.js";
+import type { IrPropertySignature, IrType } from "../../../domain/ir/nodes.js";
+import { toPropertyName } from "../../../domain/ir/property-name.js";
+import { withSchemaComment } from "../schema-comment.js";
+
+export interface DocumentMemberFlags {
+  readonly isReadonly: boolean;
+  readonly isOptional?: boolean;
+}
+
+/** A member named by a document map key (media type, header, status code), with its JSDoc. */
+export function documentMember(
+  name: string,
+  type: IrType,
+  entry: unknown,
+  flags: DocumentMemberFlags,
+): IrPropertySignature {
+  const property = irProperty(toPropertyName(name), type, flags);
+  return withSchemaComment(property, entry);
+}

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

@@ -0,0 +1,215 @@
+import { irKeyword, irObject, irRecord } from "../../../domain/ir/constructors.js";
+import type {
+  IrDeclaration,
+  IrIntersectionType,
+  IrObjectType,
+  IrType,
+  IrTypeAliasDeclaration,
+} 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 { 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 { pathMembers, pathsObjectType } from "./paths.js";
+import { apiPathsEnumDeclaration } from "./paths-enum.js";
+import { webhooksType } from "./webhooks.js";
+
+/** The root types, in output order. */
+const ROOT_KEYS = Object.freeze(["paths", "webhooks", "components", "$defs"] as const);
+type RootKey = (typeof ROOT_KEYS)[number];
+
+const OPERATIONS_NAME = "operations";
+/** The type of a root without members: `Record<string, never>`. */
+const EMPTY_ROOT_TYPE = irRecord(irKeyword("string"), irKeyword("never"));
+
+/** A root's type and the declarations that follow it (the `--root-types` aliases). */
+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 = (
+  node: object,
+  context: TransformContext,
+  document: DocumentObject,
+) => RootResult;
+
+/** Without `--exclude-deprecated` nothing is left out, so the scan is skipped. */
+function keptDeprecated(document: DocumentObject, context: TransformContext): ReadonlySet<object> {
+  return context.options.excludeDeprecated
+    ? keptDeprecatedComponents(document, context.refs)
+    : new Set();
+}
+
+const ROOT_TRANSFORMS: Readonly<Record<RootKey, RootTransform>> = {
+  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);
+    const { type, rootTypes } = componentsType(node as ComponentsObject, context, kept);
+    return { type, aliases: rootTypes };
+  },
+  $defs: (node, context) => ({
+    type: defsRootType(node as NonNullable<DocumentObject["$defs"]>, context),
+    aliases: [],
+  }),
+};
+
+function emptyAlias(name: string): IrTypeAliasDeclaration {
+  return { kind: "typeAlias", name, isExported: true, type: EMPTY_ROOT_TYPE, comments: [] };
+}
+
+/** A root type that declares something: an object with members, or an intersection of them. */
+type RootBodyType = IrObjectType | IrIntersectionType;
+
+function isRootBody(type: IrType): type is RootBodyType {
+  return (type.kind === "object" && type.members.length > 0) || type.kind === "intersection";
+}
+
+/**
+ * A root with members: an interface, or a type alias with `--export-type`. An intersection (the
+ * `paths` of overlapping `--path-params-as-types` keys) can only be a type alias.
+ */
+function rootDeclaration(
+  name: RootKey,
+  type: RootBodyType,
+  options: TransformOptions,
+): IrDeclaration {
+  return options.exportType || type.kind === "intersection"
+    ? { kind: "typeAlias", name, isExported: true, type, comments: [] }
+    : { 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
+ * members: a callback type the IR keeps as raw text does not (ADR-004).
+ */
+function rootDeclarations(
+  root: RootKey,
+  document: DocumentObject,
+  context: TransformContext,
+): RootDeclarations {
+  const node: unknown = document[root];
+  if (!node || typeof node !== "object") {
+    context.diagnostics.debug(`${root} done (skipped)`, 0);
+    return { declarations: [emptyAlias(root)] };
+  }
+  const startedAt = context.diagnostics.now();
+  const { type, aliases, withDeclaredTypes } = ROOT_TRANSFORMS[root](node, context, document);
+  if (!isRootBody(type)) {
+    context.diagnostics.debug(`${root} done (skipped)`, 0);
+    return { declarations: [emptyAlias(root), ...aliases] };
+  }
+  const declaration = rootDeclaration(root, type, context.options);
+  context.diagnostics.debug(`${root} done`, context.diagnostics.now() - startedAt);
+  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];
+  });
+}
+
+/**
+ * The `inject` text as written (ADR-010, decision 4), without the blank lines around it. The
+ * original reprinted it with the TypeScript printer; text without code printed nothing then.
+ */
+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. `footer` reads the footer's declarations once the
+ * roots are transformed.
+ */
+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 });
+  }
+  const inject = withoutBlankLinesAround(context.options.inject ?? "");
+  if (inject !== "") {
+    declarations.push({ kind: "rawDeclaration", text: inject });
+  }
+  declarations.push(...rootsDeclarations(document, context, footer));
+  return declarations;
+}
+
+/**
+ * The declarations after the footer: an empty `operations` type when the footer has no
+ * operations, and the `--make-paths-enum` enum.
+ */
+export function documentClosing(
+  document: DocumentObject,
+  context: TransformContext,
+  hasOperations: boolean,
+): IrDeclaration[] {
+  const declarations: IrDeclaration[] = [];
+  if (!hasOperations) {
+    declarations.push(emptyAlias(OPERATIONS_NAME));
+  }
+  if (context.options.makePathsEnum && document.paths) {
+    declarations.push(apiPathsEnumDeclaration(document.paths));
+  }
+  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)
+  );
+}