openapi-typesafe 0.0.0 → 1.0.0-rc.0

package/src/adapters/type-ast-bridge/typescript-to-ir.ts

@@ -0,0 +1,280 @@
+import type ts from "typescript";
+import { irRaw } from "../../domain/ir/constructors.js";
+import type {
+  IrComment,
+  IrKeyword,
+  IrMember,
+  IrPropertyName,
+  IrPropertySignature,
+  IrType,
+} from "../../domain/ir/nodes.js";
+import type { TypeScriptModule } from "./load-typescript.js";
+import { asRaw, isIrNode, needsPrintedText } from "./typescript-raw-text.js";
+
+/**
+ * Read TypeScript type nodes from user callbacks into IR (ADR-004, decision 3). Synthesized nodes
+ * are mapped by structure. Anything the IR cannot express exactly is printed with the TypeScript
+ * printer, the way the original output it, and kept as a `raw` node: parsed nodes, nodes with
+ * comments, explicit parentheses, single-quoted strings, numbers not in canonical form, and syntax
+ * the IR does not model. Every function takes the user's TypeScript module (ADR-004, decision 4):
+ * `SyntaxKind` numbers differ between versions, so a node is read with the module that made it.
+ */
+
+function keywordOf(ts: TypeScriptModule, kind: ts.SyntaxKind): IrKeyword | undefined {
+  const keywords: ReadonlyMap<ts.SyntaxKind, IrKeyword> = new Map([
+    [ts.SyntaxKind.StringKeyword, "string"],
+    [ts.SyntaxKind.NumberKeyword, "number"],
+    [ts.SyntaxKind.BooleanKeyword, "boolean"],
+    [ts.SyntaxKind.UndefinedKeyword, "undefined"],
+    [ts.SyntaxKind.UnknownKeyword, "unknown"],
+    [ts.SyntaxKind.NeverKeyword, "never"],
+  ]);
+  return keywords.get(kind);
+}
+
+function isCanonicalNumber(text: string): boolean {
+  return String(Number(text)) === text;
+}
+
+function fromNumber(ts: TypeScriptModule, literal: ts.Expression): IrType | null {
+  if (ts.isNumericLiteral(literal)) {
+    return isCanonicalNumber(literal.text)
+      ? { kind: "numberLiteral", value: Number(literal.text) }
+      : null;
+  }
+  const isNegative =
+    ts.isPrefixUnaryExpression(literal) &&
+    literal.operator === ts.SyntaxKind.MinusToken &&
+    ts.isNumericLiteral(literal.operand) &&
+    isCanonicalNumber(literal.operand.text) &&
+    Number(literal.operand.text) !== 0;
+  return isNegative
+    ? { kind: "numberLiteral", value: -Number((literal.operand as ts.NumericLiteral).text) }
+    : null;
+}
+
+function fromLiteral(ts: TypeScriptModule, node: ts.LiteralTypeNode): IrType | null {
+  const { literal } = node;
+  if (ts.isStringLiteral(literal)) {
+    const isSingleQuoted = (literal as { singleQuote?: boolean }).singleQuote === true;
+    return isSingleQuoted
+      ? null
+      : { kind: "stringLiteral", value: literal.text, encoding: "escaped" };
+  }
+  if (literal.kind === ts.SyntaxKind.NullKeyword) {
+    return { kind: "keyword", keyword: "null" };
+  }
+  if (literal.kind === ts.SyntaxKind.TrueKeyword || literal.kind === ts.SyntaxKind.FalseKeyword) {
+    return { kind: "booleanLiteral", value: literal.kind === ts.SyntaxKind.TrueKeyword };
+  }
+  return fromNumber(ts, literal);
+}
+
+/** Converts the children of one node, which becomes their parent. */
+function childrenOf(ts: TypeScriptModule, parent: ts.Node): (child: ts.TypeNode) => IrType {
+  return (child) => fromTypeNode(ts, child, parent);
+}
+
+function fromReference(ts: TypeScriptModule, node: ts.TypeReferenceNode): IrType | null {
+  if (!ts.isIdentifier(node.typeName)) {
+    return null;
+  }
+  const typeArguments = (node.typeArguments ?? []).map(childrenOf(ts, node));
+  return { kind: "reference", name: ts.idText(node.typeName), typeArguments };
+}
+
+function fromTuple(ts: TypeScriptModule, node: ts.TupleTypeNode): IrType | null {
+  const isPlain = node.elements.every(
+    (element) => !ts.isNamedTupleMember(element) && !ts.isOptionalTypeNode(element),
+  );
+  if (!isPlain) {
+    return null;
+  }
+  const convert = childrenOf(ts, node);
+  const elements = node.elements.map((element) =>
+    ts.isRestTypeNode(element)
+      ? { type: convert(element.type), isRest: true }
+      : { type: convert(element), isRest: false },
+  );
+  return { kind: "tuple", elements };
+}
+
+/**
+ * Leading comments in order, or null when the IR cannot hold them: trailing comments, or a
+ * comment without a line break after it (the IR always writes one).
+ */
+function fromComments(ts: TypeScriptModule, node: ts.Node): IrComment[] | null {
+  const comments = ts.getSyntheticLeadingComments(node) ?? [];
+  const hasTrailing = (ts.getSyntheticTrailingComments(node)?.length ?? 0) > 0;
+  if (hasTrailing || comments.some((comment) => !comment.hasTrailingNewLine)) {
+    return null;
+  }
+  return comments.map((comment) => ({
+    kind: comment.kind === ts.SyntaxKind.MultiLineCommentTrivia ? "block" : "line",
+    text: comment.text,
+  }));
+}
+
+function fromPropertyName(ts: TypeScriptModule, name: ts.PropertyName): IrPropertyName | null {
+  if (ts.isIdentifier(name)) {
+    return { kind: "identifier", text: ts.idText(name) };
+  }
+  if (ts.isStringLiteral(name) && (name as { singleQuote?: boolean }).singleQuote !== true) {
+    return { kind: "string", value: name.text };
+  }
+  return ts.isNumericLiteral(name) ? { kind: "number", text: name.text } : null;
+}
+
+/** Only `readonly` is modeled; any other modifier makes the member unreadable as IR. */
+function readonlyFlag(ts: TypeScriptModule, node: ts.TypeElement): boolean | null {
+  const modifiers = ts.canHaveModifiers(node) ? (ts.getModifiers(node) ?? []) : [];
+  const isOnlyReadonly = modifiers.every(
+    (modifier) => modifier.kind === ts.SyntaxKind.ReadonlyKeyword,
+  );
+  return isOnlyReadonly ? modifiers.length > 0 : null;
+}
+
+/** A property signature as IR, or null when it uses syntax the IR does not model. */
+export function fromPropertySignature(
+  ts: TypeScriptModule,
+  node: ts.PropertySignature,
+): IrPropertySignature | null {
+  const name = fromPropertyName(ts, node.name);
+  const comments = fromComments(ts, node);
+  const isReadonly = readonlyFlag(ts, node);
+  if (name === null || comments === null || isReadonly === null || node.type === undefined) {
+    return null;
+  }
+  return {
+    kind: "property",
+    name,
+    type: fromTypeNode(ts, node.type, node),
+    isOptional: node.questionToken !== undefined,
+    isReadonly,
+    comments,
+  };
+}
+
+function fromIndexSignature(
+  ts: TypeScriptModule,
+  node: ts.IndexSignatureDeclaration,
+): IrMember | null {
+  const [parameter, ...others] = node.parameters;
+  const comments = fromComments(ts, node);
+  const isReadonly = readonlyFlag(ts, node);
+  const isPlain =
+    parameter?.type !== undefined && ts.isIdentifier(parameter.name) && others.length === 0;
+  if (!isPlain || comments === null || isReadonly === null) {
+    return null;
+  }
+  return {
+    kind: "indexSignature",
+    parameterName: ts.idText(parameter.name as ts.Identifier),
+    parameterType: fromTypeNode(ts, parameter.type as ts.TypeNode, node),
+    type: fromTypeNode(ts, node.type, node),
+    isReadonly,
+    comments,
+  };
+}
+
+function fromMember(ts: TypeScriptModule, member: ts.TypeElement): IrMember | null {
+  if (member.pos >= 0) {
+    return null;
+  }
+  if (ts.isPropertySignature(member)) {
+    return fromPropertySignature(ts, member);
+  }
+  return ts.isIndexSignatureDeclaration(member) ? fromIndexSignature(ts, member) : null;
+}
+
+function fromTypeLiteral(ts: TypeScriptModule, node: ts.TypeLiteralNode): IrType | null {
+  const members = node.members.map((member) => fromMember(ts, member));
+  const isReadable = members.every((member) => member !== null);
+  return isReadable ? { kind: "object", members: members as IrMember[] } : null;
+}
+
+function fromComposite(ts: TypeScriptModule, node: ts.TypeNode): IrType | null {
+  const convert = childrenOf(ts, node);
+  if (ts.isArrayTypeNode(node)) {
+    return { kind: "array", element: convert(node.elementType) };
+  }
+  if (ts.isUnionTypeNode(node)) {
+    return { kind: "union", types: node.types.map(convert) };
+  }
+  if (ts.isIntersectionTypeNode(node)) {
+    return { kind: "intersection", types: node.types.map(convert) };
+  }
+  if (ts.isIndexedAccessTypeNode(node)) {
+    return {
+      kind: "indexedAccess",
+      object: convert(node.objectType),
+      index: convert(node.indexType),
+    };
+  }
+  if (ts.isTypeOperatorNode(node) && node.operator === ts.SyntaxKind.ReadonlyKeyword) {
+    return { kind: "readonly", type: convert(node.type) };
+  }
+  return ts.isTypeLiteralNode(node) ? fromTypeLiteral(ts, node) : null;
+}
+
+function fromStructure(ts: TypeScriptModule, node: ts.TypeNode): IrType | null {
+  const keyword = keywordOf(ts, node.kind);
+  if (keyword !== undefined) {
+    return { kind: "keyword", keyword };
+  }
+  if (ts.isIdentifier(node)) {
+    // The original writes JSON string literals and some references as bare identifiers.
+    return irRaw(ts.idText(node));
+  }
+  if (ts.isLiteralTypeNode(node)) {
+    return fromLiteral(ts, node);
+  }
+  if (ts.isTypeReferenceNode(node)) {
+    return fromReference(ts, node);
+  }
+  return ts.isTupleTypeNode(node) ? fromTuple(ts, node) : fromComposite(ts, node);
+}
+
+/**
+ * Whether the factory's parenthesizer put these parentheses in (same rules as the IR printer):
+ * unions, intersections and `readonly` types as array elements, indexed objects and `readonly`
+ * operands; unions and intersections as members of other unions or intersections.
+ */
+function isFactoryParenthesis(
+  ts: TypeScriptModule,
+  inner: ts.TypeNode,
+  parent: ts.Node | undefined,
+): boolean {
+  if (parent === undefined) {
+    return false;
+  }
+  const isComposite = ts.isUnionTypeNode(inner) || ts.isIntersectionTypeNode(inner);
+  const isPostfixOrReadonlyParent =
+    ts.isArrayTypeNode(parent) ||
+    ts.isIndexedAccessTypeNode(parent) ||
+    ts.isTypeOperatorNode(parent);
+  if (isPostfixOrReadonlyParent) {
+    return isComposite || ts.isTypeOperatorNode(inner);
+  }
+  const isCompositeParent = ts.isUnionTypeNode(parent) || ts.isIntersectionTypeNode(parent);
+  return isCompositeParent && isComposite;
+}
+
+/**
+ * Convert a type node. `parent` is the node that contains it: synthesized nodes have no `parent`
+ * link, and it is needed to tell parentheses the factory inserted from ones the user wrote.
+ */
+export function fromTypeNode(ts: TypeScriptModule, node: ts.TypeNode, parent?: ts.Node): IrType {
+  if (isIrNode(node)) {
+    return node;
+  }
+  if (needsPrintedText(ts, node)) {
+    return asRaw(ts, node);
+  }
+  if (ts.isParenthesizedTypeNode(node)) {
+    return isFactoryParenthesis(ts, node.type, parent)
+      ? fromTypeNode(ts, node.type, parent)
+      : asRaw(ts, node);
+  }
+  return fromStructure(ts, node) ?? asRaw(ts, node);
+}

package/src/adapters/type-ast-bridge/typescript-types.ts

@@ -0,0 +1,8 @@
+import type ts from "typescript";
+
+/**
+ * The TypeScript compiler's types for code outside the bridge (ADR-004, decision 4). Type-only:
+ * it is erased at build time, so importing it never loads TypeScript. Only the bridge imports
+ * `typescript` itself (enforced by dependency-cruiser).
+ */
+export type { ts };

package/src/api/ast-to-string.ts

@@ -0,0 +1,59 @@
+import { toStatements } from "../adapters/type-ast-bridge/ir-declarations-to-typescript.js";
+import { toTypeElement, toTypeNode } from "../adapters/type-ast-bridge/ir-to-typescript.js";
+import {
+  loadTypeScript,
+  type TypeScriptModule,
+} from "../adapters/type-ast-bridge/load-typescript.js";
+import {
+  type AstToStringOptions,
+  printWithTypeScript,
+} from "../adapters/type-ast-bridge/print-typescript.js";
+import type { ts } from "../adapters/type-ast-bridge/typescript-types.js";
+import { type IrPrintable, printFragments } from "../application/print/print-nodes.js";
+import { withStackOverflowReported } from "../application/stack-overflow.js";
+import type { IrDeclaration } from "../domain/ir/nodes.js";
+
+export type { AstToStringOptions } from "../adapters/type-ast-bridge/print-typescript.js";
+
+/** What `astToString` prints: IR (from `openapiTS` and the transformers) or TypeScript nodes. */
+export type AstToStringInput = IrPrintable | ts.Node | readonly (IrPrintable | ts.Node)[];
+
+function isIrNode(node: IrPrintable | ts.Node): node is IrPrintable {
+  return typeof node.kind === "string";
+}
+
+/** An IR node in TypeScript form, for printing it together with TypeScript nodes. */
+function toTypeScriptNodes(ts: TypeScriptModule, node: IrPrintable): ts.Node[] {
+  if (isIrDeclarationKind(node)) {
+    return toStatements(ts, node);
+  }
+  const isMember = node.kind === "property" || node.kind === "indexSignature";
+  return [isMember ? toTypeElement(ts, node) : toTypeNode(ts, node)];
+}
+
+function isIrDeclarationKind(node: IrPrintable): node is IrDeclaration {
+  return ["interface", "typeAlias", "enum", "constArray", "rawDeclaration"].includes(node.kind);
+}
+
+/**
+ * Print declarations, members or types as a TypeScript file body. IR is printed by our printer;
+ * with TypeScript nodes in the input, or with TypeScript printer options, everything goes
+ * through the TypeScript printer as before (ADR-004, decision 1).
+ */
+export function astToString(ast: AstToStringInput, options?: AstToStringOptions): string {
+  return withStackOverflowReported("print", () => printNodes(ast, options));
+}
+
+function printNodes(ast: AstToStringInput, options: AstToStringOptions | undefined): string {
+  const nodes: readonly (IrPrintable | ts.Node)[] = Array.isArray(ast)
+    ? ast
+    : [ast as IrPrintable | ts.Node];
+  if (nodes.every(isIrNode) && !options) {
+    return printFragments(nodes);
+  }
+  const ts = loadTypeScript();
+  const statements = nodes.flatMap((node) =>
+    isIrNode(node) ? toTypeScriptNodes(ts, node) : [node],
+  );
+  return printWithTypeScript(ts, statements, options);
+}

package/src/api/comment-header.ts

@@ -0,0 +1,7 @@
+/** The header of every generated file; the CLI writes it before the declarations. */
+export const COMMENT_HEADER = `/**
+ * This file was auto-generated by openapi-typesafe.
+ * Do not make direct changes to the file.
+ */
+
+`;

package/src/api/default-ports.ts

@@ -0,0 +1,44 @@
+import { performance } from "node:perf_hooks";
+import { createConfig, type Config as RedoclyConfig } from "@redocly/openapi-core";
+import supportsColor from "supports-color";
+import { createTerminalLogger } from "../adapters/terminal-logger/terminal-logger.js";
+import type { Logger } from "../application/ports/logger.js";
+
+/**
+ * The default adapters of the Node API (ENGINEERING_PLAN 4.5): this module and the CLI's
+ * composition root are where the process environment is read.
+ */
+
+/** Colors when the terminal supports them, as the original decided. */
+export function terminalSupportsColor(): boolean {
+  const stdout = supportsColor.stdout;
+  return Boolean(stdout) && stdout !== false && stdout.hasBasic !== false;
+}
+
+/** The terminal logger with `DEBUG` from the environment, writing to the console. */
+export function defaultLogger(silent: boolean): Logger {
+  return createTerminalLogger({
+    silent,
+    debugFilter: process.env.DEBUG,
+    useColors: terminalSupportsColor(),
+    sink: console,
+  });
+}
+
+/**
+ * How long one remote `$ref` (or a remote source) may take to load. Large documents (the 27 MB
+ * Cloudflare spec) download in seconds; a minute covers slow hosts, while Node's own fetch would
+ * wait five minutes for a server that never answers (ENGINEERING_PLAN 8.5).
+ */
+export const REMOTE_REF_TIMEOUT_MS = 60_000;
+
+/** A monotonic clock in milliseconds, for debug durations. */
+export function monotonicNow(): number {
+  return performance.now();
+}
+
+/** The default Redocly config: minimal rules, and duplicate operation IDs are an error. */
+export function defaultRedoclyConfig(): Promise<RedoclyConfig> {
+  const rules = { "operation-operationId-unique": { severity: "error" as const } };
+  return createConfig({ rules }, { extends: ["minimal"] });
+}

package/src/api/discriminator-enum.ts

@@ -0,0 +1,76 @@
+import type {
+  DiscriminatorObject,
+  ObjectSubtype,
+  ReferenceObject,
+  SchemaObject,
+} from "../types.js";
+
+/**
+ * The in-place patch of the discriminator pre-pass: a mapped schema gets a required enum property
+ * with its discriminator values, so that TypeScript can narrow the generated union.
+ */
+
+/** One mapped schema to patch: `ref` is the schema; `discriminatorRef` owns the discriminator. */
+export interface EnumPatch {
+  readonly ref: string;
+  readonly values: string[];
+  readonly discriminator: DiscriminatorObject;
+  readonly discriminatorRef: string;
+}
+
+function discriminatorEnum(values: string[], previous?: SchemaObject): SchemaObject {
+  return {
+    type: "string",
+    enum: values,
+    description: previous?.description
+      ? `${previous.description} (enum property replaced by openapi-typesafe)`
+      : "discriminator enum property added by openapi-typesafe",
+  };
+}
+
+/** An `allOf` schema gets one more item that holds the required enum property. */
+function patchAllOf(allOf: (SchemaObject | ReferenceObject)[], patch: EnumPatch): SchemaObject {
+  const added = discriminatorEnum(patch.values);
+  allOf.push({
+    type: "object",
+    required: [patch.discriminator.propertyName],
+    properties: { [patch.discriminator.propertyName]: added },
+  });
+  return added;
+}
+
+/** An object schema gets the enum property, which is always required, added or replaced. */
+function patchObjectSchema(schema: SchemaObject & ObjectSubtype, patch: EnumPatch): SchemaObject {
+  const name = patch.discriminator.propertyName;
+  if (!schema.properties) {
+    schema.properties = {};
+  }
+  if (!schema.required) {
+    schema.required = [name];
+  } else if (!schema.required.includes(name)) {
+    schema.required.push(name);
+  }
+  const added = discriminatorEnum(patch.values, schema.properties[name] as SchemaObject);
+  schema.properties[name] = added;
+  return added;
+}
+
+function isObjectSchema(schema: unknown): schema is SchemaObject & ObjectSubtype {
+  return (
+    typeof schema === "object" && schema !== null && "type" in schema && schema.type === "object"
+  );
+}
+
+/**
+ * Add or replace the enum property in `schema`, an `allOf` or object schema. Returns the added
+ * enum schema, or null for another kind of schema, which is left as it is.
+ */
+export function addEnumProperty(
+  schema: SchemaObject | undefined,
+  patch: EnumPatch,
+): SchemaObject | null {
+  if (schema?.allOf) {
+    return patchAllOf(schema.allOf, patch);
+  }
+  return isObjectSchema(schema) ? patchObjectSchema(schema, patch) : null;
+}