openapi-typesafe 0.0.0 → 1.0.0-rc.1

package/src/application/print/type-printer.ts

@@ -0,0 +1,287 @@
+import { assertNever } from "../../domain/assert-never.js";
+import type {
+  IrIndexedAccessType,
+  IrMember,
+  IrPropertyName,
+  IrRawType,
+  IrTupleElement,
+  IrType,
+} from "../../domain/ir/nodes.js";
+import { writeLeadingComment } from "./comment-writer.js";
+import { printEscapedString, printNumberLiteral, printStringLiteral } from "./literal-text.js";
+import type { TextWriter } from "./text-writer.js";
+
+/**
+ * Parenthesization contexts. Each predicate says when a child type needs parentheses; together they
+ * reproduce the TypeScript factory's parenthesizer rules for the node kinds of the IR, so output
+ * matches the original even when unions are nested (`A | (B | C)`).
+ */
+const isUnionOrIntersection = (type: IrType): boolean =>
+  type.kind === "union" || type.kind === "intersection";
+/** Union and intersection members (`parenthesizeConstituentTypeOf{Union,Intersection}Type`). */
+const needsParensAsConstituent = isUnionOrIntersection;
+/** Array element and indexed-access object (`parenthesizeNonArrayTypeOfPostfixType`). */
+const needsParensAsPostfixOperand = (type: IrType): boolean =>
+  type.kind === "readonly" || isUnionOrIntersection(type);
+/** Operand of `readonly` (`parenthesizeOperandOfReadonlyTypeOperator`). */
+const needsParensAsReadonlyOperand = needsParensAsPostfixOperand;
+
+function writeTypeIn(
+  writer: TextWriter,
+  type: IrType,
+  needsParens: (type: IrType) => boolean,
+): void {
+  if (!needsParens(type)) {
+    writeType(writer, type);
+    return;
+  }
+  writer.write("(");
+  writeType(writer, type);
+  writer.write(")");
+}
+
+/** Write a single-line list: `separator` between items, nothing for an empty list. */
+function writeInlineList<T>(
+  writer: TextWriter,
+  items: readonly T[],
+  separator: string,
+  writeItem: (item: T) => void,
+) {
+  items.forEach((item, index) => {
+    if (index > 0) {
+      writer.write(separator);
+    }
+    writeItem(item);
+  });
+}
+
+/**
+ * Write a multi-line list the way the TypeScript printer does: a line break after the opening
+ * token, one item per indented line, `delimiter` after every item but the last, and a line break
+ * before the closing token. An empty list prints the line break only when `isLineBreakWhenEmpty`
+ * (interfaces, enums and tuples do; object type literals print `{}`).
+ */
+export function writeMultiLineList<T>(
+  writer: TextWriter,
+  items: readonly T[],
+  format: { readonly delimiter: string; readonly isLineBreakWhenEmpty: boolean },
+  writeItem: (item: T) => void,
+): void {
+  if (items.length === 0) {
+    if (format.isLineBreakWhenEmpty) {
+      writer.writeLine();
+    }
+    return;
+  }
+  writer.writeLine();
+  writer.increaseIndent();
+  items.forEach((item, index) => {
+    if (index > 0) {
+      writer.write(format.delimiter);
+      writer.writeLine();
+    }
+    writeItem(item);
+  });
+  writer.decreaseIndent();
+  writer.writeLine();
+}
+
+function writePropertyName(writer: TextWriter, name: IrPropertyName): void {
+  switch (name.kind) {
+    case "identifier":
+    case "number":
+      writer.write(name.text);
+      break;
+    case "string":
+      writer.write(printEscapedString(name.value));
+      break;
+    default:
+      assertNever(name);
+  }
+}
+
+/**
+ * `[name: type]`. TypeScript prints index signature parameters as an indented list, so a multi-line
+ * parameter type (an object or tuple) is indented one level deeper than the member.
+ */
+function writeIndexSignatureParameter(writer: TextWriter, name: string, type: IrType): void {
+  writer.write(`[${name}: `);
+  writer.increaseIndent();
+  writeType(writer, type);
+  writer.decreaseIndent();
+  writer.write("]");
+}
+
+/** Write one member of an interface or object type, with its comment and trailing semicolon. */
+export function writeMember(writer: TextWriter, member: IrMember): void {
+  for (const comment of member.comments) {
+    writeLeadingComment(writer, comment);
+  }
+  if (member.isReadonly) {
+    writer.write("readonly ");
+  }
+  if (member.kind === "property") {
+    writePropertyName(writer, member.name);
+    writer.write(member.isOptional ? "?: " : ": ");
+  } else {
+    writeIndexSignatureParameter(writer, member.parameterName, member.parameterType);
+    writer.write(": ");
+  }
+  writeType(writer, member.type);
+  writer.write(";");
+}
+
+function writeTupleElement(writer: TextWriter, element: IrTupleElement): void {
+  if (element.isRest) {
+    writer.write("...");
+  }
+  if (element.isOptional) {
+    // TypeScript parenthesizes an optional element as a postfix operand (`(A | B)?`).
+    writeTypeIn(writer, element.type, needsParensAsPostfixOperand);
+    writer.write("?");
+    return;
+  }
+  writeType(writer, element.type);
+}
+
+function writeObjectType(writer: TextWriter, members: readonly IrMember[]): void {
+  writer.write("{");
+  writeMultiLineList(writer, members, { delimiter: "", isLineBreakWhenEmpty: false }, (member) =>
+    writeMember(writer, member),
+  );
+  writer.write("}");
+}
+
+function writeTupleType(writer: TextWriter, elements: readonly IrTupleElement[]): void {
+  writer.write("[");
+  writeMultiLineList(writer, elements, { delimiter: ",", isLineBreakWhenEmpty: true }, (element) =>
+    writeTupleElement(writer, element),
+  );
+  writer.write("]");
+}
+
+function writeReferenceType(
+  writer: TextWriter,
+  name: string,
+  typeArguments: readonly IrType[],
+): void {
+  writer.write(name);
+  if (typeArguments.length > 0) {
+    writer.write("<");
+    writeInlineList(writer, typeArguments, ", ", (argument) => writeType(writer, argument));
+    writer.write(">");
+  }
+}
+
+function writeIndexedAccessType(writer: TextWriter, type: IrIndexedAccessType): void {
+  writeTypeIn(writer, type.object, needsParensAsPostfixOperand);
+  writer.write("[");
+  writeType(writer, type.index);
+  writer.write("]");
+}
+
+function writeConstituents(writer: TextWriter, types: readonly IrType[], separator: string): void {
+  writeInlineList(writer, types, separator, (member) =>
+    writeTypeIn(writer, member, needsParensAsConstituent),
+  );
+}
+
+type IrLeafType = Extract<
+  IrType,
+  { kind: "keyword" | "stringLiteral" | "numberLiteral" | "booleanLiteral" }
+>;
+
+function printLeafType(type: IrLeafType): string {
+  switch (type.kind) {
+    case "keyword":
+      return type.keyword;
+    case "stringLiteral":
+      return printStringLiteral(type.value, type.encoding);
+    case "numberLiteral":
+      return printNumberLiteral(type.value);
+    case "booleanLiteral":
+      return String(type.value);
+    default:
+      return assertNever(type);
+  }
+}
+
+/**
+ * Raw text is printed as if it started at column 0, so its continuation lines get the current
+ * indentation, as the TypeScript printer indents a nested node.
+ */
+function writeRawType(writer: TextWriter, text: string): void {
+  text.split("\n").forEach((line, index) => {
+    if (index > 0) {
+      writer.rawWrite(writer.options.newLine);
+    }
+    writer.write(line);
+  });
+}
+
+function writeArrayType(writer: TextWriter, element: IrType): void {
+  writeTypeIn(writer, element, needsParensAsPostfixOperand);
+  writer.write("[]");
+}
+
+function writeReadonlyType(writer: TextWriter, operand: IrType): void {
+  writer.write("readonly ");
+  writeTypeIn(writer, operand, needsParensAsReadonlyOperand);
+}
+
+type IrOperatorType = Extract<IrType, { kind: "array" | "indexedAccess" | "readonly" }>;
+
+/** Types built with a type operator: `T[]`, `T[K]` and `readonly T`. */
+function writeOperatorType(writer: TextWriter, type: IrOperatorType): void {
+  if (type.kind === "array") {
+    writeArrayType(writer, type.element);
+  } else if (type.kind === "indexedAccess") {
+    writeIndexedAccessType(writer, type);
+  } else {
+    writeReadonlyType(writer, type.type);
+  }
+}
+
+const CONSTITUENT_SEPARATORS = { union: " | ", intersection: " & " } as const;
+
+/** A raw type may span lines and is re-indented; any other leaf prints on one line. */
+function writeLeafType(writer: TextWriter, type: IrLeafType | IrRawType): void {
+  if (type.kind === "raw") {
+    writeRawType(writer, type.text);
+  } else {
+    writer.write(printLeafType(type));
+  }
+}
+
+/** Write a type at the writer's current position. */
+export function writeType(writer: TextWriter, type: IrType): void {
+  switch (type.kind) {
+    case "keyword":
+    case "stringLiteral":
+    case "numberLiteral":
+    case "booleanLiteral":
+    case "raw":
+      writeLeafType(writer, type);
+      break;
+    case "reference":
+      writeReferenceType(writer, type.name, type.typeArguments);
+      break;
+    case "array":
+    case "indexedAccess":
+    case "readonly":
+      writeOperatorType(writer, type);
+      break;
+    case "union":
+    case "intersection":
+      writeConstituents(writer, type.types, CONSTITUENT_SEPARATORS[type.kind]);
+      break;
+    case "object":
+      writeObjectType(writer, type.members);
+      break;
+    case "tuple":
+      writeTupleType(writer, type.elements);
+      break;
+    default:
+      assertNever(type);
+  }
+}

package/src/application/stack-overflow.ts

@@ -0,0 +1,54 @@
+import { ERROR_CODES, OpenAPITypesafeError } from "../domain/errors.js";
+
+/**
+ * Deeply nested schemas (ENGINEERING_PLAN 8.5). Loading, bundling, transforming and printing walk
+ * schemas recursively, and Redocly follows each `$ref` inside the walk. On the default Node.js
+ * stack, about 550 levels of inline schemas or a chain of about 900 `$ref`s (each schema refers to
+ * the next) run out of call stack. Real documents stay far below: every YAML or JSON file goes
+ * through the YAML parser, which stops at 100 levels, and the whole corpus passes. The overflow is
+ * reported as a typed error instead of a `RangeError` with a stack trace.
+ */
+
+/** The step that ran out of call stack; named in the message and the details. */
+export type DeepSchemaStep = "load" | "transform" | "print";
+
+/** V8 and JavaScriptCore (Node.js, Deno, Bun) throw a `RangeError` with this message. */
+const STACK_OVERFLOW_MESSAGE = /maximum call stack size exceeded/i;
+
+/** Whether a thrown value is a call stack overflow. */
+export function isStackOverflowError(error: unknown): boolean {
+  return error instanceof RangeError && STACK_OVERFLOW_MESSAGE.test(error.message);
+}
+
+/** The typed error for a document nested too deeply for the call stack. */
+export function schemaTooDeepError(step: DeepSchemaStep, cause: unknown): OpenAPITypesafeError {
+  return new OpenAPITypesafeError({
+    code: ERROR_CODES.SCHEMA_TOO_DEEP,
+    message:
+      `The schema is nested too deeply to ${step}: the call stack ran out. Both inline ` +
+      "schemas and chains of $ref (each schema referring to the next) count; shorten the deepest.",
+    details: { step },
+    cause,
+  });
+}
+
+/** Run a step and report a stack overflow in it as SCHEMA_TOO_DEEP; other errors pass through. */
+export function withStackOverflowReported<T>(step: DeepSchemaStep, run: () => T): T {
+  try {
+    return run();
+  } catch (error) {
+    throw isStackOverflowError(error) ? schemaTooDeepError(step, error) : error;
+  }
+}
+
+/** The asynchronous form of `withStackOverflowReported`. */
+export async function withStackOverflowReportedAsync<T>(
+  step: DeepSchemaStep,
+  run: () => Promise<T>,
+): Promise<T> {
+  try {
+    return await run();
+  } catch (error) {
+    throw isStackOverflowError(error) ? schemaTooDeepError(step, error) : error;
+  }
+}

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

@@ -0,0 +1,203 @@
+import type { IrObjectType, IrPropertySignature, IrType } from "../../../domain/ir/nodes.js";
+import { indexSignaturesOf, nameOf, propertiesOf } from "./type-resolution.js";
+
+/**
+ * What the `--path-params-as-types` overlap check knows about one type where another is expected.
+ * `assignable` and `rejected` are proofs of what TypeScript decides (`strict`, without
+ * `exactOptionalPropertyTypes`); `undecided` is a pair the check does not model, such as a utility
+ * type or raw text. Only a rejection changes the output, so an undecided pair keeps the original.
+ */
+export type Assignability = "assignable" | "rejected" | "undecided";
+
+/**
+ * All of the relations: rejected when one is, assignable when each is. The relations are computed
+ * lazily, so a rejection stops the rest.
+ */
+export function everyOf<T>(
+  items: readonly T[],
+  relate: (item: T, index: number) => Assignability,
+): Assignability {
+  let result: Assignability = "assignable";
+  for (const [index, item] of items.entries()) {
+    const each = relate(item, index);
+    if (each === "rejected") {
+      return "rejected";
+    }
+    if (each === "undecided") {
+      result = "undecided";
+    }
+  }
+  return result;
+}
+
+/** One of the relations: assignable when one is, rejected when each is. */
+export function someOf<T>(items: readonly T[], relate: (item: T) => Assignability): Assignability {
+  let result: Assignability = "rejected";
+  for (const item of items) {
+    const each = relate(item);
+    if (each === "assignable") {
+      return "assignable";
+    }
+    if (each === "undecided") {
+      result = "undecided";
+    }
+  }
+  return result;
+}
+
+/** Assignable when the condition holds, rejected when it does not. */
+export function provenBy(condition: boolean): Assignability {
+  return condition ? "assignable" : "rejected";
+}
+
+/**
+ * The kinds of resolved types the check tells apart. A type of one kind is never assignable to a
+ * type of another, except that a primitive or a list may fit an object type (`string` fits
+ * `{ length: number }`), which the check models only in part. `opaque` is any type it cannot
+ * read.
+ */
+type TypeCategory = "primitive" | "list" | "object" | "opaque";
+
+function categoryOf(type: IrType): TypeCategory {
+  switch (type.kind) {
+    case "keyword":
+    case "stringLiteral":
+    case "numberLiteral":
+    case "booleanLiteral":
+      return "primitive";
+    case "array":
+    case "tuple":
+    case "readonly":
+      return "list";
+    case "object":
+      return "object";
+    default:
+      return "opaque";
+  }
+}
+
+/** Keywords that are no object: `{}` rejects them under `strictNullChecks`. */
+const NO_OBJECT_KEYWORDS: ReadonlySet<string> = new Set(["null", "undefined", "unknown", "never"]);
+
+/**
+ * The members of `ReadonlyArray` and `Array` in the TypeScript libraries up to ESNext. An object
+ * type that needs a property of another name is no list; a numeric name may be a tuple element.
+ */
+const ARRAY_MEMBER_NAMES: ReadonlySet<string> = new Set([
+  "length",
+  "toString",
+  "toLocaleString",
+  "pop",
+  "push",
+  "concat",
+  "join",
+  "reverse",
+  "shift",
+  "slice",
+  "sort",
+  "splice",
+  "unshift",
+  "indexOf",
+  "lastIndexOf",
+  "every",
+  "some",
+  "forEach",
+  "map",
+  "filter",
+  "reduce",
+  "reduceRight",
+  "find",
+  "findIndex",
+  "fill",
+  "copyWithin",
+  "entries",
+  "keys",
+  "values",
+  "includes",
+  "flatMap",
+  "flat",
+  "at",
+  "findLast",
+  "findLastIndex",
+  "toReversed",
+  "toSorted",
+  "toSpliced",
+  "with",
+]);
+
+const ARRAY_LENGTH = "length";
+/** A tuple element's name: `"0"`, `"1"`. */
+const ELEMENT_NAME_RE = /^\d+$/;
+
+function isListMemberName(name: string): boolean {
+  return ARRAY_MEMBER_NAMES.has(name) || ELEMENT_NAME_RE.test(name);
+}
+
+/**
+ * Whether a list fits an object type. It does not when the object needs a property no list has
+ * (TS2741), or when the object is a weak type and no list has one of its properties (TS2559).
+ */
+function listToObject(target: IrObjectType): Assignability {
+  const properties = [...propertiesOf(target).values()];
+  const isForeign = (property: IrPropertySignature) => !isListMemberName(nameOf(property));
+  const needsForeign = properties.some((property) => !property.isOptional && isForeign(property));
+  const isWeak =
+    properties.length > 0 &&
+    indexSignaturesOf(target).length === 0 &&
+    properties.every((property) => property.isOptional);
+  return needsForeign || (isWeak && properties.every(isForeign)) ? "rejected" : "undecided";
+}
+
+/**
+ * Whether a primitive fits an object type: `null`, `undefined` and `unknown` never do; any other
+ * may (`{}`, `{ length: number }`), which is not modelled.
+ */
+function primitiveToObject(source: IrType): Assignability {
+  const isNoObject = source.kind === "keyword" && NO_OBJECT_KEYWORDS.has(source.keyword);
+  return isNoObject ? "rejected" : "undecided";
+}
+
+/** An object type fits an array only with all of its members; `length` is the first it needs. */
+function objectToList(source: IrObjectType): Assignability {
+  return propertiesOf(source).has(ARRAY_LENGTH) ? "undecided" : "rejected";
+}
+
+/**
+ * The relation of two types of different categories, or null when they are of the same one.
+ * Primitive and list targets accept nothing of another category; see `TypeCategory`.
+ */
+export function crossCategoryRelation(source: IrType, target: IrType): Assignability | null {
+  const from = categoryOf(source);
+  const to = categoryOf(target);
+  if (from === "opaque" || to === "opaque") {
+    return "undecided";
+  }
+  if (from === to) {
+    return null;
+  }
+  if (to !== "object") {
+    return source.kind === "object" && to === "list" ? objectToList(source) : "rejected";
+  }
+  return from === "primitive" ? primitiveToObject(source) : listToObject(target as IrObjectType);
+}
+
+/** The keyword a literal type belongs to. */
+const LITERAL_KEYWORDS = {
+  stringLiteral: "string",
+  numberLiteral: "number",
+  booleanLiteral: "boolean",
+} as const;
+
+/**
+ * The relation of two primitive types written differently (the same text is assignable). A
+ * literal fits its keyword; any other pair is rejected: different keywords, different literals,
+ * a keyword for one literal (a union of literals is compared in `type-assignability.ts`), and
+ * anything for `never`.
+ */
+export function primitiveRelation(source: IrType, target: IrType): Assignability {
+  if (target.kind !== "keyword" || source.kind === "keyword") {
+    return "rejected";
+  }
+  const keyword = (LITERAL_KEYWORDS as Partial<Record<IrType["kind"], string>>)[source.kind];
+  return provenBy(keyword === target.keyword);
+}