openapi-typesafe 0.0.0 → 1.0.0-rc.0

package/src/api/legacy-ts-helpers.ts

@@ -0,0 +1,311 @@
+import { toTypeNode, toValueExpression } from "../adapters/type-ast-bridge/ir-to-typescript.js";
+import { lazyNode } from "../adapters/type-ast-bridge/lazy-node.js";
+import { loadTypeScript } from "../adapters/type-ast-bridge/load-typescript.js";
+import type { ts } from "../adapters/type-ast-bridge/typescript-types.js";
+import {
+  enumMemberDescription,
+  quotedMemberName,
+} from "../application/transform/footer/enum-naming.js";
+import { HELPER_TYPES } from "../application/transform/helper-types.js";
+import { schemaComment } from "../application/transform/schema-comment.js";
+import type { IrType } from "../domain/ir/nodes.js";
+import { declaresTypeAlias, type FooterEntry } from "./footer-entry.js";
+import type { TypeInput } from "./type-helpers.js";
+
+/**
+ * The original's helpers that build TypeScript compiler nodes, kept for 1.x and deprecated
+ * (ADR-004, decision 9). They load TypeScript on first use through the bridge; the generator
+ * itself does not use them.
+ */
+
+export const JS_PROPERTY_INDEX_RE = /^[A-Za-z_$][A-Za-z_$0-9]*$/;
+export const JS_ENUM_INVALID_CHARS_RE = /[^A-Za-z_$0-9]+(.)?/g;
+export const JS_PROPERTY_INDEX_INVALID_CHARS_RE = /[^A-Za-z_$0-9]+/g;
+export const SPECIAL_CHARACTER_MAP: Record<string, string> = {
+  "+": "Plus",
+  // Add more mappings as needed
+};
+
+/**
+ * The `?` token. Created on first use, so importing the package needs no TypeScript.
+ * @deprecated Kept for 1.x; removed in 2.0 (ADR-004, decision 9).
+ */
+export const QUESTION_TOKEN: ts.QuestionToken = lazyNode(() => {
+  const ts = loadTypeScript();
+  return ts.factory.createToken(ts.SyntaxKind.QuestionToken);
+});
+
+export interface AnnotatedSchemaObject {
+  const?: unknown; // jsdoc without value
+  default?: unknown; // jsdoc with value
+  deprecated?: boolean; // jsdoc without value
+  description?: string; // jsdoc with value
+  enum?: unknown[]; // jsdoc without value
+  example?: string; // jsdoc with value
+  examples?: unknown;
+  format?: string; // not jsdoc
+  nullable?: boolean; // Node information
+  summary?: string; // not jsdoc
+  title?: string; // not jsdoc
+  type?: string | string[]; // Type of node
+}
+
+/**
+ * Add the schema's JSDoc comment to a TypeScript property signature.
+ * @deprecated Kept for 1.x; removed in 2.0 (ADR-004, decision 9).
+ */
+export function addJSDocComment(
+  schemaObject: AnnotatedSchemaObject,
+  node: ts.PropertySignature,
+): void {
+  const ts = loadTypeScript();
+  const comment = schemaComment(schemaObject);
+  if (comment) {
+    ts.addSyntheticLeadingComment(node, ts.SyntaxKind.MultiLineCommentTrivia, comment.text, true);
+  }
+}
+
+/** A type argument of the deprecated helpers as TypeScript; IR from type helpers is converted. */
+function legacyTypeNode(type: TypeInput): ts.TypeNode {
+  const ts = loadTypeScript();
+  return typeof type.kind === "string" ? toTypeNode(ts, type as IrType) : (type as ts.TypeNode);
+}
+
+/** Add a helper type alias to the footer once, as a named raw declaration (like the generator). */
+function requireHelper(injectFooter: FooterEntry[], helper: { name: string; text: string }): void {
+  if (!injectFooter.some((entry) => declaresTypeAlias(entry, helper.name))) {
+    injectFooter.push({ kind: "rawDeclaration", name: helper.name, text: helper.text });
+  }
+}
+
+/**
+ * Deduplicate simple primitive types from an array of nodes
+ * Note: won’t deduplicate complex types like objects
+ * @deprecated Kept for 1.x; removed in 2.0 (ADR-004, decision 9).
+ */
+export function tsDedupe(types: TypeInput[]): ts.TypeNode[] {
+  const encounteredTypes = new Set<number>();
+  const filteredTypes: ts.TypeNode[] = [];
+  for (const t of types.map(legacyTypeNode)) {
+    // only mark for deduplication if this is not a const ("text" means it is a const)
+    if (!("text" in ((t as ts.LiteralTypeNode).literal ?? t))) {
+      const { kind } = (t as ts.LiteralTypeNode).literal ?? t;
+      if (encounteredTypes.has(kind)) {
+        continue;
+      }
+      if (tsIsPrimitive(t)) {
+        encounteredTypes.add(kind);
+      }
+    }
+    filteredTypes.push(t);
+  }
+  return filteredTypes;
+}
+
+/** @deprecated The generator keeps its own enum registry per run; kept for 1.x (ADR-004). */
+export const enumCache = new Map<string, ts.EnumDeclaration>();
+
+/**
+ * Create a TS enum (with sanitized name and members)
+ * @deprecated Kept for 1.x; removed in 2.0 (ADR-004, decision 9).
+ */
+export function tsEnum(
+  name: string,
+  members: (string | number)[],
+  metadata?: { name?: string; description?: string | null }[],
+  options?: { export?: boolean; shouldCache?: boolean },
+) {
+  const ts = loadTypeScript();
+  let enumName = sanitizeMemberName(name);
+  enumName = `${enumName.charAt(0).toUpperCase()}${enumName.substring(1)}`;
+  let key = "";
+  if (options?.shouldCache) {
+    key = `${members
+      .slice(0)
+      .sort()
+      .map((v, i) => {
+        return `${metadata?.[i]?.name ?? String(v)}:${metadata?.[i]?.description || ""}`;
+      })
+      .join(",")}`;
+    if (enumCache.has(key)) {
+      return enumCache.get(key) as ts.EnumDeclaration;
+    }
+  }
+  const enumDeclaration = ts.factory.createEnumDeclaration(
+    /* modifiers */ options ? tsModifiers({ export: options.export ?? false }) : undefined,
+    /* name      */ enumName,
+    /* members   */ members.map((value, i) => tsEnumMember(value, metadata?.[i])),
+  );
+  options?.shouldCache && enumCache.set(key, enumDeclaration);
+  return enumDeclaration;
+}
+
+/**
+ * Create an exported TS array literal expression
+ * @deprecated Kept for 1.x; removed in 2.0 (ADR-004, decision 9).
+ */
+export function tsArrayLiteralExpression(
+  name: string,
+  elementType: TypeInput,
+  values: (string | number)[],
+  options?: { export?: boolean; readonly?: boolean; injectFooter?: FooterEntry[] },
+) {
+  const ts = loadTypeScript();
+  let variableName = sanitizeMemberName(name);
+  variableName = `${variableName.charAt(0).toLowerCase()}${variableName.substring(1)}`;
+
+  if (options?.injectFooter) {
+    requireHelper(options.injectFooter, HELPER_TYPES.flattenedDeepRequired);
+  }
+
+  const arrayType = options?.readonly
+    ? tsReadonlyArray(elementType, options.injectFooter)
+    : ts.factory.createArrayTypeNode(legacyTypeNode(elementType));
+
+  return ts.factory.createVariableStatement(
+    options ? tsModifiers({ export: options.export ?? false }) : undefined,
+    ts.factory.createVariableDeclarationList(
+      [
+        ts.factory.createVariableDeclaration(
+          variableName,
+          undefined,
+          arrayType,
+          ts.factory.createArrayLiteralExpression(
+            values.map((value) => toValueExpression(ts, value)),
+          ),
+        ),
+      ],
+      ts.NodeFlags.Const,
+    ),
+  );
+}
+
+function sanitizeMemberName(name: string) {
+  let sanitizedName = name.replace(JS_ENUM_INVALID_CHARS_RE, (c) => {
+    // The pattern matches at least one character, so `last` is always a character.
+    const last = c.at(-1) ?? "";
+    return JS_PROPERTY_INDEX_INVALID_CHARS_RE.test(last) ? "" : last.toUpperCase();
+  });
+  if (Number(name[0]) >= 0) {
+    sanitizedName = `Value${name}`;
+  }
+  return sanitizedName;
+}
+
+/** An enum member name: a valid identifier as is; anything else prefixed, replaced or quoted. */
+function enumMemberName(value: string | number, explicitName: string | undefined): string {
+  let name = explicitName ?? String(value);
+  if (JS_PROPERTY_INDEX_RE.test(name)) {
+    return name;
+  }
+  if (Number(name[0]) >= 0) {
+    // A decimal point is not valid in a name; keep the digits readable.
+    name = `Value${name}`.replace(".", "_");
+  } else if (name[0] === "-") {
+    name = `ValueMinus${name.slice(1)}`;
+  }
+  const invalidCharMatch = name.match(JS_PROPERTY_INDEX_INVALID_CHARS_RE);
+  if (!invalidCharMatch) {
+    return name === "" ? quotedMemberName(name) : name;
+  }
+  if (invalidCharMatch[0] === name) {
+    return quotedMemberName(name);
+  }
+  return name.replace(JS_PROPERTY_INDEX_INVALID_CHARS_RE, (s) =>
+    s in SPECIAL_CHARACTER_MAP ? (SPECIAL_CHARACTER_MAP[s] as string) : "_",
+  );
+}
+
+/**
+ * Sanitize TS enum member expression
+ * @deprecated Kept for 1.x; removed in 2.0 (ADR-004, decision 9).
+ */
+export function tsEnumMember(
+  value: string | number,
+  metadata: { name?: string; description?: string | null } = {},
+) {
+  const ts = loadTypeScript();
+  const name = enumMemberName(value, metadata.name);
+  const member = ts.factory.createEnumMember(name, toValueExpression(ts, value));
+  const trimmedDescription = enumMemberDescription(metadata.description);
+  if (trimmedDescription === "") {
+    return member;
+  }
+
+  return ts.addSyntheticLeadingComment(
+    member,
+    ts.SyntaxKind.SingleLineCommentTrivia,
+    ` ${trimmedDescription}`,
+    true,
+  );
+}
+
+/**
+ * Is this a primitive type (string, number, boolean, null, undefined)?
+ * @deprecated Kept for 1.x; removed in 2.0 (ADR-004, decision 9).
+ */
+export function tsIsPrimitive(input: TypeInput): boolean {
+  const ts = loadTypeScript();
+  if (!input) {
+    return true;
+  }
+  const type = legacyTypeNode(input);
+  return (
+    ts.SyntaxKind[type.kind] === "BooleanKeyword" ||
+    ts.SyntaxKind[type.kind] === "NeverKeyword" ||
+    ts.SyntaxKind[type.kind] === "NullKeyword" ||
+    ts.SyntaxKind[type.kind] === "NumberKeyword" ||
+    ts.SyntaxKind[type.kind] === "StringKeyword" ||
+    ts.SyntaxKind[type.kind] === "UndefinedKeyword" ||
+    ("literal" in type && tsIsPrimitive(type.literal as ts.TypeLiteralNode))
+  );
+}
+
+/**
+ * Modifiers (readonly)
+ * @deprecated Kept for 1.x; removed in 2.0 (ADR-004, decision 9).
+ */
+export function tsModifiers(modifiers: { readonly?: boolean; export?: boolean }): ts.Modifier[] {
+  const ts = loadTypeScript();
+  const typeMods: ts.Modifier[] = [];
+  if (modifiers.export) {
+    typeMods.push(ts.factory.createModifier(ts.SyntaxKind.ExportKeyword));
+  }
+  if (modifiers.readonly) {
+    typeMods.push(ts.factory.createModifier(ts.SyntaxKind.ReadonlyKeyword));
+  }
+  return typeMods;
+}
+
+/**
+ * Create a valid property index
+ * @deprecated Kept for 1.x; removed in 2.0 (ADR-004, decision 9).
+ */
+export function tsPropertyIndex(index: string | number) {
+  const ts = loadTypeScript();
+  if (
+    (typeof index === "number" && !(index < 0)) ||
+    (typeof index === "string" && String(Number(index)) === index && index[0] !== "-")
+  ) {
+    return ts.factory.createNumericLiteral(index);
+  }
+  return typeof index === "string" && JS_PROPERTY_INDEX_RE.test(index)
+    ? ts.factory.createIdentifier(index)
+    : ts.factory.createStringLiteral(String(index));
+}
+
+/**
+ * Enhanced ReadonlyArray.
+ * eg: type Foo = ReadonlyArray<T>; type Bar = ReadonlyArray<T[]>
+ * Foo and Bar are both of type `readonly T[]`
+ * @deprecated Kept for 1.x; removed in 2.0 (ADR-004, decision 9).
+ */
+export function tsReadonlyArray(type: TypeInput, injectFooter?: FooterEntry[]): ts.TypeNode {
+  const ts = loadTypeScript();
+  if (injectFooter) {
+    requireHelper(injectFooter, HELPER_TYPES.readonlyArray);
+  }
+  return ts.factory.createTypeReferenceNode(ts.factory.createIdentifier("ReadonlyArray"), [
+    legacyTypeNode(type),
+  ]);
+}

package/src/api/legacy-utils.ts

@@ -0,0 +1,118 @@
+import colors from "ansi-colors";
+import { formatDuration } from "../adapters/terminal-logger/terminal-logger.js";
+import type { DebugGroup } from "../application/ports/logger.js";
+import { discriminatorProperty } from "../application/transform/schema/discriminator-property.js";
+import type { IrPropertySignature } from "../domain/ir/nodes.js";
+import { createRef as createDomainRef } from "../domain/openapi/json-pointer.js";
+import type { DiscriminatorObject } from "../types.js";
+import { defaultLogger, terminalSupportsColor } from "./default-ports.js";
+import { type ResolveRefOptions, resolveDocumentRef, walkDocument } from "./document-refs.js";
+
+/**
+ * The original's exported utilities, kept for 1.x (ADR-004, decision 9). The generator itself
+ * logs through the Logger port; `debug`, `warn` and `error` here write through the default one.
+ */
+
+// The exported `c` is the shared ansi-colors instance, switched off at import when the terminal has
+// no colors, as the original did. The generator's own logger uses a separate instance.
+if (!terminalSupportsColor()) {
+  colors.enabled = false;
+}
+
+/**
+ * The shared ansi-colors instance.
+ * @deprecated Kept for 1.x; removed in 2.0 (ADR-004, decision 9). Use a color library directly.
+ */
+export const c = colors;
+
+/**
+ * The discriminator property of a schema at `path`, typed as its discriminator value. Returns IR
+ * (task 6.2), like the exported transformers.
+ */
+export function createDiscriminatorProperty(
+  discriminator: DiscriminatorObject,
+  { path, readonly = false }: { path: string; readonly?: boolean },
+): IrPropertySignature {
+  return discriminatorProperty(discriminator, path, readonly);
+}
+
+/** Create a $ref pointer (even from other $refs) */
+export function createRef(parts: (number | string | undefined | null)[]): string {
+  return createDomainRef(parts);
+}
+
+/**
+ * Print debug message (cribbed from the `debug` package, but without all the bells & whistles
+ * @deprecated Kept for 1.x; removed in 2.0 (ADR-004, decision 9).
+ */
+export function debug(msg: string, group?: string, time?: number) {
+  // Any group name was accepted; one the logger does not know prints in white, as before.
+  defaultLogger(false).debug(msg, group as DebugGroup | undefined, time);
+}
+
+/**
+ * Print error message
+ * @deprecated Kept for 1.x; removed in 2.0 (ADR-004, decision 9).
+ */
+export function error(msg: string) {
+  defaultLogger(false).error(msg);
+}
+
+/** Format a performance log in a friendly format */
+export function formatTime(t: number) {
+  return typeof t === "number" ? formatDuration(t) : t;
+}
+
+/** Call Object.entries() and optionally sort */
+export function getEntries<T>(
+  obj: ArrayLike<T> | Record<string, T>,
+  options?: {
+    alphabetize?: boolean;
+    excludeDeprecated?: boolean;
+  },
+) {
+  let entries = Object.entries(obj);
+  if (options?.alphabetize) {
+    entries.sort(([a], [b]) => a.localeCompare(b, "en-us", { numeric: true }));
+  }
+  if (options?.excludeDeprecated) {
+    entries = entries.filter(
+      ([, v]) => !(v && typeof v === "object" && "deprecated" in v && v.deprecated),
+    );
+  }
+  return entries;
+}
+
+export type { ResolveRefOptions } from "./document-refs.js";
+
+/**
+ * resolve a $ref in a schema
+ * @deprecated Kept for 1.x; removed in 2.0 (ADR-004, decision 9).
+ */
+export function resolveRef<T>(
+  schema: any,
+  $ref: string,
+  options: ResolveRefOptions,
+): T | undefined {
+  return resolveDocumentRef<T>(schema, $ref, options);
+}
+
+/**
+ * Walk through any JSON-serializable (i.e. non-circular) object
+ * @deprecated Kept for 1.x; removed in 2.0 (ADR-004, decision 9).
+ */
+export function walk(
+  obj: unknown,
+  cb: (value: Record<string, unknown>, path: (string | number)[]) => void,
+  path: (string | number)[] = [],
+): void {
+  walkDocument(obj, cb, path);
+}
+
+/**
+ * Print warning message
+ * @deprecated Kept for 1.x; removed in 2.0 (ADR-004, decision 9).
+ */
+export function warn(msg: string, silent = false) {
+  defaultLogger(silent).warn(msg);
+}

package/src/api/openapi-ts.ts

@@ -0,0 +1,62 @@
+import { createRedoclySchemaLoader } from "../adapters/redocly-loader/redocly-schema-loader.js";
+import { withStackOverflowReported } from "../application/stack-overflow.js";
+import type { IrDeclaration } from "../domain/ir/nodes.js";
+import type { GeneratorOptions, SchemaSource } from "../types.js";
+import {
+  defaultLogger,
+  defaultRedoclyConfig,
+  monotonicNow,
+  REMOTE_REF_TIMEOUT_MS,
+} from "./default-ports.js";
+import { createDocumentRun, type GeneratorPorts } from "./document-run.js";
+import transformSchema from "./transform-schema.js";
+
+/**
+ * The Node API's composition root (ENGINEERING_PLAN 4.5): `openapiTS` wires the default adapters;
+ * `generateDeclarations` runs with any ports, which is how the CLI calls it.
+ */
+
+/** Load, validate and bundle the source, then transform it into IR declarations. */
+export async function generateDeclarations(
+  source: SchemaSource,
+  options: GeneratorOptions,
+  ports: GeneratorPorts,
+): Promise<IrDeclaration[]> {
+  const { schema, ctx } = await createDocumentRun(source, options, ports);
+  const startedAt = ports.now();
+  const result = withStackOverflowReported("transform", () => transformSchema(schema, ctx));
+  ports.logger.debug(
+    "Completed AST transformation for entire document",
+    "ts",
+    ports.now() - startedAt,
+  );
+  return result;
+}
+
+/** The default ports: the terminal logger, the given or default Redocly config, Redocly loading. */
+export async function defaultGeneratorPorts(options: GeneratorOptions): Promise<GeneratorPorts> {
+  const logger = defaultLogger(options.silent ?? false);
+  const redoc = options.redocly ?? (await defaultRedoclyConfig());
+  const loader = createRedoclySchemaLoader({
+    redoc,
+    logger,
+    now: monotonicNow,
+    remoteRefTimeoutMs: REMOTE_REF_TIMEOUT_MS,
+  });
+  return { loader, logger, redoc, now: monotonicNow };
+}
+
+/**
+ * Convert an OpenAPI schema to TypeScript declarations (IR nodes; print them with `astToString`)
+ * @param {string|URL|object|Readable} source OpenAPI schema source:
+ *   - YAML: string
+ *   - JSON: parsed object
+ *   - URL: URL to a YAML or JSON file (local or remote)
+ *   - Readable: Readable stream of YAML or JSON
+ */
+export default async function openapiTS(
+  source: SchemaSource,
+  options: GeneratorOptions = {},
+): Promise<IrDeclaration[]> {
+  return generateDeclarations(source, options, await defaultGeneratorPorts(options));
+}

package/src/api/schema-callbacks.ts

@@ -0,0 +1,211 @@
+import { toPropertySignature, toTypeNode } from "../adapters/type-ast-bridge/ir-to-typescript.js";
+import { loadTypeScript } from "../adapters/type-ast-bridge/load-typescript.js";
+import { fromPropertySignature } from "../adapters/type-ast-bridge/typescript-to-ir.js";
+import type { ts } from "../adapters/type-ast-bridge/typescript-types.js";
+import type {
+  CustomType,
+  SchemaCallbacks,
+  SchemaLocation,
+} from "../application/transform/schema/schema-context.js";
+import { ERROR_CODES, OpenAPITypesafeError } from "../domain/errors.js";
+import { irRaw } from "../domain/ir/constructors.js";
+import type { IrPropertySignature, IrType } from "../domain/ir/nodes.js";
+import type {
+  GlobalContext,
+  IrCallbackType,
+  IrPostTransform,
+  IrTransform,
+  IrTransformProperty,
+  LegacyCallbackOptions,
+  SchemaObject,
+  TransformNodeOptions,
+} from "../types.js";
+import { warnLegacyCallback } from "./legacy-callback-warning.js";
+import { toIrType } from "./type-helpers.js";
+
+/**
+ * The user's schema callbacks as the transformers call them (ENGINEERING_PLAN 6.3, ADR-004).
+ * With `irCallbacks: true` they receive and return IR; otherwise they receive TypeScript nodes and
+ * their results are read by the bridge.
+ */
+
+export class UnreadablePropertyError extends OpenAPITypesafeError {
+  constructor(path: string | undefined) {
+    super({
+      code: ERROR_CODES.CALLBACK_RESULT_UNREADABLE,
+      message:
+        `transformProperty at ${path} returned a property ` +
+        "with syntax the generator cannot read",
+      details: { callback: "transformProperty", path },
+    });
+    this.name = "UnreadablePropertyError";
+  }
+}
+
+/** A `transform` or `postTransform` result that is neither IR nor a TypeScript node. */
+export class UnreadableTypeError extends OpenAPITypesafeError {
+  constructor(callback: "transform" | "postTransform", path: string | undefined) {
+    super({
+      code: ERROR_CODES.CALLBACK_RESULT_UNREADABLE,
+      message: `${callback} at ${path} returned a value that is not a TypeScript node`,
+      details: { callback, path },
+    });
+    this.name = "UnreadableTypeError";
+  }
+}
+
+function nodeOptions(ctx: GlobalContext, location: SchemaLocation): TransformNodeOptions {
+  return { ...location, ctx } as TransformNodeOptions;
+}
+
+/** The callbacks of the run: IR callbacks when the run asks for them, legacy ones otherwise. */
+export function schemaCallbacks(ctx: GlobalContext): SchemaCallbacks {
+  return ctx.irCallbacks ? irSchemaCallbacks(ctx) : legacySchemaCallbacks(ctx);
+}
+
+/** An IR callback type; text is a raw type, printed as written. */
+function fromCallbackType(type: IrCallbackType): IrType {
+  return typeof type === "string" ? irRaw(type) : type;
+}
+
+function irCustomType(result: ReturnType<IrTransform>): CustomType | null {
+  if (result === undefined || result === null) {
+    return null;
+  }
+  if (typeof result === "object" && "schema" in result) {
+    return { type: fromCallbackType(result.schema), isOptional: Boolean(result.questionToken) };
+  }
+  return { type: fromCallbackType(result), isOptional: false };
+}
+
+/**
+ * The context fields hold either callback form; `irCallbacks` says which one, so the casts below
+ * only name the form the user declared with `OpenAPITSIrOptions`.
+ */
+function irSchemaCallbacks(ctx: GlobalContext): SchemaCallbacks {
+  const transform = ctx.transform as IrTransform | undefined;
+  const postTransform = ctx.postTransform as IrPostTransform | undefined;
+  const transformProperty = ctx.transformProperty as IrTransformProperty | undefined;
+  return {
+    transform: (schema, location) =>
+      transform
+        ? irCustomType(transform(schema as SchemaObject, nodeOptions(ctx, location)))
+        : null,
+    postTransform(type, location) {
+      const result = postTransform?.(type, nodeOptions(ctx, location));
+      return result === undefined ? null : fromCallbackType(result);
+    },
+    transformProperty: (property, schema, location) =>
+      transformProperty?.(property, schema as SchemaObject, nodeOptions(ctx, location)) ?? null,
+  };
+}
+
+type LegacyTransform = NonNullable<LegacyCallbackOptions["transform"]>;
+type LegacyPostTransform = NonNullable<LegacyCallbackOptions["postTransform"]>;
+type LegacyTransformProperty = NonNullable<LegacyCallbackOptions["transformProperty"]>;
+
+/** A legacy result type: IR from the helpers as it is; a TypeScript node through the bridge. */
+/**
+ * IR nodes have a string `kind`, TypeScript nodes a number. JavaScript callers can return any
+ * value, and anything else would crash the TypeScript printer later.
+ */
+function readResultType(
+  callback: "transform" | "postTransform",
+  result: unknown,
+  location: SchemaLocation,
+): IrType {
+  const kind = (result as { kind?: unknown }).kind;
+  if (typeof kind !== "string" && typeof kind !== "number") {
+    throw new UnreadableTypeError(callback, location.path);
+  }
+  return toIrType(result as IrType | ts.TypeNode);
+}
+
+function legacyResultType(ctx: GlobalContext, type: unknown, location: SchemaLocation): IrType {
+  const result = readResultType("transform", type, location);
+  if (typeof (type as { kind: unknown }).kind !== "string") {
+    warnLegacyCallback(ctx, "transform");
+  }
+  return result;
+}
+
+function legacyCustomType(
+  ctx: GlobalContext,
+  result: ReturnType<LegacyTransform>,
+  location: SchemaLocation,
+): CustomType | null {
+  if (!result || typeof result !== "object") {
+    return null;
+  }
+  if ("schema" in result) {
+    return {
+      type: legacyResultType(ctx, result.schema, location),
+      isOptional: Boolean(result.questionToken),
+    };
+  }
+  return { type: legacyResultType(ctx, result, location), isOptional: false };
+}
+
+/** See `irSchemaCallbacks` for the casts; `typeof` checks keep the original's tolerance. */
+function legacySchemaCallbacks(ctx: GlobalContext): SchemaCallbacks {
+  const transform = ctx.transform as LegacyTransform | undefined;
+  const postTransform = ctx.postTransform as LegacyPostTransform | undefined;
+  return {
+    transform: (schema, location) =>
+      typeof transform === "function"
+        ? legacyCustomType(
+            ctx,
+            transform(schema as SchemaObject, nodeOptions(ctx, location)),
+            location,
+          )
+        : null,
+    postTransform(type, location) {
+      if (typeof postTransform !== "function") {
+        return null;
+      }
+      warnLegacyCallback(ctx, "postTransform");
+      const result = postTransform(toTypeNode(loadTypeScript(), type), nodeOptions(ctx, location));
+      return result ? readResultType("postTransform", result, location) : null;
+    },
+    transformProperty: (property, schema, location) =>
+      legacyTransformProperty(ctx, property, schema, location),
+  };
+}
+
+function isIrProperty(
+  property: IrPropertySignature | ts.PropertySignature,
+): property is IrPropertySignature {
+  return typeof property.kind === "string";
+}
+
+function legacyTransformProperty(
+  ctx: GlobalContext,
+  property: IrPropertySignature,
+  schema: unknown,
+  location: SchemaLocation,
+): IrPropertySignature | null {
+  const transformProperty = ctx.transformProperty as LegacyTransformProperty | undefined;
+  if (typeof transformProperty !== "function") {
+    return null;
+  }
+  warnLegacyCallback(ctx, "transformProperty");
+  const ts = loadTypeScript();
+  const options = nodeOptions(ctx, location);
+  const result = transformProperty(
+    toPropertySignature(ts, property),
+    schema as SchemaObject,
+    options,
+  );
+  if (!result) {
+    return null;
+  }
+  if (isIrProperty(result)) {
+    return result;
+  }
+  // JavaScript callers can return any value, so check the node kind before reading it.
+  const converted = ts.isPropertySignature(result) ? fromPropertySignature(ts, result) : null;
+  if (converted === null) {
+    throw new UnreadablePropertyError(location.path);
+  }
+  return converted;
+}