openapi-typesafe 0.0.0 → 1.0.0-rc.0

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

@@ -0,0 +1,271 @@
+import { ERROR_CODES, OpenAPITypesafeError } from "../../../domain/errors.js";
+import {
+  irObject,
+  irProperty,
+  irReference,
+  irStringIndexSignature,
+} from "../../../domain/ir/constructors.js";
+import type { IrMember, 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 { Schema, SchemaObject } from "../../../domain/openapi/schema-object.js";
+import { documentEntries } from "../document-entries.js";
+import { refType } from "../ref-type.js";
+import { withSchemaComment } from "../schema-comment.js";
+import { UNKNOWN_TYPE } from "../shared-types.js";
+import { intersectionOf, unionOf } from "../type-combinators.js";
+import { discriminatorProperty } from "./discriminator-property.js";
+import type { SchemaOptions } from "./schema-context.js";
+import type { SchemaRequest } from "./schema-rule.js";
+
+/** Path parts where a default value cannot make a property required (inputs may omit it). */
+const INPUT_PATH_PARTS = ["parameters", "requestBody", "requestBodies"] as const;
+
+export class InvalidPropertyError extends OpenAPITypesafeError {
+  constructor(path: string | undefined, key: string, value: unknown) {
+    const received = Array.isArray(value) ? "Array" : typeof value;
+    super({
+      code: ERROR_CODES.SCHEMA_PROPERTY_INVALID,
+      message:
+        `${path}: invalid property ${key}. ` + `Expected Schema Object or boolean, got ${received}`,
+      details: { path, property: key, received },
+    });
+    this.name = "InvalidPropertyError";
+  }
+}
+
+/** `--read-write-markers`: `$Read<T>` / `$Write<T>`, unless the property is both or neither. */
+function withReadWriteMarker(type: IrType, flags: AccessFlags, options: SchemaOptions): IrType {
+  if (!options.readWriteMarkers || flags.isReadOnly === flags.isWriteOnly) {
+    return type;
+  }
+  return irReference(flags.isReadOnly ? "$Read" : "$Write", [type]);
+}
+
+interface AccessFlags {
+  readonly isReadOnly: boolean;
+  readonly isWriteOnly: boolean;
+}
+
+/** Apply `transformProperty`, then the schema's JSDoc. */
+function finishProperty(
+  property: IrPropertySignature,
+  schema: Schema,
+  path: string,
+  request: SchemaRequest,
+): IrPropertySignature {
+  const location = { ...request.location, path };
+  const transformed =
+    request.context.callbacks.transformProperty(property, schema, location) ?? property;
+  // The original adds the schema's comment after any comment the callback set.
+  return withSchemaComment(transformed, schema);
+}
+
+/** What the property loop reads from a property schema, in the original order. */
+interface PropertyFacts {
+  readonly ref: string | undefined;
+  readonly flags: AccessFlags;
+  readonly hasDefault: boolean;
+}
+
+function propertyFacts(value: Schema): PropertyFacts {
+  if (typeof value !== "object") {
+    return { ref: undefined, flags: { isReadOnly: false, isWriteOnly: false }, hasDefault: false };
+  }
+  // `in` throws for a null value, as in the original (which also reads `$ref` first).
+  const ref = "$ref" in value && value.$ref ? value.$ref : undefined;
+  const flags = {
+    isReadOnly: Boolean("readOnly" in value && value.readOnly),
+    isWriteOnly: Boolean("writeOnly" in value && value.writeOnly),
+  };
+  return { ref, flags, hasDefault: "default" in value && value.default !== undefined };
+}
+
+function isOptionalProperty(
+  key: string,
+  facts: PropertyFacts,
+  schema: SchemaObject,
+  request: SchemaRequest,
+): boolean {
+  const { options } = request.context;
+  const path = request.location.path;
+  const isDefaultRequired =
+    facts.hasDefault &&
+    options.defaultNonNullable &&
+    !INPUT_PATH_PARTS.some((part) => path?.includes(part));
+  const isRequired =
+    schema.required?.includes(key) ||
+    (schema.required === undefined && options.propertiesRequiredByDefault) ||
+    isDefaultRequired;
+  return !isRequired;
+}
+
+function isExcluded(value: Schema, facts: PropertyFacts, request: SchemaRequest): boolean {
+  if (!request.context.options.excludeDeprecated) {
+    return false;
+  }
+  const resolved = facts.ref ? request.context.refs.resolve(facts.ref) : value;
+  return Boolean((resolved as SchemaObject | undefined)?.deprecated);
+}
+
+/** A type, and whether a callback forced the property optional (null: no override). */
+interface CustomResult {
+  readonly type: IrType;
+  readonly isOptional: true | null;
+}
+
+function propertyType(
+  key: string,
+  value: Schema,
+  facts: PropertyFacts,
+  request: SchemaRequest,
+): CustomResult {
+  const path = createRef([request.location.path, key]);
+  const type = facts.ref
+    ? refType(facts.ref)
+    : request.transformNested(value, { ...request.location, path });
+  const custom = request.context.callbacks.transform(value, request.location);
+  return custom === null
+    ? { type, isOptional: null }
+    : { type: custom.type, isOptional: custom.isOptional || null };
+}
+
+function propertyMember(
+  key: string,
+  value: Schema,
+  schema: SchemaObject,
+  request: SchemaRequest,
+): IrMember | null {
+  if ((typeof value !== "object" && typeof value !== "boolean") || Array.isArray(value)) {
+    throw new InvalidPropertyError(request.location.path, key, value);
+  }
+  const facts = propertyFacts(value);
+  if (isExcluded(value, facts, request)) {
+    return null;
+  }
+  const { options } = request.context;
+  const isOptional = isOptionalProperty(key, facts, schema, request);
+  const result = propertyType(key, value, facts, request);
+  const property = irProperty(
+    toPropertyName(key),
+    withReadWriteMarker(result.type, facts.flags, options),
+    {
+      isOptional: result.isOptional ?? isOptional,
+      isReadonly: options.immutable || (!options.readWriteMarkers && facts.flags.isReadOnly),
+    },
+  );
+  return finishProperty(property, value, createRef([request.location.path, key]), request);
+}
+
+function propertyMembers(schema: SchemaObject, request: SchemaRequest): IrMember[] {
+  const members: IrMember[] = [];
+  for (const [key, value] of documentEntries(schema.properties ?? {}, request.context.options)) {
+    const member = propertyMember(key, value, schema, request);
+    if (member !== null) {
+      members.push(member);
+    }
+  }
+  return members;
+}
+
+/**
+ * `$defs` as a nested `$defs?: { … }` member, in document order (never alphabetized). It is
+ * optional because `$defs` is a schema keyword, not data: the original made it required, so a
+ * value of the type needed a `$defs` key (research/legacy-bugs.md, item 17, upstream #2664).
+ */
+function defsMember(
+  defs: Readonly<Record<string, SchemaObject>>,
+  request: SchemaRequest,
+): IrMember {
+  const { options } = request.context;
+  const members = Object.entries(defs).map(([key, value]) => {
+    const path = createRef([request.location.path, "$defs", key]);
+    const flags = {
+      isReadOnly: "readOnly" in value && !!value.readOnly,
+      isWriteOnly: "writeOnly" in value && !!value.writeOnly,
+    };
+    const type = withReadWriteMarker(
+      request.transformNested(value, { ...request.location, path }),
+      flags,
+      options,
+    );
+    const property = irProperty(toPropertyName(key), type, {
+      isReadonly: options.immutable || (!options.readWriteMarkers && flags.isReadOnly),
+    });
+    return finishProperty(property, value, path, request);
+  });
+  return irProperty(toPropertyName("$defs"), irObject(members), { isOptional: true });
+}
+
+function hasObjectKeywords(schema: SchemaObject): boolean {
+  const hasProperties = Boolean(schema.properties && Object.keys(schema.properties).length);
+  return (
+    hasProperties ||
+    Boolean(schema.additionalProperties || schema.patternProperties || schema.$defs)
+  );
+}
+
+/** Value types of the `[key: string]` index signature, in the original order. */
+function indexValueTypes(schema: SchemaObject, request: SchemaRequest): IrType[] {
+  const { additionalProperties } = schema;
+  const isObject = typeof additionalProperties === "object";
+  const hasExplicit = isObject && Object.keys(additionalProperties).length > 0;
+  const hasImplicit =
+    additionalProperties === true || (isObject && Object.keys(additionalProperties).length === 0);
+  const types: IrType[] = [];
+  if (hasExplicit) {
+    types.push(request.transformNested(additionalProperties as Schema, request.location, true));
+  }
+  if (hasImplicit || (!additionalProperties && request.context.options.additionalProperties)) {
+    types.push(UNKNOWN_TYPE);
+  }
+  const patterns = schema.patternProperties;
+  if (typeof patterns === "object" && patterns !== null && Object.keys(patterns).length > 0) {
+    for (const [, value] of documentEntries(patterns, request.context.options)) {
+      types.push(request.transformNested(value, request.location));
+    }
+  }
+  return types;
+}
+
+/** The discriminator property that a parent's mapping implies for this schema, if any. */
+function discriminatorMembers(schema: SchemaObject, request: SchemaRequest): IrMember[] {
+  if (!schema.allOf && !schema.anyOf) {
+    return [];
+  }
+  const path = request.location.path ?? "";
+  const { discriminators, options } = request.context;
+  // A schema does not get the discriminator it defines for its children, nor one added already.
+  const discriminator =
+    !schema.discriminator && !discriminators.isHandled(path) && discriminators.objectAt(path);
+  return discriminator ? [discriminatorProperty(discriminator, path, options.immutable)] : [];
+}
+
+/**
+ * Object keywords: discriminator, `properties`, `$defs`, and an index signature for
+ * `additionalProperties` / `patternProperties` (or `--additional-properties`). Null when the schema
+ * has none of them.
+ */
+export function objectType(schema: SchemaObject, request: SchemaRequest): IrType | null {
+  const members = discriminatorMembers(schema, request);
+  if (!hasObjectKeywords(schema)) {
+    return members.length > 0 ? irObject(members) : null;
+  }
+  members.push(...propertyMembers(schema, request));
+  // As in the original, a null `$defs` throws here (Object.keys) instead of being skipped.
+  if (
+    "$defs" in schema &&
+    typeof schema.$defs === "object" &&
+    Object.keys(schema.$defs).length > 0
+  ) {
+    members.push(defsMember(schema.$defs, request));
+  }
+  const valueTypes = indexValueTypes(schema, request);
+  if (valueTypes.length === 0) {
+    return members.length > 0 ? irObject(members) : null;
+  }
+  const index = irObject([
+    irStringIndexSignature("key", unionOf(valueTypes), request.context.options.immutable),
+  ]);
+  return intersectionOf([...(members.length > 0 ? [irObject(members)] : []), index]);
+}

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/schema-context.ts

@@ -0,0 +1,110 @@
+import type { IrPropertySignature, IrType } from "../../../domain/ir/nodes.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;
+}
+
+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;
+}
+
+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;
+  readonly values: readonly (string | number)[];
+  readonly metadata: readonly EnumMemberMetadata[];
+}
+
+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;
+  /** 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 { refType } from "../ref-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) => refType((schema as { $ref: string }).$ref),
+  },
+  {
+    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;
+}