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

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,10 +16,12 @@ 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;
@@ -154,6 +162,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 +229,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,
+  });
 }
 
 /**

package/src/application/transform/document/path-key-overlaps.ts

@@ -6,6 +6,8 @@
  * TS2413). These functions find the signatures that cover another key the checker rejects.
  */
 
+import { isAssignableToTemplate, type TemplateShape } from "./template-key-match.js";
+
 /** A placeholder of a template literal type, by the type it stands for. */
 export type PathPlaceholder = "string" | "number" | "boolean";
 
@@ -21,89 +23,176 @@ export type PathKey =
 
 const BOOLEAN_TEXTS: readonly string[] = ["true", "false"];
 
-/** The text one placeholder stands for in a sample of a template key. */
-const SAMPLE_TEXTS: Readonly<Record<PathPlaceholder, string>> = {
-  string: "",
-  number: "0",
-  boolean: "true",
-};
-
-/** TypeScript's rule for `${number}`: a text that converts to a finite number. */
-function isNumberText(text: string): boolean {
-  return text !== "" && Number.isFinite(Number(text));
+/** The shapes after one more part; a boolean placeholder doubles them, as TypeScript does. */
+function withPart(shapes: readonly TemplateShape[], part: PathKeyPart): TemplateShape[] {
+  return shapes.flatMap((shape): TemplateShape[] => {
+    const lead = shape.texts.slice(0, -1);
+    // A shape has one text more than it has placeholders, so it always has a last text.
+    const last = shape.texts[shape.texts.length - 1] as string;
+    if (part.kind === "text") {
+      return [{ texts: [...lead, last + part.text], types: shape.types }];
+    }
+    if (part.type === "boolean") {
+      return BOOLEAN_TEXTS.map((text) => ({ texts: [...lead, last + text], types: shape.types }));
+    }
+    return [{ texts: [...shape.texts, ""], types: [...shape.types, part.type] }];
+  });
 }
 
-function isPlaceholderText(type: PathPlaceholder, text: string): boolean {
-  if (type === "number") {
-    return isNumberText(text);
+/**
+ * The key types TypeScript makes of a key: a literal is one text; a template is one shape, or a
+ * union of shapes when `${boolean}` is in it (`` `/a/${boolean}` `` is `"/a/true" | "/a/false"`).
+ */
+function shapesOf(key: PathKey): readonly TemplateShape[] {
+  if (key.kind === "literal") {
+    return [{ texts: [key.url], types: [] }];
   }
-  return type === "boolean" ? BOOLEAN_TEXTS.includes(text) : true;
+  return key.parts.reduce<TemplateShape[]>(withPart, [{ texts: [""], types: [] }]);
 }
 
-/** Whether `text` from `start` on is one of the strings the parts from `index` on describe. */
-function matchesFrom(
-  text: string,
-  start: number,
-  parts: readonly PathKeyPart[],
-  index: number,
+/**
+ * Whether a signature checks the covered key: every type of the covered key is assignable to one
+ * of the signature's types. A shape without placeholders (a boolean-only template) is a string
+ * literal, which is no signature, so the targets leave it out.
+ */
+function isCoveredBy(
+  sources: readonly TemplateShape[],
+  targets: readonly TemplateShape[],
 ): boolean {
-  const part = parts[index];
-  if (part === undefined) {
-    return start === text.length;
-  }
-  if (part.kind === "text") {
-    return (
-      text.startsWith(part.text, start) &&
-      matchesFrom(text, start + part.text.length, parts, index + 1)
-    );
-  }
-  for (let end = start; end <= text.length; end += 1) {
-    if (
-      isPlaceholderText(part.type, text.slice(start, end)) &&
-      matchesFrom(text, end, parts, index + 1)
-    ) {
-      return true;
+  return (
+    sources.length > 0 &&
+    sources.every((source) => targets.some((target) => isAssignableToTemplate(source, target)))
+  );
+}
+
+/** Whether TypeScript rejects the key at `covered` for the signature at `covering`. */
+export type CoverRejection = (covering: number, covered: number) => boolean;
+
+/** Without type information every covered key counts. */
+const EVERY_COVER_REJECTED: CoverRejection = () => true;
+
+/**
+ * The key types TypeScript checks against a signature: a literal's, or a template's signature
+ * types. A boolean-only template is no signature (TS1337), so the checker neither checks it nor
+ * checks anything against it; a repeated one is still reported (TS2374, see `repeatedTemplates`).
+ */
+function checkedShapes(key: PathKey): readonly TemplateShape[] {
+  const shapes = shapesOf(key);
+  return key.kind === "literal" ? shapes : shapes.filter((shape) => shape.types.length > 0);
+}
+
+/** A checked key: the key, the shapes TypeScript checks, and its template identity. */
+interface CheckedKey {
+  readonly key: PathKey;
+  readonly shapes: readonly TemplateShape[];
+  /** The key types written as one string, for templates; null for a literal. */
+  readonly template: string | null;
+}
+
+function checkedKeyOf(key: PathKey): CheckedKey {
+  const template = key.kind === "template" ? JSON.stringify(shapesOf(key)) : null;
+  return { key, shapes: checkedShapes(key), template };
+}
+
+/**
+ * The templates written more than once, as paths that differ only in parameter names give
+ * (`/a/{id}`, `/a/{name}`). OpenAPI forbids such paths, and one object with both signatures fails
+ * to compile whatever their types (TS2374), so each always counts as covering the other.
+ */
+function repeatedTemplates(checked: readonly CheckedKey[]): ReadonlySet<string> {
+  const seen = new Set<string>();
+  const repeated = new Set<string>();
+  for (const { template } of checked) {
+    if (template !== null) {
+      (seen.has(template) ? repeated : seen).add(template);
     }
   }
-  return false;
+  return repeated;
 }
 
 /**
- * One string of the key. If a template key is covered, every string of it is, so a sample that is
- * not covered proves the key is not; a sample that is covered may over-report, which only moves a
- * signature that did not need it (the types stay the same, see `pathsObjectType`).
+ * The checked keys by the first text of each of their shapes, sorted. A key type is assignable to
+ * a template only when its first text starts with the template's first text (both branches of
+ * `isAssignableToTemplate`), so the keys a template can cover are one run of this list. Without
+ * it the check compares every pair of keys, which takes minutes for 10 000 paths.
  */
-function sampleOf(key: PathKey): string {
-  if (key.kind === "literal") {
-    return key.url;
+interface StartTextIndex {
+  readonly starts: readonly string[];
+  readonly keyIndexes: readonly number[];
+}
+
+/** Code unit order: in it the strings that start with one prefix are adjacent. */
+function compareCodeUnits(left: string, right: string): number {
+  if (left === right) {
+    return 0;
   }
-  return key.parts
-    .map((part) => (part.kind === "text" ? part.text : SAMPLE_TEXTS[part.type]))
-    .join("");
+  return left < right ? -1 : 1;
 }
 
-/** Whether TypeScript rejects the key at `covered` for the signature at `covering`. */
-export type CoverRejection = (covering: number, covered: number) => boolean;
+function startTextIndexOf(checked: readonly CheckedKey[]): StartTextIndex {
+  const entries = checked.flatMap(({ shapes }, keyIndex) =>
+    shapes.map((shape) => ({ start: shape.texts[0] as string, keyIndex })),
+  );
+  entries.sort((left, right) => compareCodeUnits(left.start, right.start));
+  return {
+    starts: entries.map((entry) => entry.start),
+    keyIndexes: entries.map((entry) => entry.keyIndex),
+  };
+}
 
-/** Without type information every covered key counts. */
-const EVERY_COVER_REJECTED: CoverRejection = () => true;
+/** The indexes of the keys with a shape whose first text starts with one of the prefixes. */
+function keysStartingWith(index: StartTextIndex, prefixes: readonly string[]): Set<number> {
+  const found = new Set<number>();
+  for (const prefix of prefixes) {
+    let low = 0;
+    let high = index.starts.length;
+    while (low < high) {
+      const middle = (low + high) >> 1;
+      if ((index.starts[middle] as string) < prefix) {
+        low = middle + 1;
+      } else {
+        high = middle;
+      }
+    }
+    for (let at = low; at < index.starts.length; at += 1) {
+      if (!(index.starts[at] as string).startsWith(prefix)) {
+        break;
+      }
+      found.add(index.keyIndexes[at] as number);
+    }
+  }
+  return found;
+}
 
-/** The indexes of the template keys that cover another key of the list, where it is rejected. */
+/**
+ * The indexes of the template keys that cover another key of the list, where it is rejected, or
+ * that repeat another template key. A template covers the keys TypeScript checks against it, the
+ * ones its own matching accepts (see `template-key-match.ts`), not every string it stands for:
+ * `` `/a/b/${number}` `` is no `` `/${string}/${number}` `` to the checker, which does not
+ * backtrack, so that pair is never checked.
+ */
 export function coveringTemplateKeys(
   keys: readonly PathKey[],
   isRejected: CoverRejection = EVERY_COVER_REJECTED,
 ): ReadonlySet<number> {
+  const checked = keys.map(checkedKeyOf);
+  const repeated = repeatedTemplates(checked);
+  const startTexts = startTextIndexOf(checked);
   const covering = new Set<number>();
-  keys.forEach((key, index) => {
-    if (key.kind !== "template") {
+  checked.forEach(({ template, shapes: targets }, index) => {
+    if (template === null) {
       return;
     }
-    const isCovering = keys.some(
-      (other, otherIndex) =>
-        otherIndex !== index &&
-        matchesFrom(sampleOf(other), 0, key.parts, 0) &&
-        isRejected(index, otherIndex),
-    );
+    const prefixes = targets.map((target) => target.texts[0] as string);
+    const candidates = [...keysStartingWith(startTexts, prefixes)].sort((a, b) => a - b);
+    const isCovering =
+      repeated.has(template) ||
+      candidates.some(
+        (otherIndex) =>
+          otherIndex !== index &&
+          isCoveredBy((checked[otherIndex] as CheckedKey).shapes, targets) &&
+          isRejected(index, otherIndex),
+      );
     if (isCovering) {
       covering.add(index);
     }

package/src/application/transform/document/path-template-replace.ts

@@ -0,0 +1,90 @@
+import type { PathKeyPart, PathPlaceholder } from "./path-key-overlaps.js";
+
+/**
+ * The `--path-params-as-types` key as the original builds it: each `{name}` match, in URL order,
+ * replaces the first occurrence of its text in the key so far. A parameter named `number`,
+ * `string` or `boolean` can so hit the `${number}` an earlier parameter got: of
+ * `/a/{id}/b/{number}` the original makes `/a/$${number}/b/{number}`. That output compiles, so it
+ * stays the default (ADR-021); the `path-param-type-names` fix gives every match its own
+ * placeholder.
+ */
+
+/** One `{name}` of the URL and the placeholder of its parameter's type. */
+export interface PathParameterMatch {
+  readonly match: string;
+  readonly type: PathPlaceholder;
+}
+
+/**
+ * One UTF-16 code unit of the key so far (`indexOf` counts those): URL text, or a unit of the
+ * placeholder that the match at `owner` inserted.
+ */
+interface KeyUnit {
+  readonly unit: string;
+  readonly owner: number | null;
+}
+
+const URL_TEXT = null;
+
+/** `${type}`: the text of a template literal type placeholder. */
+export function placeholderText(type: PathPlaceholder): string {
+  return `\${${type}}`;
+}
+
+/** The key's units after each match replaced the first occurrence of its text. */
+function replacedUnits(url: string, matches: readonly PathParameterMatch[]): readonly KeyUnit[] {
+  const units: KeyUnit[] = url.split("").map((unit) => ({ unit, owner: URL_TEXT }));
+  matches.forEach(({ match, type }, owner) => {
+    const at = units
+      .map(({ unit }) => unit)
+      .join("")
+      .indexOf(match);
+    if (at >= 0) {
+      const inserted = placeholderText(type)
+        .split("")
+        .map((unit) => ({ unit, owner }));
+      units.splice(at, match.length, ...inserted);
+    }
+  });
+  return units;
+}
+
+/** The placeholders, by match, that no later match cut into. */
+function intactPlaceholders(
+  units: readonly KeyUnit[],
+  matches: readonly PathParameterMatch[],
+): ReadonlyMap<number, PathPlaceholder> {
+  const intact = new Map<number, PathPlaceholder>();
+  matches.forEach(({ type }, owner) => {
+    const left = units.filter((unit) => unit.owner === owner).length;
+    if (left === placeholderText(type).length) {
+      intact.set(owner, type);
+    }
+  });
+  return intact;
+}
+
+/**
+ * The key as parts. What is left of a placeholder that a later match cut into (the `$` of
+ * `$${number}`) is text, as TypeScript reads it.
+ */
+export function replacedTemplateParts(
+  url: string,
+  matches: readonly PathParameterMatch[],
+): PathKeyPart[] {
+  const units = replacedUnits(url, matches);
+  const intact = intactPlaceholders(units, matches);
+  const parts: PathKeyPart[] = [];
+  let text = "";
+  units.forEach(({ unit, owner }, index) => {
+    const type = owner === URL_TEXT ? undefined : intact.get(owner);
+    if (type === undefined) {
+      text += unit;
+    } else if (units[index - 1]?.owner !== owner) {
+      parts.push({ kind: "text", text }, { kind: "placeholder", type });
+      text = "";
+    }
+  });
+  parts.push({ kind: "text", text });
+  return parts;
+}