openapi-typesafe 0.0.0 → 1.0.0-rc.0

package/src/application/transform/schema/composition-type.ts

@@ -0,0 +1,183 @@
+import { irKeyword, irRecord } from "../../../domain/ir/constructors.js";
+import type { IrType } from "../../../domain/ir/nodes.js";
+import { createRef } from "../../../domain/openapi/json-pointer.js";
+import type { Schema, SchemaObject } from "../../../domain/openapi/schema-object.js";
+import { OutputFix } from "../../../domain/output-fixes.js";
+import { UNKNOWN_TYPE } from "../shared-types.js";
+import {
+  intersectionOf,
+  isPrimitiveType,
+  nullableOf,
+  omitKeys,
+  unionOf,
+  withRequiredKeys,
+} from "../type-combinators.js";
+import { coreType } from "./core-type.js";
+import { allOfMembers } from "./presence-members.js";
+import type { SchemaRequest } from "./schema-rule.js";
+import { unevaluatedPropertiesType } from "./unevaluated-properties.js";
+
+/** `anyOf` / `oneOf` variants; the position is part of the path so nested names stay unique. */
+function variantTypes(
+  variants: readonly Schema[],
+  keyword: "anyOf" | "oneOf",
+  request: SchemaRequest,
+): IrType[] {
+  return variants.map((variant, index) =>
+    request.transformNested(variant, {
+      ...request.location,
+      path: createRef([request.location.path, keyword, String(index)]),
+    }),
+  );
+}
+
+/**
+ * Whether an `allOf` item is a `$ref`. Like the original, this uses `in`, so a boolean item throws
+ * a TypeError instead of being accepted.
+ */
+function isRefItem(item: Schema): item is { readonly $ref: string } {
+  return "$ref" in (item as object);
+}
+
+/** A `$ref` item gets the parent's `required` keys that its target defines (`WithRequired`). */
+function refItemType(
+  item: { readonly $ref: string },
+  required: readonly string[],
+  request: SchemaRequest,
+): IrType {
+  const type = request.transformNested(item, request.location);
+  const { refs, discriminators, footer } = request.context;
+  const resolved = refs.resolve(item.$ref) as SchemaObject | undefined;
+  const isEligible =
+    resolved &&
+    typeof resolved === "object" &&
+    "properties" in resolved &&
+    !discriminators.isHandled(item.$ref);
+  if (!isEligible) {
+    return type;
+  }
+  const keys = required.filter((key) => Boolean(resolved.properties?.[key]));
+  if (keys.length > 0) {
+    footer.requireWithRequired();
+  }
+  return withRequiredKeys(type, keys);
+}
+
+/** An inline item merges the parent's `required` keys with its own. */
+function inlineItemType(item: Schema, required: readonly string[], request: SchemaRequest): IrType {
+  const own =
+    typeof item === "object" && Array.isArray((item as SchemaObject).required)
+      ? ((item as SchemaObject).required ?? [])
+      : [];
+  return request.transformNested(
+    { ...(item as SchemaObject), required: [...required, ...own] },
+    request.location,
+  );
+}
+
+/** `allOf` items; an item with a discriminator omits that property (the parent redefines it). */
+function allOfTypes(
+  items: readonly Schema[],
+  required: readonly string[],
+  request: SchemaRequest,
+): IrType[] {
+  return items.map((item) => {
+    const isRef = isRefItem(item);
+    const type = isRef
+      ? refItemType(item, required, request)
+      : inlineItemType(item, required, request);
+    const discriminator =
+      (isRef && request.context.discriminators.objectAt(item.$ref)) ||
+      (item as SchemaObject).discriminator;
+    return discriminator?.propertyName ? omitKeys(type, [discriminator.propertyName]) : type;
+  });
+}
+
+function oneOfType(previous: IrType | null, variants: readonly IrType[]): IrType {
+  const before = previous === null ? [] : [previous];
+  // Only `oneOf` may list primitives; then it stays a flat union.
+  return variants.every(isPrimitiveType)
+    ? unionOf([...before, ...variants])
+    : intersectionOf([...before, unionOf(variants)]);
+}
+
+/**
+ * `anyOf` is a union: TypeScript unions are not exclusive, which matches anyOf better than oneOf.
+ * By default the sibling type is one more member, as in the original. With `anyof-properties` it
+ * is intersected with the union, so it applies to every variant (#2380); for a `type` list, each
+ * listed type has applied `anyOf` already (`multipleTypes`), so the list is the whole type.
+ */
+function anyOfType(
+  previous: IrType | null,
+  schema: SchemaObject,
+  request: SchemaRequest,
+): IrType | null {
+  const variants = variantTypes(schema.anyOf ?? [], "anyOf", request);
+  if (variants.length === 0 || previous === null) {
+    return variants.length === 0 ? previous : unionOf(variants);
+  }
+  if (!request.context.options.fixes.has(OutputFix.ANYOF_PROPERTIES)) {
+    return unionOf([previous, ...variants]);
+  }
+  return Array.isArray(schema.type) ? previous : intersectionOf([previous, unionOf(variants)]);
+}
+
+/** Object enums are written as `oneOf` over their values. */
+function oneOfVariants(schema: SchemaObject): readonly Schema[] {
+  const objectEnum =
+    "type" in schema && schema.type === "object" && (schema.enum as Schema[] | undefined);
+  return schema.oneOf || objectEnum || [];
+}
+
+/**
+ * The parent's `required` keys, plus the keys of left-out `allOf` members (`allof-required`).
+ * Without such keys the parent's list stays as it is, duplicates included, as in the original.
+ */
+function requiredKeys(schema: SchemaObject, presenceKeys: readonly string[]): readonly string[] {
+  const own = schema.required ?? [];
+  return presenceKeys.length === 0 ? own : [...new Set([...own, ...presenceKeys])];
+}
+
+function composedType(schema: SchemaObject, request: SchemaRequest): IrType | null {
+  let type: IrType | null = null;
+  const core = coreType(schema, request);
+  const { members, required } = allOfMembers(schema.allOf ?? [], request);
+  const allOf = allOfTypes(members, requiredKeys(schema, required), request);
+  if (core !== null || allOf.length > 0) {
+    const allOfType = allOf.length > 0 ? [intersectionOf(allOf)] : [];
+    type = intersectionOf([...(core === null ? [] : [core]), ...allOfType]);
+  }
+  type = anyOfType(type, schema, request);
+  const oneOf = variantTypes(oneOfVariants(schema), "oneOf", request);
+  return oneOf.length > 0 ? oneOfType(type, oneOf) : type;
+}
+
+/** The composed type, with the `unevaluatedProperties` index signature when it applies. */
+function combinedType(schema: SchemaObject, request: SchemaRequest): IrType | null {
+  const type = composedType(schema, request);
+  const unevaluated = unevaluatedPropertiesType(schema, type, request);
+  if (unevaluated === null) {
+    return type;
+  }
+  if (type === null) {
+    return unevaluated;
+  }
+  // One flat intersection, so an `allOf` intersection is not printed in parentheses.
+  const parts = type.kind === "intersection" ? type.types : [type];
+  return intersectionOf([...parts, unevaluated]);
+}
+
+/**
+ * The schema with composition: core type and `allOf` intersected, then `anyOf` and `oneOf`. Without
+ * any of them: `Record<string, never>` (or `unknown` with `--empty-objects-unknown`) when `type` is
+ * present, else `unknown`. `nullable: true` adds `null`, except to the shared `unknown`.
+ */
+export function compositionType(schema: SchemaObject, request: SchemaRequest): IrType {
+  const { emptyObjectsUnknown } = request.context.options;
+  const empty =
+    "type" in schema
+      ? irRecord(irKeyword("string"), emptyObjectsUnknown ? UNKNOWN_TYPE : irKeyword("never"))
+      : UNKNOWN_TYPE;
+  const type = combinedType(schema, request) ?? empty;
+  return type !== UNKNOWN_TYPE && schema.nullable ? nullableOf([type]) : type;
+}

package/src/application/transform/schema/core-type.ts

@@ -0,0 +1,115 @@
+import { irKeyword, irReference, irUnion } from "../../../domain/ir/constructors.js";
+import type { IrType } from "../../../domain/ir/nodes.js";
+import { isRawBinarySchema } from "../../../domain/openapi/binary-content.js";
+import type {
+  Schema,
+  SchemaObject,
+  SchemaTypeName,
+} from "../../../domain/openapi/schema-object.js";
+import { unionOf } from "../type-combinators.js";
+import { arrayType } from "./array-type.js";
+import { objectType } from "./object-type.js";
+import type { SchemaRequest, SchemaRule } from "./schema-rule.js";
+
+const PRIMITIVE_TYPE_NAMES: ReadonlySet<SchemaTypeName | null> = new Set([
+  "boolean",
+  "string",
+  "number",
+  "integer",
+  "null",
+]);
+
+/** Each `type` of a list becomes a union member; one already listed in `oneOf` is skipped. */
+function multipleTypes(schema: SchemaObject, request: SchemaRequest): IrType {
+  const typeNames = schema.type as readonly (SchemaTypeName | null)[];
+  const { oneOf } = schema;
+  const members: IrType[] = [];
+  for (const typeName of typeNames) {
+    const isInOneOf =
+      Array.isArray(oneOf) &&
+      PRIMITIVE_TYPE_NAMES.has(typeName) &&
+      oneOf.some(
+        (variant) => typeof variant === "object" && "type" in variant && variant.type === typeName,
+      );
+    if (isInOneOf) {
+      continue;
+    }
+    // With oneOf, the member drops it, so oneOf is not applied once per member.
+    const variant = Array.isArray(oneOf)
+      ? { ...schema, type: typeName, oneOf: undefined }
+      : { ...schema, type: typeName };
+    members.push(
+      typeName === "null" || typeName === null
+        ? irKeyword("null")
+        : request.transformNested(variant as Schema, request.location),
+    );
+  }
+  return unionOf(members);
+}
+
+function keywordRule(
+  name: string,
+  typeNames: readonly string[],
+  keyword: "null" | "number" | "boolean",
+): SchemaRule {
+  return {
+    name,
+    matches: (schema) => typeNames.includes(schema.type as string),
+    transform: () => irKeyword(keyword),
+  };
+}
+
+/** The global type of raw binary data with `--binary-as-blob` (DOM lib, `@types/node`). */
+const BLOB_TYPE_NAME = "Blob";
+
+function isBinaryAsBlob(schema: SchemaObject, request: SchemaRequest): boolean {
+  return request.context.options.binaryAsBlob && isRawBinarySchema(schema);
+}
+
+function stringType(schema: SchemaObject, request: SchemaRequest): IrType {
+  return isBinaryAsBlob(schema, request) ? irReference(BLOB_TYPE_NAME) : irKeyword("string");
+}
+
+/** Rules for schemas with a `type`, in the original order. */
+const TYPED_RULES: readonly SchemaRule[] = [
+  keywordRule("null", ["null"], "null"),
+  { name: "string", matches: (schema) => schema.type === "string", transform: stringType },
+  keywordRule("number", ["number", "integer"], "number"),
+  keywordRule("boolean", ["boolean"], "boolean"),
+  { name: "array", matches: (schema) => schema.type === "array", transform: arrayType },
+  {
+    name: "multiple types",
+    matches: (schema) => Array.isArray(schema.type),
+    transform: multipleTypes,
+  },
+];
+
+/** The `transform` callback's type; a `questionToken` adds `undefined` here. */
+function customType(schema: SchemaObject, request: SchemaRequest): IrType | null {
+  const custom = request.context.callbacks.transform(schema, request.location);
+  if (custom === null) {
+    return null;
+  }
+  return custom.isOptional ? irUnion([custom.type, irKeyword("undefined")]) : custom.type;
+}
+
+/**
+ * The schema without composition keywords: the `transform` callback, then a typed rule, then raw
+ * binary without `type` (OpenAPI 3.1 allows leaving it out), then the object keywords. Null means
+ * the schema has no type of its own.
+ */
+export function coreType(schema: SchemaObject, request: SchemaRequest): IrType | null {
+  if ("type" in schema && schema.type) {
+    const custom = customType(schema, request);
+    if (custom !== null) {
+      return custom;
+    }
+    const rule = TYPED_RULES.find((candidate) => candidate.matches(schema));
+    if (rule !== undefined) {
+      return rule.transform(schema, request);
+    }
+  } else if (isBinaryAsBlob(schema, request)) {
+    return irReference(BLOB_TYPE_NAME);
+  }
+  return objectType(schema, request);
+}

package/src/application/transform/schema/discriminator-property.ts

@@ -0,0 +1,28 @@
+import { irProperty } from "../../../domain/ir/constructors.js";
+import type { IrPropertySignature } from "../../../domain/ir/nodes.js";
+import { toPropertyName } from "../../../domain/ir/property-name.js";
+import { parseRefPointer } from "../../../domain/openapi/json-pointer.js";
+import { literalType } from "../literal-type.js";
+import type { Discriminator } from "./schema-context.js";
+
+/**
+ * The value a schema has for its parent's discriminator: the mapping key whose target is this
+ * schema (a full `$ref` or a bare schema name), else the schema's own name (the last segment).
+ */
+function discriminatorValue(discriminator: Discriminator, path: string): string | undefined {
+  const name = parseRefPointer(path).pop();
+  const match = Object.entries(discriminator.mapping ?? {}).find(([, target]) =>
+    target.startsWith("#") ? parseRefPointer(target).pop() === name : target === name,
+  );
+  return match ? match[0] : name;
+}
+
+/** The discriminator property, typed as its literal value (`createDiscriminatorProperty`). */
+export function discriminatorProperty(
+  discriminator: Discriminator,
+  path: string,
+  isReadonly: boolean,
+): IrPropertySignature {
+  const value = discriminatorValue(discriminator, path);
+  return irProperty(toPropertyName(discriminator.propertyName), literalType(value), { isReadonly });
+}

package/src/application/transform/schema/enum-rule.ts

@@ -0,0 +1,157 @@
+import {
+  irIndexedAccess,
+  irKeyword,
+  irObject,
+  irReference,
+} from "../../../domain/ir/constructors.js";
+import type { IrType } from "../../../domain/ir/nodes.js";
+import { createRef, parseRefPointer } from "../../../domain/openapi/json-pointer.js";
+import type { SchemaObject } from "../../../domain/openapi/schema-object.js";
+import { literalType } from "../literal-type.js";
+import { refType } from "../ref-type.js";
+import { intersectionOf, unionOf } from "../type-combinators.js";
+import type { EnumMemberMetadata, SchemaOptions } from "./schema-context.js";
+import type { SchemaRequest, SchemaRule } from "./schema-rule.js";
+
+/** Removed from generated names, so `#/components/schemas/Status` gives `Status`. */
+const COMPONENT_SCHEMAS_PREFIX = "components/schemas";
+const UNION_KEYWORDS: ReadonlySet<string> = new Set(["anyOf", "oneOf"]);
+const INDEX_RE = /^\d+$/;
+
+function hasAdditionalProperties(schema: SchemaObject): boolean {
+  return "additionalProperties" in schema && Boolean(schema.additionalProperties);
+}
+
+/** A name from the schema's pointer: `#/components/schemas/Pet/status` → `/Pet/status`. */
+function nameFromPath(path: string | undefined): string {
+  return parseRefPointer(path ?? "")
+    .join("/")
+    .replace(COMPONENT_SCHEMAS_PREFIX, "");
+}
+
+function hasEnumMetadata(schema: SchemaObject): boolean {
+  return [
+    schema["x-enum-varnames"],
+    schema["x-enumNames"],
+    schema["x-enum-descriptions"],
+    schema["x-enumDescriptions"],
+  ].some(Array.isArray);
+}
+
+/**
+ * `--enum`: string and number enums become TypeScript enums. The original meant to allow `null`
+ * too, but tested `typeof value` against `null`, so an enum containing null stays a union.
+ */
+function isTsEnum(schema: SchemaObject, options: SchemaOptions): boolean {
+  if (!options.enum || !schema.enum) {
+    return false;
+  }
+  const isSupported = schema.enum.every((value) => ["string", "number"].includes(typeof value));
+  // `--conditional-enums` converts only enums that carry x-enum-* metadata.
+  return isSupported && (!options.conditionalEnums || hasEnumMetadata(schema));
+}
+
+function enumMetadata(schema: SchemaObject): EnumMemberMetadata[] {
+  return (schema.enum ?? []).map((_, index) => ({
+    name: schema["x-enum-varnames"]?.[index] ?? schema["x-enumNames"]?.[index],
+    description: schema["x-enum-descriptions"]?.[index] ?? schema["x-enumDescriptions"]?.[index],
+  }));
+}
+
+/**
+ * `additionalProperties: true` on a string enum keeps other strings allowed but still offers the
+ * listed values in editors: `"a" | "b" | (string & {})`.
+ */
+function withOtherStrings(type: IrType, schema: SchemaObject): IrType {
+  if (!hasAdditionalProperties(schema) || schema.type !== "string") {
+    return type;
+  }
+  return unionOf([type, intersectionOf([irKeyword("string"), irObject([])])]);
+}
+
+function tsEnumType(schema: SchemaObject, request: SchemaRequest): IrType {
+  // `isTsEnum` admits only strings and numbers, so there is no null member to split off.
+  const name = request.context.footer.addEnum({
+    name: nameFromPath(request.location.path),
+    values: (schema.enum ?? []) as (string | number)[],
+    metadata: enumMetadata(schema),
+  });
+  return withOtherStrings(irReference(name), schema);
+}
+
+function isUnionPosition(pointer: readonly string[], index: number): boolean {
+  const next = pointer[index + 1];
+  return UNION_KEYWORDS.has(pointer[index] as string) && next !== undefined && INDEX_RE.test(next);
+}
+
+/**
+ * The pointer of `--enum-values` arrays without union positions (`anyOf/0`), so names stay
+ * stable. Every property after the first union position is narrowed with `Extract`: a no-op where
+ * all variants have it, and the needed narrowing where only some do.
+ */
+function enumValuesPointer(path: string | undefined): { ref: string; extract: string[] } {
+  const pointer = parseRefPointer(path ?? "");
+  const kept: string[] = [];
+  let firstVariantStart: number | null = null;
+  for (let index = 0; index < pointer.length; index++) {
+    if (isUnionPosition(pointer, index)) {
+      firstVariantStart ??= index + 2;
+      index++;
+      continue;
+    }
+    kept.push(pointer[index] as string);
+  }
+  const extract =
+    firstVariantStart === null
+      ? []
+      : pointer
+          .slice(firstVariantStart)
+          .filter((segment) => !UNION_KEYWORDS.has(segment) && !INDEX_RE.test(segment));
+  return { ref: createRef(kept), extract };
+}
+
+function addEnumValues(schema: SchemaObject, request: SchemaRequest): void {
+  const { ref, extract } = enumValuesPointer(request.location.path);
+  const valuesType = refType(ref, { isDeep: true, extractProperties: extract });
+  request.context.footer.addEnumValues({
+    name: `${nameFromPath(request.location.path)}Values`,
+    // A record value (`additionalProperties`) is reached by indexing with `string`.
+    type: request.isFromAdditionalProperties
+      ? irIndexedAccess(valuesType, irReference("string"))
+      : valuesType,
+    values: (schema.enum ?? []) as (string | number)[],
+  });
+}
+
+function literalEnumType(schema: SchemaObject, request: SchemaRequest): IrType {
+  const values = schema.enum ?? [];
+  const isNullable =
+    (Array.isArray(schema.type) && schema.type.includes("null")) || Boolean(schema.nullable);
+  const literals = [...values.map(literalType), ...(isNullable ? [irKeyword("null")] : [])];
+  const type = withOtherStrings(unionOf(literals), schema);
+  const isListable = values.every(
+    (value) => typeof value === "string" || typeof value === "number",
+  );
+  if (request.context.options.enumValues && isListable) {
+    addEnumValues(schema, request);
+  }
+  return type;
+}
+
+/**
+ * `enum` on anything but an object (object enums are handled as `oneOf`). With
+ * `additionalProperties`, only string enums are handled here; others fall through to composition.
+ */
+export const enumRule: SchemaRule = {
+  name: "enum",
+  matches(schema) {
+    const isCandidate =
+      Array.isArray(schema.enum) && schema.type !== "object" && !("properties" in schema);
+    return isCandidate && (!hasAdditionalProperties(schema) || schema.type === "string");
+  },
+  transform(schema, request) {
+    return isTsEnum(schema, request.context.options)
+      ? tsEnumType(schema, request)
+      : literalEnumType(schema, request);
+  },
+};