openapi-typesafe 0.0.0 → 1.0.0-rc.1

package/src/application/transform/schema/presence-members.ts

@@ -0,0 +1,96 @@
+import type { Schema, SchemaObject } from "../../../domain/openapi/schema-object.js";
+import { OutputFix } from "../../../domain/output-fixes.js";
+import type { SchemaRequest } from "./schema-rule.js";
+
+/**
+ * The `allof-required` fix (ADR-021, roadmap R6). An `allOf` member such as `{ required: [name] }`
+ * or `{ type: object }` says nothing about the shape of the object; it only asks that keys are
+ * present. Typed as an object of its own, it adds `& Record<string, never>` or `& unknown`. With
+ * the fix, such members are left out and their keys are made required in the other members, the
+ * same way the parent's `required` is (upstream #1474, #1520, #2165).
+ */
+
+/**
+ * Keywords that do not change the shape: `type: object`, `required`, and annotations that the
+ * generator does not read on an `allOf` member. `default`, `readOnly` and `writeOnly` are left out:
+ * they change types elsewhere.
+ */
+const PRESENCE_KEYWORDS: ReadonlySet<string> = new Set([
+  "$comment",
+  "deprecated",
+  "description",
+  "example",
+  "examples",
+  "required",
+  "title",
+  "type",
+]);
+
+const EXTENSION_PREFIX = "x-";
+const OBJECT_TYPE = "object";
+
+function isStringList(value: unknown): value is readonly string[] {
+  return Array.isArray(value) && value.every((entry) => typeof entry === "string");
+}
+
+function isPresenceKeyword([key, value]: readonly [string, unknown]): boolean {
+  if (key === "type") {
+    return value === OBJECT_TYPE;
+  }
+  if (key === "required") {
+    return isStringList(value);
+  }
+  return PRESENCE_KEYWORDS.has(key) || key.startsWith(EXTENSION_PREFIX);
+}
+
+function isPresenceObject(schema: unknown): schema is SchemaObject {
+  return (
+    typeof schema === "object" &&
+    schema !== null &&
+    !Array.isArray(schema) &&
+    !("$ref" in schema) &&
+    Object.entries(schema).every(isPresenceKeyword)
+  );
+}
+
+/**
+ * The schema a member stands for: itself, or the target of a `$ref` with no sibling keywords. The
+ * discriminator scan has already added the discriminator property to a mapped target, so such a
+ * target is never presence-only.
+ */
+function memberSchema(member: Schema, request: SchemaRequest): unknown {
+  if (typeof member !== "object" || member === null || !("$ref" in member)) {
+    return member;
+  }
+  const ref = (member as { readonly $ref: unknown }).$ref;
+  if (typeof ref !== "string" || Object.keys(member).length !== 1) {
+    return undefined;
+  }
+  return request.context.refs.resolve(ref);
+}
+
+/** The `allOf` members to type, and the keys the left-out members make required. */
+export interface AllOfMembers {
+  readonly members: readonly Schema[];
+  readonly required: readonly string[];
+}
+
+/**
+ * The members of `allOf` with presence-only ones left out, when the fix is on and another member
+ * is left to carry the keys; otherwise the members as they are.
+ */
+export function allOfMembers(members: readonly Schema[], request: SchemaRequest): AllOfMembers {
+  const unchanged = { members, required: [] };
+  if (!request.context.options.fixes.has(OutputFix.ALLOF_REQUIRED)) {
+    return unchanged;
+  }
+  const schemas = members.map((member) => memberSchema(member, request));
+  const kept = members.filter((_, index) => !isPresenceObject(schemas[index]));
+  if (kept.length === 0 || kept.length === members.length) {
+    return unchanged;
+  }
+  const required = schemas.flatMap((schema) =>
+    isPresenceObject(schema) ? (schema.required ?? []) : [],
+  );
+  return { members: kept, required };
+}

package/src/application/transform/schema/required-variants.ts

@@ -0,0 +1,88 @@
+import type { IrType } from "../../../domain/ir/nodes.js";
+import type { Schema, SchemaObject } from "../../../domain/openapi/schema-object.js";
+import { OutputFix } from "../../../domain/output-fixes.js";
+import { unionOf, withRequiredKeys } from "../type-combinators.js";
+import { isKeptProperty } from "./object-type.js";
+import type { SchemaRequest } from "./schema-rule.js";
+
+/**
+ * The `anyof-oneof-required` fix. `anyOf: [{ required: [a] }, { required: [b] }]` next to
+ * `properties` says which of the properties must be there. Each such variant has no type of its
+ * own (`unknown`), so the original gives `Props | unknown`, which is `unknown`. With the fix each
+ * variant is the parent with its keys required:
+ * `WithRequired<Props, "a"> | WithRequired<Props, "b">`.
+ */
+
+/** Keywords that do not change a value's type: a variant of these and `required` counts. */
+const ANNOTATION_KEYS: ReadonlySet<string> = new Set(["required", "description", "title"]);
+
+/** The `required` keys of a variant that has nothing else, or null for any other variant. */
+function requiredOnlyKeys(variant: Schema): readonly string[] | null {
+  if (typeof variant !== "object" || variant === null || "$ref" in variant) {
+    return null;
+  }
+  const { required } = variant as SchemaObject;
+  const isRequiredOnly = Object.keys(variant).every((key) => ANNOTATION_KEYS.has(key));
+  return isRequiredOnly && Array.isArray(required) && required.length > 0 ? required : null;
+}
+
+/** Whether the schema's type is an object: no `type`, `object`, or a list with `object`. */
+function isObjectTyped(schema: SchemaObject): boolean {
+  const { type } = schema;
+  return (
+    type === undefined || type === "object" || (Array.isArray(type) && type.includes("object"))
+  );
+}
+
+/** The variants' key lists, or null unless each requires only properties the type keeps. */
+function requiredKeyLists(
+  schema: SchemaObject,
+  variants: readonly Schema[],
+  request: SchemaRequest,
+): (readonly string[])[] | null {
+  const keyLists = variants.map(requiredOnlyKeys);
+  // A key of a property the type leaves out (`--exclude-deprecated`) is no key of `WithRequired`.
+  const isApplicable =
+    keyLists.length > 0 &&
+    keyLists.every((keys) => keys?.every((key) => isKeptProperty(schema, key, request)) === true);
+  return isApplicable ? (keyLists as (readonly string[])[]) : null;
+}
+
+/** Whether the fix gives `variants` of the schema their keys of its properties. */
+export function hasRequiredVariants(
+  schema: SchemaObject,
+  variants: readonly Schema[],
+  request: SchemaRequest,
+): boolean {
+  return (
+    request.context.options.fixes.has(OutputFix.ANYOF_ONEOF_REQUIRED) &&
+    isObjectTyped(schema) &&
+    requiredKeyLists(schema, variants, request) !== null
+  );
+}
+
+/**
+ * The union of the parent type with each variant's keys required, or null where the fix is off
+ * or the variants are not all required-only ones over the parent's own, kept properties. Only an
+ * object has the keys. For a `type` list, the `object` member has required them already
+ * (`multipleTypes`), so the list is the whole type.
+ */
+export function requiredVariantsType(
+  previous: IrType | null,
+  schema: SchemaObject,
+  variants: readonly Schema[],
+  request: SchemaRequest,
+): IrType | null {
+  if (!request.context.options.fixes.has(OutputFix.ANYOF_ONEOF_REQUIRED) || previous === null) {
+    return null;
+  }
+  const keyLists = isObjectTyped(schema) ? requiredKeyLists(schema, variants, request) : null;
+  if (keyLists === null) {
+    return null;
+  }
+  if (Array.isArray(schema.type)) {
+    return previous;
+  }
+  request.context.footer.requireWithRequired();
+  return unionOf(keyLists.map((keys) => withRequiredKeys(previous, keys)));
+}

package/src/application/transform/schema/schema-context.ts

@@ -0,0 +1,136 @@
+import type { IrPropertySignature, IrType } from "../../../domain/ir/nodes.js";
+import type { SchemaObject } from "../../../domain/openapi/schema-object.js";
+import type { OutputFix } from "../../../domain/output-fixes.js";
+
+/**
+ * Everything the schema transformer needs from outside, as explicit dependencies (ENGINEERING_PLAN
+ * §4.4): options, `$ref` resolution, discriminators, declarations added to the file footer, and the
+ * user callbacks. The transformer is pure given these; there is no module-level state.
+ */
+
+/** Generator options that change schema output. */
+export interface SchemaOptions {
+  readonly additionalProperties: boolean;
+  readonly alphabetize: boolean;
+  readonly arrayLength: boolean;
+  /** `--binary-as-blob`: raw binary strings become `Blob`. */
+  readonly binaryAsBlob: boolean;
+  readonly conditionalEnums: boolean;
+  readonly dedupeEnums: boolean;
+  readonly defaultNonNullable: boolean;
+  readonly emptyObjectsUnknown: boolean;
+  readonly enum: boolean;
+  readonly enumValues: boolean;
+  readonly excludeDeprecated: boolean;
+  /** `--fix`: the opt-in output fixes of this run (ADR-021). */
+  readonly fixes: ReadonlySet<OutputFix>;
+  readonly immutable: boolean;
+  readonly propertiesRequiredByDefault: boolean;
+  readonly readWriteMarkers: boolean;
+}
+
+/**
+ * Where the transformer is in the document. `schema` is whatever the caller passed along; it is
+ * only handed to user callbacks, as the original does.
+ */
+export interface SchemaLocation {
+  readonly path?: string | undefined;
+  readonly schema?: unknown;
+}
+
+/** A discriminator object, as far as the transformer reads it. */
+export interface Discriminator {
+  readonly propertyName: string;
+  readonly mapping?: Readonly<Record<string, string>> | undefined;
+}
+
+/** The enum of a discriminator owner's property, and the location it is typed at. */
+export interface DiscriminatorEnumParent {
+  readonly schema: SchemaObject;
+  readonly path: string;
+}
+
+export interface Discriminators {
+  /** The discriminator that applies to the schema at this `$ref`, if any. */
+  objectAt(ref: string): Discriminator | undefined;
+  /** Whether the discriminator property of this `$ref` was already added. */
+  isHandled(ref: string): boolean;
+  /**
+   * With `discriminator-values`: the properties of the discriminators the schema at `ref`
+   * inherits besides `objectAt`'s. It redefines them too, so its `allOf` items omit them.
+   */
+  otherPropertiesAt(ref: string): readonly string[];
+  /**
+   * With `discriminator-values`: the owner's enum that a member's value narrows, found by
+   * the enum schema the discriminator scan added or by the discriminator object of `objectAt`.
+   */
+  enumParentOf(schema: object): DiscriminatorEnumParent | undefined;
+}
+
+export interface RefResolver {
+  resolve(ref: string): unknown;
+}
+
+/** `x-enum-varnames` / `x-enum-descriptions` entry of one enum value. */
+export interface EnumMemberMetadata {
+  readonly name: string | undefined;
+  readonly description: string | undefined;
+}
+
+export interface EnumDeclarationRequest {
+  readonly name: string;
+  /** Whether the schema is a component schema itself (`#/components/schemas/Name`). */
+  readonly isComponentSchema: boolean;
+  readonly values: readonly (string | number)[];
+  readonly metadata: readonly EnumMemberMetadata[];
+  /**
+   * The request only refers to the enum, for a discriminator member's value
+   * (`discriminator-values`); the schema at `name` declares it where it is typed itself.
+   */
+  readonly isOwnerReference?: boolean;
+}
+
+export interface EnumValuesRequest {
+  readonly name: string;
+  readonly type: IrType;
+  readonly values: readonly (string | number)[];
+}
+
+/** Declarations the transformer adds once per file, after the main interfaces. */
+export interface FooterDeclarations {
+  /** Add (or reuse) an enum declaration and return the name it was declared with. */
+  addEnum(request: EnumDeclarationRequest): string;
+  /** The member names of the enum declared with this name, by value; empty for another name. */
+  enumMembers(name: string): ReadonlyMap<string | number, string>;
+  /** Add an exported, readonly array of enum values (`--enum-values`). */
+  addEnumValues(request: EnumValuesRequest): void;
+  /** Make sure the `WithRequired` helper type is declared. */
+  requireWithRequired(): void;
+  /** Make sure the `PropertyValues` helper type is declared (`unevaluated-properties`). */
+  requirePropertyValues(): void;
+}
+
+/** A type returned by the `transform` callback; `isOptional` is its `questionToken`. */
+export interface CustomType {
+  readonly type: IrType;
+  readonly isOptional: boolean;
+}
+
+/** User callbacks. A callback that is not set returns null. */
+export interface SchemaCallbacks {
+  transform(schema: unknown, location: SchemaLocation): CustomType | null;
+  postTransform(type: IrType, location: SchemaLocation): IrType | null;
+  transformProperty(
+    property: IrPropertySignature,
+    schema: unknown,
+    location: SchemaLocation,
+  ): IrPropertySignature | null;
+}
+
+export interface SchemaContext {
+  readonly options: SchemaOptions;
+  readonly refs: RefResolver;
+  readonly discriminators: Discriminators;
+  readonly footer: FooterDeclarations;
+  readonly callbacks: SchemaCallbacks;
+}

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

@@ -0,0 +1,29 @@
+import type { IrType } from "../../../domain/ir/nodes.js";
+import type { Schema, SchemaObject } from "../../../domain/openapi/schema-object.js";
+import type { SchemaContext, SchemaLocation } from "./schema-context.js";
+
+/** Transform a nested schema, with `postTransform` applied (the recursion entry point). */
+export type TransformNested = (
+  schema: Schema,
+  location: SchemaLocation,
+  isFromAdditionalProperties?: boolean,
+) => IrType;
+
+/** One call of the schema transformer. */
+export interface SchemaRequest {
+  readonly location: SchemaLocation;
+  readonly context: SchemaContext;
+  /** Set for `additionalProperties` schemas: `--enum-values` arrays then index by `string`. */
+  readonly isFromAdditionalProperties: boolean;
+  readonly transformNested: TransformNested;
+}
+
+/**
+ * One schema shape (ENGINEERING_PLAN §4.4). Rules are tried in a fixed order and the first match
+ * transforms the schema; the order is the original precedence. Internal, not a plugin point.
+ */
+export interface SchemaRule {
+  readonly name: string;
+  matches(schema: SchemaObject): boolean;
+  transform(schema: SchemaObject, request: SchemaRequest): IrType;
+}

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

@@ -0,0 +1,99 @@
+import { ERROR_CODES, OpenAPITypesafeError } from "../../../domain/errors.js";
+import { irKeyword } from "../../../domain/ir/constructors.js";
+import type { IrType } from "../../../domain/ir/nodes.js";
+import type { Schema, SchemaObject } from "../../../domain/openapi/schema-object.js";
+import { literalType } from "../literal-type.js";
+import { schemaRefType } from "../ref-pointer/pointer-type.js";
+import { UNKNOWN_TYPE } from "../shared-types.js";
+import { compositionType } from "./composition-type.js";
+import { enumRule } from "./enum-rule.js";
+import type { SchemaContext, SchemaLocation } from "./schema-context.js";
+import type { SchemaRequest, SchemaRule } from "./schema-rule.js";
+
+export class InvalidSchemaError extends OpenAPITypesafeError {
+  constructor(schema: unknown, path: string | undefined) {
+    const received = Array.isArray(schema) ? "Array" : typeof schema;
+    super({
+      code: ERROR_CODES.SCHEMA_OBJECT_INVALID,
+      message: `Expected SchemaObject, received ${received} at ${path}`,
+      details: { path, received },
+    });
+    this.name = "InvalidSchemaError";
+  }
+}
+
+/** Shape rules in the original precedence; composition handles everything they do not match. */
+const SHAPE_RULES: readonly SchemaRule[] = [
+  {
+    name: "$ref",
+    matches: (schema) => "$ref" in schema,
+    transform: (schema, request) => schemaRefType((schema as { $ref: string }).$ref, request),
+  },
+  {
+    name: "const",
+    matches: (schema) => schema.const !== null && schema.const !== undefined,
+    transform: (schema) => literalType(schema.const),
+  },
+  enumRule,
+];
+
+/** A schema checked for its input shape, or the type of a non-object schema. */
+type CheckedSchema = { readonly type: IrType } | { readonly schema: SchemaObject };
+
+/** A missing schema is `never`; `true` allows anything; other non-objects are invalid. */
+function checkSchema(schema: unknown, path: string | undefined): CheckedSchema {
+  if (!schema) {
+    return { type: irKeyword("never") };
+  }
+  if (schema === true) {
+    return { type: UNKNOWN_TYPE };
+  }
+  if (Array.isArray(schema) || typeof schema !== "object") {
+    throw new InvalidSchemaError(schema, path);
+  }
+  return { schema: schema as SchemaObject };
+}
+
+function request(
+  location: SchemaLocation,
+  context: SchemaContext,
+  isFromAdditionalProperties: boolean,
+): SchemaRequest {
+  return {
+    location,
+    context,
+    isFromAdditionalProperties,
+    transformNested: (schema, nestedLocation, isNestedFromAdditionalProperties = false) =>
+      transformSchema(schema, nestedLocation, context, isNestedFromAdditionalProperties),
+  };
+}
+
+/**
+ * Transform a schema without the `postTransform` callback (the original
+ * `transformSchemaObjectWithComposition`). Nested schemas still get `postTransform`.
+ */
+export function transformSchemaShape(
+  schema: Schema | null | undefined,
+  location: SchemaLocation,
+  context: SchemaContext,
+  isFromAdditionalProperties = false,
+): IrType {
+  const checked = checkSchema(schema, location.path);
+  if ("type" in checked) {
+    return checked.type;
+  }
+  const current = request(location, context, isFromAdditionalProperties);
+  const rule = SHAPE_RULES.find((candidate) => candidate.matches(checked.schema));
+  return rule ? rule.transform(checked.schema, current) : compositionType(checked.schema, current);
+}
+
+/** Transform a schema to IR, then apply `postTransform` (the original `transformSchemaObject`). */
+export function transformSchema(
+  schema: Schema | null | undefined,
+  location: SchemaLocation,
+  context: SchemaContext,
+  isFromAdditionalProperties = false,
+): IrType {
+  const type = transformSchemaShape(schema, location, context, isFromAdditionalProperties);
+  return context.callbacks.postTransform(type, location) ?? type;
+}

package/src/application/transform/schema/unevaluated-properties.ts

@@ -0,0 +1,105 @@
+import {
+  irKeyword,
+  irObject,
+  irReference,
+  irStringIndexSignature,
+} from "../../../domain/ir/constructors.js";
+import type { IrMember, IrType } from "../../../domain/ir/nodes.js";
+import type { Schema, SchemaObject } from "../../../domain/openapi/schema-object.js";
+import { OutputFix } from "../../../domain/output-fixes.js";
+import { HELPER_TYPES } from "../helper-types.js";
+import { UNKNOWN_TYPE } from "../shared-types.js";
+import { unionOf } from "../type-combinators.js";
+import type { SchemaRequest } from "./schema-rule.js";
+
+/**
+ * The `unevaluated-properties` fix (ADR-021, roadmap R11; upstream #2839, #2880). Without it
+ * `unevaluatedProperties` is ignored, so its value type is lost and an object with only that
+ * keyword is `Record<string, never>`. With it the composed type is intersected with an index
+ * signature, as `additionalProperties` gives: every key that no other keyword declares has the
+ * `unevaluatedProperties` type. TypeScript checks that index signature against every key of a
+ * value, declared ones included, so its type also holds the types of the declared properties
+ * (of this schema and of its `allOf`, `anyOf` and `oneOf` members); otherwise a valid value would
+ * not be assignable. `false` adds nothing, like `additionalProperties: false`: TypeScript has no
+ * closed object type.
+ */
+
+/**
+ * Whether `unevaluatedProperties` applies. It types the keys left over at this level, so it
+ * does nothing next to `additionalProperties` (which already types them all), and only an object
+ * schema has keys. A `type` list is typed one listed type at a time, so its object gets it.
+ */
+function unevaluatedSchemaOf(schema: SchemaObject, request: SchemaRequest): Schema | null {
+  const { unevaluatedProperties } = schema;
+  if (
+    !request.context.options.fixes.has(OutputFix.UNEVALUATED_PROPERTIES) ||
+    unevaluatedProperties === undefined ||
+    unevaluatedProperties === false ||
+    schema.additionalProperties !== undefined
+  ) {
+    return null;
+  }
+  return schema.type === undefined || schema.type === "object" ? unevaluatedProperties : null;
+}
+
+function isAnySchema(schema: Schema): boolean {
+  return schema === true || (typeof schema === "object" && Object.keys(schema).length === 0);
+}
+
+function memberValueTypes(member: IrMember): IrType[] {
+  if (member.kind === "indexSignature") {
+    return [member.type];
+  }
+  return member.isOptional ? [member.type, irKeyword("undefined")] : [member.type];
+}
+
+/**
+ * The value types a key of the composed type can have, read from its IR: the members of object
+ * types, through unions and intersections. A reference (a `$ref`, `Omit`, `WithRequired`) or a raw
+ * type is read with `PropertyValues`. Primitives, literals and arrays declare no keys.
+ */
+function declaredValueTypes(type: IrType, request: SchemaRequest): IrType[] {
+  switch (type.kind) {
+    case "object":
+      return type.members.flatMap(memberValueTypes);
+    case "union":
+    case "intersection":
+      return type.types.flatMap((member) => declaredValueTypes(member, request));
+    case "reference":
+    case "indexedAccess":
+    case "raw":
+      request.context.footer.requirePropertyValues();
+      return [irReference(HELPER_TYPES.propertyValues.name, [type])];
+    case "keyword":
+    case "stringLiteral":
+    case "numberLiteral":
+    case "booleanLiteral":
+    case "array":
+    case "tuple":
+    case "readonly":
+      return [];
+  }
+}
+
+/**
+ * The index signature object for `unevaluatedProperties`, given the composed type of the other
+ * keywords (null when there is none). Null when the fix is off or the keyword does not apply.
+ */
+export function unevaluatedPropertiesType(
+  schema: SchemaObject,
+  composed: IrType | null,
+  request: SchemaRequest,
+): IrType | null {
+  const unevaluated = unevaluatedSchemaOf(schema, request);
+  if (unevaluated === null) {
+    return null;
+  }
+  const valueTypes = isAnySchema(unevaluated)
+    ? [UNKNOWN_TYPE]
+    : [
+        request.transformNested(unevaluated, request.location, true),
+        ...(composed === null ? [] : declaredValueTypes(composed, request)),
+      ];
+  const { immutable } = request.context.options;
+  return irObject([irStringIndexSignature("key", unionOf(valueTypes), immutable)]);
+}