feat(openapi-typescript): Optional Export Root Type Aliases (openapi-ts#1876)

* Add root component type aliases

* Add tests for root component types

* Add root types CLI option docs

* Add unit test for components root types

* Add schema name conflict detection

* Add tests for components root types beyond schemas

* Add cross-component conflict checks

* Update examples

* Fix biome linting issues

* Add changeset

---------

Co-authored-by: bdh9 <[email protected]>

Author: BradHacker

bin/cli.js

@@ -30,6 +30,7 @@ Options
   --path-params-as-types     Convert paths to template literal types
   --alphabetize              Sort object keys alphabetically
   --exclude-deprecated       Exclude deprecated types
+  --root-types (optional)    Export schemas types at root level
 `;
 
 const OUTPUT_FILE = "FILE";
@@ -74,6 +75,7 @@ const flags = parser(args, {
     "help",
     "immutable",
     "pathParamsAsTypes",
+    "rootTypes",
   ],
   string: ["output", "redocly"],
   alias: {
@@ -133,6 +135,7 @@ async function generateSchema(schema, { redocly, silent = false }) {
       exportType: flags.exportType,
       immutable: flags.immutable,
       pathParamsAsTypes: flags.pathParamsAsTypes,
+      rootTypes: flags.rootTypes,
       redocly,
       silent,
     }),

examples/github-api-root-types.ts

@@ -62,6 +62,7 @@
   "dependencies": {
     "@redocly/openapi-core": "^1.16.0",
     "ansi-colors": "^4.1.3",
+    "change-case": "^5.4.4",
     "parse-json": "^8.1.0",
     "supports-color": "^9.4.0",
     "yargs-parser": "^21.1.1"

package.json

@@ -40,6 +40,7 @@ async function generateSchemas() {
           "-o",
           `./examples/${name}-required.ts`,
         ]);
+        args.push([`./examples/${name}${ext}`, "--root-types", "-o", `./examples/${name}-root-types.ts`]);
       }
 
       await Promise.all(args.map((a) => execa("./bin/cli.js", a, { cwd })));

scripts/update-examples.ts

@@ -79,6 +79,7 @@ export default async function openapiTS(
     excludeDeprecated: options.excludeDeprecated ?? false,
     exportType: options.exportType ?? false,
     immutable: options.immutable ?? false,
+    rootTypes: options.rootTypes ?? false,
     injectFooter: [],
     pathParamsAsTypes: options.pathParamsAsTypes ?? false,
     postTransform: typeof options.postTransform === "function" ? options.postTransform : undefined,

src/index.ts

@@ -1,4 +1,5 @@
 import ts from "typescript";
+import * as changeCase from "change-case";
 import { performance } from "node:perf_hooks";
 import { NEVER, QUESTION_TOKEN, addJSDocComment, tsModifiers, tsPropertyIndex } from "../lib/ts.js";
 import { createRef, debug, getEntries } from "../lib/utils.js";
@@ -25,8 +26,9 @@ const transformers: Record<ComponentTransforms, (node: any, options: TransformNo
  * 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.TypeNode {
+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();
@@ -63,6 +65,24 @@ export default function transformComponentsObject(componentsObject: ComponentsOb
         );
         addJSDocComment(item as unknown as any, property);
         items.push(property);
+
+        if (ctx.rootTypes) {
+          let aliasName = changeCase.pascalCase(singularizeComponentKey(key)) + changeCase.pascalCase(name);
+          // Add counter suffix (e.g. "_2") if conflict in name
+          let conflictCounter = 1;
+          while (rootTypeAliases[aliasName] !== undefined) {
+            conflictCounter++;
+            aliasName = `${changeCase.pascalCase(singularizeComponentKey(key))}${changeCase.pascalCase(name)}_${conflictCounter}`;
+          }
+          const ref = ts.factory.createTypeReferenceNode(`components['${key}']['${name}']`);
+          const typeAlias = ts.factory.createTypeAliasDeclaration(
+            /* modifiers      */ tsModifiers({ export: true }),
+            /* name           */ aliasName,
+            /* typeParameters */ undefined,
+            /* type           */ ref,
+          );
+          rootTypeAliases[aliasName] = typeAlias;
+        }
       }
     }
     type.push(
@@ -77,5 +97,24 @@ export default function transformComponentsObject(componentsObject: ComponentsOb
     debug(`Transformed components → ${key}`, "ts", performance.now() - componentT);
   }
 
-  return ts.factory.createTypeLiteralNode(type);
+  // 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);
+  }
 }

src/transform/components-object.ts

@@ -10,7 +10,7 @@ import transformWebhooksObject from "./webhooks-object.js";
 
 type SchemaTransforms = keyof Pick<OpenAPI3, "paths" | "webhooks" | "components" | "$defs">;
 
-const transformers: Record<SchemaTransforms, (node: any, options: GlobalContext) => ts.TypeNode> = {
+const transformers: Record<SchemaTransforms, (node: any, options: GlobalContext) => ts.Node | ts.Node[]> = {
   paths: transformPathsObject,
   webhooks: transformWebhooksObject,
   components: transformComponentsObject,
@@ -35,28 +35,37 @@ export default function transformSchema(schema: OpenAPI3, ctx: GlobalContext) {
 
     if (schema[root] && typeof schema[root] === "object") {
       const rootT = performance.now();
-      const subType = transformers[root](schema[root], ctx);
-      if ((subType as ts.TypeLiteralNode).members?.length) {
-        type.push(
-          ctx.exportType
-            ? ts.factory.createTypeAliasDeclaration(
-                /* modifiers      */ tsModifiers({ export: true }),
-                /* name           */ root,
-                /* typeParameters */ undefined,
-                /* type           */ subType,
-              )
-            : ts.factory.createInterfaceDeclaration(
-                /* modifiers       */ tsModifiers({ export: true }),
-                /* name            */ root,
-                /* typeParameters  */ undefined,
-                /* heritageClauses */ undefined,
-                /* members         */ (subType as TypeLiteralNode).members,
-              ),
-        );
-        debug(`${root} done`, "ts", performance.now() - rootT);
-      } else {
-        type.push(emptyObj);
-        debug(`${root} done (skipped)`, "ts", 0);
+      const subTypes = ([] as ts.Node[]).concat(transformers[root](schema[root], ctx));
+      for (const subType of subTypes) {
+        if (ts.isTypeNode(subType)) {
+          if ((subType as ts.TypeLiteralNode).members?.length) {
+            type.push(
+              ctx.exportType
+                ? ts.factory.createTypeAliasDeclaration(
+                    /* modifiers      */ tsModifiers({ export: true }),
+                    /* name           */ root,
+                    /* typeParameters */ undefined,
+                    /* type           */ subType,
+                  )
+                : ts.factory.createInterfaceDeclaration(
+                    /* modifiers       */ tsModifiers({ export: true }),
+                    /* name            */ root,
+                    /* typeParameters  */ undefined,
+                    /* heritageClauses */ undefined,
+                    /* members         */ (subType as TypeLiteralNode).members,
+                  ),
+            );
+            debug(`${root} done`, "ts", performance.now() - rootT);
+          } else {
+            type.push(emptyObj);
+            debug(`${root} done (skipped)`, "ts", 0);
+          }
+        } else if (ts.isTypeAliasDeclaration(subType)) {
+          type.push(subType);
+        } else {
+          type.push(emptyObj);
+          debug(`${root} done (skipped)`, "ts", 0);
+        }
       }
     } else {
       type.push(emptyObj);

src/transform/index.ts

@@ -657,6 +657,8 @@ export interface OpenAPITSOptions {
   pathParamsAsTypes?: boolean;
   /** Treat all objects as if they have \`required\` set to all properties by default (default: false) */
   propertiesRequiredByDefault?: boolean;
+  /** (optional) Generate schema types at root level */
+  rootTypes?: boolean;
   /**
    * Configure Redocly for validation, schema fetching, and bundling
    * @see https://redocly.com/docs/cli/configuration/
@@ -688,6 +690,7 @@ export interface GlobalContext {
   pathParamsAsTypes: boolean;
   postTransform: OpenAPITSOptions["postTransform"];
   propertiesRequiredByDefault: boolean;
+  rootTypes: boolean;
   redoc: RedoclyConfig;
   silent: boolean;
   transform: OpenAPITSOptions["transform"];

src/types.ts

@@ -36,6 +36,14 @@ describe("CLI", () => {
         ci: { timeout: TIMEOUT },
       },
     ],
+    [
+      "snapshot > GitHub API (root types)",
+      {
+        given: ["./examples/github-api.yaml", "--root-types"],
+        want: new URL("./examples/github-api-root-types.ts", root),
+        ci: { timeout: TIMEOUT },
+      },
+    ],
     [
       "snapshot > GitHub API (next)",
       {

test/cli.test.ts

@@ -23,6 +23,7 @@ export const DEFAULT_CTX: GlobalContext = {
   pathParamsAsTypes: false,
   postTransform: undefined,
   propertiesRequiredByDefault: false,
+  rootTypes: false,
   redoc: await createConfig({}, { extends: ["minimal"] }),
   resolve($ref) {
     return resolveRef({}, $ref, { silent: false });