openapi-typesafe 0.0.0 → 1.0.0-rc.1

package/src/application/transform/ref-pointer/typed-walk.ts

@@ -0,0 +1,192 @@
+import { irIndexedAccess, irKeyword, irReference } from "../../../domain/ir/constructors.js";
+import type { IrKeyword, IrType } from "../../../domain/ir/nodes.js";
+import { indexBy, indexKeyword, rootType } from "../ref-type.js";
+import type { RefResolver, SchemaOptions } from "../schema/schema-context.js";
+import {
+  followRefs,
+  isArrayShape,
+  isJsonObject,
+  isObjectShape,
+  type Presence,
+  propertyPresence,
+  schemaPresence,
+} from "./generated-shape.js";
+import {
+  isOptionalHeader,
+  isOptionalRequestBody,
+  isParameterList,
+  isTypedAsSchema,
+  leadingNode,
+  leadingSegmentsOf,
+  type RefPointer,
+  startsInSchema,
+} from "./pointer-walk.js";
+
+/**
+ * The type of a `$ref` pointer as the generated types have it: the `schema` of a media type,
+ * header or component parameter is its type, `items` is indexed by `number`,
+ * `additionalProperties` by `string`, and a value that may be `undefined` or `null` is wrapped in
+ * `NonNullable` before it is indexed. The walk stops at a segment with no type of its own
+ * (`allOf/0`, `definitions/A`, operation `parameters/0`): the caller types the target itself.
+ */
+
+const DEFS_KEYWORD = "$defs";
+
+export interface TypedWalk {
+  readonly type: IrType;
+  /** The document node the type stands for (not followed through a `$ref`). */
+  readonly node: unknown;
+  readonly isSchema: boolean;
+  /** The segment is a property or `$defs` name, not a keyword. */
+  readonly isName: boolean;
+  readonly presence: Presence;
+}
+
+export interface TypedWalkInput {
+  readonly pointer: RefPointer;
+  readonly options: SchemaOptions;
+  readonly refs: RefResolver;
+}
+
+/** The walk result: a type, or the index of the first segment that has no type. */
+export type TypedWalkResult =
+  | { readonly kind: "typed"; readonly walk: TypedWalk }
+  | { readonly kind: "untyped"; readonly index: number };
+
+function present(walk: TypedWalk): IrType {
+  return walk.presence === "present" ? walk.type : irReference("NonNullable", [walk.type]);
+}
+
+function indexEntries(walk: TypedWalk, key: IrKeyword, keyword: string, refs: RefResolver) {
+  const owner = followRefs(walk.node, refs);
+  const child = isJsonObject(owner) ? owner[keyword] : undefined;
+  return {
+    ...walk,
+    type: irIndexedAccess(present(walk), irKeyword(key)),
+    node: child,
+    presence: schemaPresence(child, refs),
+  };
+}
+
+function nameStep(walk: TypedWalk, name: string, isLast: boolean, input: TypedWalkInput) {
+  const owner = followRefs(walk.node, input.refs);
+  const properties = isJsonObject(owner) && isJsonObject(owner.properties) ? owner.properties : {};
+  const type =
+    walk.presence === "present"
+      ? indexKeyword(walk.type, name, isLast)
+      : indexBy(present(walk), name);
+  return {
+    ...walk,
+    type,
+    node: properties[name],
+    isName: false,
+    presence: propertyPresence(walk.node, name, input.options, input.refs),
+  };
+}
+
+/** `$defs` is optional (`NonNullable` when more follows); its members are present. */
+function defsStep(walk: TypedWalk, owner: unknown, isLast: boolean): TypedWalk {
+  const defs = isJsonObject(owner) && isJsonObject(owner[DEFS_KEYWORD]) ? owner[DEFS_KEYWORD] : {};
+  return {
+    ...walk,
+    type: indexKeyword(present(walk), DEFS_KEYWORD, isLast),
+    node: { properties: defs, required: Object.keys(defs) },
+    isName: true,
+    presence: "present",
+  };
+}
+
+const SHAPED_KEYWORDS: ReadonlySet<string> = new Set([
+  "properties",
+  "items",
+  "additionalProperties",
+]);
+
+/**
+ * Whether the keyword gives the owner's generated type a member: `items` only an array,
+ * `properties` and `additionalProperties` only an object (`type: string` ignores them). A node
+ * that is not in the document is indexed as the keyword says.
+ */
+function hasKeywordMember(owner: unknown, segment: string): boolean {
+  if (!SHAPED_KEYWORDS.has(segment) || !isJsonObject(owner)) {
+    return true;
+  }
+  return segment === "items" ? isArrayShape(owner) : isObjectShape(owner);
+}
+
+function keywordStep(walk: TypedWalk, segment: string, isLast: boolean, input: TypedWalkInput) {
+  const owner = followRefs(walk.node, input.refs);
+  if (!hasKeywordMember(owner, segment)) {
+    return null;
+  }
+  switch (segment) {
+    case "properties":
+      return { ...walk, isName: true };
+    case "items":
+      return indexEntries(walk, "number", "items", input.refs);
+    case "additionalProperties":
+      return indexEntries(walk, "string", "additionalProperties", input.refs);
+    case DEFS_KEYWORD:
+      return defsStep(walk, owner, isLast);
+    default:
+      return null;
+  }
+}
+
+function containerStep(walk: TypedWalk, index: number, input: TypedWalkInput): TypedWalk {
+  const segment = input.pointer.segments[index] as string;
+  const owner = followRefs(walk.node, input.refs);
+  const isOptional =
+    (segment === "requestBody" && isOptionalRequestBody(owner, input.refs)) ||
+    isOptionalHeader(input.pointer, index, owner);
+  return {
+    ...walk,
+    type: indexBy(present(walk), segment),
+    node: isJsonObject(owner) ? owner[segment] : undefined,
+    presence: isOptional ? "absent" : "present",
+  };
+}
+
+function step(walk: TypedWalk, index: number, input: TypedWalkInput): TypedWalk | null {
+  const { segments } = input.pointer;
+  const segment = segments[index] as string;
+  const isLast = index === segments.length - 1;
+  if (walk.isSchema) {
+    return walk.isName
+      ? nameStep(walk, segment, isLast, input)
+      : keywordStep(walk, segment, isLast, input);
+  }
+  if (segment === "schema" && isTypedAsSchema(input.pointer, index)) {
+    const owner = followRefs(walk.node, input.refs);
+    const schema = isJsonObject(owner) ? owner.schema : undefined;
+    // The container's type is its schema's type: an optional header stays optional.
+    const presence = walk.presence === "absent" ? "absent" : schemaPresence(schema, input.refs);
+    return { ...walk, node: schema, isSchema: true, presence };
+  }
+  return isParameterList(input.pointer, index) ? null : containerStep(walk, index, input);
+}
+
+/** Walk the whole pointer; see the module comment. */
+export function typedWalk(input: TypedWalkInput): TypedWalkResult {
+  const { pointer } = input;
+  const node = leadingNode(pointer, input.refs);
+  const isSchema = startsInSchema(pointer);
+  let walk: TypedWalk = {
+    type: indexBy(
+      rootType(pointer.rootSegment, false),
+      ...pointer.segments.slice(0, leadingSegmentsOf(pointer)),
+    ),
+    node,
+    isSchema,
+    isName: false,
+    presence: isSchema ? schemaPresence(node, input.refs) : "present",
+  };
+  for (let index = leadingSegmentsOf(pointer); index < pointer.segments.length; index++) {
+    const next = step(walk, index, input);
+    if (next === null) {
+      return { kind: "untyped", index };
+    }
+    walk = next;
+  }
+  return { kind: "typed", walk };
+}

package/src/application/transform/ref-type.ts

@@ -0,0 +1,102 @@
+import { ERROR_CODES, OpenAPITypesafeError } from "../../domain/errors.js";
+import {
+  irIndexedAccess,
+  irKeyword,
+  irObject,
+  irProperty,
+  irReference,
+  irString,
+} from "../../domain/ir/constructors.js";
+import type { IrType } from "../../domain/ir/nodes.js";
+import { toPropertyName } from "../../domain/ir/property-name.js";
+import { parseRefPointer } from "../../domain/openapi/json-pointer.js";
+
+/** Where a referenced parameter lives in the generated `parameters` type. */
+export interface RefParameterTarget {
+  readonly in: string;
+  readonly name: string;
+}
+
+export interface RefTypeOptions {
+  /** Wrap the root in `FlattenedDeepRequired<…>`. */
+  readonly isDeep?: boolean;
+  /** Segments to narrow with `Extract<T, { segment: unknown }>` before indexing. */
+  readonly extractProperties?: readonly string[];
+  /** Set when the `$ref` resolves to a parameter object: its last segment indexes `in`, `name`. */
+  readonly parameter?: RefParameterTarget | null;
+}
+
+export class InvalidRefError extends OpenAPITypesafeError {
+  constructor(ref: string) {
+    super({
+      code: ERROR_CODES.SCHEMA_REF_INVALID,
+      message: `Error parsing $ref: ${ref}. Is this a valid $ref?`,
+      details: { ref },
+    });
+    this.name = "InvalidRefError";
+  }
+}
+
+/** Segments that index into the root type, always as escaped string literal types. */
+export function indexBy(type: IrType, ...segments: readonly string[]): IrType {
+  return segments.reduce<IrType>(
+    (object, segment) => irIndexedAccess(object, irString(segment, "escaped")),
+    type,
+  );
+}
+
+/**
+ * `Extract<T, { name: unknown }>`. The original wrote the name as an identifier even when it is
+ * not one (`{ content-type: unknown }`), which is a syntax error; it is now quoted like any other
+ * property name, and an identifier stays as it was.
+ */
+export function extractVariantsWith(type: IrType, propertyName: string): IrType {
+  const probe = irProperty(toPropertyName(propertyName), irKeyword("unknown"));
+  return irReference("Extract", [type, irObject([probe])]);
+}
+
+const DEFS_KEYWORD = "$defs";
+
+/**
+ * Index by `segment`. A `$defs` member is optional (it is a keyword, not data), so when more
+ * segments follow it is wrapped in `NonNullable<…>` first; otherwise the next index fails on
+ * `undefined` (upstream #2664).
+ */
+export function indexKeyword(type: IrType, segment: string, isLast: boolean): IrType {
+  const indexed = indexBy(type, segment);
+  return segment === DEFS_KEYWORD && !isLast ? irReference("NonNullable", [indexed]) : indexed;
+}
+
+export function rootType(rootSegment: string, isDeep: boolean): IrType {
+  return irReference(isDeep ? `FlattenedDeepRequired<${rootSegment}>` : rootSegment);
+}
+
+/**
+ * The indexed-access type of a `$ref` into the generated types (the original `oapiRef`), for
+ * example `components["schemas"]["Foo"]`. The first three segments index directly. After them,
+ * `properties` segments are skipped (objects are flattened, upstream issue 1742), a parameter's
+ * last segment becomes `[in][name]`, and listed segments are narrowed with `Extract` first.
+ *
+ * Throws InvalidRefError when the `$ref` has no pointer.
+ */
+export function refType(ref: string, options: RefTypeOptions = {}): IrType {
+  const [rootSegment, ...pointer] = parseRefPointer(ref);
+  if (rootSegment === undefined) {
+    throw new InvalidRefError(ref);
+  }
+  const extracted = new Set(options.extractProperties ?? []);
+  const lastIndex = pointer.length - 1;
+  const leading = indexBy(rootType(rootSegment, options.isDeep ?? false), ...pointer.slice(0, 2));
+  return pointer.slice(2).reduce<IrType>((type, segment, offset) => {
+    if (segment === "properties") {
+      return type;
+    }
+    if (options.parameter && offset + 2 === lastIndex) {
+      return indexBy(type, options.parameter.in, options.parameter.name);
+    }
+    const isLast = offset + 2 === lastIndex;
+    return extracted.has(segment)
+      ? indexBy(extractVariantsWith(type, segment), segment)
+      : indexKeyword(type, segment, isLast);
+  }, leading);
+}

package/src/application/transform/schema/access-flags.ts

@@ -0,0 +1,63 @@
+import type { Schema, SchemaObject } from "../../../domain/openapi/schema-object.js";
+import { OutputFix } from "../../../domain/output-fixes.js";
+import type { SchemaContext } from "./schema-context.js";
+
+/** Whether a property is `readOnly` or `writeOnly` (JSON Schema 2020-12 Validation §9.4). */
+export interface AccessFlags {
+  readonly isReadOnly: boolean;
+  readonly isWriteOnly: boolean;
+}
+
+const NO_FLAGS: AccessFlags = { isReadOnly: false, isWriteOnly: false };
+
+function ownFlags(schema: SchemaObject): AccessFlags {
+  return { isReadOnly: Boolean(schema.readOnly), isWriteOnly: Boolean(schema.writeOnly) };
+}
+
+function merged(left: AccessFlags, right: AccessFlags): AccessFlags {
+  return {
+    isReadOnly: left.isReadOnly || right.isReadOnly,
+    isWriteOnly: left.isWriteOnly || right.isWriteOnly,
+  };
+}
+
+/**
+ * The flags of a schema and of the schemas that always apply to the same value: the one its
+ * `$ref` names and its `allOf` members, followed until a schema repeats. `readOnly` is an
+ * annotation, and the annotations of those schemas are the value's (2020-12 Core §7.7.1); in
+ * OpenAPI 3.0 a referenced schema is the property's definition. `anyOf` and `oneOf` members apply
+ * only when they match, which the type cannot tell, so they are not read.
+ */
+function appliedFlags(
+  schema: Schema | undefined,
+  context: SchemaContext,
+  seen: ReadonlySet<Schema>,
+): AccessFlags {
+  if (typeof schema !== "object" || schema === null || seen.has(schema)) {
+    return NO_FLAGS;
+  }
+  const inner = new Set([...seen, schema]);
+  // `readOnly` next to a `$ref` is read too, as the generator always has.
+  const object = schema as SchemaObject & { readonly $ref?: unknown };
+  const target =
+    typeof object.$ref === "string" ? (context.refs.resolve(object.$ref) as Schema) : undefined;
+  return (object.allOf ?? []).reduce<AccessFlags>(
+    (flags, member) => merged(flags, appliedFlags(member, context, inner)),
+    merged(ownFlags(object), appliedFlags(target, context, inner)),
+  );
+}
+
+/**
+ * The flags of a property schema. Without the `read-write-refs` fix only the keywords written on
+ * it count, as in openapi-typescript; with it, also those of the schemas its `$ref` and `allOf`
+ * apply (upstream #1938).
+ */
+export function propertyAccessFlags(value: Schema, context: SchemaContext): AccessFlags {
+  if (typeof value !== "object") {
+    return NO_FLAGS;
+  }
+  if (!context.options.fixes.has(OutputFix.READ_WRITE_REFS)) {
+    return ownFlags(value as SchemaObject);
+  }
+  return appliedFlags(value, context, new Set());
+}

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

@@ -0,0 +1,213 @@
+import {
+  irArray,
+  irOptionalTupleElement,
+  irReadonly,
+  irTuple,
+  irTupleElement,
+} from "../../../domain/ir/constructors.js";
+import type { IrTupleElement, IrType } from "../../../domain/ir/nodes.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 { unionOf } from "../type-combinators.js";
+import type { SchemaRequest } from "./schema-rule.js";
+
+/**
+ * `--array-length` writes tuples only while the estimated number of tuple elements stays below
+ * this; the original chose it as roughly where TypeScript starts to struggle with tuple inference.
+ */
+const MAX_LENGTH_TUPLE_ELEMENTS = 30;
+
+/**
+ * The tuple of `prefixItems` (or of an `items` list); null without either. The original closes a
+ * `prefixItems` tuple and requires every element; the `prefix-items` fix does not.
+ */
+function prefixTupleType(schema: SchemaObject, request: SchemaRequest): IrType | null {
+  const { items } = schema;
+  if (schema.prefixItems && isPrefixItemsFixed(schema, request)) {
+    return prefixItemsTupleType(schema.prefixItems, schema, request);
+  }
+  if (!schema.prefixItems && !Array.isArray(items)) {
+    return null;
+  }
+  const prefixItems = schema.prefixItems ?? (items as SchemaObject[]);
+  return irTuple(
+    prefixItems.map((item) => irTupleElement(request.transformNested(item, request.location))),
+  );
+}
+
+/** The type of the items after the prefix, or null when there may be none (`false`). */
+function restItemType(schema: Schema, request: SchemaRequest): IrType | null {
+  return schema === false ? null : request.transformNested(schema, request.location);
+}
+
+/**
+ * The type of the items after a `prefixItems` tuple (JSON Schema 2020-12 §10.3.1): `items`, else
+ * `unevaluatedItems`, which does not apply to the items `contains` matches, else any item. Null
+ * when no item may follow. An `items` list is not a schema in 2020-12, so it allows any item.
+ */
+function prefixRestType(schema: SchemaObject, request: SchemaRequest): IrType | null {
+  const { items, unevaluatedItems, contains } = schema;
+  if (items !== undefined && !Array.isArray(items)) {
+    return restItemType(items as Schema, request);
+  }
+  if (unevaluatedItems === undefined || items !== undefined) {
+    return UNKNOWN_TYPE;
+  }
+  const unevaluated = restItemType(unevaluatedItems, request);
+  const matched = contains === undefined ? null : restItemType(contains, request);
+  const types = [unevaluated, matched].filter((type): type is IrType => type !== null);
+  return types.length === 0 ? null : unionOf(types);
+}
+
+/**
+ * The `prefix-items` tuple of `prefixItems`: an array may end before the prefix does, so the
+ * elements from `minItems` on are optional (`T?`), and a rest element types the items after it.
+ */
+function prefixItemsTupleType(
+  prefixItems: readonly Schema[],
+  schema: SchemaObject,
+  request: SchemaRequest,
+): IrType {
+  const { min } = lengthBounds(schema);
+  const elements = prefixItems.map((item, index): IrTupleElement => {
+    const type = request.transformNested(item, request.location);
+    return index < min ? irTupleElement(type) : irOptionalTupleElement(type);
+  });
+  const rest = prefixRestType(schema, request);
+  return irTuple(rest === null ? elements : [...elements, irTupleElement(irArray(rest), true)]);
+}
+
+function isPrefixItemsFixed(schema: SchemaObject, request: SchemaRequest): boolean {
+  return (
+    schema.prefixItems !== undefined && request.context.options.fixes.has(OutputFix.PREFIX_ITEMS)
+  );
+}
+
+/** The type of one item; `unknown` without `items`. */
+function singleItemType(schema: SchemaObject, request: SchemaRequest): IrType {
+  const { items } = schema;
+  return items ? request.transformNested(items as SchemaObject, request.location) : UNKNOWN_TYPE;
+}
+
+/**
+ * The item type as the original returns it: a tuple stands for the whole array, and a nested
+ * `type: array` item is wrapped in an array here already.
+ */
+function itemType(schema: SchemaObject, request: SchemaRequest): IrType {
+  const tuple = prefixTupleType(schema, request);
+  if (tuple !== null) {
+    return tuple;
+  }
+  const { items } = schema;
+  // Checked first: the `in` test below throws for `items: null`.
+  if (!items) {
+    return UNKNOWN_TYPE;
+  }
+  const nested = singleItemType(schema, request);
+  const isNestedArray = typeof items === "object" && "type" in items && items.type === "array";
+  return isNestedArray ? irArray(nested) : nested;
+}
+
+function repeat(type: IrType, count: number): IrType[] {
+  return Array.from({ length: count }, () => type);
+}
+
+interface LengthBounds {
+  readonly min: number;
+  readonly max: number | undefined;
+}
+
+function lengthBounds(schema: SchemaObject): LengthBounds {
+  const { minItems, maxItems } = schema;
+  const min = typeof minItems === "number" && minItems >= 0 ? minItems : 0;
+  const isMaxValid = typeof maxItems === "number" && maxItems >= 0 && min <= maxItems;
+  return { min, max: isMaxValid ? maxItems : undefined };
+}
+
+/**
+ * Tuples for `--array-length`, as the original builds them. With both bounds it emits tuples of
+ * length 0 to `max - min` (not `min` to `max`); the `array-length-tuples` fix corrects it.
+ */
+function lengthTupleType(schema: SchemaObject, item: IrType, bounds: LengthBounds): IrType {
+  const { min, max } = bounds;
+  if (min === max) {
+    return unionOf([irTuple(repeat(item, min).map((type) => irTupleElement(type)))]);
+  }
+  if ((schema.maxItems as number) > 0) {
+    const lengths = Array.from({ length: Math.max(0, (max ?? 0) - min + 1) }, (_, index) => index);
+    return unionOf(
+      lengths.map((length) => irTuple(repeat(item, length).map((type) => irTupleElement(type)))),
+    );
+  }
+  const elements = repeat(item, min).map((type) => irTupleElement(type));
+  return irTuple([...elements, irTupleElement(irArray(item), true)]);
+}
+
+function isLengthTupleWanted(bounds: LengthBounds, request: SchemaRequest): boolean {
+  const { min, max } = bounds;
+  const estimatedSize = max === undefined ? min : (max * (max + 1) - min * (min - 1)) / 2;
+  const hasBounds = min !== 0 || max !== undefined;
+  return (
+    request.context.options.arrayLength && hasBounds && estimatedSize < MAX_LENGTH_TUPLE_ELEMENTS
+  );
+}
+
+/** Applies `--immutable` to one array or tuple type. */
+type ArrayWrapper = (type: IrType) => IrType;
+
+function tupleOf(item: IrType, length: number, isOpen: boolean): IrType {
+  const elements = repeat(item, length).map((type) => irTupleElement(type));
+  return irTuple(isOpen ? [...elements, irTupleElement(irArray(item), true)] : elements);
+}
+
+/** Tuples of every length from `min` to `max`; without `max`, `min` items and a rest element. */
+function fixedLengthTupleType(item: IrType, bounds: LengthBounds, wrap: ArrayWrapper): IrType {
+  const { min, max } = bounds;
+  if (max === undefined) {
+    return wrap(tupleOf(item, min, true));
+  }
+  const lengths = Array.from({ length: max - min + 1 }, (_, index) => min + index);
+  return unionOf(lengths.map((length) => wrap(tupleOf(item, length, false))));
+}
+
+/**
+ * `type: array` with `--array-length` and the `array-length-tuples` fix (#2048, #2330, #2546):
+ * the tuples have `min` to `max` items, the item type is used as it is (a nested array stays one
+ * level deep), a `prefixItems` tuple gets no length tuples around it, and `--immutable` makes
+ * every tuple `readonly`.
+ */
+function fixedArrayType(schema: SchemaObject, request: SchemaRequest): IrType {
+  const wrap: ArrayWrapper = (type) =>
+    request.context.options.immutable ? irReadonly(type) : type;
+  const tuple = prefixTupleType(schema, request);
+  if (tuple !== null) {
+    return wrap(tuple);
+  }
+  const item = singleItemType(schema, request);
+  const bounds = lengthBounds(schema);
+  return isLengthTupleWanted(bounds, request)
+    ? fixedLengthTupleType(item, bounds, wrap)
+    : wrap(irArray(item));
+}
+
+function isArrayLengthFixed(request: SchemaRequest): boolean {
+  const { arrayLength, fixes } = request.context.options;
+  return arrayLength && fixes.has(OutputFix.ARRAY_LENGTH_TUPLES);
+}
+
+/** `type: array`, including tuples (`prefixItems`, array `items`) and `--array-length`. */
+export function arrayType(schema: SchemaObject, request: SchemaRequest): IrType {
+  if (isArrayLengthFixed(request)) {
+    return fixedArrayType(schema, request);
+  }
+  const item = itemType(schema, request);
+  const bounds = lengthBounds(schema);
+  // A `prefix-items` tuple has its own lengths, so `--array-length` adds no tuples around it.
+  if (!isPrefixItemsFixed(schema, request) && isLengthTupleWanted(bounds, request)) {
+    return lengthTupleType(schema, item, bounds);
+  }
+  // A tuple or an array item is used as the array type itself.
+  const type = item.kind === "tuple" || item.kind === "array" ? item : irArray(item);
+  return request.context.options.immutable ? irReadonly(type) : type;
+}