feat(parser): generate enums into their own file

.changeset/modern-dots-study.md

@@ -0,0 +1,5 @@
+---
+"@hey-api/openapi-ts": minor
+---
+
+fix: generate enums into their own file

.changeset/young-moles-enjoy.md

@@ -0,0 +1,5 @@
+---
+"openapi-ts-docs": patch
+---
+
+docs: add enums migration

docs/openapi-ts/migrating.md

@@ -5,7 +5,7 @@ description: Migrating to @hey-api/openapi-ts.
 
 # Migrating
 
-While we try to avoid breaking changes, sometimes it's unavoidable in order to offer you the latest features. This page lists changes that require updates to your code.
+While we try to avoid breaking changes, sometimes it's unavoidable in order to offer you the latest features. This page lists changes that require updates to your code. If you run into an issue with migration, please [open an issue](https://github.com/hey-api/openapi-ts/issues).
 
 ## @next
 
@@ -50,6 +50,25 @@ This config option is deprecated and will be removed.
 
 This config option is deprecated and will be removed.
 
+## v0.39.0
+
+### Single `enums.gen.ts` file
+
+Enums are now exported from a single file. If you used imports from `model.ts`, you can change it to `enums.gen.ts`.
+
+```js
+import { Enum } from 'client/models' // [!code --]
+import { Enum } from 'client/enums.gen.ts' // [!code ++]
+```
+
+Enums are no longer exported from `index.ts`. If you used imports from index file, you will need to move enums into their own import statement.
+
+```js
+import { Enum, DefaultService } from 'client' // [!code --]
+import { Enum } from 'client/enums.gen.ts' // [!code ++]
+import { DefaultService } from 'client/services' // [!code ++]
+```
+
 ## v0.38.0
 
 ### Renamed `write`
@@ -140,15 +159,4 @@ This config option has been removed. Generated types will behave the same as `us
 
 ## OpenAPI TypeScript Codegen
 
-`openapi-ts` was originally forked from Ferdi Koomen's [openapi-typescript-codegen](https://github.com/ferdikoomen/openapi-typescript-codegen). Therefore, we want you to be able to migrate your openapi-typescript-codegen projects. Migration should be relatively straightforward if you follow the release notes on this page. If you run into an issue with migration, please [open an issue](https://github.com/hey-api/openapi-ts/issues).
-
-### Changed
-
-- `exportSchemas` is `true` by default (see [v0.27.36](#v0-27-36))
-- `useOptions` is `true` by default (see [v0.27.38](#v0-27-38))
-
-### Removed
-
-- `useUnionTypes` has been removed (see [v0.27.24](#v0-27-24))
-- `indent` has been removed (see [v0.27.26](#v0-27-26))
-- `postfixModels` has been removed (see [v0.35.0](#v0-35-0))
+`openapi-ts` was originally forked from Ferdi Koomen's [openapi-typescript-codegen](https://github.com/ferdikoomen/openapi-typescript-codegen). Therefore, we want you to be able to migrate your projects. Migration should be relatively straightforward if you follow the release notes on this page. Start here and scroll up to the release you're migrating to.

packages/openapi-ts/src/compiler/index.ts

@@ -1,4 +1,4 @@
-import { type PathOrFileDescriptor, writeFileSync } from 'node:fs';
+import { writeFileSync } from 'node:fs';
 
 import ts from 'typescript';
 
@@ -15,6 +15,7 @@ export class TypeScriptFile {
     private _headers: Array<string> = [];
     private _imports: Array<ts.Node> = [];
     private _items: Array<ts.Node | string> = [];
+    private _path: string = '';
 
     public add(...nodes: Array<ts.Node | string>): void {
         this._items = [...this._items, ...nodes];
@@ -31,6 +32,11 @@ export class TypeScriptFile {
         this._imports = [...this._imports, compiler.import.named(...params)];
     }
 
+    public setPath(path: string) {
+        this._path = path;
+        return this;
+    }
+
     public toString(seperator: string = '\n') {
         let output: string[] = [];
         if (this._headers.length) {
@@ -43,11 +49,12 @@ export class TypeScriptFile {
         return output.join(seperator);
     }
 
-    public write(file: PathOrFileDescriptor, seperator: string = '\n') {
-        if (!this._items.length) {
+    public write(seperator = '\n') {
+        // TODO: throw if path is not set. do not throw if items are empty
+        if (!this._items.length || !this._path) {
             return;
         }
-        writeFileSync(file, this.toString(seperator));
+        writeFileSync(this._path, this.toString(seperator));
     }
 }
 

packages/openapi-ts/src/compiler/types.ts

@@ -9,11 +9,11 @@
  */
 export const toExpression = (value: unknown, unescape = false): ts.Expression | undefined => {
     if (Array.isArray(value)) {
-        return createArrayType(value);
+        return createArrayType({ arr: value });
     }
 
     if (typeof value === 'object' && value !== null) {
-        return createObjectType(value);
+        return createObjectType({ obj: value });
     }
 
     if (typeof value === 'number') {
@@ -39,7 +39,13 @@
  * @param multiLine - if the array should be multiline.
  * @returns ts.ArrayLiteralExpression
  */
-export const createArrayType = <T>(arr: T[], multiLine: boolean = false): ts.ArrayLiteralExpression =>
+export const createArrayType = <T>({
+    arr,
+    multiLine = false,
+}: {
+    arr: T[];
+    multiLine?: boolean;
+}): ts.ArrayLiteralExpression =>
     ts.factory.createArrayLiteralExpression(
         arr.map(v => toExpression(v)).filter(isType<ts.Expression>),
         // Multiline if the array contains objects, or if specified by the user.
@@ -48,59 +54,60 @@
 
 /**
  * Create Object type expression.
- * @param obj - the object to create.
  * @param options - options to use when creating type.
  * @returns ts.ObjectLiteralExpression
  */
-export const createObjectType = <T extends object>(
-    obj: T,
-    options: {
-        multiLine?: boolean;
-        unescape?: boolean;
-        comments?: Record<string | number, Comments>;
-    } = {
-        comments: {},
-        multiLine: true,
-        unescape: false,
-    }
-): ts.ObjectLiteralExpression => {
-    const expression = ts.factory.createObjectLiteralExpression(
-        Object.entries(obj)
-            .map(([key, value]) => {
-                const initializer = toExpression(value, options.unescape);
-                if (!initializer) {
-                    return undefined;
-                }
-                const c = options.comments?.[key];
-                if (key.match(/\W/g) && !key.startsWith("'") && !key.endsWith("'")) {
-                    key = `'${key}'`;
-                }
-                const assignment = ts.factory.createPropertyAssignment(key, initializer);
-                if (c?.length) {
-                    addLeadingComment(assignment, c);
-                }
-                return assignment;
-            })
-            .filter(isType<ts.PropertyAssignment>),
-        options.multiLine
-    );
+export const createObjectType = <T extends object>({
+    comments = {},
+    multiLine = true,
+    obj,
+    unescape = false,
+}: {
+    obj: T;
+    multiLine?: boolean;
+    unescape?: boolean;
+    comments?: Record<string | number, Comments>;
+}): ts.ObjectLiteralExpression => {
+    const properties = Object.entries(obj)
+        .map(([key, value]) => {
+            const initializer = toExpression(value, unescape);
+            if (!initializer) {
+                return undefined;
+            }
+            if (key.match(/\W/g) && !key.startsWith("'") && !key.endsWith("'")) {
+                key = `'${key}'`;
+            }
+            const assignment = ts.factory.createPropertyAssignment(key, initializer);
+            const c = comments?.[key];
+            if (c?.length) {
+                addLeadingComment(assignment, c);
+            }
+            return assignment;
+        })
+        .filter(isType<ts.PropertyAssignment>);
+    const expression = ts.factory.createObjectLiteralExpression(properties, multiLine);
     return expression;
 };
 
 /**
  * Create enum declaration. Example `export enum T = { X, Y };`
  * @param name - the name of the enum.
  * @param obj - the object representing the enum.
- * @param comment - comment to add to enum.
+ * @param leadingComment - leading comment to add to enum.
  * @param comments - comments to add to each property of enum.
  * @returns
  */
-export const createEnumDeclaration = <T extends object>(
-    name: string,
-    obj: T,
-    comment: Comments = [],
-    comments: Record<string | number, Comments> = {}
-): ts.EnumDeclaration => {
+export const createEnumDeclaration = <T extends object>({
+    name,
+    obj,
+    leadingComment = [],
+    comments = {},
+}: {
+    name: string;
+    obj: T;
+    leadingComment: Comments;
+    comments: Record<string | number, Comments>;
+}): ts.EnumDeclaration => {
     const declaration = ts.factory.createEnumDeclaration(
         [ts.factory.createModifier(ts.SyntaxKind.ExportKeyword)],
         ts.factory.createIdentifier(name),
@@ -114,8 +121,8 @@
             return assignment;
         })
     );
-    if (comment.length) {
-        addLeadingComment(declaration, comment);
+    if (leadingComment.length) {
+        addLeadingComment(declaration, leadingComment);
     }
     return declaration;
 };

packages/openapi-ts/src/utils/enum.ts

@@ -43,17 +43,12 @@
  */
 export const enumName = (client: Client, name?: string) => {
     if (!name) {
-        return name;
+        return null;
     }
     const escapedName = unescapeName(name).replace(/[-_]([a-z])/gi, ($0, $1: string) => $1.toLocaleUpperCase());
-    let result = `${escapedName.charAt(0).toLocaleUpperCase() + escapedName.slice(1)}Enum`;
-    let index = 1;
-    while (client.enumNames.includes(result)) {
-        if (result.endsWith(index.toString())) {
-            result = result.slice(0, result.length - index.toString().length);
-        }
-        index += 1;
-        result = result + index.toString();
+    const result = `${escapedName.charAt(0).toLocaleUpperCase() + escapedName.slice(1)}Enum`;
+    if (client.enumNames.includes(result)) {
+        return null;
     }
     client.enumNames = [...client.enumNames, result];
     return result;

packages/openapi-ts/src/utils/write/__tests__/core.spec.ts

@@ -4,20 +4,20 @@ import path from 'node:path';
 import { beforeEach, describe, expect, it, vi } from 'vitest';
 
 import { setConfig } from '../../config';
-import { writeClientCore } from '../core';
+import { writeCore } from '../core';
 import { mockTemplates } from './mocks';
 import { openApi } from './models';
 
 vi.mock('node:fs');
 
-describe('writeClientCore', () => {
-    let templates: Parameters<typeof writeClientCore>[3];
+describe('writeCore', () => {
+    let templates: Parameters<typeof writeCore>[3];
     beforeEach(() => {
         templates = mockTemplates;
     });
 
     it('writes to filesystem', async () => {
-        const client: Parameters<typeof writeClientCore>[2] = {
+        const client: Parameters<typeof writeCore>[2] = {
             enumNames: [],
             models: [],
             server: 'http://localhost:8080',
@@ -46,7 +46,7 @@ describe('writeClientCore', () => {
             useOptions: true,
         });
 
-        await writeClientCore(openApi, '/', client, templates);
+        await writeCore(openApi, '/', client, templates);
 
         expect(writeFileSync).toHaveBeenCalledWith(path.resolve('/', '/OpenAPI.ts'), 'settings');
         expect(writeFileSync).toHaveBeenCalledWith(path.resolve('/', '/ApiError.ts'), 'apiError');
@@ -57,7 +57,7 @@ describe('writeClientCore', () => {
     });
 
     it('uses client server value for base', async () => {
-        const client: Parameters<typeof writeClientCore>[2] = {
+        const client: Parameters<typeof writeCore>[2] = {
             enumNames: [],
             models: [],
             server: 'http://localhost:8080',
@@ -86,7 +86,7 @@ describe('writeClientCore', () => {
             useOptions: true,
         });
 
-        await writeClientCore(openApi, '/', client, templates);
+        await writeCore(openApi, '/', client, templates);
 
         expect(templates.core.settings).toHaveBeenCalledWith({
             $config: config,
@@ -97,7 +97,7 @@ describe('writeClientCore', () => {
     });
 
     it('uses custom value for base', async () => {
-        const client: Parameters<typeof writeClientCore>[2] = {
+        const client: Parameters<typeof writeCore>[2] = {
             enumNames: [],
             models: [],
             server: 'http://localhost:8080',
@@ -127,7 +127,7 @@ describe('writeClientCore', () => {
             useOptions: true,
         });
 
-        await writeClientCore(openApi, '/', client, templates);
+        await writeCore(openApi, '/', client, templates);
 
         expect(templates.core.settings).toHaveBeenCalledWith({
             $config: config,

packages/openapi-ts/src/utils/write/__tests__/models.spec.ts

@@ -4,12 +4,12 @@ import path from 'node:path';
 import { describe, expect, it, vi } from 'vitest';
 
 import { setConfig } from '../../config';
-import { writeClientModels } from '../models';
+import { writeTypesAndEnums } from '../models';
 import { openApi } from './models';
 
 vi.mock('node:fs');
 
-describe('writeClientModels', () => {
+describe('writeTypesAndEnums', () => {
     it('writes to filesystem', async () => {
         setConfig({
             client: 'fetch',
@@ -32,7 +32,7 @@ describe('writeClientModels', () => {
             useOptions: true,
         });
 
-        const client: Parameters<typeof writeClientModels>[2] = {
+        const client: Parameters<typeof writeTypesAndEnums>[2] = {
             enumNames: [],
             models: [
                 {
@@ -59,7 +59,7 @@ describe('writeClientModels', () => {
             version: 'v1',
         };
 
-        await writeClientModels(openApi, '/', client);
+        await writeTypesAndEnums(openApi, '/', client);
 
         expect(writeFileSync).toHaveBeenCalledWith(path.resolve('/', '/models.ts'), expect.anything());
     });