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

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-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_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-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,23 @@ 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 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";
+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 +54,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 +64,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 +71,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);
 }
 

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

@@ -1,12 +1,8 @@
 import { irKeyword, irObject, irProperty } from "../../../domain/ir/constructors.js";
 import type { IrMember, 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, ROOT_POINTER } from "../../../domain/openapi/json-pointer.js";
 import type { OperationObject } from "../../../domain/openapi/operation-object.js";
-import type {
-  ParameterObject,
-  ParameterOrReference,
-} from "../../../domain/openapi/parameter-object.js";
 import {
   ADDITIONAL_OPERATIONS_KEY,
   HTTP_METHODS,
@@ -21,11 +17,17 @@ import type { SchemaLocation } from "../schema/schema-context.js";
 import type { TransformContext } from "../transform-context.js";
 import { documentMember } from "./document-member.js";
 import { operationMembers } from "./operation.js";
+import { mergedParameters } from "./parameter-entries.js";
 import { parametersMember } from "./parameters.js";
 
 /** Redocly reads `#` in an operation ID as a pointer, so it is replaced (upstream issue #1542). */
 const HASH_RE = /#/g;
 
+/** The `operations` key an `operationId` asks for, before a repeated one gets a number. */
+export function operationKeyOf(operationId: string): string {
+  return operationId.replace(HASH_RE, "/");
+}
+
 /** Whether the method has an operation, not removed by `--exclude-deprecated`. */
 function isIncluded(
   operation: OperationEntry | undefined,
@@ -41,26 +43,6 @@ function isIncluded(
   return !(context.options.excludeDeprecated && resolved?.deprecated);
 }
 
-/**
- * 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).
- */
-function mergedParameters(
-  pathItem: PathItemObject,
-  operation: OperationObject,
-  context: TransformContext,
-): ParameterOrReference[] {
-  const byKey = new Map<string, ParameterOrReference>();
-  for (const parameter of [...(pathItem.parameters ?? []), ...(operation.parameters ?? [])]) {
-    const resolved =
-      "$ref" in parameter
-        ? (context.refs.resolve(parameter.$ref) as ParameterObject | undefined)
-        : parameter;
-    byKey.set(`${resolved?.in}-${resolved?.name}`, parameter);
-  }
-  return [...byKey.values()];
-}
-
 /**
  * An operation with an `operationId` goes into the `operations` interface and is referenced from
  * the path item; others are written inline.
@@ -71,17 +53,17 @@ function operationType(
   location: SchemaLocation,
   context: TransformContext,
 ): IrType {
-  const merged = { ...operation, parameters: mergedParameters(pathItem, operation, context) };
+  const merged = { ...operation, parameters: mergedParameters(pathItem, operation, context.refs) };
   if (!operation.operationId) {
     return irObject(operationMembers(merged, location, context));
   }
-  const operationId = operation.operationId.replace(HASH_RE, "/");
+  const operationId = context.footer.operationKey(operationKeyOf(operation.operationId));
   context.footer.addOperation(() =>
     irProperty(toPropertyName(operationId), irObject(operationMembers(merged, location, context)), {
       isReadonly: context.options.immutable,
     }),
   );
-  return refType(createRef(["operations", operationId]));
+  return refType(appendPointer(ROOT_POINTER, ["operations", operationId]));
 }
 
 /** An included operation, the member name it gets and its location below the path item. */
@@ -116,7 +98,7 @@ function methodMember(
     const isReadonly = context.options.immutable;
     return irProperty(toPropertyName(method), irKeyword("never"), { isOptional: true, isReadonly });
   }
-  const path = createRef([location.path, method]);
+  const path = appendPointer(location.path, [method]);
   return operationMember({ name: method, operation, path }, pathItem, location, context);
 }
 
@@ -133,7 +115,7 @@ function additionalOperationsMember(
   const members = entries
     .filter(([, operation]) => isIncluded(operation, context))
     .map(([method, operation]) => {
-      const path = createRef([location.path, ADDITIONAL_OPERATIONS_KEY, method]);
+      const path = appendPointer(location.path, [ADDITIONAL_OPERATIONS_KEY, method]);
       return operationMember({ name: method, operation, path }, pathItem, location, context);
     });
   return members.length > 0
@@ -152,7 +134,7 @@ export function pathItemType(
   location: SchemaLocation,
   context: TransformContext,
 ): IrType {
-  const parametersLocation = { ...location, path: createRef([location.path, "parameters"]) };
+  const parametersLocation = { ...location, path: appendPointer(location.path, ["parameters"]) };
   const members: IrMember[] = [
     parametersMember(pathItem.parameters ?? [], parametersLocation, context),
     ...HTTP_METHODS.map((method) => methodMember(method, pathItem, location, context)),

package/src/application/transform/document/paths-enum.ts

@@ -15,7 +15,7 @@ import type { EnumMemberMetadata } from "../schema/schema-context.js";
 const PARAMETER_SEGMENT_RE = /^(?:{(.+)}|:(.+))$/;
 /** Characters not allowed in an enum key, or a `{param}` / `:param` part (first match only). */
 const INVALID_KEY_PART_RE = /{.*}|:.*|[^a-zA-Z\d_]+/;
-const API_PATHS_NAME = "ApiPaths";
+export const API_PATHS_NAME = "ApiPaths";
 const METHODS: ReadonlySet<string> = new Set<PathItemMethod>([...HTTP_METHODS, QUERY_METHOD]);
 
 /** The members of the `ApiPaths` enum (`--make-paths-enum`). */

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

@@ -2,7 +2,7 @@ import { irIntersection, irObject, irProperty, irRaw } from "../../../domain/ir/
 import type { IrMember, IrType } from "../../../domain/ir/nodes.js";
 import { toPropertyName } from "../../../domain/ir/property-name.js";
 import { escapeTemplateText } from "../../../domain/ir/raw-text-escapes.js";
-import { createRef } from "../../../domain/openapi/json-pointer.js";
+import { appendPointer, ROOT_POINTER } from "../../../domain/openapi/json-pointer.js";
 import type { OperationObject } from "../../../domain/openapi/operation-object.js";
 import type {
   ParameterObject,
@@ -145,7 +145,11 @@ function pathItemMember(
   context: TransformContext,
 ): PathMember {
   const isReadonly = context.options.immutable;
-  const type = pathItemType(pathItem, { path: createRef(["paths", url]) }, context);
+  const type = pathItemType(
+    pathItem,
+    { path: appendPointer(ROOT_POINTER, ["paths", url]) },
+    context,
+  );
   const parts =
     context.options.pathParamsAsTypes && url.includes("{")
       ? pathTemplateParts(url, pathItem, context)

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

@@ -0,0 +1,146 @@
+import { irReference } from "../../../domain/ir/constructors.js";
+import type { IrType } from "../../../domain/ir/nodes.js";
+import {
+  appendPointer,
+  parseRefPointer,
+  ROOT_POINTER,
+} from "../../../domain/openapi/json-pointer.js";
+import type { OperationObject } from "../../../domain/openapi/operation-object.js";
+import {
+  type ParameterObject,
+  type ParameterOrReference,
+  QUERYSTRING_LOCATION,
+} from "../../../domain/openapi/parameter-object.js";
+import {
+  ADDITIONAL_OPERATIONS_KEY,
+  HTTP_METHODS,
+  type PathItemObject,
+  QUERY_METHOD,
+} from "../../../domain/openapi/path-item-object.js";
+import { indexBy, refType } from "../ref-type.js";
+import type { RefResolver } from "../schema/schema-context.js";
+import type { TransformContext } from "../transform-context.js";
+import { mergedParameters, type ParameterEntry, parameterEntries } from "./parameter-entries.js";
+
+/**
+ * The type of a parameter `$ref`. The original indexed the parameter's location and name
+ * (`refType`): `#/paths/~1a/get/parameters/0` gave
+ * `paths["/a"]["get"]["parameters"]["query"]["q"]`.
+ * Where the generated type differs, that does not compile, and only there it changes:
+ *
+ * - A location whose parameters are all optional is an optional member (`query?:`), so indexing it
+ *   fails (TS2339); it is wrapped in `NonNullable` before the name is indexed.
+ * - An OpenAPI 3.2 `in: querystring` parameter is the whole `query` member (ADR-020), not a member
+ *   `querystring`, so the pointer reads `["query"]`.
+ *
+ * A `$ref` to a component parameter, or into a list the generator types elsewhere (a `$ref` path
+ * item or operation, a callback), keeps the original type.
+ */
+
+const INDEX_RE = /^\d+$/;
+const OPERATION_KEYS: ReadonlySet<string> = new Set([...HTTP_METHODS, QUERY_METHOD]);
+
+/** A `parameters/N` pointer, split into its root and the segments of the list's owner. */
+interface ParameterListPointer {
+  readonly root: string;
+  readonly owner: readonly string[];
+}
+
+function listPointerOf(ref: string): ParameterListPointer | null {
+  if (!ref.startsWith(`${ROOT_POINTER}/`)) {
+    return null;
+  }
+  const [root, ...segments] = parseRefPointer(ref);
+  const [list, position] = segments.slice(-2);
+  const isList = list === "parameters" && position !== undefined && INDEX_RE.test(position);
+  return root !== undefined && isList ? { root, owner: segments.slice(0, -2) } : null;
+}
+
+function pointerTo(root: string, segments: readonly string[]): string {
+  return appendPointer(ROOT_POINTER, [root, ...segments]);
+}
+
+/** Whether the segments name a path item that `pathItemType` types in place. */
+function isPathItemAt(root: string, segments: readonly string[]): boolean {
+  const isNamedRoot = root === "paths" || root === "webhooks";
+  return (
+    (isNamedRoot && segments.length === 1) ||
+    (root === "components" && segments[0] === "pathItems" && segments.length === 2)
+  );
+}
+
+/** The segments of the path item that holds the operation at `owner`, or null. */
+function pathItemOfOperation(root: string, owner: readonly string[]): readonly string[] | null {
+  const method = owner.at(-1) ?? "";
+  if (OPERATION_KEYS.has(method) && isPathItemAt(root, owner.slice(0, -1))) {
+    return owner.slice(0, -1);
+  }
+  const isAdditional = owner.at(-2) === ADDITIONAL_OPERATIONS_KEY;
+  return isAdditional && isPathItemAt(root, owner.slice(0, -2)) ? owner.slice(0, -2) : null;
+}
+
+function documentNode<T>(refs: RefResolver, root: string, segments: readonly string[]): T | null {
+  const node = refs.resolve(pointerTo(root, segments));
+  const isTypedHere = typeof node === "object" && node !== null && !("$ref" in node);
+  return isTypedHere ? (node as T) : null;
+}
+
+/** The parameters the generator types at the list's owner; null where it types them elsewhere. */
+function typedParameters(
+  pointer: ParameterListPointer,
+  refs: RefResolver,
+): readonly ParameterOrReference[] | null {
+  const { root, owner } = pointer;
+  if (isPathItemAt(root, owner)) {
+    return documentNode<PathItemObject>(refs, root, owner)?.parameters ?? null;
+  }
+  const pathItemSegments = pathItemOfOperation(root, owner);
+  const pathItem = pathItemSegments && documentNode<PathItemObject>(refs, root, pathItemSegments);
+  const operation = pathItem && documentNode<OperationObject>(refs, root, owner);
+  return pathItem && operation ? mergedParameters(pathItem, operation, refs) : null;
+}
+
+/** A location member is optional when none of its parameters is required (`locationParts`). */
+function isLocationOptional(entries: readonly ParameterEntry[], location: string): boolean {
+  return entries
+    .filter((entry) => entry.resolved?.in === location)
+    .every((entry) => location !== "path" && !entry.resolved?.required);
+}
+
+/** The corrected type, or null where the original type compiles or no correction applies. */
+function correctedType(
+  listType: IrType,
+  entries: readonly ParameterEntry[],
+  parameter: ParameterObject,
+): IrType | null {
+  if (parameter.in === QUERYSTRING_LOCATION) {
+    // Next to `in: query` parameters it is not in the generated types (QUERYSTRING_NEXT_TO_QUERY).
+    const isTyped = !entries.some((entry) => entry.resolved?.in === "query");
+    return isTyped ? indexBy(listType, "query") : null;
+  }
+  if (!isLocationOptional(entries, parameter.in)) {
+    return null;
+  }
+  const location = irReference("NonNullable", [indexBy(listType, parameter.in)]);
+  return indexBy(location, parameter.name);
+}
+
+/** The type of a parameter `$ref` whose target resolved to `resolved`; see the module comment. */
+export function referencedParameterType(
+  ref: string,
+  resolved: ParameterObject,
+  context: TransformContext,
+): IrType {
+  // A `$ref` that resolves to another `$ref` is not a parameter object yet: index it as a path.
+  if ((resolved as { $ref?: unknown }).$ref) {
+    return refType(ref, { parameter: null });
+  }
+  const original = refType(ref, { parameter: { in: resolved.in, name: resolved.name } });
+  const pointer = listPointerOf(ref);
+  const parameters = pointer && typedParameters(pointer, context.refs);
+  if (pointer === null || parameters === null) {
+    return original;
+  }
+  const listType = refType(pointerTo(pointer.root, [...pointer.owner, "parameters"]));
+  return correctedType(listType, parameterEntries(parameters, context), resolved) ?? original;
+}

package/src/application/transform/document/request-body.ts

@@ -1,7 +1,7 @@
 import { irKeyword, irObject, irProperty } from "../../../domain/ir/constructors.js";
 import type { IrMember, 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 type { RequestBodyObject } from "../../../domain/openapi/request-body-object.js";
 import { documentEntries } from "../document-entries.js";
 import type { SchemaContext, SchemaLocation } from "../schema/schema-context.js";
@@ -18,7 +18,7 @@ function contentMembers(
 ): IrMember[] {
   const entries = documentEntries(requestBody.content ?? {}, context.options);
   return entries.map(([contentType, entry]) => {
-    const path = createRef([location.path, "content", contentType]);
+    const path = appendPointer(location.path, ["content", contentType]);
     const type = contentEntryType(entry, { ...location, path }, context);
     return documentMember(contentType, type, entry, { isReadonly: context.options.immutable });
   });

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

@@ -6,7 +6,7 @@ import {
 } from "../../../domain/ir/constructors.js";
 import type { IrMember, 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 {
   isMediaTypeComponentRef,
   type MediaTypeObject,
@@ -34,7 +34,7 @@ function headerMember(
     ? refType(header.$ref)
     : headerType(
         header,
-        { ...location, path: createRef([location.path, "headers", name]) },
+        { ...location, path: appendPointer(location.path, ["headers", name]) },
         context,
       );
   return documentMember(name, type, header, {
@@ -79,7 +79,7 @@ function contentMember(
 ): IrPropertySignature {
   const entries = documentEntries(response.content ?? {}, context.options);
   const members = entries.map(([contentType, entry]) => {
-    const path = createRef([location.path, "content", contentType]);
+    const path = appendPointer(location.path, ["content", contentType]);
     const type = mediaTypeEntryType(entry, { ...location, path }, context);
     return documentMember(contentType, type, entry, { isReadonly: context.options.immutable });
   });

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

@@ -1,6 +1,6 @@
 import { irKeyword, irObject } 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 { ResponsesObject } from "../../../domain/openapi/response-object.js";
 import { documentEntries } from "../document-entries.js";
 import { refType } from "../ref-type.js";
@@ -20,7 +20,7 @@ export function responsesType(
         ? refType(response.$ref)
         : responseType(
             response,
-            { ...location, path: createRef([location.path, "responses", code]) },
+            { ...location, path: appendPointer(location.path, ["responses", code]) },
             context,
           );
     return documentMember(code, type, response, { isReadonly: context.options.immutable });

package/src/application/transform/document/root-type-aliases.ts

@@ -2,6 +2,8 @@ import { irRaw } from "../../../domain/ir/constructors.js";
 import type { IrDeclaration, IrTypeAliasDeclaration } from "../../../domain/ir/nodes.js";
 import { escapeSingleQuotedText } from "../../../domain/ir/raw-text-escapes.js";
 import type { ComponentKind } from "../../../domain/openapi/components-object.js";
+import { freeNumberedName } from "../numbered-names.js";
+import { typeNamesDeclaredBy } from "./declared-type-names.js";
 import { globalTypeReferences } from "./global-type-references.js";
 
 /** The `--root-types` aliases: `export type Pet = components['schemas']['Pet'];`. */
@@ -25,7 +27,8 @@ export function rootTypeAlias(
   };
 }
 
-function isRootTypeAlias(declaration: IrDeclaration): declaration is IrTypeAliasDeclaration {
+/** Whether the declaration is a `--root-types` alias, which gives way to every other name. */
+export function isRootTypeAlias(declaration: IrDeclaration): declaration is IrTypeAliasDeclaration {
   return (
     declaration.kind === "typeAlias" &&
     declaration.type.kind === "raw" &&
@@ -33,23 +36,6 @@ function isRootTypeAlias(declaration: IrDeclaration): declaration is IrTypeAlias
   );
 }
 
-/**
- * The type names the footer declares that an alias must not take: enums, and helper types such as
- * `WithRequired`. Value declarations (`--enum-values` arrays) live in another namespace.
- */
-function footerTypeNames(declarations: readonly IrDeclaration[]): Set<string> {
-  return new Set(
-    declarations.flatMap((declaration) => {
-      if (declaration.kind === "enum") {
-        return [declaration.name];
-      }
-      return declaration.kind === "rawDeclaration" && declaration.name !== undefined
-        ? [declaration.name]
-        : [];
-    }),
-  );
-}
-
 function declaredNames(declarations: readonly IrDeclaration[]): Set<string> {
   return new Set(
     declarations.flatMap((declaration) =>
@@ -58,21 +44,15 @@ function declaredNames(declarations: readonly IrDeclaration[]): Set<string> {
   );
 }
 
-function freeName(name: string, taken: ReadonlySet<string>): string {
-  let candidate = `${name}_2`;
-  for (let counter = 3; taken.has(candidate); counter++) {
-    candidate = `${name}_${counter}`;
-  }
-  return candidate;
-}
-
 /**
- * Rename each root alias whose name an enum or a helper type of the footer also declares, or that
- * shadows a TypeScript global type the output refers to (`Record` in `Record<string, never>`), to
- * the next free `Name_2`, `Name_3`, … (the suffix `--root-types` uses for its own conflicts). The
- * footer and the globals keep their names, because the generated types refer to them. Before, the
- * output did not compile (enums: upstream #2099, #2341, #2206; helpers: a schema named
- * `WithRequired`, roadmap R11; globals: TS2315). Other declarations are returned unchanged.
+ * Rename each root alias whose name another declaration of the output also takes (an enum, a
+ * helper type, the `--make-paths-enum` enum `ApiPaths`, a root interface, `--read-write-markers`
+ * or `inject` types), or that shadows a TypeScript global type the output refers to (`Record` in
+ * `Record<string, never>`), to the next free `Name_2`, `Name_3`, … (the suffix `--root-types` uses
+ * for its own conflicts). The others and the globals keep their names, because the generated
+ * types refer to them. Before, the output did not compile (enums: upstream #2099, #2341, #2206;
+ * helpers: a schema named `WithRequired`, roadmap R11; globals: TS2315; `ApiPaths`: TS2567).
+ * Other declarations are returned unchanged.
  *
  * With the `root-type-numbering` fix (ADR-021, roadmap R13, backlog 30) the body also holds the
  * aliases a later schema of one exported name took the name from, after the other aliases and
@@ -85,11 +65,10 @@ export function renameTakenAliases<T extends IrDeclaration>(
   footer: readonly IrDeclaration[],
   closing: readonly IrDeclaration[] = [],
 ): T[] {
-  const reserved = footerTypeNames(footer);
-  for (const name of globalTypeReferences([...body, ...footer, ...closing])) {
-    reserved.add(name);
-  }
-  const taken = declaredNames([...body, ...footer, ...closing]);
+  const all = [...body, ...footer, ...closing];
+  const others = all.filter((declaration) => !isRootTypeAlias(declaration));
+  const reserved = new Set([...typeNamesDeclaredBy(others), ...globalTypeReferences(all)]);
+  const taken = new Set([...declaredNames(all), ...typeNamesDeclaredBy(all)]);
   const aliasNames = new Set<string>();
   return body.map((declaration) => {
     if (!isRootTypeAlias(declaration)) {
@@ -100,7 +79,7 @@ export function renameTakenAliases<T extends IrDeclaration>(
     if (!isRepeated && !reserved.has(declaration.name)) {
       return declaration;
     }
-    const name = freeName(declaration.name, taken);
+    const name = freeNumberedName(declaration.name, taken);
     taken.add(name);
     return { ...declaration, name };
   });

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

@@ -1,3 +1,4 @@
+import { appendAll } from "../../../domain/append-all.js";
 import type {
   IrIndexSignature,
   IrMember,
@@ -156,7 +157,7 @@ export class TypeResolution {
       if (objects === null) {
         return null;
       }
-      parts.push(...objects);
+      appendAll(parts, objects);
     }
     return parts;
   }