@gabrielbryk/json-schema-to-zod 2.10.1 → 2.11.0

package/docs/IMPROVEMENT-PLAN.md

@@ -0,0 +1,243 @@
+# Improvement Plan: Aligning with Zod v4 Best Practices
+
+Based on analysis of our generated output and Zod v4 limitations research.
+
+---
+
+## Current Problems in Our Generated Output
+
+### Problem 1: `z.record()` with recursive values lacks `z.lazy()`
+
+**Current output:**
+```typescript
+export const TaskList: z.ZodArray<z.ZodRecord<typeof z, typeof Task>> =
+  z.array(z.record(z.string(), Task).meta({...}))
+```
+
+**Issues:**
+1. `Task` referenced directly in `z.record()` - Colin confirmed in #4881 this REQUIRES `z.lazy()`
+2. Type annotation is completely wrong - `typeof z` as key type is nonsense
+3. This will cause runtime TDZ errors if Task isn't declared yet
+
+**Should be:**
+```typescript
+export const TaskList = z.array(
+  z.record(z.string(), z.lazy(() => Task)).meta({...})
+)
+```
+
+---
+
+### Problem 2: Union type annotations use `z.ZodTypeAny`
+
+**Current output:**
+```typescript
+export const CallTask: z.ZodUnion<readonly z.ZodTypeAny[]> = z.union([...])
+```
+
+**Issues:**
+1. `z.ZodTypeAny[]` defeats the entire purpose of type safety
+2. Loses all type information about what's actually in the union
+
+**Should be:**
+Either remove the type annotation entirely:
+```typescript
+export const CallTask = z.union([...])
+```
+
+Or if we must have one (for circular reference reasons), at least don't use `ZodTypeAny`.
+
+---
+
+### Problem 3: Object type annotations use `Record<string, z.ZodTypeAny>`
+
+**Current output:**
+```typescript
+export const DoTask: z.ZodIntersection<
+  z.ZodObject<Record<string, z.ZodTypeAny>>,
+  z.ZodIntersection<typeof TaskBase, z.ZodObject<Record<string, z.ZodTypeAny>>>
+> = ...
+```
+
+**Issues:**
+1. `Record<string, z.ZodTypeAny>` loses all property type information
+2. The intersection type is overly complex and still loses info
+
+**Should be:**
+Remove the type annotation and let TypeScript infer:
+```typescript
+export const DoTask = z.object({}).and(z.intersection(TaskBase, z.object({...})))
+```
+
+---
+
+### Problem 4: Getters ARE being used correctly ✅
+
+**Current output (GOOD):**
+```typescript
+get "do"(): z.ZodOptional<typeof TaskList>{ return TaskList.optional() }
+```
+
+This follows the Zod v4 pattern correctly! The getter with explicit return type annotation.
+
+---
+
+### Problem 5: Empty object base with `.and()` is wasteful
+
+**Current output:**
+```typescript
+z.object({}).and(z.intersection(TaskBase, z.object({...})))
+```
+
+**Issue:**
+Starting with `z.object({})` then using `.and()` is unnecessary when there are no direct properties.
+
+**Should be:**
+```typescript
+z.intersection(TaskBase, z.object({...}))
+// OR
+TaskBase.and(z.object({...}))
+```
+
+---
+
+## Specific Code Changes Required
+
+### Change 1: Fix `z.record()` recursive handling
+
+**File:** `src/parsers/parseSchema.ts`
+
+When reference is inside a `z.record()` context AND the target is recursive, use `z.lazy()`:
+
+```typescript
+// Check if we're inside a record value context
+const inRecordValue = refs.path.some((p, i) =>
+  p === "additionalProperties" ||
+  (refs.path[i-1] === "record" && p === "1") // second arg to z.record
+);
+
+if (inRecordValue && (isSameCycle || isForwardRef)) {
+  return `z.lazy(() => ${refName})`;
+}
+```
+
+---
+
+### Change 2: Remove bad type annotations
+
+**File:** `src/core/emitZod.ts`
+
+Current logic adds type annotations when there's a cycle/lazy/getter. Change to:
+1. Only add type annotation if we can infer a GOOD type
+2. Never use `z.ZodTypeAny` - either infer correctly or don't annotate
+
+```typescript
+if (isCycle || hasLazy || hasGetter) {
+  const inferredType = inferTypeFromExpression(value);
+  // Skip annotation if it's useless or wrong
+  if (inferredType !== "z.ZodTypeAny" &&
+      !inferredType.includes("Record<string, z.ZodTypeAny>") &&
+      !inferredType.includes("typeof z,")) {
+    return `${shouldExport ? "export " : ""}const ${refName}: ${inferredType} = ${value}`;
+  }
+}
+// Let TypeScript infer instead
+return `${shouldExport ? "export " : ""}const ${refName} = ${value}`;
+```
+
+---
+
+### Change 3: Fix `inferTypeFromExpression` for records
+
+**File:** `src/utils/schemaRepresentation.ts`
+
+The current inference for `z.record()` is broken. Fix it:
+
+```typescript
+// Handle z.record(K, V)
+if (expr.startsWith("z.record(")) {
+  const argsStart = 9;
+  const argsEnd = findMatchingParen(expr, argsStart - 1);
+  if (argsEnd !== -1) {
+    const args = expr.substring(argsStart, argsEnd);
+    const commaIndex = findTopLevelComma(args);
+    if (commaIndex !== -1) {
+      const keyExpr = args.substring(0, commaIndex).trim();
+      const valueExpr = args.substring(commaIndex + 1).trim();
+
+      // CRITICAL: Don't use "typeof z" - that's nonsense
+      const keyType = keyExpr === "z.string()" ? "z.ZodString" : inferTypeFromExpression(keyExpr);
+      const valueType = inferTypeFromExpression(valueExpr);
+
+      return `z.ZodRecord<${keyType}, ${valueType}>`;
+    }
+  }
+}
+```
+
+---
+
+### Change 4: Remove unnecessary `z.object({}).and()`
+
+**File:** `src/parsers/parseObject.ts`
+
+When there are no direct properties but there IS composition (allOf), don't create empty object:
+
+```typescript
+// Current (line ~218):
+: hasCompositionKeywords
+  ? "z.object({})"  // Creates empty object unnecessarily
+  : `z.record(z.string(), ${anyOrUnknown(refs)})`;
+
+// Should be:
+: hasCompositionKeywords
+  ? null  // Let composition be the base, not empty object
+  : `z.record(z.string(), ${anyOrUnknown(refs)})`;
+```
+
+Then when building output with `.and()`:
+```typescript
+if (output === null && its.an.allOf(objectSchema)) {
+  // No base object, just use the composition directly
+  output = parseAllOf(...);
+} else if (its.an.allOf(objectSchema)) {
+  output += `.and(${parseAllOf(...)})`;
+}
+```
+
+---
+
+## Summary of Changes
+
+| File | Change | Priority |
+|------|--------|----------|
+| `parseSchema.ts` | Add `z.lazy()` for refs inside `z.record()` | HIGH |
+| `emitZod.ts` | Don't add `z.ZodTypeAny` annotations | HIGH |
+| `schemaRepresentation.ts` | Fix `z.record()` type inference | HIGH |
+| `parseObject.ts` | Remove unnecessary `z.object({}).and()` | MEDIUM |
+
+---
+
+## Expected Outcome
+
+**Before:**
+```typescript
+export const TaskList: z.ZodArray<z.ZodRecord<typeof z, typeof Task>> =
+  z.array(z.record(z.string(), Task).meta({...}))
+
+export const CallTask: z.ZodUnion<readonly z.ZodTypeAny[]> = z.union([...])
+```
+
+**After:**
+```typescript
+export const TaskList = z.array(
+  z.record(z.string(), z.lazy(() => Task)).meta({...})
+)
+
+export const CallTask = z.union([...])  // Let TS infer
+```
+
+This aligns with:
+1. Colin's guidance that `z.record()` REQUIRES `z.lazy()` for recursive values
+2. Best practice of not using `z.ZodTypeAny` which defeats type safety
+3. Zod v4's getter pattern for recursive object properties (which we already do)

package/docs/ZOD-V4-RECURSIVE-TYPE-LIMITATIONS.md

@@ -0,0 +1,292 @@
+# Zod v4 Recursive Type Inference: TypeScript Limitations & Workarounds
+
+## Executive Summary
+
+Zod v4 introduced a new getter-based approach for recursive schemas that eliminates the need for `z.lazy()` in many cases. However, **this approach has significant TypeScript limitations**, particularly when recursive schemas are used within unions, discriminated unions, records, or when chaining multiple methods.
+
+This document consolidates findings from multiple GitHub issues to inform our code generation strategy.
+
+---
+
+## The Core Problem
+
+**TypeScript's type inference breaks when recursive schemas are embedded inside certain Zod APIs.**
+
+From Colin McDonnell (Zod creator) in [#4691](https://github.com/colinhacks/zod/issues/4691):
+> "You're hitting against TypeScript limitations, not Zod limitations."
+
+### What Works (Standalone Recursive Object)
+
+```typescript
+const Category = z.object({
+  name: z.string(),
+  get subcategories() {
+    return z.array(Category);
+  },
+});
+
+type Category = z.infer<typeof Category>;
+// { name: string; subcategories: Category[] }  ✅ Correct inference
+```
+
+### What Breaks (Recursive Object in Union)
+
+```typescript
+const ActivityUnion = z.union([
+  z.object({
+    name: z.string(),
+    get subactivities() {
+      return z.nullable(z.array(ActivityUnion));
+    },
+  }),
+  z.string(),
+]);
+
+type Activity = z.infer<typeof ActivityUnion>;
+// string | { name: string; subactivities: unknown[] | null }  ❌ Lost type info
+```
+
+---
+
+## Affected Scenarios
+
+Based on issues [#4691](https://github.com/colinhacks/zod/issues/4691), [#4351](https://github.com/colinhacks/zod/issues/4351), [#4561](https://github.com/colinhacks/zod/issues/4561), [#4264](https://github.com/colinhacks/zod/issues/4264), [#4502](https://github.com/colinhacks/zod/issues/4502), [#4881](https://github.com/colinhacks/zod/issues/4881):
+
+| Scenario | Getter Works? | Notes |
+|----------|---------------|-------|
+| Self-recursive object property | ✅ Yes | The happy path |
+| Mutually recursive objects | ✅ Yes | With explicit type annotations |
+| Recursive inside `z.union()` | ❌ No | Falls back to `unknown` |
+| Recursive inside `z.discriminatedUnion()` | ❌ No | Requires `z.lazy()` |
+| Recursive inside `z.record()` | ❌ No | Must use `z.lazy()` |
+| Recursive inside `z.array()` nested in union | ❌ No | Complex nesting breaks inference |
+| Chaining methods on recursive type | ⚠️ Partial | `.optional()` often breaks it |
+| Using `.extend()` with recursive getters | ⚠️ Partial | Can cause TDZ errors |
+| Using spread operator `{...schema.shape}` | ❌ No | Breaks recursive inference |
+
+---
+
+## Key Rules from Colin McDonnell
+
+### Rule 1: Put Object Types at Top-Level
+From [#4691](https://github.com/colinhacks/zod/issues/4691):
+> "Embedding the object schema declaration inside other APIs can break things."
+
+**Bad:**
+```typescript
+const Schema = z.union([
+  z.object({ get recursive() { return Schema; } }),  // Inside union
+  z.string()
+]);
+```
+
+**Good:**
+```typescript
+const RecursiveObject = z.object({
+  get recursive() { return RecursiveObject; }
+});
+const Schema = z.union([RecursiveObject, z.string()]);
+```
+
+### Rule 2: Don't Chain Methods on Recursive Types
+From [#4570](https://github.com/colinhacks/zod/issues/4570):
+> "Rule of thumb: do not directly chain method calls on the recursive types"
+
+**Bad:**
+```typescript
+const Category = z.object({
+  get subcategories() {
+    return z.array(Category);
+  },
+}).meta({ description: "..." });  // .meta() forces eager evaluation
+```
+
+**Good:**
+```typescript
+const _Category = z.object({
+  get subcategories() {
+    return z.array(_Category);
+  },
+});
+const Category = _Category.meta({ description: "..." });
+```
+
+### Rule 3: Avoid Nesting Function Calls in Getters
+From [#4264](https://github.com/colinhacks/zod/issues/4264):
+> "You'll have a hard time using top-level functions like `z.optional()` or `z.discriminatedUnion()` inside getters. [...] type checking is the enemy of recursive type inference"
+
+**Bad:**
+```typescript
+get children() {
+  return z.optional(z.array(Schema));  // Function call
+}
+```
+
+**Good:**
+```typescript
+get children() {
+  return z.array(Schema).optional();  // Method chain
+}
+```
+
+### Rule 4: Use Explicit Type Annotations When Needed
+From [#4351](https://github.com/colinhacks/zod/issues/4351):
+
+```typescript
+const Activity = z.object({
+  name: z.string(),
+  get subactivities(): z.ZodNullable<z.ZodArray<typeof Activity>> {
+    return z.nullable(z.array(Activity));
+  },
+});
+```
+
+### Rule 5: Use `readonly` in Union Type Annotations
+From [#4502](https://github.com/colinhacks/zod/issues/4502):
+
+```typescript
+// Without readonly - FAILS
+get children(): ZodArray<ZodUnion<[typeof span, typeof tagB]>> { ... }
+
+// With readonly - WORKS
+get children(): ZodArray<ZodUnion<readonly [typeof span, typeof tagB]>> { ... }
+```
+
+---
+
+## When `z.lazy()` Is Still Required
+
+From [#4881](https://github.com/colinhacks/zod/issues/4881), Colin confirms:
+> "Stick with `z.lazy` as you're doing. Getters provided a clean way to 'lazify' object types [...] I could add callback-style APIs to every `z` factory [...] but it would be a big lift for comparatively minimal upside."
+
+**`z.lazy()` is required for:**
+1. Recursive types inside `z.record()`
+2. Complex recursive unions where getters fail
+3. Non-object recursive schemas (arrays, tuples used at top-level)
+4. When TypeScript inference completely fails
+
+---
+
+## Working Patterns
+
+### Pattern 1: Extract and Compose (Recommended for Unions)
+From [#4691](https://github.com/colinhacks/zod/issues/4691):
+
+```typescript
+const ActivitySchemaBase = z.object({
+  name: z.string(),
+});
+
+const Subactivity = ActivitySchemaBase.extend({
+  get subactivities(): z.ZodNullable<z.ZodArray<typeof ActivitySchema>> {
+    return z.nullable(z.array(ActivitySchema));
+  },
+});
+
+const ActivitySchema = z.union([z.string(), Subactivity]);
+```
+
+### Pattern 2: Explicit Input/Output Types
+From [#4691](https://github.com/colinhacks/zod/issues/4691):
+
+```typescript
+type IActivityInput = string | { name: string; subactivities: IActivityInput[] | null };
+type IActivityOutput = string | { name: string; subactivities: IActivityOutput[] | null };
+
+const ActivitySchema: z.ZodType<IActivityOutput, IActivityInput> = z.union([
+  z.string(),
+  z.object({
+    name: z.string(),
+    get subactivities() {
+      return z.nullable(z.array(ActivitySchema));
+    },
+  }),
+]);
+```
+
+### Pattern 3: Use `z.lazy()` for Records
+From [#4881](https://github.com/colinhacks/zod/issues/4881):
+
+```typescript
+const TreeNode = z.object({
+  value: z.string(),
+  children: z.record(z.string(), z.lazy(() => TreeNode)),
+});
+```
+
+### Pattern 4: Avoid `.extend()` TDZ Issues
+From [#4691](https://github.com/colinhacks/zod/issues/4691) (kfranqueiro's comment):
+
+**Bad (TDZ error at runtime):**
+```typescript
+const Recursive = z.object({
+  get children() { return ArrayOfThings.optional(); }
+});
+const ArrayOfThings = z.array(Reusable.extend(Recursive.shape));  // TDZ!
+```
+
+**Good:**
+```typescript
+const ArrayOfThings = z.array(
+  Reusable.extend({
+    get children() { return ArrayOfThings.optional(); }
+  })
+);
+```
+
+---
+
+## Implications for json-schema-to-zod
+
+### What We Should Do
+
+1. **For recursive object properties**: Use getters with explicit type annotations
+   ```typescript
+   get subcategories(): z.ZodArray<typeof Category> {
+     return z.array(Category);
+   }
+   ```
+
+2. **For unions containing recursive schemas**: Define member schemas at top-level first, then compose
+   ```typescript
+   export const CallTask = z.object({ ... });
+   export const DoTask = z.object({ ... });
+   export const Task = z.union([CallTask, DoTask, ...]);  // Direct refs
+   ```
+
+3. **For `z.record()` with recursive values**: Use `z.lazy()`
+   ```typescript
+   z.record(z.string(), z.lazy(() => Task))
+   ```
+
+4. **For type annotations**: Use correct types with `readonly` where needed
+   ```typescript
+   z.ZodUnion<readonly [typeof A, typeof B]>  // Not z.ZodTypeAny!
+   ```
+
+5. **Avoid chaining methods** on schemas that contain recursive getters
+
+### What We Should NOT Do
+
+1. Don't wrap union members in `z.lazy()` if they're already defined
+2. Don't use `z.ZodTypeAny` as a type annotation - it defeats the purpose
+3. Don't embed object schema definitions inside union calls
+4. Don't use spread operator for recursive schema composition
+
+---
+
+## References
+
+- [#4691](https://github.com/colinhacks/zod/issues/4691) - Recursive union type inference (main issue)
+- [#4351](https://github.com/colinhacks/zod/issues/4351) - Recursive record inference
+- [#4561](https://github.com/colinhacks/zod/issues/4561) - z.lazy with discriminatedUnion
+- [#4570](https://github.com/colinhacks/zod/issues/4570) - Method chaining breaks recursion
+- [#4592](https://github.com/colinhacks/zod/issues/4592) - Optional breaking inference
+- [#4610](https://github.com/colinhacks/zod/issues/4610) - Complex nesting exceeds TS limits
+- [#4625](https://github.com/colinhacks/zod/issues/4625) - `.optional()` breaks mutual recursion
+- [#4264](https://github.com/colinhacks/zod/issues/4264) - Discriminated union recursion
+- [#4502](https://github.com/colinhacks/zod/issues/4502) - Mapped type circular reference
+- [#4783](https://github.com/colinhacks/zod/issues/4783) - discriminatedUnion inference
+- [#4881](https://github.com/colinhacks/zod/issues/4881) - Recursive types in z.record()
+- [Zod v4 Docs: Recursive Objects](https://zod.dev/api#recursive-objects)
+- [Zod v4 Docs: Circularity Errors](https://zod.dev/api#circularity-errors)

package/docs/proposals/bundle-refactor.md

@@ -13,7 +13,7 @@
 ## Proposed Architecture
 - **Analyzer (`analyzeSchema`)**: Convert JsonSchema + options into an intermediate representation (IR) containing symbols, ref pointer map, dependency graph, cycle info, and metadata flags. No code strings.
 - **Emitters**:
-  - `emitZod(ir, emitOptions)`: IR → zod code (esm/cjs/none), with naming hooks and export policies.
+  - `emitZod(ir, emitOptions)`: IR → zod code (esm), with naming hooks and export policies.
   - `emitTypes(ir, typeOptions)`: optional type-only exports (for nested types or barrel typing).
 - **Strategies**:
   - `SingleFileStrategy`: analyze root → emit zod once.