fix(zod): emit recursive reusable schemas with full TypeScript types (orval-labs#3467)

* fix(zod): emit recursive reusable schemas with full TypeScript types

A self-referential reusable schema is generated as a `const X = ...zod.lazy(
() => X)...` that reads its own binding inside its initializer. Under strict /
noImplicitAny TypeScript rejects this with TS7022 ("'X' implicitly has type
'any' ... referenced directly or indirectly in its own initializer").

Detect schemas that sit in a cycle (SCC > 1 or a self-loop) and, for those,
generate the recursive TS type with orval's own model generator (`resolveValue`,
the same path that produces `export type X` in the model output, so identifiers
line up via `getRefInfo`) and pin the schema to it:

  export type X = ...X[]...;
  export const X: zod.ZodType<X> = zod.union([...zod.lazy(() => X)...]);

The annotation both satisfies the compiler and preserves full `z.infer` typing
through the recursion, instead of collapsing recursive positions to `unknown`.
Acyclic schemas are unchanged (still derive `zod.input<typeof X>`). Applies to
both the inline single-file and per-file reusable writers; verified on zod v3
and v4 incl. mutual recursion, coercion + defaults, and sanitized names.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* fix(zod): address review on recursive reusable schemas

- resolve the recursive schema lookup key via getRefInfo/isComponentRef
  instead of a blind ref slice (decodes JSON Pointer escapes, guards the
  #/components/schemas/ prefix before indexing components.schemas)
- make the recursive-type assertion whitespace-tolerant (regex)
- drop the Record<string, unknown> cast in reusable-schema tests; the
  typed override.zod shape already carries generateReusableSchemas

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: z4o4z

packages/orval/src/generate-spec.test.ts

@@ -162,3 +162,110 @@ describe('generateSpec - generateReusableSchemas inline (single mode)', () => {
     }
   });
 });
+
+describe('generateSpec - generateReusableSchemas recursive ($ref to self)', () => {
+  // Regression: a self-referential component schema is emitted as a single
+  // reusable `const` whose initializer references itself through `zod.lazy`.
+  // TypeScript rejects such a `const` under strict / noImplicitAny with TS7022
+  // ("'X' implicitly has type 'any' ... referenced directly or indirectly in
+  // its own initializer"). The writer fixes this by generating the recursive
+  // TS type and pinning the schema to it: `const X: zod.ZodType<X>`. That both
+  // satisfies the compiler and preserves full `z.infer` typing through the
+  // recursion (rather than collapsing recursive positions to `unknown`).
+  const RECURSIVE_SPEC: OpenApiDocument = {
+    openapi: '3.1.0',
+    info: { title: 'Recursive', version: '1.0.0' },
+    paths: {
+      '/values': {
+        get: {
+          operationId: 'listValues',
+          responses: {
+            '200': {
+              description: 'ok',
+              content: {
+                'application/json': {
+                  schema: {
+                    type: 'array',
+                    items: { $ref: '#/components/schemas/JsonValue' },
+                  },
+                },
+              },
+            },
+          },
+        },
+      },
+    },
+    components: {
+      schemas: {
+        JsonValue: {
+          anyOf: [
+            {
+              anyOf: [
+                { type: 'string' },
+                { type: 'number' },
+                { type: 'boolean' },
+              ],
+            },
+            {
+              type: 'array',
+              items: { $ref: '#/components/schemas/JsonValue' },
+            },
+            {
+              type: 'object',
+              additionalProperties: { $ref: '#/components/schemas/JsonValue' },
+            },
+          ],
+        },
+      },
+    },
+  };
+
+  it('pins the recursive schema to a generated TS type so it type-checks with full inference', async () => {
+    const workspace = await createTempWorkspace();
+    const targetFile = path.join(workspace, 'zod.ts');
+
+    try {
+      const options = await normalizeOptions(
+        {
+          input: { target: RECURSIVE_SPEC },
+          output: {
+            target: './zod.ts',
+            mode: 'single',
+            client: 'zod',
+            override: { zod: { generateReusableSchemas: true } },
+          },
+        },
+        workspace,
+      );
+
+      await generateSpec(workspace, options);
+
+      const content = await fs.readFile(targetFile, 'utf8');
+
+      // A recursive TS type is generated for the schema. Asserted with a
+      // whitespace-tolerant regex (union-bar spacing and index-signature brace
+      // spacing are formatter-dependent) that still pins the structure: the
+      // union of the four primitives plus the self-referential array and the
+      // index signature whose value type is `JsonValue`.
+      expect(content).toMatch(
+        /export type JsonValue\s*=\s*string\s*\|\s*number\s*\|\s*boolean\s*\|\s*JsonValue\[\]\s*\|\s*\{\s*\[key:\s*string\]:\s*JsonValue\s*\}/,
+      );
+      // ...and the schema const is pinned to it (the fix for TS7022).
+      expect(content).toContain(
+        'export const JsonValue: zod.ZodType<JsonValue> = zod.union(',
+      );
+      // The self-reference is a plain lazy (the const annotation breaks the
+      // self-inference cycle, so no callback annotation is needed).
+      expect(content).toContain('zod.lazy(() => JsonValue)');
+      // The recursive schema must NOT re-derive its type from itself via
+      // `zod.input<typeof JsonValue>` — that alias would be circular.
+      expect(content).not.toContain(
+        'export type JsonValue = zod.input<typeof JsonValue>',
+      );
+      // No unresolved sentinels.
+      expect(content).not.toContain('__REF_');
+    } finally {
+      await rm(workspace, { recursive: true, force: true });
+    }
+  });
+});

packages/orval/src/reusable-schemas.test.ts

@@ -257,6 +257,8 @@ describe('rewriteReusableSchemas', () => {
     expect(pet?.zod).toBe('zod.object({ owner: owner })');
     // Topological order: owner emitted before pet.
     expect(result.map((e) => e.name)).toEqual(['owner', 'pet']);
+    // Acyclic schemas are not flagged recursive.
+    expect(result.every((e) => e.isRecursive !== true)).toBe(true);
   });
 
   it('wraps cycle edges in z.lazy(() => Name)', () => {
@@ -283,6 +285,10 @@ describe('rewriteReusableSchemas', () => {
       s?.includes('zod.lazy'),
     ).length;
     expect(lazyCount).toBe(1);
+    // Both members of the cycle are flagged recursive so the writer pins each
+    // to `zod.ZodType<Name>` (the const-level fix for TS7022).
+    expect(a?.isRecursive).toBe(true);
+    expect(b?.isRecursive).toBe(true);
   });
 
   it('wraps self-loops in z.lazy', () => {
@@ -297,5 +303,7 @@ describe('rewriteReusableSchemas', () => {
     ];
     const result = rewriteReusableSchemas(entries);
     expect(result[0].zod).toBe('zod.object({ child: zod.lazy(() => node) })');
+    // Self-loop ⇒ recursive; the writer annotates `const node: zod.ZodType<node>`.
+    expect(result[0].isRecursive).toBe(true);
   });
 });

packages/orval/src/reusable-schemas.ts

@@ -122,6 +122,15 @@ export interface ReusableSchemaEntry {
   zod: string;
   consts: string;
   usedRefs: Set<string>;
+  /**
+   * True when this schema references itself directly or transitively (its node
+   * sits in a cycle: an SCC of size > 1, or a self-loop). Such a schema is
+   * emitted as a recursive `const` that reads its own binding inside its
+   * initializer, so the writer must give it an explicit type annotation
+   * (`const X: zod.ZodType<X>`) to avoid TS7022. Set by
+   * {@link rewriteReusableSchemas}; `undefined`/`false` for acyclic schemas.
+   */
+  isRecursive?: boolean;
 }
 
 export interface GenerateReusableSchemaSetOptions {
@@ -307,6 +316,15 @@ export const rewriteSentinelsToDirect = (zod: string): string =>
  * reorder entries so that every non-lazy reference is emitted AFTER its
  * target. This avoids TDZ errors at module load.
  *
+ * Entries that sit in a cycle (SCC of size > 1, or a self-loop) are flagged
+ * `isRecursive`. Their generated `const` reads its own binding inside the
+ * initializer (through the `zod.lazy` wrapper), which TypeScript rejects with
+ * TS7022 ("'X' implicitly has type 'any' ... referenced directly or indirectly
+ * in its own initializer") unless the `const` carries an explicit type
+ * annotation. The writer (`write-zod-specs`) supplies that annotation —
+ * `const X: zod.ZodType<X>` — backed by a generated TS type, which both
+ * silences TS7022 and preserves full `z.infer` typing through the recursion.
+ *
  * Both the lazy classification and the emit order come from a single Tarjan
  * run, guaranteeing they agree: a non-lazy edge u→v means v is visited (and
  * popped) before u in DFS, so v appears earlier in the SCC array → emitted
@@ -329,6 +347,17 @@ export const rewriteReusableSchemas = (
 
   const { sccs, lazyEdges } = tarjan(graph);
 
+  // A node is recursive iff it sits in a cycle: either an SCC with more than
+  // one member (mutual recursion), or a single-node SCC that has a self-loop.
+  const recursiveNames = new Set<string>();
+  for (const scc of sccs) {
+    if (scc.length > 1) {
+      for (const name of scc) recursiveNames.add(name);
+    } else if (lazyEdges.has(edgeKey(scc[0], scc[0]))) {
+      recursiveNames.add(scc[0]);
+    }
+  }
+
   const rewritten = new Map(
     entries.map((entry) => {
       const newZod = entry.zod.replaceAll(
@@ -338,7 +367,10 @@ export const rewriteReusableSchemas = (
           return isLazy ? `zod.lazy(() => ${refName})` : refName;
         },
       );
-      return [entry.name, { ...entry, zod: newZod }] as const;
+      return [
+        entry.name,
+        { ...entry, zod: newZod, isRecursive: recursiveNames.has(entry.name) },
+      ] as const;
     }),
   );
 

packages/orval/src/write-zod-specs.test.ts

@@ -29,11 +29,17 @@ const createOutputOptions = (): Parameters<typeof writeZodSchemas>[4] =>
     namingConvention: 'PascalCase',
     indexFiles: true,
     override: {
+      // Mirrors the normalized defaults the real pipeline supplies; the
+      // recursive-schema TS-type generation (`resolveValue`) reads these.
+      components: {
+        schemas: { suffix: '', itemSuffix: 'Item' },
+      },
       zod: {
         strict: {
           body: true,
         },
         generate: {
+          param: true,
           body: true,
           query: true,
           header: true,
@@ -355,8 +361,7 @@ describe('writeZodSchemas with generateReusableSchemas', () => {
     } satisfies Parameters<typeof writeZodSchemas>[0];
 
     const options = createOutputOptions();
-    (options.override.zod as Record<string, unknown>).generateReusableSchemas =
-      true;
+    options.override.zod.generateReusableSchemas = true;
 
     await writeZodSchemas(builder, schemasPath, '.ts', '', options);
 
@@ -402,8 +407,7 @@ describe('writeZodSchemas with generateReusableSchemas', () => {
     } satisfies Parameters<typeof writeZodSchemas>[0];
 
     const options = createOutputOptions();
-    (options.override.zod as Record<string, unknown>).generateReusableSchemas =
-      true;
+    options.override.zod.generateReusableSchemas = true;
 
     await writeZodSchemas(builder, schemasPath, '.ts', '', options);
 
@@ -420,6 +424,64 @@ describe('writeZodSchemas with generateReusableSchemas', () => {
 
     await fs.remove(root);
   });
+
+  it('pins recursive schemas to a generated TS type across files', async () => {
+    const root = await fs.mkdtemp(path.join(tmpdir(), 'orval-zod-reuse-rec-'));
+    const schemasPath = path.join(root, 'schemas');
+
+    // Node <-> Edge mutual recursion: the back-edge is emitted as a `zod.lazy`,
+    // so each `const` reads (transitively) its own binding and needs an
+    // explicit `zod.ZodType<...>` annotation to satisfy TS7022.
+    const builder = {
+      spec: {
+        components: {
+          schemas: {
+            Node: {
+              type: 'object',
+              properties: {
+                edges: {
+                  type: 'array',
+                  items: { $ref: '#/components/schemas/Edge' },
+                },
+              },
+              required: ['edges'],
+            },
+            Edge: {
+              type: 'object',
+              properties: { to: { $ref: '#/components/schemas/Node' } },
+              required: ['to'],
+            },
+          },
+        },
+      },
+      target: '',
+      schemas: [
+        { name: 'Node', schema: { $ref: '#/components/schemas/Node' } },
+        { name: 'Edge', schema: { $ref: '#/components/schemas/Edge' } },
+      ],
+    } satisfies Parameters<typeof writeZodSchemas>[0];
+
+    const options = createOutputOptions();
+    options.override.zod.generateReusableSchemas = true;
+
+    await writeZodSchemas(builder, schemasPath, '.ts', '', options);
+
+    const nodeContent = await fs.readFile(
+      path.join(schemasPath, 'Node.ts'),
+      'utf8',
+    );
+
+    // The recursive TS type is generated and the const is pinned to it.
+    expect(nodeContent).toContain('export type Node = ');
+    expect(nodeContent).toContain('export const Node: zod.ZodType<Node> = ');
+    // Cross-file reference to Edge is imported (so the generated type resolves).
+    expect(nodeContent).toMatch(/from '\.\/Edge'/);
+    // The acyclic `zod.input<typeof Node>` alias would be circular here.
+    expect(nodeContent).not.toContain('export type Node = zod.input<');
+    expect(nodeContent).not.toContain('__REF_');
+
+    await fs.remove(root);
+  });
 });
 
 describe('writeZodSchemasFromVerbs with generateReusableSchemas', () => {
@@ -444,8 +506,7 @@ describe('writeZodSchemasFromVerbs with generateReusableSchemas', () => {
     } as never;
 
     const options = createOutputOptions();
-    (options.override.zod as Record<string, unknown>).generateReusableSchemas =
-      true;
+    options.override.zod.generateReusableSchemas = true;
     const ctx = {
       output: {
         override: {
@@ -515,8 +576,7 @@ describe('writeZodSchemasFromVerbs with generateReusableSchemas', () => {
     // camelCase namingConvention → file names are camelCased (`petStatus.ts`),
     // but the exported identifier is always PascalCase (`PetStatus`).
     (options as { namingConvention: string }).namingConvention = 'camelCase';
-    (options.override.zod as Record<string, unknown>).generateReusableSchemas =
-      true;
+    options.override.zod.generateReusableSchemas = true;
     const ctx = {
       output: {
         override: {