@depup/openapi-typescript 7.13.0-depup.0

package/src/lib/utils.ts

@@ -0,0 +1,394 @@
+import { escapePointer, parseRef } from "@redocly/openapi-core/lib/ref-utils.js";
+import c from "ansi-colors";
+import supportsColor from "supports-color";
+import ts from "typescript";
+import type { DiscriminatorObject, OpenAPI3, OpenAPITSOptions, ReferenceObject, SchemaObject } from "../types.js";
+import { tsLiteral, tsModifiers, tsPropertyIndex } from "./ts.js";
+
+if (!supportsColor.stdout || supportsColor.stdout.hasBasic === false) {
+  c.enabled = false;
+}
+
+const DEBUG_GROUPS: Record<string, c.StyleFunction | undefined> = {
+  redoc: c.cyanBright,
+  lint: c.yellowBright,
+  bundle: c.magentaBright,
+  ts: c.blueBright,
+};
+
+export { c };
+
+/** Given a discriminator object, get the property name */
+export function createDiscriminatorProperty(
+  discriminator: DiscriminatorObject,
+  { path, readonly = false }: { path: string; readonly?: boolean },
+): ts.TypeElement {
+  // get the inferred propertyName value from the last section of the path (as the spec suggests to do)
+  let value = parseRef(path).pointer.pop();
+  // if mapping, and there’s a match, use this rather than the inferred name
+  if (discriminator.mapping) {
+    // Mapping value can either be a fully-qualified ref (#/components/schemas/XYZ) or a schema name (XYZ)
+    const matchedValue = Object.entries(discriminator.mapping).find(
+      ([, v]) => (!v.startsWith("#") && v === value) || (v.startsWith("#") && parseRef(v).pointer.pop() === value),
+    );
+    if (matchedValue) {
+      value = matchedValue[0]; // why was this designed backwards!?
+    }
+  }
+  return ts.factory.createPropertySignature(
+    /* modifiers     */ tsModifiers({
+      readonly,
+    }),
+    /* name          */ tsPropertyIndex(discriminator.propertyName),
+    /* questionToken */ undefined,
+    /* type          */ tsLiteral(value),
+  );
+}
+
+/** Create a $ref pointer (even from other $refs) */
+export function createRef(parts: (number | string | undefined | null)[]): string {
+  let pointer = "#";
+  for (const part of parts) {
+    if (part === undefined || part === null || part === "") {
+      continue;
+    }
+    const maybeRef = parseRef(String(part)).pointer;
+    if (maybeRef.length) {
+      for (const refPart of maybeRef) {
+        pointer += `/${escapePointer(refPart)}`;
+      }
+    } else {
+      pointer += `/${escapePointer(part)}`;
+    }
+  }
+  return pointer;
+}
+
+/** Print debug message (cribbed from the `debug` package, but without all the bells & whistles */
+export function debug(msg: string, group?: string, time?: number) {
+  if (
+    process.env.DEBUG &&
+    (!group ||
+      process.env.DEBUG === "*" ||
+      process.env.DEBUG === "openapi-ts:*" ||
+      process.env.DEBUG.toLocaleLowerCase() === `openapi-ts:${group.toLocaleLowerCase()}`)
+  ) {
+    const groupColor = (group && DEBUG_GROUPS[group]) || c.whiteBright;
+    const groupName = groupColor(`openapi-ts:${group ?? "info"}`);
+    let timeFormatted = "";
+    if (typeof time === "number") {
+      timeFormatted = c.green(` ${formatTime(time)} `);
+    }
+    // biome-ignore lint/suspicious/noConsole: this is a CLI
+    console.debug(`  ${c.bold(groupName)}${timeFormatted}${msg}`);
+  }
+}
+
+/** Print error message */
+export function error(msg: string) {
+  // biome-ignore lint/suspicious/noConsole: this is a CLI
+  console.error(c.red(` ✘  ${msg}`));
+}
+
+/** Format a performance log in a friendly format */
+export function formatTime(t: number) {
+  if (typeof t === "number") {
+    if (t < 1000) {
+      return `${Math.round(10 * t) / 10}ms`;
+    }
+    if (t < 60000) {
+      return `${Math.round(t / 100) / 10}s`;
+    }
+    return `${Math.round(t / 6000) / 10}m`;
+  }
+  return 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;
+}
+
+/** resolve a $ref in a schema */
+export function resolveRef<T>(
+  schema: any,
+  $ref: string,
+  { silent = false, visited = [] }: { silent: boolean; visited?: string[] },
+): T | undefined {
+  const { pointer } = parseRef($ref);
+  if (!pointer.length) {
+    return undefined;
+  }
+  let node = schema;
+  for (const key of pointer) {
+    if (node && typeof node === "object" && node[key]) {
+      node = node[key];
+    } else {
+      warn(`Could not resolve $ref "${$ref}"`, silent);
+      return undefined;
+    }
+  }
+
+  // if this is also a $ref, keep tracing
+  if (node && typeof node === "object" && node.$ref) {
+    if (visited.includes(node.$ref)) {
+      warn(`Could not resolve circular $ref "${$ref}"`, silent);
+      return undefined;
+    }
+    return resolveRef(schema, node.$ref, {
+      silent,
+      visited: [...visited, node.$ref],
+    });
+  }
+
+  return node;
+}
+
+function createDiscriminatorEnum(values: string[], prevSchema?: SchemaObject): SchemaObject {
+  return {
+    type: "string",
+    enum: values,
+    description: prevSchema?.description
+      ? `${prevSchema.description} (enum property replaced by openapi-typescript)`
+      : "discriminator enum property added by openapi-typescript",
+  };
+}
+
+/** Adds or replaces the discriminator enum with the passed `values` in a schema defined by `ref` */
+function patchDiscriminatorEnum(
+  schema: SchemaObject,
+  ref: string,
+  values: string[],
+  discriminator: DiscriminatorObject,
+  discriminatorRef: string,
+  options: OpenAPITSOptions,
+): boolean {
+  const resolvedSchema = resolveRef<SchemaObject>(schema, ref, {
+    silent: options.silent ?? false,
+  });
+
+  if (resolvedSchema?.allOf) {
+    // if the schema is an allOf, we can append a new schema object to the allOf array
+    resolvedSchema.allOf.push({
+      type: "object",
+      // discriminator enum properties always need to be required
+      required: [discriminator.propertyName],
+      properties: {
+        [discriminator.propertyName]: createDiscriminatorEnum(values),
+      },
+    });
+
+    return true;
+  } else if (typeof resolvedSchema === "object" && "type" in resolvedSchema && resolvedSchema.type === "object") {
+    // if the schema is an object, we can apply the discriminator enums to its properties
+    if (!resolvedSchema.properties) {
+      resolvedSchema.properties = {};
+    }
+
+    // discriminator enum properties always need to be required
+    if (!resolvedSchema.required) {
+      resolvedSchema.required = [discriminator.propertyName];
+    } else if (!resolvedSchema.required.includes(discriminator.propertyName)) {
+      resolvedSchema.required.push(discriminator.propertyName);
+    }
+
+    // add/replace the discriminator enum property
+    resolvedSchema.properties[discriminator.propertyName] = createDiscriminatorEnum(
+      values,
+      resolvedSchema.properties[discriminator.propertyName] as SchemaObject,
+    );
+
+    return true;
+  }
+
+  warn(
+    `Discriminator mapping has an invalid schema (neither an object schema nor an allOf array): ${ref} => ${values.join(
+      ", ",
+    )} (Discriminator: ${discriminatorRef})`,
+    options.silent,
+  );
+
+  return false;
+}
+
+type InternalDiscriminatorMapping = Record<string, { inferred?: string; defined?: string[] }>;
+
+/** Return a key–value map of discriminator objects found in a schema */
+export function scanDiscriminators(schema: OpenAPI3, options: OpenAPITSOptions) {
+  // all discriminator objects found in the schema
+  const objects: Record<string, DiscriminatorObject> = {};
+
+  // refs of all mapped schema objects we have successfully handled to infer the discriminator enum value
+  const refsHandled: string[] = [];
+
+  // perform 2 passes: first, collect all discriminator definitions and handle oneOf and mappings
+  walk(schema, (obj, path) => {
+    const discriminator = obj?.discriminator as DiscriminatorObject | undefined;
+    if (!discriminator?.propertyName) {
+      return;
+    }
+
+    // collect discriminator object for later usage
+    const ref = createRef(path);
+
+    objects[ref] = discriminator;
+
+    // if a mapping is available we will help Typescript to infer properties by adding the discriminator enum with its single mapped value to each schema
+    // we only handle the mapping in advance for discriminator + oneOf compositions right now
+    if (!obj?.oneOf || !Array.isArray(obj.oneOf)) {
+      return;
+    }
+
+    const oneOf: (SchemaObject | ReferenceObject)[] = obj.oneOf;
+    const mapping: InternalDiscriminatorMapping = {};
+
+    // the mapping can be inferred from the oneOf refs next to the discriminator object
+    for (const item of oneOf) {
+      if ("$ref" in item) {
+        // the name of the schema is the inferred discriminator enum value
+        const value = item.$ref.split("/").pop();
+
+        if (value) {
+          if (!mapping[item.$ref]) {
+            mapping[item.$ref] = { inferred: value };
+          } else {
+            mapping[item.$ref].inferred = value;
+          }
+        }
+      }
+    }
+
+    // the mapping can be defined in the discriminator object itself
+    if (discriminator.mapping) {
+      for (const mappedValue in discriminator.mapping) {
+        const mappedRef = discriminator.mapping[mappedValue];
+        if (!mappedRef) {
+          continue;
+        }
+
+        if (!mapping[mappedRef]?.defined) {
+          // this overrides inferred values, but we don't need them anymore as soon as we have a defined value
+          mapping[mappedRef] = { defined: [] };
+        }
+
+        mapping[mappedRef].defined?.push(mappedValue);
+      }
+    }
+
+    for (const [mappedRef, { inferred, defined }] of Object.entries(mapping)) {
+      if (refsHandled.includes(mappedRef)) {
+        continue;
+      }
+
+      if (!inferred && !defined) {
+        continue;
+      }
+
+      // prefer defined values over automatically inferred ones
+      // the inferred enum values from the schema might not represent the actual enum values of the discriminator,
+      // so if we have defined values, use them instead
+      // biome-ignore lint/style/noNonNullAssertion: we just checked for this
+      const mappedValues = defined ?? [inferred!];
+
+      if (
+        patchDiscriminatorEnum(schema as unknown as SchemaObject, mappedRef, mappedValues, discriminator, ref, options)
+      ) {
+        refsHandled.push(mappedRef);
+      }
+    }
+  });
+
+  // second, collect the schema objects that inherit from discriminators
+  // (sometimes this mapping is implicit, so it can’t be done until we know
+  // about every discriminator in the document)
+  walk(schema, (obj, path) => {
+    if (!obj || !Array.isArray(obj.allOf)) {
+      return;
+    }
+
+    for (const item of (obj as any).allOf) {
+      if ("$ref" in item) {
+        if (!objects[item.$ref]) {
+          return;
+        }
+
+        const ref = createRef(path);
+        const discriminator = objects[item.$ref];
+        const mappedValues: string[] = [];
+
+        if (discriminator.mapping) {
+          for (const mappedValue in discriminator.mapping) {
+            if (discriminator.mapping[mappedValue] === ref) {
+              mappedValues.push(mappedValue);
+            }
+          }
+
+          if (mappedValues.length > 0) {
+            if (
+              patchDiscriminatorEnum(
+                schema as unknown as SchemaObject,
+                ref,
+                mappedValues,
+                discriminator,
+                item.$ref,
+                options,
+              )
+            ) {
+              refsHandled.push(ref);
+            }
+          }
+        }
+
+        objects[ref] = {
+          ...objects[item.$ref],
+        };
+      } else if (item.discriminator?.propertyName) {
+        objects[createRef(path)] = { ...item.discriminator };
+      }
+    }
+  });
+
+  return { objects, refsHandled };
+}
+
+/** Walk through any JSON-serializable (i.e. non-circular) object */
+export function walk(
+  obj: unknown,
+  cb: (value: Record<string, unknown>, path: (string | number)[]) => void,
+  path: (string | number)[] = [],
+): void {
+  if (!obj || typeof obj !== "object") {
+    return;
+  }
+  if (Array.isArray(obj)) {
+    for (let i = 0; i < obj.length; i++) {
+      walk(obj[i], cb, path.concat(i));
+    }
+    return;
+  }
+  cb(obj as Record<string, unknown>, path);
+  for (const k of Object.keys(obj)) {
+    walk((obj as Record<string, unknown>)[k], cb, path.concat(k));
+  }
+}
+
+/** Print warning message */
+export function warn(msg: string, silent = false) {
+  if (!silent) {
+    // biome-ignore lint/suspicious/noConsole: this is a CLI
+    console.warn(c.yellow(` ⚠  ${msg}`));
+  }
+}

package/src/transform/components-object.ts

@@ -0,0 +1,161 @@
+import { performance } from "node:perf_hooks";
+import * as changeCase from "change-case";
+import ts from "typescript";
+import { addJSDocComment, NEVER, QUESTION_TOKEN, tsModifiers, tsPropertyIndex } from "../lib/ts.js";
+import { createRef, debug, getEntries } from "../lib/utils.js";
+import type { ComponentsObject, GlobalContext, SchemaObject, TransformNodeOptions } from "../types.js";
+import transformHeaderObject from "./header-object.js";
+import transformParameterObject from "./parameter-object.js";
+import transformPathItemObject from "./path-item-object.js";
+import transformRequestBodyObject from "./request-body-object.js";
+import transformResponseObject from "./response-object.js";
+import transformSchemaObject from "./schema-object.js";
+
+/**
+ * Determines if a schema object represents an enum type to prevent duplicate exports
+ * when using --root-types and --enum flags together.
+ *
+ * When both flags are enabled:
+ * - --enum flag generates TypeScript enums at the bottom of the file
+ * - --root-types flag would normally also export these as root type aliases
+ * - This results in duplicate exports (both enum and type alias for the same schema)
+ *
+ * This function identifies enum schemas so they can be excluded from root type generation,
+ * allowing only the TypeScript enum to be generated.
+ *
+ * @param schema The schema object to check
+ * @returns true if the schema represents an enum type
+ */
+export function isEnumSchema(schema: unknown): boolean {
+  return (
+    typeof schema === "object" &&
+    schema !== null &&
+    !Array.isArray(schema) &&
+    "enum" in schema &&
+    Array.isArray((schema as any).enum) &&
+    (!("type" in schema) || (schema as any).type !== "object") &&
+    !("properties" in schema) &&
+    !("additionalProperties" in schema)
+  );
+}
+
+type ComponentTransforms = keyof Omit<ComponentsObject, "examples" | "securitySchemes" | "links" | "callbacks">;
+
+const transformers: Record<ComponentTransforms, (node: any, options: TransformNodeOptions) => ts.TypeNode> = {
+  schemas: transformSchemaObject,
+  responses: transformResponseObject,
+  parameters: transformParameterObject,
+  requestBodies: transformRequestBodyObject,
+  headers: transformHeaderObject,
+  pathItems: transformPathItemObject,
+};
+
+/**
+ * Transform the ComponentsObject (4.8.7)
+ * @see https://spec.openapis.org/oas/latest.html#components-object
+ */
+export default function transformComponentsObject(componentsObject: ComponentsObject, ctx: GlobalContext): ts.Node[] {
+  const type: ts.TypeElement[] = [];
+  const rootTypeAliases: { [key: string]: ts.TypeAliasDeclaration } = {};
+  for (const key of Object.keys(transformers) as ComponentTransforms[]) {
+    const componentT = performance.now();
+
+    const items: ts.TypeElement[] = [];
+    if (componentsObject[key]) {
+      for (const [name, item] of getEntries<SchemaObject>(componentsObject[key], ctx)) {
+        let subType = transformers[key](item, {
+          path: createRef(["components", key, name]),
+          schema: item,
+          ctx,
+        });
+
+        let hasQuestionToken = false;
+        if (ctx.transform) {
+          const result = ctx.transform(item, {
+            path: createRef(["components", key, name]),
+            schema: item,
+            ctx,
+          });
+          if (result) {
+            if ("schema" in result) {
+              subType = result.schema;
+              hasQuestionToken = result.questionToken;
+            } else {
+              subType = result;
+            }
+          }
+        }
+
+        const property = ts.factory.createPropertySignature(
+          /* modifiers     */ tsModifiers({ readonly: ctx.immutable }),
+          /* name          */ tsPropertyIndex(name),
+          /* questionToken */ hasQuestionToken ? QUESTION_TOKEN : undefined,
+          /* type          */ subType,
+        );
+        addJSDocComment(item as unknown as any, property);
+        items.push(property);
+
+        if (ctx.rootTypes) {
+          // Skip enum schemas when generating root types to prevent duplication (only when --enum flag is enabled)
+          const shouldSkipEnumSchema = ctx.enum && key === "schemas" && isEnumSchema(item);
+
+          if (!shouldSkipEnumSchema) {
+            const componentKey = changeCase.pascalCase(singularizeComponentKey(key));
+            const componentName = ctx.rootTypesKeepCasing && key === "schemas" ? name : changeCase.pascalCase(name);
+            let aliasName = `${componentKey}${componentName}`;
+
+            // Add counter suffix (e.g. "_2") if conflict in name
+            let conflictCounter = 1;
+
+            while (rootTypeAliases[aliasName] !== undefined) {
+              conflictCounter++;
+              aliasName = `${componentKey}${componentName}_${conflictCounter}`;
+            }
+            const ref = ts.factory.createTypeReferenceNode(`components['${key}']['${name}']`);
+            if (ctx.rootTypesNoSchemaPrefix && key === "schemas") {
+              aliasName = aliasName.replace(componentKey, "");
+            }
+            const typeAlias = ts.factory.createTypeAliasDeclaration(
+              /* modifiers      */ tsModifiers({ export: true }),
+              /* name           */ aliasName,
+              /* typeParameters */ undefined,
+              /* type           */ ref,
+            );
+            rootTypeAliases[aliasName] = typeAlias;
+          }
+        }
+      }
+    }
+    type.push(
+      ts.factory.createPropertySignature(
+        /* modifiers     */ undefined,
+        /* name          */ tsPropertyIndex(key),
+        /* questionToken */ undefined,
+        /* type          */ items.length ? ts.factory.createTypeLiteralNode(items) : NEVER,
+      ),
+    );
+
+    debug(`Transformed components → ${key}`, "ts", performance.now() - componentT);
+  }
+
+  // Extract root types
+  let rootTypes: ts.TypeAliasDeclaration[] = [];
+  if (ctx.rootTypes) {
+    rootTypes = Object.keys(rootTypeAliases).map((k) => rootTypeAliases[k]);
+  }
+
+  return [ts.factory.createTypeLiteralNode(type), ...rootTypes];
+}
+
+export function singularizeComponentKey(
+  key: `x-${string}` | "schemas" | "responses" | "parameters" | "requestBodies" | "headers" | "pathItems",
+): string {
+  switch (key) {
+    // Handle special singular case
+    case "requestBodies":
+      return "requestBody";
+    // Default to removing the "s"
+    default:
+      return key.slice(0, -1);
+  }
+}

package/src/transform/header-object.ts

@@ -0,0 +1,45 @@
+import { escapePointer } from "@redocly/openapi-core/lib/ref-utils.js";
+import ts from "typescript";
+import { addJSDocComment, tsModifiers, tsPropertyIndex, UNKNOWN } from "../lib/ts.js";
+import { getEntries } from "../lib/utils.js";
+import type { HeaderObject, TransformNodeOptions } from "../types.js";
+import transformMediaTypeObject from "./media-type-object.js";
+import transformSchemaObject from "./schema-object.js";
+
+/**
+ * Transform HeaderObject nodes (4.8.21)
+ * @see https://spec.openapis.org/oas/v3.1.0#header-object
+ */
+export default function transformHeaderObject(headerObject: HeaderObject, options: TransformNodeOptions): ts.TypeNode {
+  if (headerObject.schema) {
+    return transformSchemaObject(headerObject.schema, options);
+  }
+
+  if (headerObject.content) {
+    const type: ts.TypeElement[] = [];
+    for (const [contentType, mediaTypeObject] of getEntries(headerObject.content ?? {}, options.ctx)) {
+      const nextPath = `${options.path ?? "#"}/${escapePointer(contentType)}`;
+      const mediaType =
+        "$ref" in mediaTypeObject
+          ? transformSchemaObject(mediaTypeObject, {
+              ...options,
+              path: nextPath,
+            })
+          : transformMediaTypeObject(mediaTypeObject, {
+              ...options,
+              path: nextPath,
+            });
+      const property = ts.factory.createPropertySignature(
+        /* modifiers     */ tsModifiers({ readonly: options.ctx.immutable }),
+        /* name          */ tsPropertyIndex(contentType),
+        /* questionToken */ undefined,
+        /* type          */ mediaType,
+      );
+      addJSDocComment(mediaTypeObject, property);
+      type.push(property);
+    }
+    return ts.factory.createTypeLiteralNode(type);
+  }
+
+  return UNKNOWN;
+}