feat: root types

docs/cli.md

@@ -107,6 +107,7 @@ The following flags are supported in the CLI:
 | `--export-type`           | `-t`  | `false`  | Export `type` instead of `interface`                                                                                |
 | `--immutable`             |       | `false`  | Generates immutable types (readonly properties and readonly array)                                                  |
 | `--path-params-as-types`  |       | `false`  | Allow dynamic string lookups on the `paths` object                                                                  |
+| `--root-types`            |       | `false`  | Export components and paths types at root level                                                                     |
 
 ### pathParamsAsTypes
 

packages/openapi-typescript/bin/cli.js

@@ -33,6 +33,7 @@ Options
   --path-params-as-types     Convert paths to template literal types
   --alphabetize              Sort object keys alphabetically
   --exclude-deprecated       Exclude deprecated types
+  --root-types               Export components and paths types at root level    
 `;
 
 const OUTPUT_FILE = "FILE";
@@ -76,6 +77,7 @@ const flags = parser(args, {
     "help",
     "immutable",
     "pathParamsAsTypes",
+    "rootTypes",
   ],
   string: ["output", "redoc"],
   alias: {
@@ -103,6 +105,7 @@ async function generateSchema(schema, { redoc, silent = false }) {
       exportType: flags.exportType,
       immutable: flags.immutable,
       pathParamsAsTypes: flags.pathParamsAsTypes,
+      rootTypes: flags.rootTypes,
       redoc,
       silent,
     }),

packages/openapi-typescript/package.json

@@ -75,6 +75,7 @@
     "del-cli": "^5.1.0",
     "esbuild": "^0.20.1",
     "execa": "^7.2.0",
+    "scule": "^1.3.0",
     "typescript": "^5.3.3",
     "vite-node": "^1.3.1",
     "vitest": "^1.3.1"

packages/openapi-typescript/src/index.ts

@@ -88,6 +88,7 @@ export default async function openapiTS(
     arrayLength: options.arrayLength ?? false,
     transform:
       typeof options.transform === "function" ? options.transform : undefined,
+    rootTypes: options.rootTypes ?? false,
     resolve($ref) {
       return resolveRef(schema, $ref, { silent: options.silent ?? false });
     },

packages/openapi-typescript/src/lib/utils.ts

@@ -373,3 +373,24 @@ export function warn(msg: string, silent = false) {
     console.warn(c.yellow(` ⚠  ${msg}`)); // eslint-disable-line no-console
   }
 }
+
+export function renameDuplicates(arr: string[]): string[] {
+  const count: Record<string, number> = {};
+  const res: string[] = [];
+
+  for (const item of arr) {
+    if (count[item]) {
+      let newName = item + count[item];
+      while (res.includes(newName)) {
+        count[item]++;
+        newName = item + count[item];
+      }
+      res.push(newName);
+    } else {
+      count[item] = 1;
+      res.push(item);
+    }
+  }
+
+  return res;
+}

packages/openapi-typescript/src/transform/components-object.ts

@@ -1,12 +1,19 @@
+import { pascalCase } from "scule";
 import ts from "typescript";
 import {
   NEVER,
   QUESTION_TOKEN,
   addJSDocComment,
   tsModifiers,
   tsPropertyIndex,
+  oapiRef,
 } from "../lib/ts.js";
-import { createRef, debug, getEntries } from "../lib/utils.js";
+import {
+  createRef,
+  debug,
+  getEntries,
+  renameDuplicates,
+} from "../lib/utils.js";
 import type {
   ComponentsObject,
   GlobalContext,
@@ -44,15 +51,17 @@ const transformers: Record<
 export default function transformComponentsObject(
   componentsObject: ComponentsObject,
   ctx: GlobalContext,
-): ts.TypeNode {
+): [ts.TypeNode, ts.TypeAliasDeclaration[]] {
   const type: ts.TypeElement[] = [];
+  const refs: 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(componentsObject[key], ctx)) {
+      const entries = getEntries(componentsObject[key], ctx);
+      for (const [name, item] of entries) {
         let subType = transformers[key](item, {
           path: createRef(["components", key, name]),
           ctx,
@@ -83,6 +92,25 @@ export default function transformComponentsObject(
         addJSDocComment(item as unknown as any, property); // eslint-disable-line @typescript-eslint/no-explicit-any
         items.push(property);
       }
+
+      if (ctx.rootTypes) {
+        const keySingular = key.slice(0, -1);
+        const pascalNames = renameDuplicates(
+          entries.map(([name]) => pascalCase(`${keySingular}-${name}`)),
+        );
+        for (let i = 0; i < entries.length; i++) {
+          refs.push(
+            ts.factory.createTypeAliasDeclaration(
+              /* modifiers      */ tsModifiers({ export: true }),
+              /* name           */ pascalNames[i],
+              /* typeParameters */ undefined,
+              /* type           */ oapiRef(
+                createRef(["components", key, entries[i][0]]),
+              ),
+            ),
+          );
+        }
+      }
     }
     type.push(
       ts.factory.createPropertySignature(
@@ -102,5 +130,5 @@ export default function transformComponentsObject(
     );
   }
 
-  return ts.factory.createTypeLiteralNode(type);
+  return [ts.factory.createTypeLiteralNode(type), refs];
 }

packages/openapi-typescript/src/transform/index.ts

@@ -17,13 +17,18 @@ type SchemaTransforms = keyof Pick<
 
 const transformers: Record<
   SchemaTransforms,
-  (node: any, options: GlobalContext) => ts.TypeNode // eslint-disable-line @typescript-eslint/no-explicit-any
+  (
+    node: any, // eslint-disable-line @typescript-eslint/no-explicit-any
+    options: GlobalContext,
+  ) => [ts.TypeNode, ts.TypeAliasDeclaration[]]
 > = {
   paths: transformPathsObject,
   webhooks: transformWebhooksObject,
   components: transformComponentsObject,
-  $defs: (node, options) =>
+  $defs: (node, options) => [
     transformSchemaObject(node, { path: createRef(["$defs"]), ctx: options }),
+    [],
+  ],
 };
 
 export default function transformSchema(schema: OpenAPI3, ctx: GlobalContext) {
@@ -39,7 +44,7 @@ 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);
+      const [subType, aliasTypes] = transformers[root](schema[root], ctx);
       if ((subType as ts.TypeLiteralNode).members?.length) {
         type.push(
           ctx.exportType
@@ -62,6 +67,12 @@ export default function transformSchema(schema: OpenAPI3, ctx: GlobalContext) {
         type.push(emptyObj);
         debug(`${root} done (skipped)`, "ts", 0);
       }
+
+      if (ctx.rootTypes) {
+        for (const alias of aliasTypes) {
+          type.push(alias);
+        }
+      }
     } else {
       type.push(emptyObj);
       debug(`${root} done (skipped)`, "ts", 0);

packages/openapi-typescript/src/transform/paths-object.ts

@@ -1,3 +1,4 @@
+import { pascalCase } from "scule";
 import ts from "typescript";
 import {
   addJSDocComment,
@@ -26,8 +27,9 @@ const PATH_PARAM_RE = /\{[^}]+\}/g;
 export default function transformPathsObject(
   pathsObject: PathsObject,
   ctx: GlobalContext,
-): ts.TypeNode {
+): [ts.TypeNode, ts.TypeAliasDeclaration[]] {
   const type: ts.TypeElement[] = [];
+  const refs: ts.TypeAliasDeclaration[] = [];
   for (const [url, pathItemObject] of getEntries(pathsObject, ctx)) {
     if (!pathItemObject || typeof pathItemObject !== "object") {
       continue;
@@ -52,7 +54,10 @@ export default function transformPathsObject(
 
       // pathParamsAsTypes
       if (ctx.pathParamsAsTypes && url.includes("{")) {
-        const pathParams = extractPathParams(pathItemObject, ctx);
+        const { parameters: pathParams = {} } = extractParams(
+          pathItemObject,
+          ctx,
+        );
         const matches = url.match(PATH_PARAM_RE);
         let rawPath = `\`${url}\``;
         if (matches) {
@@ -106,20 +111,45 @@ export default function transformPathsObject(
 
       debug(`Transformed path "${url}"`, "ts", performance.now() - pathT);
     }
+
+    if (ctx.rootTypes) {
+      const { operations } = extractParams(pathItemObject, ctx);
+      for (const name in operations) {
+        refs.push(
+          ts.factory.createTypeAliasDeclaration(
+            /* modifiers      */ tsModifiers({ export: true }),
+            /* name           */ pascalCase(`request-${operations[name]}`),
+            /* typeParameters */ undefined,
+            /* type           */ oapiRef(
+              createRef(["paths", url, name, "parameters"]),
+            ),
+          ),
+        );
+      }
+    }
   }
 
-  return ts.factory.createTypeLiteralNode(type);
+  return [ts.factory.createTypeLiteralNode(type), refs];
 }
 
-function extractPathParams(pathItemObject: PathItemObject, ctx: GlobalContext) {
-  const params: Record<string, ParameterObject> = {};
+function extractParams(pathItemObject: PathItemObject, ctx: GlobalContext) {
+  const params: {
+    parameters: Record<string, ParameterObject>;
+    operations: Record<string, string>;
+  } = {
+    parameters: {},
+    operations: {},
+  };
   for (const p of pathItemObject.parameters ?? []) {
     const resolved =
       "$ref" in p && p.$ref
         ? ctx.resolve<ParameterObject>(p.$ref)
         : (p as ParameterObject);
-    if (resolved && resolved.in === "path") {
-      params[resolved.name] = resolved;
+    if (resolved) {
+      params.parameters = {
+        ...params.parameters,
+        [resolved.name]: resolved,
+      };
     }
   }
   for (const method of [
@@ -146,8 +176,17 @@ function extractPathParams(pathItemObject: PathItemObject, ctx: GlobalContext) {
           "$ref" in p && p.$ref
             ? ctx.resolve<ParameterObject>(p.$ref)
             : (p as ParameterObject);
-        if (resolvedParam && resolvedParam.in === "path") {
-          params[resolvedParam.name] = resolvedParam;
+        if (resolvedParam) {
+          params.parameters = {
+            ...params.parameters,
+            [resolvedParam.name]: resolvedParam,
+          };
+          if (resolvedMethod.operationId) {
+            params.operations = {
+              ...params.operations,
+              [method]: resolvedMethod.operationId,
+            };
+          }
         }
       }
     }

packages/openapi-typescript/src/transform/webhooks-object.ts

@@ -7,7 +7,7 @@ import transformPathItemObject from "./path-item-object.js";
 export default function transformWebhooksObject(
   webhooksObject: WebhooksObject,
   options: GlobalContext,
-): ts.TypeNode {
+): [ts.TypeNode, ts.TypeAliasDeclaration[]] {
   const type: ts.TypeElement[] = [];
 
   for (const [name, pathItemObject] of getEntries(webhooksObject, options)) {
@@ -26,5 +26,5 @@ export default function transformWebhooksObject(
     );
   }
 
-  return ts.factory.createTypeLiteralNode(type);
+  return [ts.factory.createTypeLiteralNode(type), []];
 }

packages/openapi-typescript/src/types.ts

@@ -673,6 +673,8 @@ export interface OpenAPITSOptions {
   pathParamsAsTypes?: boolean;
   /** Exclude deprecated fields from types? (default: false) */
   excludeDeprecated?: boolean;
+  /** Export components and paths types at root level */
+  rootTypes?: boolean;
   /**
    * Configure Redocly for validation, schema fetching, and bundling
    * @see https://redocly.com/docs/cli/configuration/
@@ -702,6 +704,7 @@ export interface GlobalContext {
   silent: boolean;
   arrayLength: boolean;
   transform: OpenAPITSOptions["transform"];
+  rootTypes: boolean;
   /** retrieve a node by $ref */
   resolve<T>($ref: string): T | undefined;
 }

packages/openapi-typescript/test/test-helpers.ts

@@ -28,6 +28,7 @@ export const DEFAULT_CTX: GlobalContext = {
   },
   silent: true,
   transform: undefined,
+  rootTypes: false,
 };
 
 /** Generic test case */

packages/openapi-typescript/test/transform/components-object.test.ts

@@ -513,7 +513,7 @@ describe("transformComponentsObject", () => {
       testName,
       async () => {
         const result = astToString(
-          transformComponentsObject(given, options ?? DEFAULT_OPTIONS),
+          transformComponentsObject(given, options ?? DEFAULT_OPTIONS)[0],
         );
         if (want instanceof URL) {
           expect(result).toMatchFileSnapshot(fileURLToPath(want));

packages/openapi-typescript/test/transform/paths-object.test.ts

@@ -377,7 +377,7 @@ describe("transformPathsObject", () => {
     test.skipIf(ci?.skipIf)(
       testName,
       async () => {
-        const result = astToString(transformPathsObject(given, options));
+        const result = astToString(transformPathsObject(given, options)[0]);
         if (want instanceof URL) {
           expect(result).toMatchFileSnapshot(fileURLToPath(want));
         } else {

packages/openapi-typescript/test/transform/webhooks-object.test.ts

@@ -187,7 +187,7 @@ describe("transformWebhooksObject", () => {
     test.skipIf(ci?.skipIf)(
       testName,
       async () => {
-        const result = astToString(transformWebhooksObject(given, options));
+        const result = astToString(transformWebhooksObject(given, options)[0]);
         if (want instanceof URL) {
           expect(result).toMatchFileSnapshot(fileURLToPath(want));
         } else {