openapi-typesafe 0.0.0 → 1.0.0-rc.1

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

@@ -0,0 +1,265 @@
+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";
+import {
+  PARAMETER_LOCATIONS,
+  type ParameterLocation,
+  type ParameterObject,
+  type ParameterOrReference,
+  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;
+
+/** 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) => ({
+    name: match.slice(1, -1),
+    in: "path",
+    required: true,
+    schema: { type: "string" },
+  }));
+}
+
+/** `--generate-path-params`: add the path template parameters the list does not define. */
+function withPathTemplateParameters(
+  parameters: readonly ParameterOrReference[],
+  location: SchemaLocation,
+  context: TransformContext,
+): ParameterOrReference[] {
+  const result = [...parameters];
+  if (!context.options.generatePathParams || !location.path) {
+    return result;
+  }
+  for (const parameter of pathTemplateParameters(location.path)) {
+    const isDefined = result.some((candidate) => {
+      const resolved = resolveParameter(candidate, context);
+      return resolved?.in === "path" && resolved.name === parameter.name;
+    });
+    if (!isDefined) {
+      result.push(parameter);
+    }
+  }
+  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"
+    ? toPropertyName(name)
+    : { 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]);
+  return "$ref" in original
+    ? referencedParameterType(original.$ref, resolved)
+    : parameterType(resolved, { ...location, path }, context);
+}
+
+function parameterMember(
+  entry: ResolvedEntry,
+  location: SchemaLocation,
+  context: TransformContext,
+): IrPropertySignature {
+  const { resolved } = entry;
+  const property = irProperty(parameterName(resolved.name), entryType(entry, location, context), {
+    isOptional: resolved.in !== "path" && !resolved.required,
+    isReadonly: context.options.immutable,
+  });
+  return withSchemaComment(property, resolved);
+}
+
+/**
+ * The `query` member typed by an `in: querystring` parameter (OpenAPI 3.2, ADR-020): the parameter
+ * is the whole query string. Null when there is none, or when `in: query` parameters sit next to
+ * it, which 3.2 does not allow; those keep their types, and a warning names the parameter.
+ */
+function querystringMember(
+  entries: readonly ParameterEntry[],
+  location: SchemaLocation,
+  context: TransformContext,
+): IrPropertySignature | null {
+  const querystring = entries.find(
+    (entry): entry is ResolvedEntry => entry.resolved?.in === QUERYSTRING_LOCATION,
+  );
+  if (!querystring || entries.some((entry) => entry.resolved?.in === "query")) {
+    return null;
+  }
+  const property = irProperty(toPropertyName("query"), entryType(querystring, location, context), {
+    isOptional: !querystring.resolved.required,
+    isReadonly: context.options.immutable,
+  });
+  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,
+  entries: readonly ParameterEntry[],
+  location: SchemaLocation,
+  context: TransformContext,
+): IrPropertySignature {
+  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,
+  });
+}
+
+/**
+ * The `parameters` property of an operation or path item: one member per location, each an object
+ * of that location's parameters. `location.path` is the path template for
+ * `--generate-path-params`.
+ */
+export function parametersMember(
+  parameters: readonly ParameterOrReference[],
+  location: SchemaLocation,
+  context: TransformContext,
+): IrPropertySignature {
+  const entries = parameterEntries(
+    withPathTemplateParameters(parameters, location, context),
+    context,
+  );
+  const querystring = querystringMember(entries, location, context);
+  const members = PARAMETER_LOCATIONS.map((parameterIn) =>
+    parameterIn === "query" && querystring
+      ? querystring
+      : locationMember(parameterIn, entries, location, context),
+  );
+  return irProperty(toPropertyName("parameters"), irObject(members), {
+    isReadonly: context.options.immutable,
+  });
+}

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

@@ -0,0 +1,168 @@
+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 type { OperationObject } from "../../../domain/openapi/operation-object.js";
+import type {
+  ParameterObject,
+  ParameterOrReference,
+} from "../../../domain/openapi/parameter-object.js";
+import {
+  ADDITIONAL_OPERATIONS_KEY,
+  HTTP_METHODS,
+  type OperationEntry,
+  type PathItemMethod,
+  type PathItemObject,
+  QUERY_METHOD,
+} from "../../../domain/openapi/path-item-object.js";
+import { documentEntries } from "../document-entries.js";
+import { refType } from "../ref-type.js";
+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 { parametersMember } from "./parameters.js";
+
+/** Redocly reads `#` in an operation ID as a pointer, so it is replaced (upstream issue #1542). */
+const HASH_RE = /#/g;
+
+/** Whether the method has an operation, not removed by `--exclude-deprecated`. */
+function isIncluded(
+  operation: OperationEntry | undefined,
+  context: TransformContext,
+): operation is OperationEntry {
+  if (!operation) {
+    return false;
+  }
+  const resolved =
+    "$ref" in operation
+      ? (context.refs.resolve(operation.$ref) as OperationObject | undefined)
+      : operation;
+  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.
+ */
+function operationType(
+  pathItem: PathItemObject,
+  operation: OperationObject,
+  location: SchemaLocation,
+  context: TransformContext,
+): IrType {
+  const merged = { ...operation, parameters: mergedParameters(pathItem, operation, context) };
+  if (!operation.operationId) {
+    return irObject(operationMembers(merged, location, context));
+  }
+  const operationId = operation.operationId.replace(HASH_RE, "/");
+  context.footer.addOperation(() =>
+    irProperty(toPropertyName(operationId), irObject(operationMembers(merged, location, context)), {
+      isReadonly: context.options.immutable,
+    }),
+  );
+  return refType(createRef(["operations", operationId]));
+}
+
+/** An included operation, the member name it gets and its location below the path item. */
+interface DeclaredOperation {
+  readonly name: string;
+  readonly operation: OperationEntry;
+  readonly path: string;
+}
+
+function operationMember(
+  { name, operation, path }: DeclaredOperation,
+  pathItem: PathItemObject,
+  location: SchemaLocation,
+  context: TransformContext,
+): IrPropertySignature {
+  const type =
+    "$ref" in operation
+      ? refType(operation.$ref)
+      : operationType(pathItem, operation, { ...location, path }, context);
+  return documentMember(name, type, operation, { isReadonly: context.options.immutable });
+}
+
+/** A method member: the operation, or `?: never` when there is none or it is excluded. */
+function methodMember(
+  method: PathItemMethod,
+  pathItem: PathItemObject,
+  location: SchemaLocation,
+  context: TransformContext,
+): IrPropertySignature {
+  const operation = pathItem[method];
+  if (!isIncluded(operation, context)) {
+    const isReadonly = context.options.immutable;
+    return irProperty(toPropertyName(method), irKeyword("never"), { isOptional: true, isReadonly });
+  }
+  const path = createRef([location.path, method]);
+  return operationMember({ name: method, operation, path }, pathItem, location, context);
+}
+
+/**
+ * `additionalOperations` (OpenAPI 3.2): the included operations keyed by their exact method name,
+ * or null when the path item has none left.
+ */
+function additionalOperationsMember(
+  pathItem: PathItemObject,
+  location: SchemaLocation,
+  context: TransformContext,
+): IrPropertySignature | null {
+  const entries = documentEntries(pathItem.additionalOperations ?? {}, context.options);
+  const members = entries
+    .filter(([, operation]) => isIncluded(operation, context))
+    .map(([method, operation]) => {
+      const path = createRef([location.path, ADDITIONAL_OPERATIONS_KEY, method]);
+      return operationMember({ name: method, operation, path }, pathItem, location, context);
+    });
+  return members.length > 0
+    ? irProperty(toPropertyName(ADDITIONAL_OPERATIONS_KEY), irObject(members), {
+        isReadonly: context.options.immutable,
+      })
+    : null;
+}
+
+/**
+ * A path item (OpenAPI 3.2 §4.8.9): its `parameters`, one member per HTTP method, then `query` and
+ * `additionalOperations` when the path item declares them (ADR-020).
+ */
+export function pathItemType(
+  pathItem: PathItemObject,
+  location: SchemaLocation,
+  context: TransformContext,
+): IrType {
+  const parametersLocation = { ...location, path: createRef([location.path, "parameters"]) };
+  const members: IrMember[] = [
+    parametersMember(pathItem.parameters ?? [], parametersLocation, context),
+    ...HTTP_METHODS.map((method) => methodMember(method, pathItem, location, context)),
+  ];
+  if (pathItem[QUERY_METHOD] !== undefined) {
+    members.push(methodMember(QUERY_METHOD, pathItem, location, context));
+  }
+  const additionalOperations = additionalOperationsMember(pathItem, location, context);
+  if (additionalOperations) {
+    members.push(additionalOperations);
+  }
+  return irObject(members);
+}

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

@@ -0,0 +1,201 @@
+/**
+ * `--path-params-as-types` overlaps (roadmap R10.2, backlog 28). A path key with parameters is an
+ * index signature over a template literal type, such as `` `/apps/${string}` ``. `${string}` also
+ * matches `/`, so that signature covers `/apps/regions` and `` `/apps/${string}/restart` `` as
+ * well, and TypeScript requires the covered keys' types to be assignable to its type (TS2411,
+ * 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";
+
+/** One part of a path key: text, or a placeholder. */
+export type PathKeyPart =
+  | { readonly kind: "text"; readonly text: string }
+  | { readonly kind: "placeholder"; readonly type: PathPlaceholder };
+
+/** A path key: a URL written as a property, or a template literal type of an index signature. */
+export type PathKey =
+  | { readonly kind: "literal"; readonly url: string }
+  | { readonly kind: "template"; readonly parts: readonly PathKeyPart[] };
+
+const BOOLEAN_TEXTS: readonly string[] = ["true", "false"];
+
+/** 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] }];
+  });
+}
+
+/**
+ * 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 key.parts.reduce<TemplateShape[]>(withPart, [{ texts: [""], types: [] }]);
+}
+
+/**
+ * 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 {
+  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 repeated;
+}
+
+/**
+ * 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.
+ */
+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 left < right ? -1 : 1;
+}
+
+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),
+  };
+}
+
+/** 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, 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>();
+  checked.forEach(({ template, shapes: targets }, index) => {
+    if (template === null) {
+      return;
+    }
+    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);
+    }
+  });
+  return covering;
+}