zod-codegen 1.4.1 → 1.5.0

package/.github/workflows/ci.yml

@@ -107,7 +107,7 @@ jobs:
           test -e "generated/type.ts"
 
       - name: Upload build artifacts
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v6
         with:
           name: build-${{ github.sha }}
           path: dist/

package/CHANGELOG.md

@@ -1,3 +1,18 @@
+## 1.5.0 (2025-12-22)
+
+- Merge pull request #44 from julienandreu/dependabot/github_actions/actions/upload-artifact-6 ([cebfd55](https://github.com/julienandreu/zod-codegen/commit/cebfd55)), closes [#44](https://github.com/julienandreu/zod-codegen/issues/44)
+- Merge pull request #45 from julienandreu/dependabot/npm_and_yarn/dev-dependencies-ab633d47b1 ([8663f40](https://github.com/julienandreu/zod-codegen/commit/8663f40)), closes [#45](https://github.com/julienandreu/zod-codegen/issues/45)
+- Merge pull request #46 from julienandreu/dependabot/npm_and_yarn/production-dependencies-eefc12583a ([eac5279](https://github.com/julienandreu/zod-codegen/commit/eac5279)), closes [#46](https://github.com/julienandreu/zod-codegen/issues/46)
+- Merge pull request #47 from julienandreu/dependabot/npm_and_yarn/types/node-25.0.2 ([687ce64](https://github.com/julienandreu/zod-codegen/commit/687ce64)), closes [#47](https://github.com/julienandreu/zod-codegen/issues/47)
+- Merge pull request #49 from julienandreu/dependabot/npm_and_yarn/production-dependencies-5419ff3310 ([1d6485c](https://github.com/julienandreu/zod-codegen/commit/1d6485c)), closes [#49](https://github.com/julienandreu/zod-codegen/issues/49)
+- Merge pull request #50 from julienandreu/feat/circular-dependency-detection ([527cbb6](https://github.com/julienandreu/zod-codegen/commit/527cbb6)), closes [#50](https://github.com/julienandreu/zod-codegen/issues/50)
+- feat: detect circular dependencies and wrap with z.lazy() ([4f5f545](https://github.com/julienandreu/zod-codegen/commit/4f5f545))
+- chore(deps-dev): bump @types/node from 24.10.1 to 25.0.2 ([da9bbc7](https://github.com/julienandreu/zod-codegen/commit/da9bbc7))
+- chore(deps-dev): bump the dev-dependencies group with 2 updates ([29ad3ef](https://github.com/julienandreu/zod-codegen/commit/29ad3ef))
+- chore(deps): bump zod in the production-dependencies group ([391d6ea](https://github.com/julienandreu/zod-codegen/commit/391d6ea))
+- chore(deps): bump zod in the production-dependencies group ([41177c8](https://github.com/julienandreu/zod-codegen/commit/41177c8))
+- ci(deps): bump actions/upload-artifact from 4 to 6 ([c19e254](https://github.com/julienandreu/zod-codegen/commit/c19e254))
+
 ## <small>1.4.1 (2025-12-08)</small>
 
 - Merge branch 'refactor/build-config-and-class-exports' of github.com:julienandreu/zod-codegen into r ([bdd9bc5](https://github.com/julienandreu/zod-codegen/commit/bdd9bc5))

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

@@ -8,6 +8,8 @@ export declare class TypeScriptCodeGeneratorService implements CodeGenerator, Sc
     private readonly printer;
     private readonly namingConvention;
     private readonly operationNameTransformer;
+    private circularSchemas;
+    private currentSchemaName;
     constructor(options?: GeneratorOptions);
     private readonly ZodAST;
     generate(spec: OpenApiSpecType): string;
@@ -52,6 +54,19 @@ export declare class TypeScriptCodeGeneratorService implements CodeGenerator, Sc
     private buildArrayTypeFromSchema;
     private isReference;
     private buildFromReference;
+    /**
+     * 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;
+    /**
+     * 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;
     private topologicalSort;
 }
 //# sourceMappingURL=code-generator.service.d.ts.map

package/dist/src/services/code-generator.service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"code-generator.service.d.ts","sourceRoot":"","sources":["../../../src/services/code-generator.service.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,MAAM,YAAY,CAAC;AAEjC,OAAO,KAAK,EAAC,aAAa,EAAE,aAAa,EAAC,MAAM,iCAAiC,CAAC;AAClF,OAAO,KAAK,EAAmB,eAAe,EAAgB,MAAM,qBAAqB,CAAC;AAC1F,OAAO,KAAK,EAAC,gBAAgB,EAAC,MAAM,+BAA+B,CAAC;AAWpE,qBAAa,8BAA+B,YAAW,aAAa,EAAE,aAAa;IACjF,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAsC;IAClE,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAwC;IACtE,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAwD;IAChF,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAA+B;IAChE,OAAO,CAAC,QAAQ,CAAC,wBAAwB,CAAuC;gBAEpE,OAAO,GAAE,gBAAqB;IAK1C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAGpB;IAEH,QAAQ,CAAC,IAAI,EAAE,eAAe,GAAG,MAAM;IAMvC,WAAW,CAAC,MAAM,EAAE,OAAO,EAAE,QAAQ,UAAO,GAAG,EAAE,CAAC,cAAc,GAAG,EAAE,CAAC,UAAU;IA2BhF,OAAO,CAAC,QAAQ;IAmBhB,OAAO,CAAC,YAAY;IA8BpB,OAAO,CAAC,sBAAsB;IAe9B,OAAO,CAAC,gBAAgB;IAsBxB,OAAO,CAAC,gBAAgB;IAmGxB,OAAO,CAAC,gCAAgC;IAwBxC,OAAO,CAAC,sBAAsB;IAqmB9B,OAAO,CAAC,kBAAkB;IAsB1B;;;OAGG;IACH,OAAO,CAAC,sBAAsB;IA0B9B,OAAO,CAAC,mBAAmB;IAgH3B,OAAO,CAAC,mBAAmB;IA6D3B,OAAO,CAAC,qBAAqB;IAwF7B,OAAO,CAAC,gBAAgB;IA0CxB,OAAO,CAAC,iBAAiB;IAmCzB,OAAO,CAAC,iBAAiB;IA8BzB,OAAO,CAAC,eAAe;IAuDvB,OAAO,CAAC,wBAAwB;IA4IhC,OAAO,CAAC,gBAAgB;IAqBxB,OAAO,CAAC,6BAA6B;IAkPrC,OAAO,CAAC,kBAAkB;IAO1B,OAAO,CAAC,aAAa;IAMrB;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAuFzB,OAAO,CAAC,WAAW;IA0CnB,OAAO,CAAC,aAAa;IAmjBrB,OAAO,CAAC,iBAAiB;IAuCzB,OAAO,CAAC,qBAAqB;IAe7B,OAAO,CAAC,oBAAoB;IAyE5B,OAAO,CAAC,8BAA8B;IActC,OAAO,CAAC,wBAAwB;IAyBhC,OAAO,CAAC,yBAAyB;IA8BjC,OAAO,CAAC,wBAAwB;IAYhC,OAAO,CAAC,WAAW;IAQnB,OAAO,CAAC,kBAAkB;IAM1B,OAAO,CAAC,eAAe;CAuCxB"}
+{"version":3,"file":"code-generator.service.d.ts","sourceRoot":"","sources":["../../../src/services/code-generator.service.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,MAAM,YAAY,CAAC;AAEjC,OAAO,KAAK,EAAC,aAAa,EAAE,aAAa,EAAC,MAAM,iCAAiC,CAAC;AAClF,OAAO,KAAK,EAAmB,eAAe,EAAgB,MAAM,qBAAqB,CAAC;AAC1F,OAAO,KAAK,EAAC,gBAAgB,EAAC,MAAM,+BAA+B,CAAC;AAWpE,qBAAa,8BAA+B,YAAW,aAAa,EAAE,aAAa;IACjF,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAsC;IAClE,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAwC;IACtE,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAwD;IAChF,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAA+B;IAChE,OAAO,CAAC,QAAQ,CAAC,wBAAwB,CAAuC;IAGhF,OAAO,CAAC,eAAe,CAAqB;IAC5C,OAAO,CAAC,iBAAiB,CAAuB;gBAEpC,OAAO,GAAE,gBAAqB;IAK1C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAGpB;IAEH,QAAQ,CAAC,IAAI,EAAE,eAAe,GAAG,MAAM;IAMvC,WAAW,CAAC,MAAM,EAAE,OAAO,EAAE,QAAQ,UAAO,GAAG,EAAE,CAAC,cAAc,GAAG,EAAE,CAAC,UAAU;IA2BhF,OAAO,CAAC,QAAQ;IAmBhB,OAAO,CAAC,YAAY;IA2CpB,OAAO,CAAC,sBAAsB;IAe9B,OAAO,CAAC,gBAAgB;IAsBxB,OAAO,CAAC,gBAAgB;IAmGxB,OAAO,CAAC,gCAAgC;IAwBxC,OAAO,CAAC,sBAAsB;IAqmB9B,OAAO,CAAC,kBAAkB;IAsB1B;;;OAGG;IACH,OAAO,CAAC,sBAAsB;IA0B9B,OAAO,CAAC,mBAAmB;IAgH3B,OAAO,CAAC,mBAAmB;IA6D3B,OAAO,CAAC,qBAAqB;IAwF7B,OAAO,CAAC,gBAAgB;IA0CxB,OAAO,CAAC,iBAAiB;IAmCzB,OAAO,CAAC,iBAAiB;IA8BzB,OAAO,CAAC,eAAe;IAuDvB,OAAO,CAAC,wBAAwB;IA4IhC,OAAO,CAAC,gBAAgB;IAqBxB,OAAO,CAAC,6BAA6B;IAkPrC,OAAO,CAAC,kBAAkB;IAO1B,OAAO,CAAC,aAAa;IAMrB;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAuFzB,OAAO,CAAC,WAAW;IA0CnB,OAAO,CAAC,aAAa;IAmjBrB,OAAO,CAAC,iBAAiB;IAuCzB,OAAO,CAAC,qBAAqB;IAe7B,OAAO,CAAC,oBAAoB;IAyE5B,OAAO,CAAC,8BAA8B;IActC,OAAO,CAAC,wBAAwB;IAyBhC,OAAO,CAAC,yBAAyB;IA8BjC,OAAO,CAAC,wBAAwB;IAYhC,OAAO,CAAC,WAAW;IAQnB,OAAO,CAAC,kBAAkB;IA8B1B;;;;;OAKG;IACH,OAAO,CAAC,mBAAmB;IAmB3B;;;;OAIG;IACH,OAAO,CAAC,0BAA0B;IAiFlC,OAAO,CAAC,eAAe;CAuCxB"}

package/dist/src/services/code-generator.service.js

@@ -11,6 +11,9 @@ export class TypeScriptCodeGeneratorService {
     printer = ts.createPrinter({ newLine: ts.NewLineKind.LineFeed });
     namingConvention;
     operationNameTransformer;
+    // Track circular dependencies for z.lazy() wrapping
+    circularSchemas = new Set();
+    currentSchemaName = null;
     constructor(options = {}) {
         this.namingConvention = options.namingConvention;
         this.operationNameTransformer = options.operationNameTransformer;
@@ -63,13 +66,21 @@ export class TypeScriptCodeGeneratorService {
     }
     buildSchemas(openapi) {
         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((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([
-                ts.factory.createVariableDeclaration(ts.factory.createIdentifier(this.typeBuilder.sanitizeIdentifier(name)), undefined, undefined, this.buildSchema(schema)),
+                ts.factory.createVariableDeclaration(ts.factory.createIdentifier(this.typeBuilder.sanitizeIdentifier(name)), undefined, undefined, schemaExpression),
             ], ts.NodeFlags.Const));
             return {
                 ...schemaRegistered,
@@ -1223,7 +1234,114 @@ export class TypeScriptCodeGeneratorService {
     buildFromReference(reference) {
         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)
+     */
+    isCircularReference(refName) {
+        // 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.
+     */
+    detectCircularDependencies(schemas) {
+        const circularSchemas = new Set();
+        // Build dependency graph
+        const graph = new Map();
+        for (const [name, schema] of Object.entries(schemas)) {
+            const dependencies = jp
+                .query(schema, '$..["$ref"]')
+                .filter((ref) => ref.startsWith('#/components/schemas/'))
+                .map((ref) => ref.replace('#/components/schemas/', ''))
+                .filter((dep) => dep in schemas);
+            graph.set(name, dependencies);
+        }
+        // Tarjan's algorithm for finding SCCs
+        let index = 0;
+        const indices = new Map();
+        const lowlinks = new Map();
+        const onStack = new Set();
+        const stack = [];
+        const strongConnect = (node) => {
+            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 = [];
+                let w;
+                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;
     }
     topologicalSort(schemas) {
         const visited = new Set();

package/package.json

@@ -17,7 +17,7 @@
     "typescript": "^5.9.3",
     "url-pattern": "^1.0.3",
     "yargs": "^18.0.0",
-    "zod": "^4.1.13"
+    "zod": "^4.2.1"
   },
   "description": "A powerful TypeScript code generator that creates Zod schemas and type-safe clients from OpenAPI specifications",
   "keywords": [
@@ -34,18 +34,18 @@
   "devDependencies": {
     "@commitlint/cli": "^20.1.0",
     "@commitlint/config-conventional": "^20.0.0",
-    "@eslint/js": "^9.39.1",
+    "@eslint/js": "^9.39.2",
     "@semantic-release/changelog": "^6.0.3",
     "@semantic-release/git": "^10.0.1",
     "@types/debug": "^4.1.12",
     "@types/jest": "^30.0.0",
     "@types/js-yaml": "^4.0.9",
     "@types/jsonpath": "^0.2.4",
-    "@types/node": "^24.10.1",
+    "@types/node": "^25.0.2",
     "@types/yargs": "^17.0.35",
     "@vitest/coverage-v8": "^4.0.14",
     "cross-env": "^10.1.0",
-    "eslint": "^9.39.1",
+    "eslint": "^9.39.2",
     "eslint-config-prettier": "^10.1.8",
     "husky": "^9.1.7",
     "lint-staged": "^16.2.7",
@@ -110,5 +110,5 @@
     "release": "semantic-release",
     "release:dry": "semantic-release --dry-run"
   },
-  "version": "1.4.1"
+  "version": "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,
@@ -2688,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

@@ -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)');
+    });
+  });
 });