zod-codegen 1.4.0 → 1.5.0

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

@@ -21,6 +21,10 @@ export class TypeScriptCodeGeneratorService implements CodeGenerator, SchemaBuil
   private readonly namingConvention: NamingConvention | undefined;
   private readonly operationNameTransformer: OperationNameTransformer | undefined;
 
+  // Track circular dependencies for z.lazy() wrapping
+  private circularSchemas = new Set<string>();
+  private currentSchemaName: string | null = null;
+
   constructor(options: GeneratorOptions = {}) {
     this.namingConvention = options.namingConvention;
     this.operationNameTransformer = options.operationNameTransformer;
@@ -85,12 +89,25 @@ export class TypeScriptCodeGeneratorService implements CodeGenerator, SchemaBuil
 
   private buildSchemas(openapi: OpenApiSpecType): Record<string, ts.VariableStatement> {
     const schemasEntries = Object.entries(openapi.components?.schemas ?? {});
-    const sortedSchemaNames = this.topologicalSort(Object.fromEntries(schemasEntries));
+    const schemasMap = Object.fromEntries(schemasEntries);
+
+    // Detect circular dependencies before building schemas
+    this.circularSchemas = this.detectCircularDependencies(schemasMap);
+
+    const sortedSchemaNames = this.topologicalSort(schemasMap);
 
     return sortedSchemaNames.reduce<Record<string, ts.VariableStatement>>((schemaRegistered, name) => {
       const schema = openapi.components?.schemas?.[name];
       if (!schema) return schemaRegistered;
 
+      // Set context for current schema being built
+      this.currentSchemaName = name;
+
+      const schemaExpression = this.buildSchema(schema);
+
+      // Clear context
+      this.currentSchemaName = null;
+
       const variableStatement = ts.factory.createVariableStatement(
         [ts.factory.createToken(ts.SyntaxKind.ExportKeyword)],
         ts.factory.createVariableDeclarationList(
@@ -99,7 +116,7 @@ export class TypeScriptCodeGeneratorService implements CodeGenerator, SchemaBuil
               ts.factory.createIdentifier(this.typeBuilder.sanitizeIdentifier(name)),
               undefined,
               undefined,
-              this.buildSchema(schema),
+              schemaExpression,
             ),
           ],
           ts.NodeFlags.Const,
@@ -136,7 +153,7 @@ export class TypeScriptCodeGeneratorService implements CodeGenerator, SchemaBuil
     const methods = this.buildClientMethods(openapi, schemas);
 
     return ts.factory.createClassDeclaration(
-      [ts.factory.createToken(ts.SyntaxKind.ExportKeyword)],
+      [ts.factory.createToken(ts.SyntaxKind.ExportKeyword), ts.factory.createToken(ts.SyntaxKind.DefaultKeyword)],
       ts.factory.createIdentifier(clientName),
       undefined,
       undefined,
@@ -275,9 +292,9 @@ export class TypeScriptCodeGeneratorService implements CodeGenerator, SchemaBuil
 
   private buildHttpRequestMethod(): ts.MethodDeclaration {
     return ts.factory.createMethodDeclaration(
-      [ts.factory.createToken(ts.SyntaxKind.AsyncKeyword)],
+      [ts.factory.createToken(ts.SyntaxKind.ProtectedKeyword), ts.factory.createToken(ts.SyntaxKind.AsyncKeyword)],
       undefined,
-      ts.factory.createPrivateIdentifier('#makeRequest'),
+      ts.factory.createIdentifier('makeRequest'),
       undefined,
       [this.typeBuilder.createGenericType('T')],
       [
@@ -1002,10 +1019,7 @@ export class TypeScriptCodeGeneratorService implements CodeGenerator, SchemaBuil
 
     // Call makeRequest
     const makeRequestCall = ts.factory.createCallExpression(
-      ts.factory.createPropertyAccessExpression(
-        ts.factory.createThis(),
-        ts.factory.createPrivateIdentifier('#makeRequest'),
-      ),
+      ts.factory.createPropertyAccessExpression(ts.factory.createThis(), ts.factory.createIdentifier('makeRequest')),
       undefined,
       [ts.factory.createStringLiteral(method.toUpperCase(), true), pathExpression, optionsExpression],
     );
@@ -2691,10 +2705,145 @@ export class TypeScriptCodeGeneratorService implements CodeGenerator, SchemaBuil
     return false;
   }
 
-  private buildFromReference(reference: ReferenceType): ts.Identifier {
+  private buildFromReference(reference: ReferenceType): ts.CallExpression | ts.Identifier {
     const {$ref = ''} = Reference.parse(reference);
     const refName = $ref.split('/').pop() ?? 'never';
-    return ts.factory.createIdentifier(this.typeBuilder.sanitizeIdentifier(refName));
+    const sanitizedRefName = this.typeBuilder.sanitizeIdentifier(refName);
+
+    // Check if this reference creates a circular dependency
+    if (this.isCircularReference(refName)) {
+      // Generate: z.lazy(() => RefSchema)
+      return ts.factory.createCallExpression(
+        ts.factory.createPropertyAccessExpression(
+          ts.factory.createIdentifier('z'),
+          ts.factory.createIdentifier('lazy'),
+        ),
+        undefined,
+        [
+          ts.factory.createArrowFunction(
+            undefined,
+            undefined,
+            [],
+            undefined,
+            ts.factory.createToken(ts.SyntaxKind.EqualsGreaterThanToken),
+            ts.factory.createIdentifier(sanitizedRefName),
+          ),
+        ],
+      );
+    }
+
+    return ts.factory.createIdentifier(sanitizedRefName);
+  }
+
+  /**
+   * Determines if a reference creates a circular dependency that needs z.lazy().
+   * A reference is circular if:
+   * 1. It's a direct self-reference (schema references itself)
+   * 2. It's part of a circular dependency chain (A -> B -> A)
+   */
+  private isCircularReference(refName: string): boolean {
+    // Case 1: Direct self-reference
+    if (refName === this.currentSchemaName) {
+      return true;
+    }
+
+    // Case 2: Reference to a schema that's part of a circular dependency chain
+    // and we're currently building a schema that's also in that chain
+    if (
+      this.circularSchemas.has(refName) &&
+      this.currentSchemaName !== null &&
+      this.circularSchemas.has(this.currentSchemaName)
+    ) {
+      return true;
+    }
+
+    return false;
+  }
+
+  /**
+   * Detects schemas that are part of circular dependency chains.
+   * Uses a modified Tarjan's algorithm to find strongly connected components (SCCs).
+   * Schemas in SCCs with more than one node, or self-referencing schemas, are circular.
+   */
+  private detectCircularDependencies(schemas: Record<string, unknown>): Set<string> {
+    const circularSchemas = new Set<string>();
+
+    // Build dependency graph
+    const graph = new Map<string, string[]>();
+    for (const [name, schema] of Object.entries(schemas)) {
+      const dependencies = jp
+        .query(schema, '$..["$ref"]')
+        .filter((ref: string) => ref.startsWith('#/components/schemas/'))
+        .map((ref: string) => ref.replace('#/components/schemas/', ''))
+        .filter((dep: string) => dep in schemas);
+      graph.set(name, dependencies);
+    }
+
+    // Tarjan's algorithm for finding SCCs
+    let index = 0;
+    const indices = new Map<string, number>();
+    const lowlinks = new Map<string, number>();
+    const onStack = new Set<string>();
+    const stack: string[] = [];
+
+    const strongConnect = (node: string): void => {
+      indices.set(node, index);
+      lowlinks.set(node, index);
+      index++;
+      stack.push(node);
+      onStack.add(node);
+
+      const neighbors = graph.get(node) ?? [];
+      for (const neighbor of neighbors) {
+        if (!indices.has(neighbor)) {
+          strongConnect(neighbor);
+          const currentLowlink = lowlinks.get(node) ?? 0;
+          const neighborLowlink = lowlinks.get(neighbor) ?? 0;
+          lowlinks.set(node, Math.min(currentLowlink, neighborLowlink));
+        } else if (onStack.has(neighbor)) {
+          const currentLowlink = lowlinks.get(node) ?? 0;
+          const neighborIndex = indices.get(neighbor) ?? 0;
+          lowlinks.set(node, Math.min(currentLowlink, neighborIndex));
+        }
+      }
+
+      // If node is a root of an SCC
+      if (lowlinks.get(node) === indices.get(node)) {
+        const scc: string[] = [];
+        let w: string | undefined;
+        do {
+          w = stack.pop();
+          if (w !== undefined) {
+            onStack.delete(w);
+            scc.push(w);
+          }
+        } while (w !== undefined && w !== node);
+
+        // An SCC is circular if it has more than one node
+        // or if it has one node that references itself
+        if (scc.length > 1) {
+          for (const schemaName of scc) {
+            circularSchemas.add(schemaName);
+          }
+        } else if (scc.length === 1) {
+          const schemaName = scc[0];
+          if (schemaName !== undefined) {
+            const deps = graph.get(schemaName) ?? [];
+            if (deps.includes(schemaName)) {
+              circularSchemas.add(schemaName);
+            }
+          }
+        }
+      }
+    };
+
+    for (const node of graph.keys()) {
+      if (!indices.has(node)) {
+        strongConnect(node);
+      }
+    }
+
+    return circularSchemas;
   }
 
   private topologicalSort(schemas: Record<string, unknown>): string[] {

package/tests/unit/code-generator.test.ts

@@ -212,7 +212,7 @@ describe('TypeScriptCodeGeneratorService', () => {
       expect(code).toBeTruthy();
       expect(typeof code).toBe('string');
       expect(code).toMatch(/import\s*{\s*z\s*}\s*from\s*['"]zod['"]/);
-      expect(code).toContain('export class');
+      expect(code).toContain('export default class');
     });
 
     it('should generate schemas for component schemas', () => {
@@ -275,7 +275,7 @@ describe('TypeScriptCodeGeneratorService', () => {
 
       const code = generator.generate(spec);
       expect(code).toContain('async getUsers');
-      expect(code).toContain('#makeRequest');
+      expect(code).toContain('makeRequest');
     });
 
     it('should generate getBaseRequestOptions method', () => {
@@ -408,7 +408,7 @@ describe('TypeScriptCodeGeneratorService', () => {
       expect(code).not.toContain('ExecutionMode: z.enum');
     });
 
-    it('should merge baseOptions with request-specific options in #makeRequest', () => {
+    it('should merge baseOptions with request-specific options in makeRequest', () => {
       const spec: OpenApiSpecType = {
         openapi: '3.0.0',
         info: {
@@ -506,4 +506,200 @@ describe('TypeScriptCodeGeneratorService', () => {
       expect(result).toBeDefined();
     });
   });
+
+  describe('circular dependencies', () => {
+    it('should use z.lazy() for direct self-referencing schemas', () => {
+      const spec: OpenApiSpecType = {
+        openapi: '3.0.0',
+        info: {
+          title: 'Test API',
+          version: '1.0.0',
+        },
+        paths: {},
+        components: {
+          schemas: {
+            TreeNode: {
+              type: 'object',
+              properties: {
+                value: {type: 'string'},
+                children: {
+                  type: 'array',
+                  items: {$ref: '#/components/schemas/TreeNode'},
+                },
+              },
+              required: ['value'],
+            },
+          },
+        },
+      };
+
+      const code = generator.generate(spec);
+      expect(code).toContain('z.lazy(() => TreeNode)');
+    });
+
+    it('should use z.lazy() for indirect circular dependencies (A -> B -> A)', () => {
+      const spec: OpenApiSpecType = {
+        openapi: '3.0.0',
+        info: {
+          title: 'Test API',
+          version: '1.0.0',
+        },
+        paths: {},
+        components: {
+          schemas: {
+            Person: {
+              type: 'object',
+              properties: {
+                name: {type: 'string'},
+                bestFriend: {$ref: '#/components/schemas/Friend'},
+              },
+              required: ['name'],
+            },
+            Friend: {
+              type: 'object',
+              properties: {
+                nickname: {type: 'string'},
+                person: {$ref: '#/components/schemas/Person'},
+              },
+              required: ['nickname'],
+            },
+          },
+        },
+      };
+
+      const code = generator.generate(spec);
+      // Both references should use z.lazy()
+      expect(code).toContain('z.lazy(() => Friend)');
+      expect(code).toContain('z.lazy(() => Person)');
+    });
+
+    it('should not use z.lazy() for non-circular references', () => {
+      const spec: OpenApiSpecType = {
+        openapi: '3.0.0',
+        info: {
+          title: 'Test API',
+          version: '1.0.0',
+        },
+        paths: {},
+        components: {
+          schemas: {
+            User: {
+              type: 'object',
+              properties: {
+                id: {type: 'integer'},
+                profile: {$ref: '#/components/schemas/Profile'},
+              },
+              required: ['id'],
+            },
+            Profile: {
+              type: 'object',
+              properties: {
+                name: {type: 'string'},
+              },
+              required: ['name'],
+            },
+          },
+        },
+      };
+
+      const code = generator.generate(spec);
+      // Profile should be referenced directly, not with z.lazy()
+      expect(code).not.toContain('z.lazy(() => Profile)');
+      expect(code).toContain('profile: Profile.optional()');
+    });
+
+    it('should handle complex circular chains (A -> B -> C -> A)', () => {
+      const spec: OpenApiSpecType = {
+        openapi: '3.0.0',
+        info: {
+          title: 'Test API',
+          version: '1.0.0',
+        },
+        paths: {},
+        components: {
+          schemas: {
+            Alpha: {
+              type: 'object',
+              properties: {
+                beta: {$ref: '#/components/schemas/Beta'},
+              },
+            },
+            Beta: {
+              type: 'object',
+              properties: {
+                gamma: {$ref: '#/components/schemas/Gamma'},
+              },
+            },
+            Gamma: {
+              type: 'object',
+              properties: {
+                alpha: {$ref: '#/components/schemas/Alpha'},
+              },
+            },
+          },
+        },
+      };
+
+      const code = generator.generate(spec);
+      // All references in the cycle should use z.lazy()
+      expect(code).toContain('z.lazy(() => Beta)');
+      expect(code).toContain('z.lazy(() => Gamma)');
+      expect(code).toContain('z.lazy(() => Alpha)');
+    });
+
+    it('should handle self-referencing schemas in arrays', () => {
+      const spec: OpenApiSpecType = {
+        openapi: '3.0.0',
+        info: {
+          title: 'Test API',
+          version: '1.0.0',
+        },
+        paths: {},
+        components: {
+          schemas: {
+            Category: {
+              type: 'object',
+              properties: {
+                name: {type: 'string'},
+                subcategories: {
+                  type: 'array',
+                  items: {$ref: '#/components/schemas/Category'},
+                },
+              },
+              required: ['name'],
+            },
+          },
+        },
+      };
+
+      const code = generator.generate(spec);
+      expect(code).toContain('z.array(z.lazy(() => Category))');
+    });
+
+    it('should handle self-referencing schemas in anyOf', () => {
+      const spec: OpenApiSpecType = {
+        openapi: '3.0.0',
+        info: {
+          title: 'Test API',
+          version: '1.0.0',
+        },
+        paths: {},
+        components: {
+          schemas: {
+            Expression: {
+              type: 'object',
+              properties: {
+                value: {
+                  anyOf: [{type: 'string'}, {$ref: '#/components/schemas/Expression'}],
+                },
+              },
+            },
+          },
+        },
+      };
+
+      const code = generator.generate(spec);
+      expect(code).toContain('z.lazy(() => Expression)');
+    });
+  });
 });

package/tests/unit/generator.test.ts

@@ -68,7 +68,7 @@ describe('Generator', () => {
       // Verify file contains expected content
       const content = readFileSync(outputFile, 'utf-8');
       expect(content).toMatch(/import\s*{\s*z\s*}\s*from\s*['"]zod['"]/);
-      expect(content).toContain('export class');
+      expect(content).toContain('export default class');
       expect(content).toContain('getBaseRequestOptions');
     });
 
@@ -109,7 +109,7 @@ describe('Generator', () => {
       expect(content).toMatch(/import\s*{\s*z\s*}\s*from\s*['"]zod['"]/);
       expect(content).toContain('export const');
       expect(content).toContain('protected getBaseRequestOptions');
-      expect(content).toContain('async #makeRequest');
+      expect(content).toContain('protected async makeRequest');
     });
 
     it('should include header comments in generated file', async () => {

package/tsconfig.json

@@ -41,6 +41,6 @@
     "useUnknownInCatchVariables": true,
     "verbatimModuleSyntax": true
   },
-  "exclude": ["node_modules", "dist", "build", "examples/**/*.ts"],
+  "exclude": ["node_modules", "dist", "build", "examples/**/*.ts", "tests/**/*.ts", "scripts/**/*.ts"],
   "include": ["src/**/*.ts", "scripts/**/*.ts", "tests/**/*.ts", "vitest.config.ts"]
 }

package/.claude/settings.local.json

@@ -1,43 +0,0 @@
-{
-  "permissions": {
-    "allow": [
-      "Bash(npm install:*)",
-      "Bash(npm uninstall:*)",
-      "Bash(npm run type-check:*)",
-      "Bash(npm run build:*)",
-      "Bash(./dist/src/cli.js --help)",
-      "Bash(./dist/src/cli.js --version)",
-      "Bash(npm run dev:*)",
-      "Bash(node:*)",
-      "Bash(npm run lint)",
-      "Bash(npx husky init:*)",
-      "Bash(chmod:*)",
-      "Bash(npm run validate:*)",
-      "Bash(npm run format:*)",
-      "Bash(npm run test:*)",
-      "Bash(npm test)",
-      "Bash(npm audit:*)",
-      "Bash(npx depcheck:*)",
-      "Bash(npm outdated)",
-      "Bash(npm update:*)",
-      "WebSearch",
-      "Bash(find:*)",
-      "Bash(npx zod-codegen:*)",
-      "Bash(DEBUG=1 node ./dist/src/cli.js --input ./samples/openapi.json --output ./test-generated)",
-      "Bash(rm:*)",
-      "Bash(npm outdated:*)",
-      "Bash(npm view:*)",
-      "Bash(git tag:*)",
-      "Bash(npm run release:*)",
-      "Bash(git log:*)",
-      "Bash(npx commitlint:*)",
-      "Bash(git rev-list:*)",
-      "Bash(./fix-commit-messages.sh:*)",
-      "Bash(git add:*)",
-      "Bash(git commit:*)",
-      "Bash(FILTER_BRANCH_SQUELCH_WARNING=1 ./fix-commit-messages.sh)"
-    ],
-    "deny": [],
-    "ask": []
-  }
-}

package/dist/scripts/update-manifest.d.ts

@@ -1,14 +0,0 @@
-interface PackageJson {
-    name: string;
-    version: string;
-    description: string;
-}
-/**
- * Type guard for the package.json object
- *
- * @param input Unknown input
- * @returns true if the input is an event object
- */
-export declare function isPackageJson(input: unknown): input is PackageJson;
-export {};
-//# sourceMappingURL=update-manifest.d.ts.map

package/dist/scripts/update-manifest.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"update-manifest.d.ts","sourceRoot":"","sources":["../../scripts/update-manifest.ts"],"names":[],"mappings":"AAIA,UAAU,WAAW;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,WAAW,CAclE"}

package/dist/scripts/update-manifest.js

@@ -1,31 +0,0 @@
-import { readFileSync, writeFileSync } from 'fs';
-import { resolve } from 'path';
-import { z } from 'zod';
-/**
- * Type guard for the package.json object
- *
- * @param input Unknown input
- * @returns true if the input is an event object
- */
-export function isPackageJson(input) {
-    const event = z
-        .object({
-        name: z.string(),
-        version: z.string(),
-        description: z.string(),
-    })
-        .strict()
-        .catchall(z.any())
-        .required();
-    const { success } = event.safeParse(input);
-    return success;
-}
-const sourcePath = resolve(__dirname, '..', 'package.json');
-const data = JSON.parse(readFileSync(sourcePath, 'utf8'));
-if (!isPackageJson(data)) {
-    process.exit(1);
-}
-const { name, version, description } = data;
-const targetPath = resolve(__dirname, '..', 'src', 'assets', 'manifest.json');
-writeFileSync(targetPath, JSON.stringify({ name, version, description }, null, 2));
-process.exit(0);

package/dist/tests/integration/cli.test.d.ts

@@ -1,2 +0,0 @@
-export {};
-//# sourceMappingURL=cli.test.d.ts.map

package/dist/tests/integration/cli.test.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"cli.test.d.ts","sourceRoot":"","sources":["../../../tests/integration/cli.test.ts"],"names":[],"mappings":""}

package/dist/tests/integration/cli.test.js

@@ -1,25 +0,0 @@
-import { describe, expect, it } from 'vitest';
-import { execSync } from 'node:child_process';
-import { resolve } from 'node:path';
-describe('CLI Integration', () => {
-    describe('--help', () => {
-        it('should display help information', () => {
-            const result = execSync('npm run build && node ./dist/src/cli.js --help', {
-                encoding: 'utf-8',
-                cwd: resolve(__dirname, '../..'),
-            });
-            expect(result).toContain('Usage:');
-            expect(result).toContain('--input');
-            expect(result).toContain('--output');
-        });
-    });
-    describe('--version', () => {
-        it('should display version information', () => {
-            const result = execSync('npm run build && node ./dist/src/cli.js --version', {
-                encoding: 'utf-8',
-                cwd: resolve(__dirname, '../..'),
-            });
-            expect(result).toMatch(/\d+\.\d+\.\d+/);
-        });
-    });
-});

package/dist/tests/unit/code-generator.test.d.ts

@@ -1,2 +0,0 @@
-export {};
-//# sourceMappingURL=code-generator.test.d.ts.map

package/dist/tests/unit/code-generator.test.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"code-generator.test.d.ts","sourceRoot":"","sources":["../../../tests/unit/code-generator.test.ts"],"names":[],"mappings":""}