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

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # @gabrielbryk/json-schema-to-zod
 
+## 2.10.1
+
+### Patch Changes
+
+- 1c318a0: Ensure bundled outputs remain type-safe by grouping strongly connected defs, emitting lazy getters for recursive object refs, and reordering bundle members to avoid duplicate exports.
+- 87526f0: Preserve precise types for recursive schemas by emitting typed lazy wrappers instead of erasing types, and add a workflow regression type-check to guard against inference blowups.
+
 ## 2.9.0
 
 ### Minor Changes

package/dist/cjs/core/emitZod.js

@@ -73,6 +73,16 @@ const emitZod = (analysis) => {
     const { module, name, type, noImport, exportRefs, withMeta, ...rest } = options;
     const declarations = new Map();
     const dependencies = new Map();
+    const reserveName = (base) => {
+        let candidate = base;
+        let i = 1;
+        while (usedNames.has(candidate) || declarations.has(candidate)) {
+            candidate = `${base}${i}`;
+            i += 1;
+        }
+        usedNames.add(candidate);
+        return candidate;
+    };
     const parsedSchema = (0, parseSchema_js_1.parseSchema)(schema, {
         module,
         name,
@@ -94,10 +104,16 @@ const emitZod = (analysis) => {
     });
     const declarationBlock = declarations.size
         ? orderDeclarations(Array.from(declarations.entries()), dependencies)
-            .map(([refName, value]) => {
+            .flatMap(([refName, value]) => {
             const shouldExport = exportRefs && module === "esm";
-            const decl = `${shouldExport ? "export " : ""}const ${refName} = ${value}`;
-            return decl;
+            const isCycle = cycleRefNames.has(refName);
+            if (!isCycle) {
+                return [`${shouldExport ? "export " : ""}const ${refName} = ${value}`];
+            }
+            const baseName = `${refName}Def`;
+            const lines = [`const ${baseName} = ${value}`];
+            lines.push(`${shouldExport ? "export " : ""}const ${refName} = ${baseName}`);
+            return lines;
         })
             .join("\n")
         : "";

package/dist/cjs/generators/generateBundle.js

@@ -11,23 +11,27 @@ const generateSchemaBundle = (schema, options = {}) => {
     const defs = schema.$defs || {};
     const definitions = schema.definitions || {};
     const defNames = Object.keys(defs);
-    const { rootName, rootTypeName, defInfoMap } = buildBundleContext(defNames, defs, options);
+    const { rootName, rootTypeName, defInfoMap, groups } = buildBundleContext(defNames, defs, options);
     const files = [];
-    const targets = planBundleTargets(schema, defs, definitions, defNames, options, rootName, rootTypeName);
+    const targets = planBundleTargets(schema, defs, definitions, defNames, options, rootName, defInfoMap, rootTypeName);
     for (const target of targets) {
         const usedRefs = target.usedRefs;
-        const analysis = (0, analyzeSchema_js_1.analyzeSchema)(target.schemaWithDefs, {
-            ...options,
-            module,
-            name: target.schemaName,
-            type: target.typeName,
-            parserOverride: createRefHandler(target.defName, defInfoMap, usedRefs, {
-                ...(target.schemaWithDefs.$defs || {}),
-                ...(target.schemaWithDefs.definitions || {}),
-            }, options),
-        });
-        const zodSchema = (0, emitZod_js_1.emitZod)(analysis);
-        const finalSchema = buildSchemaFile(zodSchema, usedRefs, defInfoMap, module);
+        const zodParts = [];
+        for (const member of target.members) {
+            const analysis = (0, analyzeSchema_js_1.analyzeSchema)(member.schemaWithDefs, {
+                ...options,
+                module,
+                name: member.schemaName,
+                type: member.typeName,
+                parserOverride: createRefHandler(member.defName, defInfoMap, usedRefs, {
+                    ...(member.schemaWithDefs.$defs || {}),
+                    ...(member.schemaWithDefs.definitions || {}),
+                }, options, target.groupId),
+            });
+            const zodSchema = (0, emitZod_js_1.emitZod)(analysis);
+            zodParts.push(zodSchema);
+        }
+        const finalSchema = buildSchemaFile(zodParts, usedRefs, defInfoMap, module, target);
         files.push({ fileName: target.fileName, contents: finalSchema });
     }
     // Nested types extraction (optional)
@@ -57,13 +61,16 @@ const buildDefInfoMap = (defNames, defs, options) => {
         const pascalName = toPascalCase(defName);
         const schemaName = options.splitDefs?.schemaName?.(defName, { isRoot: false }) ?? `${pascalName}Schema`;
         const typeName = options.splitDefs?.typeName?.(defName, { isRoot: false }) ?? pascalName;
+        const fileName = options.splitDefs?.fileName?.(defName, { isRoot: false }) ?? `${defName}.schema.ts`;
         map.set(defName, {
             name: defName,
             pascalName,
             schemaName,
             typeName,
+            fileName,
             dependencies,
             hasCycle: false,
+            groupId: "",
         });
     }
     return map;
@@ -76,13 +83,21 @@ const buildBundleContext = (defNames, defs, options) => {
         if (info)
             info.hasCycle = true;
     }
+    const groups = buildSccGroups(defInfoMap);
+    for (const [groupId, members] of groups) {
+        for (const defName of members) {
+            const info = defInfoMap.get(defName);
+            if (info)
+                info.groupId = groupId;
+        }
+    }
     const rootName = options.splitDefs?.rootName ?? options.name ?? "RootSchema";
     const rootTypeName = typeof options.type === "string"
         ? options.type
         : options.splitDefs?.rootTypeName ?? (typeof options.type === "boolean" && options.type ? rootName : undefined);
-    return { defInfoMap, rootName, rootTypeName };
+    return { defInfoMap, rootName, rootTypeName, groups };
 };
-const createRefHandler = (currentDefName, defInfoMap, usedRefs, allDefs, options) => {
+const createRefHandler = (currentDefName, defInfoMap, usedRefs, allDefs, options, currentGroupId) => {
     const useLazyCrossRefs = options.refResolution?.lazyCrossRefs ?? true;
     return (schema, refs) => {
         if (typeof schema["$ref"] === "string") {
@@ -97,7 +112,7 @@ const createRefHandler = (currentDefName, defInfoMap, usedRefs, allDefs, options
                 const refInfo = defInfoMap.get(refName);
                 if (refInfo) {
                     // Track imports when referencing other defs
-                    if (refName !== currentDefName) {
+                    if (refName !== currentDefName && refInfo.groupId !== currentGroupId) {
                         usedRefs.add(refName);
                     }
                     const isCycle = refName === currentDefName || (refInfo.hasCycle && !!currentDefName);
@@ -111,6 +126,13 @@ const createRefHandler = (currentDefName, defInfoMap, usedRefs, allDefs, options
                     if (resolved)
                         return resolved;
                     if (isCycle && useLazyCrossRefs) {
+                        const inObjectProperty = refs.path.includes("properties") ||
+                            refs.path.includes("patternProperties") ||
+                            refs.path.includes("additionalProperties");
+                        if (inObjectProperty && refName === currentDefName) {
+                            // Self-recursion inside object getters can safely reference the schema name
+                            return refInfo.schemaName;
+                        }
                         return `z.lazy(() => ${refInfo.schemaName})`;
                     }
                     return refInfo.schemaName;
@@ -129,42 +151,73 @@ const createRefHandler = (currentDefName, defInfoMap, usedRefs, allDefs, options
         return undefined;
     };
 };
-const buildSchemaFile = (zodCode, usedRefs, defInfoMap, module) => {
+const buildSchemaFile = (zodCodeParts, usedRefs, defInfoMap, module, target) => {
     if (module !== "esm")
-        return zodCode;
-    const imports = [];
+        return zodCodeParts.join("\n");
+    const groupFileById = new Map();
+    for (const info of defInfoMap.values()) {
+        if (!groupFileById.has(info.groupId)) {
+            groupFileById.set(info.groupId, info.fileName.replace(/\.ts$/, ".js"));
+        }
+    }
+    const importsByFile = new Map();
     for (const refName of [...usedRefs].sort()) {
         const refInfo = defInfoMap.get(refName);
         if (refInfo) {
-            imports.push(`import { ${refInfo.schemaName} } from './${refName}.schema.js';`);
+            const groupFile = groupFileById.get(refInfo.groupId) ?? refInfo.fileName.replace(/\.ts$/, ".js");
+            const path = `./${groupFile}`;
+            const set = importsByFile.get(path) ?? new Set();
+            set.add(refInfo.schemaName);
+            importsByFile.set(path, set);
         }
     }
-    if (!imports.length)
-        return zodCode;
-    return zodCode.replace('import { z } from "zod"', `import { z } from "zod"\n${imports.join("\n")}`);
+    const imports = [];
+    for (const [path, names] of [...importsByFile.entries()].sort(([a], [b]) => a.localeCompare(b))) {
+        imports.push(`import { ${[...names].sort().join(", ")} } from '${path}';`);
+    }
+    const body = zodCodeParts
+        .map((code, idx) => {
+        if (idx === 0)
+            return code;
+        return code.replace(/^import \{ z \} from "zod"\n?/, "");
+    })
+        .join("\n");
+    return imports.length
+        ? body.replace('import { z } from "zod"', `import { z } from "zod"\n${imports.join("\n")}`)
+        : body;
 };
-const planBundleTargets = (rootSchema, defs, definitions, defNames, options, rootName, rootTypeName) => {
+const planBundleTargets = (rootSchema, defs, definitions, defNames, options, rootName, defInfoMap, rootTypeName) => {
     const targets = [];
+    const groupById = new Map();
     for (const defName of defNames) {
-        const defSchema = defs[defName];
-        const defSchemaWithDefs = {
-            ...defSchema,
-            $defs: { ...defs, ...defSchema?.$defs },
-            definitions: {
-                ...defSchema.definitions,
-                ...definitions,
-            },
-        };
-        const pascalName = toPascalCase(defName);
-        const schemaName = options.splitDefs?.schemaName?.(defName, { isRoot: false }) ?? `${pascalName}Schema`;
-        const typeName = options.splitDefs?.typeName?.(defName, { isRoot: false }) ?? pascalName;
-        const fileName = options.splitDefs?.fileName?.(defName, { isRoot: false }) ?? `${defName}.schema.ts`;
+        const info = defInfoMap.get(defName);
+        const gid = info?.groupId || defName;
+        if (!groupById.has(gid))
+            groupById.set(gid, []);
+        groupById.get(gid).push(defName);
+    }
+    for (const [groupId, memberDefs] of groupById.entries()) {
+        const orderedDefs = orderGroupMembers(memberDefs, defInfoMap);
+        const members = orderedDefs.map((defName) => {
+            const defSchema = defs[defName];
+            const defSchemaWithDefs = {
+                ...defSchema,
+                $defs: { ...defs, ...defSchema?.$defs },
+                definitions: {
+                    ...defSchema.definitions,
+                    ...definitions,
+                },
+            };
+            const pascalName = toPascalCase(defName);
+            const schemaName = options.splitDefs?.schemaName?.(defName, { isRoot: false }) ?? `${pascalName}Schema`;
+            const typeName = options.splitDefs?.typeName?.(defName, { isRoot: false }) ?? pascalName;
+            return { defName, schemaWithDefs: defSchemaWithDefs, schemaName, typeName };
+        });
+        const fileName = defInfoMap.get(memberDefs[0])?.fileName ?? `${memberDefs[0]}.schema.ts`;
         targets.push({
-            defName,
-            schemaWithDefs: defSchemaWithDefs,
-            schemaName,
-            typeName,
+            groupId,
             fileName,
+            members,
             usedRefs: new Set(),
             isRoot: false,
         });
@@ -172,17 +225,22 @@ const planBundleTargets = (rootSchema, defs, definitions, defNames, options, roo
     if (options.splitDefs?.includeRoot ?? true) {
         const rootFile = options.splitDefs?.fileName?.("root", { isRoot: true }) ?? "workflow.schema.ts";
         targets.push({
-            defName: null,
-            schemaWithDefs: {
-                ...rootSchema,
-                definitions: {
-                    ...rootSchema.definitions,
-                    ...definitions,
-                },
-            },
-            schemaName: rootName,
-            typeName: rootTypeName,
+            groupId: "root",
             fileName: rootFile,
+            members: [
+                {
+                    defName: null,
+                    schemaWithDefs: {
+                        ...rootSchema,
+                        definitions: {
+                            ...rootSchema.definitions,
+                            ...definitions,
+                        },
+                    },
+                    schemaName: rootName,
+                    typeName: rootTypeName,
+                },
+            ],
             usedRefs: new Set(),
             isRoot: true,
         });
@@ -213,6 +271,35 @@ const findRefDependencies = (schema, validDefNames) => {
     traverse(schema);
     return deps;
 };
+const orderGroupMembers = (defs, defInfoMap) => {
+    const inGroup = new Set(defs);
+    const visited = new Set();
+    const temp = new Set();
+    const result = [];
+    const visit = (name) => {
+        if (visited.has(name))
+            return;
+        if (temp.has(name)) {
+            return;
+        }
+        temp.add(name);
+        const info = defInfoMap.get(name);
+        if (info) {
+            for (const dep of info.dependencies) {
+                if (inGroup.has(dep)) {
+                    visit(dep);
+                }
+            }
+        }
+        temp.delete(name);
+        visited.add(name);
+        result.push(name);
+    };
+    for (const name of defs) {
+        visit(name);
+    }
+    return result;
+};
 const detectCycles = (defInfoMap) => {
     const cycleNodes = new Set();
     const visited = new Set();
@@ -246,6 +333,52 @@ const detectCycles = (defInfoMap) => {
     }
     return cycleNodes;
 };
+const buildSccGroups = (defInfoMap) => {
+    const indexMap = new Map();
+    const lowLink = new Map();
+    const onStack = new Set();
+    const stack = [];
+    let index = 0;
+    const groups = new Map();
+    const strongConnect = (node) => {
+        indexMap.set(node, index);
+        lowLink.set(node, index);
+        index += 1;
+        stack.push(node);
+        onStack.add(node);
+        const info = defInfoMap.get(node);
+        if (info) {
+            for (const dep of info.dependencies) {
+                if (!indexMap.has(dep)) {
+                    strongConnect(dep);
+                    lowLink.set(node, Math.min(lowLink.get(node), lowLink.get(dep)));
+                }
+                else if (onStack.has(dep)) {
+                    lowLink.set(node, Math.min(lowLink.get(node), indexMap.get(dep)));
+                }
+            }
+        }
+        if (lowLink.get(node) === indexMap.get(node)) {
+            const members = [];
+            let w;
+            do {
+                w = stack.pop();
+                if (w) {
+                    onStack.delete(w);
+                    members.push(w);
+                }
+            } while (w && w !== node);
+            const groupId = members.sort().join("__");
+            groups.set(groupId, members);
+        }
+    };
+    for (const name of defInfoMap.keys()) {
+        if (!indexMap.has(name)) {
+            strongConnect(name);
+        }
+    }
+    return groups;
+};
 const collectNestedTypes = (rootSchema, defs, defNames, rootTypeName) => {
     const allNestedTypes = [];
     for (const defName of defNames) {
@@ -321,6 +454,26 @@ const generateNestedTypesFile = (nestedTypes) => {
         " * They are extracted using TypeScript indexed access types.",
         " */",
         "",
+        "type Access<T, P extends readonly (string | number)[]> =",
+        "  P extends []",
+        "    ? NonNullable<T>",
+        "    : P extends readonly [infer H, ...infer R]",
+        "      ? H extends \"items\"",
+        "        ? Access<NonNullable<T> extends Array<infer U> ? U : unknown, Extract<R, (string | number)[]>>",
+        "        : H extends \"additionalProperties\"",
+        "          ? Access<NonNullable<T> extends Record<string, infer V> ? V : unknown, Extract<R, (string | number)[]>>",
+        "          : H extends number",
+        "            ? Access<NonNullable<T> extends Array<infer U> ? U : unknown, Extract<R, (string | number)[]>>",
+        "            : H extends string",
+        "              ? Access<",
+        "                  H extends keyof NonNullable<T>",
+        "                    ? NonNullable<NonNullable<T>[H]>",
+        "                    : unknown,",
+        "                  Extract<R, (string | number)[]>",
+        "                >",
+        "              : unknown",
+        "      : unknown;",
+        "",
     ];
     const byParent = new Map();
     for (const info of nestedTypes) {
@@ -340,16 +493,8 @@ const generateNestedTypesFile = (nestedTypes) => {
     }
     lines.push("");
     const buildAccessExpr = (parentType, propertyPath) => {
-        let accessExpr = parentType;
-        for (const prop of propertyPath) {
-            const accessor = prop === "items"
-                ? "[number]"
-                : typeof prop === "number"
-                    ? `[${prop}]`
-                    : `[${JSON.stringify(prop)}]`;
-            accessExpr = `NonNullable<${accessExpr}${accessor}>`;
-        }
-        return accessExpr;
+        const path = propertyPath.map((prop) => (typeof prop === "number" ? prop : JSON.stringify(prop))).join(", ");
+        return `Access<${parentType}, [${path}]>`;
     };
     for (const [parentType, types] of [...byParent.entries()].sort()) {
         lines.push(`// From ${parentType}`);

package/dist/cjs/parsers/parseIfThenElse.js

@@ -18,7 +18,7 @@ const parseIfThenElse = (schema, refs) => {
     : ${$else}.safeParse(value);
   if (!result.success) {
     const issues = result.error.issues;
-    issues.forEach((issue) => ctx.addIssue(issue))
+    issues.forEach((issue) => ctx.addIssue({ ...issue }))
   }
 })`;
     // Store original if/then/else for JSON Schema round-trip

package/dist/cjs/parsers/parseObject.js

@@ -311,5 +311,8 @@ const shouldUseGetter = (parsed, refs) => {
     if (refs.currentSchemaName && parsed.includes(refs.currentSchemaName)) {
         return true;
     }
+    if (refs.cycleRefNames?.has(parsed)) {
+        return true;
+    }
     return Boolean(refs.inProgress && refs.inProgress.has(parsed));
 };

package/dist/cjs/parsers/parseSchema.js

@@ -124,6 +124,14 @@ const parseRef = (schema, refs) => {
     // (or is currently being resolved). This avoids TDZ on true cycles while
     // letting ordered, acyclic refs stay direct.
     if (isSameCycle || refs.inProgress.has(refName)) {
+        const inObjectProperty = refs.path.includes("properties") ||
+            refs.path.includes("patternProperties") ||
+            refs.path.includes("additionalProperties");
+        if (inObjectProperty && refName === refs.currentSchemaName) {
+            // Getter properties defer evaluation, so a direct reference avoids extra lazies
+            // for self-recursion.
+            return refName;
+        }
         return `z.lazy(() => ${refName})`;
     }
     return refName;

package/dist/esm/core/emitZod.js

@@ -70,6 +70,16 @@ export const emitZod = (analysis) => {
     const { module, name, type, noImport, exportRefs, withMeta, ...rest } = options;
     const declarations = new Map();
     const dependencies = new Map();
+    const reserveName = (base) => {
+        let candidate = base;
+        let i = 1;
+        while (usedNames.has(candidate) || declarations.has(candidate)) {
+            candidate = `${base}${i}`;
+            i += 1;
+        }
+        usedNames.add(candidate);
+        return candidate;
+    };
     const parsedSchema = parseSchema(schema, {
         module,
         name,
@@ -91,10 +101,16 @@ export const emitZod = (analysis) => {
     });
     const declarationBlock = declarations.size
         ? orderDeclarations(Array.from(declarations.entries()), dependencies)
-            .map(([refName, value]) => {
+            .flatMap(([refName, value]) => {
             const shouldExport = exportRefs && module === "esm";
-            const decl = `${shouldExport ? "export " : ""}const ${refName} = ${value}`;
-            return decl;
+            const isCycle = cycleRefNames.has(refName);
+            if (!isCycle) {
+                return [`${shouldExport ? "export " : ""}const ${refName} = ${value}`];
+            }
+            const baseName = `${refName}Def`;
+            const lines = [`const ${baseName} = ${value}`];
+            lines.push(`${shouldExport ? "export " : ""}const ${refName} = ${baseName}`);
+            return lines;
         })
             .join("\n")
         : "";

package/dist/esm/generators/generateBundle.js

@@ -8,23 +8,27 @@ export const generateSchemaBundle = (schema, options = {}) => {
     const defs = schema.$defs || {};
     const definitions = schema.definitions || {};
     const defNames = Object.keys(defs);
-    const { rootName, rootTypeName, defInfoMap } = buildBundleContext(defNames, defs, options);
+    const { rootName, rootTypeName, defInfoMap, groups } = buildBundleContext(defNames, defs, options);
     const files = [];
-    const targets = planBundleTargets(schema, defs, definitions, defNames, options, rootName, rootTypeName);
+    const targets = planBundleTargets(schema, defs, definitions, defNames, options, rootName, defInfoMap, rootTypeName);
     for (const target of targets) {
         const usedRefs = target.usedRefs;
-        const analysis = analyzeSchema(target.schemaWithDefs, {
-            ...options,
-            module,
-            name: target.schemaName,
-            type: target.typeName,
-            parserOverride: createRefHandler(target.defName, defInfoMap, usedRefs, {
-                ...(target.schemaWithDefs.$defs || {}),
-                ...(target.schemaWithDefs.definitions || {}),
-            }, options),
-        });
-        const zodSchema = emitZod(analysis);
-        const finalSchema = buildSchemaFile(zodSchema, usedRefs, defInfoMap, module);
+        const zodParts = [];
+        for (const member of target.members) {
+            const analysis = analyzeSchema(member.schemaWithDefs, {
+                ...options,
+                module,
+                name: member.schemaName,
+                type: member.typeName,
+                parserOverride: createRefHandler(member.defName, defInfoMap, usedRefs, {
+                    ...(member.schemaWithDefs.$defs || {}),
+                    ...(member.schemaWithDefs.definitions || {}),
+                }, options, target.groupId),
+            });
+            const zodSchema = emitZod(analysis);
+            zodParts.push(zodSchema);
+        }
+        const finalSchema = buildSchemaFile(zodParts, usedRefs, defInfoMap, module, target);
         files.push({ fileName: target.fileName, contents: finalSchema });
     }
     // Nested types extraction (optional)
@@ -53,13 +57,16 @@ const buildDefInfoMap = (defNames, defs, options) => {
         const pascalName = toPascalCase(defName);
         const schemaName = options.splitDefs?.schemaName?.(defName, { isRoot: false }) ?? `${pascalName}Schema`;
         const typeName = options.splitDefs?.typeName?.(defName, { isRoot: false }) ?? pascalName;
+        const fileName = options.splitDefs?.fileName?.(defName, { isRoot: false }) ?? `${defName}.schema.ts`;
         map.set(defName, {
             name: defName,
             pascalName,
             schemaName,
             typeName,
+            fileName,
             dependencies,
             hasCycle: false,
+            groupId: "",
         });
     }
     return map;
@@ -72,13 +79,21 @@ const buildBundleContext = (defNames, defs, options) => {
         if (info)
             info.hasCycle = true;
     }
+    const groups = buildSccGroups(defInfoMap);
+    for (const [groupId, members] of groups) {
+        for (const defName of members) {
+            const info = defInfoMap.get(defName);
+            if (info)
+                info.groupId = groupId;
+        }
+    }
     const rootName = options.splitDefs?.rootName ?? options.name ?? "RootSchema";
     const rootTypeName = typeof options.type === "string"
         ? options.type
         : options.splitDefs?.rootTypeName ?? (typeof options.type === "boolean" && options.type ? rootName : undefined);
-    return { defInfoMap, rootName, rootTypeName };
+    return { defInfoMap, rootName, rootTypeName, groups };
 };
-const createRefHandler = (currentDefName, defInfoMap, usedRefs, allDefs, options) => {
+const createRefHandler = (currentDefName, defInfoMap, usedRefs, allDefs, options, currentGroupId) => {
     const useLazyCrossRefs = options.refResolution?.lazyCrossRefs ?? true;
     return (schema, refs) => {
         if (typeof schema["$ref"] === "string") {
@@ -93,7 +108,7 @@ const createRefHandler = (currentDefName, defInfoMap, usedRefs, allDefs, options
                 const refInfo = defInfoMap.get(refName);
                 if (refInfo) {
                     // Track imports when referencing other defs
-                    if (refName !== currentDefName) {
+                    if (refName !== currentDefName && refInfo.groupId !== currentGroupId) {
                         usedRefs.add(refName);
                     }
                     const isCycle = refName === currentDefName || (refInfo.hasCycle && !!currentDefName);
@@ -107,6 +122,13 @@ const createRefHandler = (currentDefName, defInfoMap, usedRefs, allDefs, options
                     if (resolved)
                         return resolved;
                     if (isCycle && useLazyCrossRefs) {
+                        const inObjectProperty = refs.path.includes("properties") ||
+                            refs.path.includes("patternProperties") ||
+                            refs.path.includes("additionalProperties");
+                        if (inObjectProperty && refName === currentDefName) {
+                            // Self-recursion inside object getters can safely reference the schema name
+                            return refInfo.schemaName;
+                        }
                         return `z.lazy(() => ${refInfo.schemaName})`;
                     }
                     return refInfo.schemaName;
@@ -125,42 +147,73 @@ const createRefHandler = (currentDefName, defInfoMap, usedRefs, allDefs, options
         return undefined;
     };
 };
-const buildSchemaFile = (zodCode, usedRefs, defInfoMap, module) => {
+const buildSchemaFile = (zodCodeParts, usedRefs, defInfoMap, module, target) => {
     if (module !== "esm")
-        return zodCode;
-    const imports = [];
+        return zodCodeParts.join("\n");
+    const groupFileById = new Map();
+    for (const info of defInfoMap.values()) {
+        if (!groupFileById.has(info.groupId)) {
+            groupFileById.set(info.groupId, info.fileName.replace(/\.ts$/, ".js"));
+        }
+    }
+    const importsByFile = new Map();
     for (const refName of [...usedRefs].sort()) {
         const refInfo = defInfoMap.get(refName);
         if (refInfo) {
-            imports.push(`import { ${refInfo.schemaName} } from './${refName}.schema.js';`);
+            const groupFile = groupFileById.get(refInfo.groupId) ?? refInfo.fileName.replace(/\.ts$/, ".js");
+            const path = `./${groupFile}`;
+            const set = importsByFile.get(path) ?? new Set();
+            set.add(refInfo.schemaName);
+            importsByFile.set(path, set);
         }
     }
-    if (!imports.length)
-        return zodCode;
-    return zodCode.replace('import { z } from "zod"', `import { z } from "zod"\n${imports.join("\n")}`);
+    const imports = [];
+    for (const [path, names] of [...importsByFile.entries()].sort(([a], [b]) => a.localeCompare(b))) {
+        imports.push(`import { ${[...names].sort().join(", ")} } from '${path}';`);
+    }
+    const body = zodCodeParts
+        .map((code, idx) => {
+        if (idx === 0)
+            return code;
+        return code.replace(/^import \{ z \} from "zod"\n?/, "");
+    })
+        .join("\n");
+    return imports.length
+        ? body.replace('import { z } from "zod"', `import { z } from "zod"\n${imports.join("\n")}`)
+        : body;
 };
-const planBundleTargets = (rootSchema, defs, definitions, defNames, options, rootName, rootTypeName) => {
+const planBundleTargets = (rootSchema, defs, definitions, defNames, options, rootName, defInfoMap, rootTypeName) => {
     const targets = [];
+    const groupById = new Map();
     for (const defName of defNames) {
-        const defSchema = defs[defName];
-        const defSchemaWithDefs = {
-            ...defSchema,
-            $defs: { ...defs, ...defSchema?.$defs },
-            definitions: {
-                ...defSchema.definitions,
-                ...definitions,
-            },
-        };
-        const pascalName = toPascalCase(defName);
-        const schemaName = options.splitDefs?.schemaName?.(defName, { isRoot: false }) ?? `${pascalName}Schema`;
-        const typeName = options.splitDefs?.typeName?.(defName, { isRoot: false }) ?? pascalName;
-        const fileName = options.splitDefs?.fileName?.(defName, { isRoot: false }) ?? `${defName}.schema.ts`;
+        const info = defInfoMap.get(defName);
+        const gid = info?.groupId || defName;
+        if (!groupById.has(gid))
+            groupById.set(gid, []);
+        groupById.get(gid).push(defName);
+    }
+    for (const [groupId, memberDefs] of groupById.entries()) {
+        const orderedDefs = orderGroupMembers(memberDefs, defInfoMap);
+        const members = orderedDefs.map((defName) => {
+            const defSchema = defs[defName];
+            const defSchemaWithDefs = {
+                ...defSchema,
+                $defs: { ...defs, ...defSchema?.$defs },
+                definitions: {
+                    ...defSchema.definitions,
+                    ...definitions,
+                },
+            };
+            const pascalName = toPascalCase(defName);
+            const schemaName = options.splitDefs?.schemaName?.(defName, { isRoot: false }) ?? `${pascalName}Schema`;
+            const typeName = options.splitDefs?.typeName?.(defName, { isRoot: false }) ?? pascalName;
+            return { defName, schemaWithDefs: defSchemaWithDefs, schemaName, typeName };
+        });
+        const fileName = defInfoMap.get(memberDefs[0])?.fileName ?? `${memberDefs[0]}.schema.ts`;
         targets.push({
-            defName,
-            schemaWithDefs: defSchemaWithDefs,
-            schemaName,
-            typeName,
+            groupId,
             fileName,
+            members,
             usedRefs: new Set(),
             isRoot: false,
         });
@@ -168,17 +221,22 @@ const planBundleTargets = (rootSchema, defs, definitions, defNames, options, roo
     if (options.splitDefs?.includeRoot ?? true) {
         const rootFile = options.splitDefs?.fileName?.("root", { isRoot: true }) ?? "workflow.schema.ts";
         targets.push({
-            defName: null,
-            schemaWithDefs: {
-                ...rootSchema,
-                definitions: {
-                    ...rootSchema.definitions,
-                    ...definitions,
-                },
-            },
-            schemaName: rootName,
-            typeName: rootTypeName,
+            groupId: "root",
             fileName: rootFile,
+            members: [
+                {
+                    defName: null,
+                    schemaWithDefs: {
+                        ...rootSchema,
+                        definitions: {
+                            ...rootSchema.definitions,
+                            ...definitions,
+                        },
+                    },
+                    schemaName: rootName,
+                    typeName: rootTypeName,
+                },
+            ],
             usedRefs: new Set(),
             isRoot: true,
         });
@@ -209,6 +267,35 @@ const findRefDependencies = (schema, validDefNames) => {
     traverse(schema);
     return deps;
 };
+const orderGroupMembers = (defs, defInfoMap) => {
+    const inGroup = new Set(defs);
+    const visited = new Set();
+    const temp = new Set();
+    const result = [];
+    const visit = (name) => {
+        if (visited.has(name))
+            return;
+        if (temp.has(name)) {
+            return;
+        }
+        temp.add(name);
+        const info = defInfoMap.get(name);
+        if (info) {
+            for (const dep of info.dependencies) {
+                if (inGroup.has(dep)) {
+                    visit(dep);
+                }
+            }
+        }
+        temp.delete(name);
+        visited.add(name);
+        result.push(name);
+    };
+    for (const name of defs) {
+        visit(name);
+    }
+    return result;
+};
 const detectCycles = (defInfoMap) => {
     const cycleNodes = new Set();
     const visited = new Set();
@@ -242,6 +329,52 @@ const detectCycles = (defInfoMap) => {
     }
     return cycleNodes;
 };
+const buildSccGroups = (defInfoMap) => {
+    const indexMap = new Map();
+    const lowLink = new Map();
+    const onStack = new Set();
+    const stack = [];
+    let index = 0;
+    const groups = new Map();
+    const strongConnect = (node) => {
+        indexMap.set(node, index);
+        lowLink.set(node, index);
+        index += 1;
+        stack.push(node);
+        onStack.add(node);
+        const info = defInfoMap.get(node);
+        if (info) {
+            for (const dep of info.dependencies) {
+                if (!indexMap.has(dep)) {
+                    strongConnect(dep);
+                    lowLink.set(node, Math.min(lowLink.get(node), lowLink.get(dep)));
+                }
+                else if (onStack.has(dep)) {
+                    lowLink.set(node, Math.min(lowLink.get(node), indexMap.get(dep)));
+                }
+            }
+        }
+        if (lowLink.get(node) === indexMap.get(node)) {
+            const members = [];
+            let w;
+            do {
+                w = stack.pop();
+                if (w) {
+                    onStack.delete(w);
+                    members.push(w);
+                }
+            } while (w && w !== node);
+            const groupId = members.sort().join("__");
+            groups.set(groupId, members);
+        }
+    };
+    for (const name of defInfoMap.keys()) {
+        if (!indexMap.has(name)) {
+            strongConnect(name);
+        }
+    }
+    return groups;
+};
 const collectNestedTypes = (rootSchema, defs, defNames, rootTypeName) => {
     const allNestedTypes = [];
     for (const defName of defNames) {
@@ -317,6 +450,26 @@ const generateNestedTypesFile = (nestedTypes) => {
         " * They are extracted using TypeScript indexed access types.",
         " */",
         "",
+        "type Access<T, P extends readonly (string | number)[]> =",
+        "  P extends []",
+        "    ? NonNullable<T>",
+        "    : P extends readonly [infer H, ...infer R]",
+        "      ? H extends \"items\"",
+        "        ? Access<NonNullable<T> extends Array<infer U> ? U : unknown, Extract<R, (string | number)[]>>",
+        "        : H extends \"additionalProperties\"",
+        "          ? Access<NonNullable<T> extends Record<string, infer V> ? V : unknown, Extract<R, (string | number)[]>>",
+        "          : H extends number",
+        "            ? Access<NonNullable<T> extends Array<infer U> ? U : unknown, Extract<R, (string | number)[]>>",
+        "            : H extends string",
+        "              ? Access<",
+        "                  H extends keyof NonNullable<T>",
+        "                    ? NonNullable<NonNullable<T>[H]>",
+        "                    : unknown,",
+        "                  Extract<R, (string | number)[]>",
+        "                >",
+        "              : unknown",
+        "      : unknown;",
+        "",
     ];
     const byParent = new Map();
     for (const info of nestedTypes) {
@@ -336,16 +489,8 @@ const generateNestedTypesFile = (nestedTypes) => {
     }
     lines.push("");
     const buildAccessExpr = (parentType, propertyPath) => {
-        let accessExpr = parentType;
-        for (const prop of propertyPath) {
-            const accessor = prop === "items"
-                ? "[number]"
-                : typeof prop === "number"
-                    ? `[${prop}]`
-                    : `[${JSON.stringify(prop)}]`;
-            accessExpr = `NonNullable<${accessExpr}${accessor}>`;
-        }
-        return accessExpr;
+        const path = propertyPath.map((prop) => (typeof prop === "number" ? prop : JSON.stringify(prop))).join(", ");
+        return `Access<${parentType}, [${path}]>`;
     };
     for (const [parentType, types] of [...byParent.entries()].sort()) {
         lines.push(`// From ${parentType}`);

package/dist/esm/parsers/parseIfThenElse.js

@@ -15,7 +15,7 @@ export const parseIfThenElse = (schema, refs) => {
     : ${$else}.safeParse(value);
   if (!result.success) {
     const issues = result.error.issues;
-    issues.forEach((issue) => ctx.addIssue(issue))
+    issues.forEach((issue) => ctx.addIssue({ ...issue }))
   }
 })`;
     // Store original if/then/else for JSON Schema round-trip

package/dist/esm/parsers/parseObject.js

@@ -308,5 +308,8 @@ const shouldUseGetter = (parsed, refs) => {
     if (refs.currentSchemaName && parsed.includes(refs.currentSchemaName)) {
         return true;
     }
+    if (refs.cycleRefNames?.has(parsed)) {
+        return true;
+    }
     return Boolean(refs.inProgress && refs.inProgress.has(parsed));
 };

package/dist/esm/parsers/parseSchema.js

@@ -120,6 +120,14 @@ const parseRef = (schema, refs) => {
     // (or is currently being resolved). This avoids TDZ on true cycles while
     // letting ordered, acyclic refs stay direct.
     if (isSameCycle || refs.inProgress.has(refName)) {
+        const inObjectProperty = refs.path.includes("properties") ||
+            refs.path.includes("patternProperties") ||
+            refs.path.includes("additionalProperties");
+        if (inObjectProperty && refName === refs.currentSchemaName) {
+            // Getter properties defer evaluation, so a direct reference avoids extra lazies
+            // for self-recursion.
+            return refName;
+        }
         return `z.lazy(() => ${refName})`;
     }
     return refName;

package/package.json

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