openapi-typesafe 0.0.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/header.ts

@@ -0,0 +1,34 @@
+import { irObject } from "../../../domain/ir/constructors.js";
+import type { IrType } from "../../../domain/ir/nodes.js";
+import type { HeaderObject } from "../../../domain/openapi/header-object.js";
+import { escapePointerSegment } from "../../../domain/openapi/json-pointer.js";
+import { documentEntries } from "../document-entries.js";
+import type { SchemaContext, SchemaLocation } from "../schema/schema-context.js";
+import { transformSchema } from "../schema/schema-transform.js";
+import { UNKNOWN_TYPE } from "../shared-types.js";
+import { documentMember } from "./document-member.js";
+import { contentEntryType } from "./media-type.js";
+
+/**
+ * A header's type (OpenAPI 3.1 §4.8.21): its schema, else an object with one property per media
+ * type in `content`, else `unknown`.
+ */
+export function headerType(
+  header: HeaderObject,
+  location: SchemaLocation,
+  context: SchemaContext,
+): IrType {
+  if (header.schema) {
+    return transformSchema(header.schema, location, context);
+  }
+  if (!header.content) {
+    return UNKNOWN_TYPE;
+  }
+  const members = documentEntries(header.content, context.options).map(([contentType, entry]) => {
+    // Unlike other content maps, the original joins this path by hand: a missing path is `#`.
+    const path = `${location.path ?? "#"}/${escapePointerSegment(contentType)}`;
+    const type = contentEntryType(entry, { ...location, path }, context);
+    return documentMember(contentType, type, entry, { isReadonly: context.options.immutable });
+  });
+  return irObject(members);
+}

package/src/application/transform/document/kept-deprecated.ts

@@ -0,0 +1,135 @@
+import {
+  COMPONENT_KINDS,
+  type ComponentsObject,
+  DECLARED_COMPONENT_KINDS,
+} from "../../../domain/openapi/components-object.js";
+import type { DocumentObject } from "../../../domain/openapi/document-object.js";
+import { isDeprecated } from "../document-entries.js";
+import type { RefResolver } from "../schema/schema-context.js";
+
+/**
+ * `--exclude-deprecated` and references (roadmap R10.3, backlog 29). A deprecated component is
+ * left out, but a kept schema may still point to it (an array's `items`, say), and the output then
+ * names a missing `components` key. This scan finds the deprecated components that the kept output
+ * references, so they are kept too. It follows the generator's rules: a property, parameter or
+ * operation whose (resolved) object is deprecated is dropped, so its `$ref` does not count. Keys
+ * that are not typed are not followed, so a component they name stays out, as before.
+ */
+
+/** Keys whose contents the generator does not type. */
+const UNTYPED_KEYS: ReadonlySet<string> = new Set([
+  "callbacks",
+  "discriminator",
+  "example",
+  "examples",
+  "externalDocs",
+  "links",
+  "security",
+  "securitySchemes",
+  "servers",
+  "xml",
+]);
+const EXTENSION_PREFIX = "x-";
+/** Keys whose entries the generator drops when the entry or its `$ref` target is deprecated. */
+const RESOLVED_ENTRY_KEYS: ReadonlySet<string> = new Set([
+  "properties",
+  "parameters",
+  "get",
+  "put",
+  "post",
+  "delete",
+  "options",
+  "head",
+  "patch",
+  "trace",
+  "query",
+]);
+const COMPONENTS_PREFIX = "#/components/";
+
+interface Scan {
+  readonly refs: RefResolver;
+  /** The deprecated components to keep, as the document's own objects. */
+  readonly kept: Set<object>;
+}
+
+function isObject(value: unknown): value is Readonly<Record<string, unknown>> {
+  return typeof value === "object" && value !== null;
+}
+
+function refOf(value: unknown): string | undefined {
+  return isObject(value) && typeof value.$ref === "string" ? value.$ref : undefined;
+}
+
+/** Whether a dropped-when-deprecated entry is dropped: its own or its target's `deprecated`. */
+function isDroppedEntry(value: unknown, scan: Scan): boolean {
+  const ref = refOf(value);
+  return isDeprecated(value) || (ref !== undefined && isDeprecated(scan.refs.resolve(ref)));
+}
+
+/** A `$ref` to a deprecated component keeps it, and the component is scanned once. */
+function visitRef(ref: string, scan: Scan): void {
+  const target = ref.startsWith(COMPONENTS_PREFIX) ? scan.refs.resolve(ref) : undefined;
+  if (isObject(target) && isDeprecated(target) && !scan.kept.has(target)) {
+    scan.kept.add(target);
+    visitContents(target, scan);
+  }
+}
+
+function visitEntries(value: unknown, scan: Scan): void {
+  for (const entry of Array.isArray(value) ? value : Object.values(value as object)) {
+    if (!isDroppedEntry(entry, scan)) {
+      visit(entry, scan);
+    }
+  }
+}
+
+/** A node of kept output; a deprecated object here is dropped, so it is not followed. */
+function visit(node: unknown, scan: Scan): void {
+  if (Array.isArray(node)) {
+    for (const item of node) {
+      visit(item, scan);
+    }
+  } else if (isObject(node) && !isDeprecated(node)) {
+    visitContents(node, scan);
+  }
+}
+
+/** The `$ref` and the typed keys of an object. */
+function visitContents(node: Readonly<Record<string, unknown>>, scan: Scan): void {
+  const ref = refOf(node);
+  if (ref !== undefined) {
+    visitRef(ref, scan);
+  }
+  for (const [key, value] of Object.entries(node)) {
+    if (UNTYPED_KEYS.has(key) || key.startsWith(EXTENSION_PREFIX) || !isObject(value)) {
+      continue;
+    }
+    if (RESOLVED_ENTRY_KEYS.has(key)) {
+      visitEntries(key === "properties" || key === "parameters" ? value : [value], scan);
+    } else {
+      visit(value, scan);
+    }
+  }
+}
+
+/** The kept (not deprecated) entries of the typed component kinds. */
+function keptComponentEntries(components: ComponentsObject | undefined): unknown[] {
+  const kinds = [...COMPONENT_KINDS, ...DECLARED_COMPONENT_KINDS];
+  return kinds.flatMap((kind) =>
+    Object.values(components?.[kind] ?? {}).filter((item) => !isDeprecated(item)),
+  );
+}
+
+/**
+ * The deprecated components that kept output references, as the objects of `document.components`
+ * (the resolver returns those), so names that need escaping in a `$ref` match too.
+ */
+export function keptDeprecatedComponents(
+  document: DocumentObject,
+  refs: RefResolver,
+): ReadonlySet<object> {
+  const scan: Scan = { refs, kept: new Set() };
+  visit([document.paths, document.webhooks, document.$defs], scan);
+  visit(keptComponentEntries(document.components), scan);
+  return scan.kept;
+}

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/media-type.ts

@@ -0,0 +1,78 @@
+import { irObject, irProperty } from "../../../domain/ir/constructors.js";
+import type { 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 ContentMap,
+  isMediaTypeComponentRef,
+  type MediaTypeObject,
+} from "../../../domain/openapi/media-type-object.js";
+import { documentEntries } from "../document-entries.js";
+import type { SchemaContext, SchemaLocation } from "../schema/schema-context.js";
+import { transformSchema } from "../schema/schema-transform.js";
+import { UNKNOWN_TYPE } from "../shared-types.js";
+import { documentMember } from "./document-member.js";
+
+/** The sibling of `content` that holds item types (ADR-020). */
+const ITEM_CONTENT_KEY = "itemContent";
+
+/** A media type's schema, or `unknown` when it has none (OpenAPI 3.1 §4.8.14). */
+export function mediaTypeType(
+  mediaType: MediaTypeObject,
+  location: SchemaLocation,
+  context: SchemaContext,
+): IrType {
+  return mediaType.schema ? transformSchema(mediaType.schema, location, context) : UNKNOWN_TYPE;
+}
+
+/** A `content` entry: a `$ref` is transformed like a schema `$ref`, the rest as a media type. */
+export function contentEntryType(
+  entry: ContentMap[string],
+  location: SchemaLocation,
+  context: SchemaContext,
+): IrType {
+  // `in` throws for a null entry, as in the original.
+  return "$ref" in entry
+    ? transformSchema(entry, location, context)
+    : mediaTypeType(entry, location, context);
+}
+
+/** The `itemSchema` of a `content` entry and where it is, following a `$ref` to a component. */
+function itemSchemaAt(
+  entry: ContentMap[string],
+  path: string,
+  context: SchemaContext,
+): { readonly schema: MediaTypeObject["itemSchema"]; readonly path: string } {
+  if ("$ref" in entry) {
+    // Other `$ref`s in `content` keep their pre-3.2 output, so only media type components count.
+    const resolved = isMediaTypeComponentRef(entry.$ref)
+      ? (context.refs.resolve(entry.$ref) as MediaTypeObject | undefined)
+      : undefined;
+    return { schema: resolved?.itemSchema, path: createRef([entry.$ref, "itemSchema"]) };
+  }
+  return { schema: entry.itemSchema, path: createRef([path, "itemSchema"]) };
+}
+
+/**
+ * `itemContent`: the type of one item of each media type with an `itemSchema` (OpenAPI 3.2), next
+ * to `content`, which keeps the type of the complete body. Null when no media type has one.
+ */
+export function itemContentMember(
+  content: ContentMap,
+  location: SchemaLocation,
+  context: SchemaContext,
+  flags: { readonly isReadonly: boolean },
+): IrPropertySignature | null {
+  const members = documentEntries(content, context.options).flatMap(([mediaType, entry]) => {
+    const contentPath = createRef([location.path, "content", mediaType]);
+    const item = itemSchemaAt(entry, contentPath, context);
+    if (item.schema === undefined) {
+      return [];
+    }
+    const type = transformSchema(item.schema, { ...location, path: item.path }, context);
+    return [documentMember(mediaType, type, entry, { isReadonly: context.options.immutable })];
+  });
+  return members.length > 0
+    ? irProperty(toPropertyName(ITEM_CONTENT_KEY), irObject(members), flags)
+    : null;
+}

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

@@ -0,0 +1,64 @@
+import { irKeyword, irProperty } from "../../../domain/ir/constructors.js";
+import type { IrPropertySignature } 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 { RequestBodyObject } from "../../../domain/openapi/request-body-object.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 { parametersMember } from "./parameters.js";
+import { requestBodyType } from "./request-body.js";
+import { responsesType } from "./responses.js";
+
+/** `requestBody`, optional unless the resolved body is required; `requestBody?: never` if none. */
+function requestBodyMember(
+  operation: OperationObject,
+  location: SchemaLocation,
+  context: TransformContext,
+): IrPropertySignature {
+  const isReadonly = context.options.immutable;
+  const body = operation.requestBody;
+  if (!body) {
+    return irProperty(toPropertyName("requestBody"), irKeyword("never"), {
+      isOptional: true,
+      isReadonly,
+    });
+  }
+  const isReference = "$ref" in body;
+  const type = isReference
+    ? refType(body.$ref)
+    : requestBodyType(
+        body,
+        { ...location, path: createRef([location.path, "requestBody"]) },
+        context,
+      );
+  const resolved = isReference
+    ? (context.refs.resolve(body.$ref) as RequestBodyObject | undefined)
+    : body;
+  return documentMember("requestBody", type, body, {
+    isReadonly,
+    isOptional: !resolved?.required,
+  });
+}
+
+/**
+ * The members of an operation (OpenAPI 3.1 §4.8.10): `parameters`, `requestBody` and `responses`.
+ * `location.path` is the operation's pointer.
+ */
+export function operationMembers(
+  operation: OperationObject,
+  location: SchemaLocation,
+  context: TransformContext,
+): IrPropertySignature[] {
+  // Built in document order: each part may add footer declarations (enums), in this order.
+  const parameters = parametersMember(operation.parameters ?? [], location, context);
+  const requestBody = requestBodyMember(operation, location, context);
+  const responses = responsesType(operation.responses ?? {}, location, context);
+  return [
+    parameters,
+    requestBody,
+    irProperty(toPropertyName("responses"), responses, { isReadonly: context.options.immutable }),
+  ];
+}

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

@@ -0,0 +1,45 @@
+import { irKeyword } from "../../../domain/ir/constructors.js";
+import type { IrType } from "../../../domain/ir/nodes.js";
+import { createRef } from "../../../domain/openapi/json-pointer.js";
+import {
+  type ParameterObject,
+  QUERYSTRING_LOCATION,
+} from "../../../domain/openapi/parameter-object.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.
+ */
+function querystringType(
+  parameter: ParameterObject,
+  location: SchemaLocation,
+  context: SchemaContext,
+): IrType {
+  const [mediaType, entry] = Object.entries(parameter.content ?? {})[0] ?? [];
+  if (mediaType === undefined || entry === undefined) {
+    return irKeyword("string");
+  }
+  const path = createRef([location.path, "content", mediaType]);
+  return contentEntryType(entry, { ...location, path }, context);
+}
+
+/**
+ * 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.
+ */
+export function parameterType(
+  parameter: ParameterObject,
+  location: SchemaLocation,
+  context: SchemaContext,
+): IrType {
+  if (parameter.in === QUERYSTRING_LOCATION) {
+    return querystringType(parameter, location, context);
+  }
+  return parameter.schema
+    ? transformSchema(parameter.schema, location, context)
+    : irKeyword("string");
+}