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

package/CHANGELOG.md

@@ -1,5 +1,30 @@
 # @gabrielbryk/json-schema-to-zod
 
+## 2.12.0
+
+### Minor Changes
+
+- 719e761: Add `typeExports` option to export TypeScript types for all generated schemas
+
+  When `typeExports: true` is set (along with `exportRefs: true`), each generated schema will have a corresponding type export:
+
+  ```typescript
+  export const MySchema = z.object({...});
+  export type MySchema = z.infer<typeof MySchema>;
+  ```
+
+  This makes it easier to use the generated types throughout your codebase without manually creating type aliases.
+
+## 2.11.1
+
+### Patch Changes
+
+- 466d672: Fix TS7056 error when generating declarations for schemas referencing recursive types
+
+  - Add explicit type annotations to any schema that references recursive schemas (not just unions)
+  - This prevents TypeScript from trying to serialize extremely large expanded types when generating .d.ts files
+  - Fix type narrowing in parseObject for allOf required array handling
+
 ## 2.11.0
 
 ### Minor Changes

package/check-types.sh

@@ -8,7 +8,7 @@ import { readFileSync, writeFileSync } from 'fs';
 import { jsonSchemaToZod } from './src/jsonSchemaToZod.js';
 
 const schema = yaml.load(readFileSync('test/fixtures/workflow.yaml', 'utf8'));
-const output = jsonSchemaToZod(schema, { name: 'workflowSchema' });
+const output = jsonSchemaToZod(schema, { name: 'workflowSchema', typeExports: true });
 writeFileSync('.tmp-workflow-schema-output.ts', output);
 console.log('Generated .tmp-workflow-schema-output.ts');
 EOF

package/dist/core/emitZod.js

@@ -149,7 +149,7 @@ const orderDeclarations = (entries, dependencies) => {
 };
 export const emitZod = (analysis) => {
     const { schema, options, refNameByPointer, cycleRefNames, cycleComponentByName, } = analysis;
-    const { name, type, noImport, exportRefs, withMeta, ...rest } = options;
+    const { name, type, noImport, exportRefs, typeExports, withMeta, ...rest } = options;
     const declarations = new Map();
     const dependencies = new Map();
     // Fresh name registry for the emission pass.
@@ -196,14 +196,14 @@ export const emitZod = (analysis) => {
                 : undefined;
             const hasLazy = expression.includes("z.lazy(");
             const hasGetter = expression.includes("get ");
-            const isUnion = expression.startsWith("z.union(") || expression.startsWith("z.discriminatedUnion(");
-            // Check if this union references any cycle members (recursive schemas)
-            const referencesRecursiveSchema = isUnion && Array.from(cycleRefNames).some(cycleName => new RegExp(`\\b${cycleName}\\b`).test(expression));
+            // Check if this schema references any cycle members (recursive schemas)
+            // This can cause TS7056 when TypeScript tries to serialize the expanded type
+            const referencesRecursiveSchema = Array.from(cycleRefNames).some(cycleName => new RegExp(`\\b${cycleName}\\b`).test(expression));
             // Per Zod v4 docs: type annotations should be on GETTERS for recursive types, not on const declarations.
             // TypeScript can infer the type of const declarations.
             // Exceptions that need explicit type annotation:
             // 1. z.lazy() without getters
-            // 2. Union types that reference recursive schemas (for proper type inference)
+            // 2. Any schema that references recursive schemas (to prevent TS7056)
             const needsTypeAnnotation = (hasLazy && !hasGetter) || referencesRecursiveSchema;
             const storedType = needsTypeAnnotation ? (hintedType ?? inferTypeFromExpression(expression)) : undefined;
             // Rule 2 from Zod v4: Don't chain methods on recursive types
@@ -227,6 +227,13 @@ export const emitZod = (analysis) => {
                         expression: `${baseName}${methodChain}`,
                         exported: exportRefs,
                     });
+                    // Export type for this declaration if typeExports is enabled
+                    if (typeExports && exportRefs) {
+                        emitter.addTypeExport({
+                            name: refName,
+                            type: `z.infer<typeof ${refName}>`,
+                        });
+                    }
                     continue;
                 }
             }
@@ -236,6 +243,13 @@ export const emitZod = (analysis) => {
                 exported: exportRefs,
                 typeAnnotation: storedType !== "z.ZodTypeAny" ? storedType : undefined,
             });
+            // Export type for this declaration if typeExports is enabled
+            if (typeExports && exportRefs) {
+                emitter.addTypeExport({
+                    name: refName,
+                    type: `z.infer<typeof ${refName}>`,
+                });
+            }
         }
     }
     if (name) {
@@ -252,7 +266,8 @@ export const emitZod = (analysis) => {
             jsdoc: jsdocs,
         });
     }
-    if (type && name) {
+    // Export type for root schema if type option is set, or if typeExports is enabled
+    if (name && (type || typeExports)) {
         const typeName = typeof type === "string" ? type : `${name[0].toUpperCase()}${name.substring(1)}`;
         emitter.addTypeExport({
             name: typeName,

package/dist/parsers/parseObject.js

@@ -13,6 +13,16 @@ export function parseObject(objectSchema, refs) {
     const hasAdditionalProperties = objectSchema.additionalProperties !== undefined;
     const hasPatternProperties = objectSchema.patternProperties !== undefined;
     const hasNoDirectSchema = !hasDirectProperties && !hasAdditionalProperties && !hasPatternProperties;
+    const parentRequired = Array.isArray(objectSchema.required) ? objectSchema.required : [];
+    const allOfRequired = its.an.allOf(objectSchema)
+        ? objectSchema.allOf.flatMap((member) => {
+            if (typeof member !== "object" || member === null)
+                return [];
+            const req = member.required;
+            return Array.isArray(req) ? req : [];
+        })
+        : [];
+    const combinedAllOfRequired = [...new Set([...parentRequired, ...allOfRequired])];
     // Helper to add type: "object" to composition members that have properties but no explicit type
     const addObjectType = (members) => members.map((x) => typeof x === "object" &&
         x !== null &&
@@ -20,9 +30,31 @@ export function parseObject(objectSchema, refs) {
         (x.properties || x.additionalProperties || x.patternProperties)
         ? { ...x, type: "object" }
         : x);
+    const addObjectTypeAndMergeRequired = (members) => members.map((x) => {
+        if (typeof x !== "object" || x === null)
+            return x;
+        let normalized = x;
+        const hasShape = normalized.properties || normalized.additionalProperties || normalized.patternProperties;
+        if (hasShape && !normalized.type) {
+            normalized = { ...normalized, type: "object" };
+        }
+        if (combinedAllOfRequired.length &&
+            normalized.properties &&
+            Object.keys(normalized.properties).length) {
+            const memberRequired = Array.isArray(normalized.required) ? normalized.required : [];
+            const mergedRequired = Array.from(new Set([
+                ...memberRequired,
+                ...combinedAllOfRequired.filter((key) => Object.prototype.hasOwnProperty.call(normalized.properties, key)),
+            ]));
+            if (mergedRequired.length) {
+                normalized = { ...normalized, required: mergedRequired };
+            }
+        }
+        return normalized;
+    });
     // If only allOf, delegate to parseAllOf
     if (hasNoDirectSchema && its.an.allOf(objectSchema) && !its.an.anyOf(objectSchema) && !its.a.oneOf(objectSchema) && !its.a.conditional(objectSchema)) {
-        return parseAllOf({ ...objectSchema, allOf: addObjectType(objectSchema.allOf) }, refs);
+        return parseAllOf({ ...objectSchema, allOf: addObjectTypeAndMergeRequired(objectSchema.allOf) }, refs);
     }
     // If only anyOf, delegate to parseAnyOf
     if (hasNoDirectSchema && its.an.anyOf(objectSchema) && !its.an.allOf(objectSchema) && !its.a.oneOf(objectSchema) && !its.a.conditional(objectSchema)) {
@@ -285,12 +317,7 @@ export function parseObject(objectSchema, refs) {
     if (its.an.allOf(objectSchema)) {
         const allOfResult = parseAllOf({
             ...objectSchema,
-            allOf: objectSchema.allOf.map((x) => typeof x === "object" &&
-                x !== null &&
-                !x.type &&
-                (x.properties || x.additionalProperties || x.patternProperties)
-                ? { ...x, type: "object" }
-                : x),
+            allOf: addObjectTypeAndMergeRequired(objectSchema.allOf),
         }, refs);
         output += `.and(${allOfResult.expression})`;
         intersectionTypes.push(allOfResult.type);

package/dist/types/Types.d.ts

@@ -84,6 +84,18 @@ export type Options = {
     noImport?: boolean;
     /** Export all generated reference schemas (for $refs) when using ESM */
     exportRefs?: boolean;
+    /**
+     * Export TypeScript types for all generated schemas using z.infer.
+     * When true, exports a type for each schema (including lifted/ref schemas when exportRefs is true).
+     * Type names match their corresponding schema const names.
+     * @example
+     * // With typeExports: true, exportRefs: true, and name: "MySchema"
+     * export const SubSchema = z.object({...});
+     * export type SubSchema = z.infer<typeof SubSchema>;
+     * export const MySchema = z.object({ sub: SubSchema });
+     * export type MySchema = z.infer<typeof MySchema>;
+     */
+    typeExports?: boolean;
     /**
      * Store original JSON Schema constructs in .meta({ __jsonSchema: {...} })
      * for features that can't be natively represented in Zod (patternProperties,

package/docs/proposals/allof-required-merging.md

@@ -0,0 +1,53 @@
+# Proposal: Strengthen `allOf` required handling
+
+## Problem
+- Required keys are dropped when properties live in a different `allOf` member than the `required` array (e.g., workflow schema `call`/`with`).
+- Spread path only looks at each member’s own `required`, ignoring parent + sibling required-only members.
+- Intersection fallback also skips parent required enforcement because `parseObject` disables missing-key checks when composition keywords exist.
+- `$ref` members with required lists don’t inform optionality of sibling properties.
+- Conflicting property definitions across `allOf` members fail silently (often ending up as permissive intersections).
+
+## Goals
+1) Preserve required semantics across `allOf`, even when properties and `required` are split across members.
+2) Keep spread optimization where safe; otherwise, enforce required keys in the intersection path.
+3) Respect `unevaluatedProperties`/`additionalProperties` constraints from stricter members.
+4) Surface conflicts clearly instead of silently widening to `z.any()`.
+
+## Proposed changes
+- **Normalize `allOf` members up front (done partially):**
+  - Add `type: "object"` when shape hints exist and merge parent+member required into any member that actually declares those properties (already implemented for the spread path; extend to intersection path and `$ref` resolution).
+
+- **Intersection required enforcement:**
+  - When spread is not possible, compute a combined required set (parent + all member `required` + required-only members) and add a `superRefine` that checks presence of those keys on the final intersection result.
+  - Skip keys that none of the members define (avoid false positives).
+
+- **Required-only + properties-only pattern:**
+  - Detect an `allOf` where one member has only `required` and another has the properties; merge those required keys into the properties member before parsing.
+
+- **$ref-aware required merge:**
+  - When an `allOf` member is a `$ref`, resolve its schema shape/required (using existing ref resolution) and merge required keys that match properties provided by other members.
+
+- **Policy reconciliation:**
+  - When merging shapes, intersect `unevaluatedProperties`/`additionalProperties` so a member that disallows extras keeps that restriction after spread/intersection.
+
+- **Conflict detection:**
+  - If multiple members define the same property with incompatible primitive types (e.g., `string` vs `number`), emit a `superRefine` that fails with a clear message instead of silently widening.
+
+## Testing
+- Unit tests in `test/parsers/parseAllOf.test.ts` and `parseObject.test.ts` covering:
+  - properties-only + required-only split (current workflow pattern).
+  - Overlapping required across multiple members (including parent required).
+  - `$ref` member with required + sibling properties.
+  - Spread eligible vs. ineligible `allOf` and intersection fallback enforcing required.
+  - `unevaluatedProperties` interactions where one member disallows extras.
+  - Conflict detection on incompatible property types.
+
+## Risks & mitigations
+- **Over-enforcement**: Ensure required keys are only checked when at least one member defines the property. Filter combined required sets accordingly.
+- **Ref resolution cost**: Cache resolved `$ref` shapes when harvesting required sets to avoid repeated work.
+- **False conflicts**: Limit conflict detection to clear primitive mismatches; avoid flagging unions/anyOf/any as conflicts.
+
+## Rollout
+- Implement normalization + intersection required enforcement first, add tests for workflow fixture regression.
+- Follow with `$ref`-aware required merge and policy reconciliation tests.
+- Add conflict detection last (guarded behind a clear error message) to avoid unexpected breakage.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gabrielbryk/json-schema-to-zod",
-  "version": "2.11.0",
+  "version": "2.12.0",
   "description": "Converts JSON schema objects or files into Zod schemas",
   "type": "module",
   "types": "./dist/types/index.d.ts",