openapi-typesafe 0.0.0 → 1.0.0-rc.0

package/src/application/transform/document/defs-root.ts

@@ -0,0 +1,25 @@
+import { irObject, irProperty } from "../../../domain/ir/constructors.js";
+import type { IrObjectType } from "../../../domain/ir/nodes.js";
+import { toPropertyName } from "../../../domain/ir/property-name.js";
+import { createRef } from "../../../domain/openapi/json-pointer.js";
+import type { Schema } from "../../../domain/openapi/schema-object.js";
+import { transformSchema } from "../schema/schema-transform.js";
+import type { TransformContext } from "../transform-context.js";
+
+/**
+ * The root `$defs` type: one required member per named subschema, so `#/$defs/<name>` refs
+ * (`$defs["<name>"]`) resolve. The original transformed the whole `$defs` map as one schema,
+ * which gave `Record<string, never>` and made every such ref `never` (research/legacy-bugs.md,
+ * item 18).
+ */
+export function defsRootType(
+  defs: Readonly<Record<string, Schema>>,
+  context: TransformContext,
+): IrObjectType {
+  const members = Object.entries(defs).map(([name, schema]) => {
+    const location = { path: createRef(["$defs", name]), schema };
+    const type = transformSchema(schema, location, context);
+    return irProperty(toPropertyName(name), type, { isReadonly: context.options.immutable });
+  });
+  return irObject(members);
+}

package/src/application/transform/document/document-member.ts

@@ -0,0 +1,20 @@
+import { irProperty } from "../../../domain/ir/constructors.js";
+import type { IrPropertySignature, IrType } from "../../../domain/ir/nodes.js";
+import { toPropertyName } from "../../../domain/ir/property-name.js";
+import { withSchemaComment } from "../schema-comment.js";
+
+export interface DocumentMemberFlags {
+  readonly isReadonly: boolean;
+  readonly isOptional?: boolean;
+}
+
+/** A member named by a document map key (media type, header, status code), with its JSDoc. */
+export function documentMember(
+  name: string,
+  type: IrType,
+  entry: unknown,
+  flags: DocumentMemberFlags,
+): IrPropertySignature {
+  const property = irProperty(toPropertyName(name), type, flags);
+  return withSchemaComment(property, entry);
+}

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

@@ -0,0 +1,157 @@
+import { irKeyword, irRecord } from "../../../domain/ir/constructors.js";
+import type {
+  IrDeclaration,
+  IrIntersectionType,
+  IrObjectType,
+  IrType,
+  IrTypeAliasDeclaration,
+} from "../../../domain/ir/nodes.js";
+import type { ComponentsObject } from "../../../domain/openapi/components-object.js";
+import type { DocumentObject } from "../../../domain/openapi/document-object.js";
+import type { PathsObject } from "../../../domain/openapi/path-item-object.js";
+import { READ_WRITE_MARKER_TYPES } from "../helper-types.js";
+import type { TransformContext, TransformOptions } from "../transform-context.js";
+import { componentsType } from "./components.js";
+import { defsRootType } from "./defs-root.js";
+import { keptDeprecatedComponents } from "./kept-deprecated.js";
+import { pathsType } from "./paths.js";
+import { apiPathsEnumDeclaration } from "./paths-enum.js";
+import { webhooksType } from "./webhooks.js";
+
+/** The root types, in output order. */
+const ROOT_KEYS = Object.freeze(["paths", "webhooks", "components", "$defs"] as const);
+type RootKey = (typeof ROOT_KEYS)[number];
+
+const OPERATIONS_NAME = "operations";
+/** The type of a root without members: `Record<string, never>`. */
+const EMPTY_ROOT_TYPE = irRecord(irKeyword("string"), irKeyword("never"));
+
+/** A root's type and the declarations that follow it (the `--root-types` aliases). */
+interface RootResult {
+  readonly type: IrType;
+  readonly aliases: readonly IrTypeAliasDeclaration[];
+}
+
+type RootTransform = (
+  node: object,
+  context: TransformContext,
+  document: DocumentObject,
+) => RootResult;
+
+/** Without `--exclude-deprecated` nothing is left out, so the scan is skipped. */
+function keptDeprecated(document: DocumentObject, context: TransformContext): ReadonlySet<object> {
+  return context.options.excludeDeprecated
+    ? keptDeprecatedComponents(document, context.refs)
+    : new Set();
+}
+
+const ROOT_TRANSFORMS: Readonly<Record<RootKey, RootTransform>> = {
+  paths: (node, context) => ({ type: pathsType(node as PathsObject, context), aliases: [] }),
+  webhooks: (node, context) => ({ type: webhooksType(node as PathsObject, context), aliases: [] }),
+  components: (node, context, document) => {
+    const kept = keptDeprecated(document, context);
+    const { type, rootTypes } = componentsType(node as ComponentsObject, context, kept);
+    return { type, aliases: rootTypes };
+  },
+  $defs: (node, context) => ({
+    type: defsRootType(node as NonNullable<DocumentObject["$defs"]>, context),
+    aliases: [],
+  }),
+};
+
+function emptyAlias(name: string): IrTypeAliasDeclaration {
+  return { kind: "typeAlias", name, isExported: true, type: EMPTY_ROOT_TYPE, comments: [] };
+}
+
+/** A root type that declares something: an object with members, or an intersection of them. */
+type RootBodyType = IrObjectType | IrIntersectionType;
+
+function isRootBody(type: IrType): type is RootBodyType {
+  return (type.kind === "object" && type.members.length > 0) || type.kind === "intersection";
+}
+
+/**
+ * A root with members: an interface, or a type alias with `--export-type`. An intersection (the
+ * `paths` of overlapping `--path-params-as-types` keys) can only be a type alias.
+ */
+function rootDeclaration(
+  name: RootKey,
+  type: RootBodyType,
+  options: TransformOptions,
+): IrDeclaration {
+  return options.exportType || type.kind === "intersection"
+    ? { kind: "typeAlias", name, isExported: true, type, comments: [] }
+    : { kind: "interface", name, isExported: true, members: type.members, comments: [] };
+}
+
+/**
+ * The declarations of one root. A root that is missing, or whose type has no members, is
+ * `Record<string, never>`. Only an object type (or the `paths` intersection) counts as having
+ * members: a callback type the IR keeps as raw text does not (ADR-004).
+ */
+function rootDeclarations(
+  root: RootKey,
+  document: DocumentObject,
+  context: TransformContext,
+): IrDeclaration[] {
+  const node: unknown = document[root];
+  if (!node || typeof node !== "object") {
+    context.diagnostics.debug(`${root} done (skipped)`, 0);
+    return [emptyAlias(root)];
+  }
+  const startedAt = context.diagnostics.now();
+  const { type, aliases } = ROOT_TRANSFORMS[root](node, context, document);
+  if (!isRootBody(type)) {
+    context.diagnostics.debug(`${root} done (skipped)`, 0);
+    return [emptyAlias(root), ...aliases];
+  }
+  const declaration = rootDeclaration(root, type, context.options);
+  context.diagnostics.debug(`${root} done`, context.diagnostics.now() - startedAt);
+  return [declaration, ...aliases];
+}
+
+/**
+ * The `inject` text as written (ADR-010, decision 4), without the blank lines around it. The
+ * original reprinted it with the TypeScript printer; text without code printed nothing then.
+ */
+function withoutBlankLinesAround(text: string): string {
+  return text.replace(/^(?:[ \t]*\r?\n)+/, "").trimEnd();
+}
+
+/**
+ * The document's declarations before the footer: helper types, injected code, then one root type
+ * per root key with the aliases that follow it.
+ */
+export function documentBody(document: DocumentObject, context: TransformContext): IrDeclaration[] {
+  const declarations: IrDeclaration[] = [];
+  if (context.options.readWriteMarkers) {
+    declarations.push({ kind: "rawDeclaration", text: READ_WRITE_MARKER_TYPES });
+  }
+  const inject = withoutBlankLinesAround(context.options.inject ?? "");
+  if (inject !== "") {
+    declarations.push({ kind: "rawDeclaration", text: inject });
+  }
+  for (const root of ROOT_KEYS) {
+    declarations.push(...rootDeclarations(root, document, context));
+  }
+  return declarations;
+}
+
+/**
+ * The declarations after the footer: an empty `operations` type when the footer has no
+ * operations, and the `--make-paths-enum` enum.
+ */
+export function documentClosing(
+  document: DocumentObject,
+  context: TransformContext,
+  hasOperations: boolean,
+): IrDeclaration[] {
+  const declarations: IrDeclaration[] = [];
+  if (!hasOperations) {
+    declarations.push(emptyAlias(OPERATIONS_NAME));
+  }
+  if (context.options.makePathsEnum && document.paths) {
+    declarations.push(apiPathsEnumDeclaration(document.paths));
+  }
+  return declarations;
+}

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/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");
+}