zod-codegen 1.3.0 → 1.4.0

package/dist/tests/unit/naming-convention.test.js

@@ -0,0 +1,231 @@
+import { describe, expect, it } from 'vitest';
+import { transformNamingConvention } from '../../src/utils/naming-convention.js';
+describe('transformNamingConvention', () => {
+    describe('transform', () => {
+        const testCases = [
+            // camelCase
+            {
+                input: 'get_user_by_id',
+                convention: 'camelCase',
+                expected: 'getUserById',
+                description: 'should convert snake_case to camelCase',
+            },
+            {
+                input: 'GetUserById',
+                convention: 'camelCase',
+                expected: 'getUserById',
+                description: 'should convert PascalCase to camelCase',
+            },
+            {
+                input: 'get-user-by-id',
+                convention: 'camelCase',
+                expected: 'getUserById',
+                description: 'should convert kebab-case to camelCase',
+            },
+            {
+                input: 'getUserById',
+                convention: 'camelCase',
+                expected: 'getUserById',
+                description: 'should keep camelCase as camelCase',
+            },
+            // PascalCase
+            {
+                input: 'get_user_by_id',
+                convention: 'PascalCase',
+                expected: 'GetUserById',
+                description: 'should convert snake_case to PascalCase',
+            },
+            {
+                input: 'get-user-by-id',
+                convention: 'PascalCase',
+                expected: 'GetUserById',
+                description: 'should convert kebab-case to PascalCase',
+            },
+            {
+                input: 'getUserById',
+                convention: 'PascalCase',
+                expected: 'GetUserById',
+                description: 'should convert camelCase to PascalCase',
+            },
+            // snake_case
+            {
+                input: 'getUserById',
+                convention: 'snake_case',
+                expected: 'get_user_by_id',
+                description: 'should convert camelCase to snake_case',
+            },
+            {
+                input: 'GetUserById',
+                convention: 'snake_case',
+                expected: 'get_user_by_id',
+                description: 'should convert PascalCase to snake_case',
+            },
+            {
+                input: 'get-user-by-id',
+                convention: 'snake_case',
+                expected: 'get_user_by_id',
+                description: 'should convert kebab-case to snake_case',
+            },
+            // kebab-case
+            {
+                input: 'getUserById',
+                convention: 'kebab-case',
+                expected: 'get-user-by-id',
+                description: 'should convert camelCase to kebab-case',
+            },
+            {
+                input: 'GetUserById',
+                convention: 'kebab-case',
+                expected: 'get-user-by-id',
+                description: 'should convert PascalCase to kebab-case',
+            },
+            {
+                input: 'get_user_by_id',
+                convention: 'kebab-case',
+                expected: 'get-user-by-id',
+                description: 'should convert snake_case to kebab-case',
+            },
+            // SCREAMING_SNAKE_CASE
+            {
+                input: 'getUserById',
+                convention: 'SCREAMING_SNAKE_CASE',
+                expected: 'GET_USER_BY_ID',
+                description: 'should convert camelCase to SCREAMING_SNAKE_CASE',
+            },
+            {
+                input: 'get-user-by-id',
+                convention: 'SCREAMING_SNAKE_CASE',
+                expected: 'GET_USER_BY_ID',
+                description: 'should convert kebab-case to SCREAMING_SNAKE_CASE',
+            },
+            // SCREAMING-KEBAB-CASE
+            {
+                input: 'getUserById',
+                convention: 'SCREAMING-KEBAB-CASE',
+                expected: 'GET-USER-BY-ID',
+                description: 'should convert camelCase to SCREAMING-KEBAB-CASE',
+            },
+            {
+                input: 'get_user_by_id',
+                convention: 'SCREAMING-KEBAB-CASE',
+                expected: 'GET-USER-BY-ID',
+                description: 'should convert snake_case to SCREAMING-KEBAB-CASE',
+            },
+            // Edge cases
+            {
+                input: '',
+                convention: 'camelCase',
+                expected: '',
+                description: 'should handle empty string',
+            },
+            {
+                input: 'a',
+                convention: 'camelCase',
+                expected: 'a',
+                description: 'should handle single character',
+            },
+            {
+                input: 'API',
+                convention: 'camelCase',
+                expected: 'aPI',
+                description: 'should handle all uppercase (splits at uppercase boundaries)',
+            },
+            {
+                input: 'getUser123ById',
+                convention: 'snake_case',
+                expected: 'get_user_123_by_id',
+                description: 'should handle numbers in identifiers (splits at digit boundaries)',
+            },
+        ];
+        testCases.forEach(({ input, convention, expected, description }) => {
+            it(description, () => {
+                const result = transformNamingConvention(input, convention);
+                expect(result).toBe(expected);
+            });
+        });
+    });
+    describe('edge cases', () => {
+        describe('consecutive delimiters', () => {
+            it('should handle consecutive underscores', () => {
+                expect(transformNamingConvention('get__user__by__id', 'camelCase')).toBe('getUserById');
+            });
+            it('should handle consecutive hyphens', () => {
+                expect(transformNamingConvention('get--user--by--id', 'snake_case')).toBe('get_user_by_id');
+            });
+            it('should handle mixed consecutive delimiters', () => {
+                expect(transformNamingConvention('get__user--by_id', 'kebab-case')).toBe('get-user-by-id');
+            });
+        });
+        describe('mixed delimiters', () => {
+            it('should handle snake_case and kebab-case mixed', () => {
+                // Note: Delimiters split the string, so 'byId' becomes 'by' and 'id' (normalized to lowercase)
+                expect(transformNamingConvention('get_user-byId', 'camelCase')).toBe('getUserByid');
+            });
+            it('should handle camelCase with underscores', () => {
+                // Note: Underscore delimiter splits, so 'byId' becomes 'by' and 'id'
+                expect(transformNamingConvention('getUser_byId', 'PascalCase')).toBe('GetuserByid');
+            });
+            it('should handle dots as delimiters', () => {
+                expect(transformNamingConvention('get.user.by.id', 'snake_case')).toBe('get_user_by_id');
+            });
+            it('should handle spaces as delimiters', () => {
+                expect(transformNamingConvention('get user by id', 'kebab-case')).toBe('get-user-by-id');
+            });
+        });
+        describe('unicode and special characters', () => {
+            it('should handle accented characters', () => {
+                expect(transformNamingConvention('getRésumé', 'snake_case')).toBe('get_résumé');
+            });
+            it('should handle numbers at start', () => {
+                expect(transformNamingConvention('123getUser', 'camelCase')).toBe('123getUser');
+            });
+            it('should handle single uppercase letter', () => {
+                expect(transformNamingConvention('getX', 'snake_case')).toBe('get_x');
+            });
+            it('should handle all numbers', () => {
+                expect(transformNamingConvention('123456', 'camelCase')).toBe('123456');
+            });
+        });
+        describe('acronyms and abbreviations', () => {
+            it('should handle acronyms in camelCase (splits on uppercase boundaries)', () => {
+                // Note: Algorithm splits on uppercase boundaries, so 'XML' becomes 'X', 'M', 'L'
+                // This is correct behavior - detecting acronyms would require a dictionary
+                expect(transformNamingConvention('getXMLData', 'snake_case')).toBe('get_x_m_l_data');
+            });
+            it('should handle multiple acronyms (splits on uppercase boundaries)', () => {
+                // Note: 'JSON' and 'XML' are split into individual letters
+                // 'parseJSONToXML' → ['parse', 'j', 's', 'o', 'n', 'to', 'x', 'm', 'l']
+                expect(transformNamingConvention('parseJSONToXML', 'kebab-case')).toBe('parse-j-s-o-n-to-x-m-l');
+            });
+            it('should handle ID abbreviation (splits on uppercase boundaries)', () => {
+                // Note: 'ID' is split into 'I' and 'D' because the algorithm splits on uppercase boundaries
+                // This is correct behavior - detecting acronyms would require a dictionary
+                expect(transformNamingConvention('getUserID', 'snake_case')).toBe('get_user_i_d');
+            });
+        });
+        describe('already transformed names', () => {
+            it('should be idempotent for camelCase', () => {
+                const input = 'getUserById';
+                const result = transformNamingConvention(input, 'camelCase');
+                expect(transformNamingConvention(result, 'camelCase')).toBe(result);
+            });
+            it('should be idempotent for snake_case', () => {
+                const input = 'get_user_by_id';
+                const result = transformNamingConvention(input, 'snake_case');
+                expect(transformNamingConvention(result, 'snake_case')).toBe(result);
+            });
+        });
+        describe('special patterns', () => {
+            it('should handle single word', () => {
+                expect(transformNamingConvention('user', 'PascalCase')).toBe('User');
+            });
+            it('should handle two words', () => {
+                expect(transformNamingConvention('getUser', 'snake_case')).toBe('get_user');
+            });
+            it('should handle very long names', () => {
+                const longName = 'getVeryLongOperationNameWithManyWords';
+                expect(transformNamingConvention(longName, 'kebab-case')).toBe('get-very-long-operation-name-with-many-words');
+            });
+        });
+    });
+});

package/dist/vitest.config.d.ts

@@ -0,0 +1,3 @@
+declare const _default: import("vite").UserConfig;
+export default _default;
+//# sourceMappingURL=vitest.config.d.ts.map

package/dist/vitest.config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vitest.config.d.ts","sourceRoot":"","sources":["../vitest.config.ts"],"names":[],"mappings":";AAGA,wBAmCG"}

package/package.json

@@ -45,7 +45,7 @@
     "@types/jsonpath": "^0.2.4",
     "@types/node": "^24.10.1",
     "@types/yargs": "^17.0.35",
-    "@vitest/coverage-v8": "^4.0.13",
+    "@vitest/coverage-v8": "^4.0.14",
     "eslint": "^9.39.1",
     "eslint-config-prettier": "^10.1.8",
     "husky": "^9.1.7",
@@ -54,16 +54,17 @@
     "ts-node": "^10.9.2",
     "typescript-eslint": "^8.46.4",
     "undici": "^7.16.0",
-    "vitest": "^4.0.13",
+    "vitest": "^4.0.14",
     "yarn-audit-fix": "^10.1.1"
   },
   "optionalDependencies": {
     "undici": "^7.16.0"
   },
   "homepage": "https://github.com/julienandreu/zod-codegen",
-  "license": "MIT",
+  "license": "Apache-2.0",
   "name": "zod-codegen",
   "type": "module",
+  "types": "./dist/src/generator.d.ts",
   "exports": {
     ".": {
       "types": "./dist/src/generator.d.ts",
@@ -84,7 +85,11 @@
       "tar": "^7.5.2"
     },
     "glob": "^11.1.0",
-    "tar": "^7.5.2"
+    "tar": "^7.5.2",
+    "yargs": "^18.0.0"
+  },
+  "resolutions": {
+    "yargs": "^18.0.0"
   },
   "scripts": {
     "audit:fix": "yarn-audit-fix",
@@ -110,5 +115,5 @@
     "release": "semantic-release",
     "release:dry": "semantic-release --dry-run"
   },
-  "version": "1.3.0"
+  "version": "1.4.0"
 }

package/src/cli.ts

@@ -2,7 +2,7 @@
 
 import yargs from 'yargs';
 import {hideBin} from 'yargs/helpers';
-import {Generator} from './generator.js';
+import {Generator, type GeneratorOptions, type NamingConvention} from './generator.js';
 import {readFileSync} from 'node:fs';
 import {fileURLToPath} from 'node:url';
 import {dirname, join} from 'node:path';
@@ -72,15 +72,46 @@ const argv = yargs(hideBin(process.argv))
     description: 'Directory to output the generated files',
     default: 'generated',
   })
+  .option('naming-convention', {
+    alias: 'n',
+    type: 'string',
+    description: 'Naming convention to apply to operation IDs',
+    choices: ['camelCase', 'PascalCase', 'snake_case', 'kebab-case', 'SCREAMING_SNAKE_CASE', 'SCREAMING-KEBAB-CASE'],
+    default: undefined,
+  })
   .strict()
   .help()
   .parseSync();
 
-const {input, output} = argv;
+const {input, output, namingConvention} = argv;
+
+/**
+ * Type guard to validate that a string is a valid naming convention.
+ * This ensures type safety when parsing CLI arguments.
+ *
+ * @param value - The value to check
+ * @returns True if the value is a valid NamingConvention
+ */
+function isValidNamingConvention(value: string | undefined): value is NamingConvention {
+  if (value === undefined) {
+    return false;
+  }
+  const validConventions: readonly NamingConvention[] = [
+    'camelCase',
+    'PascalCase',
+    'snake_case',
+    'kebab-case',
+    'SCREAMING_SNAKE_CASE',
+    'SCREAMING-KEBAB-CASE',
+  ] as const;
+  return validConventions.includes(value as NamingConvention);
+}
 
 void (async () => {
   try {
-    const generator = new Generator(name, version, reporter, input, output);
+    const options: GeneratorOptions = isValidNamingConvention(namingConvention) ? {namingConvention} : {};
+
+    const generator = new Generator(name, version, reporter, input, output, options);
     const exitCode = await generator.run();
     process.exit(exitCode);
   } catch (error) {

package/src/generator.ts

@@ -1,13 +1,18 @@
 import type {Reporter} from './utils/reporter.js';
 import type {OpenApiSpecType} from './types/openapi.js';
+import type {GeneratorOptions} from './types/generator-options.js';
 import {OpenApiFileParserService, SyncFileReaderService} from './services/file-reader.service.js';
 import {TypeScriptCodeGeneratorService} from './services/code-generator.service.js';
 import {SyncFileWriterService} from './services/file-writer.service.js';
 
+// Re-export types for library users
+export type {GeneratorOptions} from './types/generator-options.js';
+export type {NamingConvention, OperationDetails, OperationNameTransformer} from './utils/naming-convention.js';
+
 export class Generator {
   private readonly fileReader = new SyncFileReaderService();
   private readonly fileParser = new OpenApiFileParserService();
-  private readonly codeGenerator = new TypeScriptCodeGeneratorService();
+  private readonly codeGenerator: TypeScriptCodeGeneratorService;
   private readonly fileWriter: SyncFileWriterService;
   private readonly outputPath: string;
 
@@ -17,9 +22,11 @@ export class Generator {
     private readonly reporter: Reporter,
     private readonly inputPath: string,
     private readonly _outputDir: string,
+    options: GeneratorOptions = {},
   ) {
     this.fileWriter = new SyncFileWriterService(this._name, this._version, inputPath);
     this.outputPath = this.fileWriter.resolveOutputPath(this._outputDir);
+    this.codeGenerator = new TypeScriptCodeGeneratorService(options);
   }
 
   async run(): Promise<number> {

package/src/services/code-generator.service.ts

@@ -3,14 +3,28 @@ import * as ts from 'typescript';
 import {z} from 'zod';
 import type {CodeGenerator, SchemaBuilder} from '../interfaces/code-generator.js';
 import type {MethodSchemaType, OpenApiSpecType, ReferenceType} from '../types/openapi.js';
+import type {GeneratorOptions} from '../types/generator-options.js';
 import {MethodSchema, Reference, SchemaProperties} from '../types/openapi.js';
 import {TypeScriptImportBuilderService} from './import-builder.service.js';
 import {TypeScriptTypeBuilderService} from './type-builder.service.js';
+import {
+  type NamingConvention,
+  type OperationDetails,
+  type OperationNameTransformer,
+  transformNamingConvention,
+} from '../utils/naming-convention.js';
 
 export class TypeScriptCodeGeneratorService implements CodeGenerator, SchemaBuilder {
   private readonly typeBuilder = new TypeScriptTypeBuilderService();
   private readonly importBuilder = new TypeScriptImportBuilderService();
   private readonly printer = ts.createPrinter({newLine: ts.NewLineKind.LineFeed});
+  private readonly namingConvention: NamingConvention | undefined;
+  private readonly operationNameTransformer: OperationNameTransformer | undefined;
+
+  constructor(options: GeneratorOptions = {}) {
+    this.namingConvention = options.namingConvention;
+    this.operationNameTransformer = options.operationNameTransformer;
+  }
 
   private readonly ZodAST = z.object({
     type: z.enum(['string', 'number', 'boolean', 'object', 'array', 'unknown', 'record']),
@@ -894,6 +908,36 @@ export class TypeScriptCodeGeneratorService implements CodeGenerator, SchemaBuil
     }, []);
   }
 
+  /**
+   * Transforms operation ID according to the configured naming convention or transformer
+   * Ensures the result is a valid TypeScript identifier
+   */
+  private transformOperationName(operationId: string, method: string, path: string, schema: MethodSchemaType): string {
+    let transformed: string;
+
+    // Custom transformer takes precedence
+    if (this.operationNameTransformer) {
+      const details: OperationDetails = {
+        operationId,
+        method,
+        path,
+        ...(schema.tags !== undefined && {tags: schema.tags}),
+        ...(schema.summary !== undefined && {summary: schema.summary}),
+        ...(schema.description !== undefined && {description: schema.description}),
+      };
+      transformed = this.operationNameTransformer(details);
+    } else if (this.namingConvention) {
+      // Apply naming convention if specified
+      transformed = transformNamingConvention(operationId, this.namingConvention);
+    } else {
+      // Return original operationId if no transformation is configured
+      transformed = operationId;
+    }
+
+    // Sanitize to ensure valid TypeScript identifier (handles edge cases from custom transformers)
+    return this.typeBuilder.sanitizeIdentifier(transformed);
+  }
+
   private buildEndpointMethod(
     method: string,
     path: string,
@@ -979,10 +1023,12 @@ export class TypeScriptCodeGeneratorService implements CodeGenerator, SchemaBuil
       statements.push(ts.factory.createReturnStatement(ts.factory.createAwaitExpression(makeRequestCall)));
     }
 
+    const transformedOperationId = this.transformOperationName(String(schema.operationId), method, path, schema);
+
     const methodDeclaration = ts.factory.createMethodDeclaration(
       [ts.factory.createToken(ts.SyntaxKind.AsyncKeyword)],
       undefined,
-      ts.factory.createIdentifier(String(schema.operationId)),
+      ts.factory.createIdentifier(transformedOperationId),
       undefined,
       undefined,
       parameters,

package/src/types/generator-options.ts

@@ -0,0 +1,60 @@
+import type {NamingConvention, OperationNameTransformer} from '../utils/naming-convention.js';
+
+/**
+ * Configuration options for the Generator class.
+ *
+ * These options control how operation IDs are transformed during code generation.
+ * You can either use a predefined naming convention or provide a custom transformer function.
+ *
+ * @example
+ * ```typescript
+ * // Using a naming convention
+ * const generator = new Generator(..., {
+ *   namingConvention: 'camelCase'
+ * });
+ *
+ * // Using a custom transformer
+ * const generator = new Generator(..., {
+ *   operationNameTransformer: (details) => {
+ *     return `${details.method}_${details.operationId}`;
+ *   }
+ * });
+ * ```
+ */
+export interface GeneratorOptions {
+  /**
+   * Naming convention to apply to operation IDs.
+   *
+   * If provided, all operation IDs will be transformed according to the specified convention.
+   * This is useful when OpenAPI specs have inconsistent or poorly named operation IDs.
+   *
+   * **Note:** If `operationNameTransformer` is also provided, it takes precedence.
+   *
+   * @example
+   * ```typescript
+   * { namingConvention: 'camelCase' } // Transforms 'get_user_by_id' → 'getUserById'
+   * ```
+   */
+  namingConvention?: NamingConvention;
+
+  /**
+   * Custom transformer function for operation names.
+   *
+   * If provided, this function will be called for each operation with full operation details.
+   * This allows for advanced customization based on HTTP method, path, tags, etc.
+   *
+   * **Note:** This takes precedence over `namingConvention` if both are provided.
+   * The returned name will be sanitized to ensure it's a valid TypeScript identifier.
+   *
+   * @example
+   * ```typescript
+   * {
+   *   operationNameTransformer: (details) => {
+   *     const tag = details.tags?.[0] || 'default';
+   *     return `${details.method.toUpperCase()}_${tag}_${details.operationId}`;
+   *   }
+   * }
+   * ```
+   */
+  operationNameTransformer?: OperationNameTransformer;
+}

package/src/utils/error-handler.ts

@@ -7,7 +7,7 @@ export const errorReceived = (process: NodeJS.Process, startTime: bigint) => ():
 
 export const handleErrors = (process: NodeJS.Process, startTime: bigint): void => {
   const catchErrors: string[] = ['unhandledRejection', 'uncaughtException'];
-  catchErrors.map((event): NodeJS.EventEmitter => {
-    return process.on(event, errorReceived(process, startTime));
+  catchErrors.forEach((event) => {
+    process.on(event, errorReceived(process, startTime));
   });
 };