@gabrielbryk/json-schema-to-zod 2.7.4 → 2.9.0

package/dist/esm/core/emitZod.js

@@ -0,0 +1,137 @@
+import { parseSchema } from "../parsers/parseSchema.js";
+import { expandJsdocs } from "../utils/jsdocs.js";
+const orderDeclarations = (entries, dependencies) => {
+    const valueByName = new Map(entries);
+    const depGraph = new Map();
+    for (const [from, set] of dependencies.entries()) {
+        const onlyKnown = new Set();
+        for (const dep of set) {
+            if (valueByName.has(dep) && dep !== from) {
+                onlyKnown.add(dep);
+            }
+        }
+        if (onlyKnown.size)
+            depGraph.set(from, onlyKnown);
+    }
+    const names = Array.from(valueByName.keys());
+    for (const [name, value] of entries) {
+        const deps = depGraph.get(name) ?? new Set();
+        for (const candidate of names) {
+            if (candidate === name)
+                continue;
+            const matcher = new RegExp(`\\b${candidate}\\b`);
+            if (matcher.test(value)) {
+                deps.add(candidate);
+            }
+        }
+        if (deps.size)
+            depGraph.set(name, deps);
+    }
+    const ordered = [];
+    const perm = new Set();
+    const temp = new Set();
+    const visit = (name) => {
+        if (perm.has(name))
+            return;
+        if (temp.has(name)) {
+            temp.delete(name);
+            perm.add(name);
+            ordered.push(name);
+            return;
+        }
+        temp.add(name);
+        const deps = depGraph.get(name);
+        if (deps) {
+            for (const dep of deps) {
+                if (valueByName.has(dep)) {
+                    visit(dep);
+                }
+            }
+        }
+        temp.delete(name);
+        perm.add(name);
+        ordered.push(name);
+    };
+    for (const name of valueByName.keys()) {
+        visit(name);
+    }
+    const unique = [];
+    const seen = new Set();
+    for (const name of ordered) {
+        if (!seen.has(name)) {
+            seen.add(name);
+            unique.push(name);
+        }
+    }
+    return unique.map((name) => [name, valueByName.get(name)]);
+};
+export const emitZod = (analysis) => {
+    const { schema, options, refNameByPointer, usedNames, cycleRefNames, cycleComponentByName, } = analysis;
+    const { module, name, type, noImport, exportRefs, withMeta, ...rest } = options;
+    const declarations = new Map();
+    const dependencies = new Map();
+    const parsedSchema = parseSchema(schema, {
+        module,
+        name,
+        path: [],
+        seen: new Map(),
+        declarations,
+        dependencies,
+        inProgress: new Set(),
+        refNameByPointer,
+        usedNames,
+        root: schema,
+        currentSchemaName: name,
+        cycleRefNames,
+        cycleComponentByName,
+        refRegistry: analysis.refRegistry,
+        rootBaseUri: analysis.rootBaseUri,
+        ...rest,
+        withMeta,
+    });
+    const declarationBlock = declarations.size
+        ? orderDeclarations(Array.from(declarations.entries()), dependencies)
+            .map(([refName, value]) => {
+            const shouldExport = exportRefs && module === "esm";
+            const decl = `${shouldExport ? "export " : ""}const ${refName} = ${value}`;
+            return decl;
+        })
+            .join("\n")
+        : "";
+    const jsdocs = rest.withJsdocs && typeof schema !== "boolean" && schema.description
+        ? expandJsdocs(schema.description)
+        : "";
+    const lines = [];
+    if (module === "cjs" && !noImport) {
+        lines.push(`const { z } = require("zod")`);
+    }
+    if (module === "esm" && !noImport) {
+        lines.push(`import { z } from "zod"`);
+    }
+    if (declarationBlock) {
+        lines.push(declarationBlock);
+    }
+    if (module === "cjs") {
+        const payload = name ? `{ ${JSON.stringify(name)}: ${parsedSchema} }` : parsedSchema;
+        lines.push(`${jsdocs}module.exports = ${payload}`);
+    }
+    else if (module === "esm") {
+        const exportLine = `${jsdocs}export ${name ? `const ${name} =` : `default`} ${parsedSchema}`;
+        lines.push(exportLine);
+    }
+    else if (name) {
+        lines.push(`${jsdocs}const ${name} = ${parsedSchema}`);
+    }
+    else {
+        lines.push(`${jsdocs}${parsedSchema}`);
+    }
+    let typeLine;
+    if (type && name) {
+        const typeName = typeof type === "string" ? type : `${name[0].toUpperCase()}${name.substring(1)}`;
+        typeLine = `export type ${typeName} = z.infer<typeof ${name}>`;
+    }
+    const joined = lines.filter(Boolean).join("\n\n");
+    const combined = typeLine ? `${joined}\n${typeLine}` : joined;
+    const shouldEndWithNewline = module === "esm" || module === "cjs";
+    return `${combined}${shouldEndWithNewline ? "\n" : ""}`;
+};

package/dist/esm/generators/generateBundle.js

@@ -0,0 +1,351 @@
+import { analyzeSchema } from "../core/analyzeSchema.js";
+import { emitZod } from "../core/emitZod.js";
+export const generateSchemaBundle = (schema, options = {}) => {
+    const module = options.module ?? "esm";
+    if (!schema || typeof schema !== "object") {
+        throw new Error("generateSchemaBundle requires an object schema");
+    }
+    const defs = schema.$defs || {};
+    const definitions = schema.definitions || {};
+    const defNames = Object.keys(defs);
+    const { rootName, rootTypeName, defInfoMap } = buildBundleContext(defNames, defs, options);
+    const files = [];
+    const targets = planBundleTargets(schema, defs, definitions, defNames, options, rootName, 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);
+        files.push({ fileName: target.fileName, contents: finalSchema });
+    }
+    // Nested types extraction (optional)
+    const nestedTypesEnabled = options.nestedTypes?.enable;
+    if (nestedTypesEnabled) {
+        const nestedTypes = collectNestedTypes(schema, defs, defNames, rootTypeName ?? rootName);
+        if (nestedTypes.length > 0) {
+            const nestedFileName = options.nestedTypes?.fileName ?? "nested-types.ts";
+            const nestedContent = generateNestedTypesFile(nestedTypes);
+            files.push({ fileName: nestedFileName, contents: nestedContent });
+        }
+    }
+    return { files, defNames };
+};
+// ---------------------------------------------------------------------------
+// Internals
+// ---------------------------------------------------------------------------
+const toPascalCase = (str) => str
+    .split(/[-_]/)
+    .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
+    .join("");
+const buildDefInfoMap = (defNames, defs, options) => {
+    const map = new Map();
+    for (const defName of defNames) {
+        const dependencies = findRefDependencies(defs[defName], defNames);
+        const pascalName = toPascalCase(defName);
+        const schemaName = options.splitDefs?.schemaName?.(defName, { isRoot: false }) ?? `${pascalName}Schema`;
+        const typeName = options.splitDefs?.typeName?.(defName, { isRoot: false }) ?? pascalName;
+        map.set(defName, {
+            name: defName,
+            pascalName,
+            schemaName,
+            typeName,
+            dependencies,
+            hasCycle: false,
+        });
+    }
+    return map;
+};
+const buildBundleContext = (defNames, defs, options) => {
+    const defInfoMap = buildDefInfoMap(defNames, defs, options);
+    const cycles = detectCycles(defInfoMap);
+    for (const defName of cycles) {
+        const info = defInfoMap.get(defName);
+        if (info)
+            info.hasCycle = true;
+    }
+    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 };
+};
+const createRefHandler = (currentDefName, defInfoMap, usedRefs, allDefs, options) => {
+    return (schema, refs) => {
+        if (typeof schema["$ref"] === "string") {
+            const refPath = schema["$ref"];
+            const match = refPath.match(/^#\/(?:\$defs|definitions)\/(.+)$/);
+            if (match) {
+                const refName = match[1];
+                // Only intercept top-level def refs (no nested path like a/$defs/x)
+                if (refName.includes("/")) {
+                    return undefined;
+                }
+                const refInfo = defInfoMap.get(refName);
+                if (refInfo) {
+                    // Track imports when referencing other defs
+                    if (refName !== currentDefName) {
+                        usedRefs.add(refName);
+                    }
+                    const isCycle = refName === currentDefName || (refInfo.hasCycle && !!currentDefName);
+                    const resolved = options.refResolution?.onRef?.({
+                        ref: refPath,
+                        refName,
+                        currentDef: currentDefName,
+                        path: refs.path,
+                        isCycle,
+                    });
+                    if (resolved)
+                        return resolved;
+                    if (isCycle && options.refResolution?.lazyCrossRefs) {
+                        return `z.lazy(() => ${refInfo.schemaName})`;
+                    }
+                    return refInfo.schemaName;
+                }
+                // If the ref points to a local/inline $def (not part of top-level defs),
+                // let the default parser resolve it normally.
+                if (allDefs && Object.prototype.hasOwnProperty.call(allDefs, refName)) {
+                    return undefined;
+                }
+            }
+            const unknown = options.refResolution?.onUnknownRef?.({ ref: refPath, currentDef: currentDefName });
+            if (unknown)
+                return unknown;
+            return options.useUnknown ? "z.unknown()" : "z.any()";
+        }
+        return undefined;
+    };
+};
+const buildSchemaFile = (zodCode, usedRefs, defInfoMap, module) => {
+    if (module !== "esm")
+        return zodCode;
+    const imports = [];
+    for (const refName of [...usedRefs].sort()) {
+        const refInfo = defInfoMap.get(refName);
+        if (refInfo) {
+            imports.push(`import { ${refInfo.schemaName} } from './${refName}.schema.js';`);
+        }
+    }
+    if (!imports.length)
+        return zodCode;
+    return zodCode.replace('import { z } from "zod"', `import { z } from "zod"\n${imports.join("\n")}`);
+};
+const planBundleTargets = (rootSchema, defs, definitions, defNames, options, rootName, rootTypeName) => {
+    const targets = [];
+    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`;
+        targets.push({
+            defName,
+            schemaWithDefs: defSchemaWithDefs,
+            schemaName,
+            typeName,
+            fileName,
+            usedRefs: new Set(),
+            isRoot: false,
+        });
+    }
+    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,
+            fileName: rootFile,
+            usedRefs: new Set(),
+            isRoot: true,
+        });
+    }
+    return targets;
+};
+const findRefDependencies = (schema, validDefNames) => {
+    const deps = new Set();
+    function traverse(obj) {
+        if (obj === null || typeof obj !== "object")
+            return;
+        if (Array.isArray(obj)) {
+            obj.forEach(traverse);
+            return;
+        }
+        const record = obj;
+        if (typeof record["$ref"] === "string") {
+            const ref = record["$ref"];
+            const match = ref.match(/^#\/(?:\$defs|definitions)\/(.+)$/);
+            if (match && validDefNames.includes(match[1])) {
+                deps.add(match[1]);
+            }
+        }
+        for (const value of Object.values(record)) {
+            traverse(value);
+        }
+    }
+    traverse(schema);
+    return deps;
+};
+const detectCycles = (defInfoMap) => {
+    const cycleNodes = new Set();
+    const visited = new Set();
+    const recursionStack = new Set();
+    function dfs(node, path) {
+        if (recursionStack.has(node)) {
+            const cycleStart = path.indexOf(node);
+            for (let i = cycleStart; i < path.length; i++) {
+                cycleNodes.add(path[i]);
+            }
+            cycleNodes.add(node);
+            return true;
+        }
+        if (visited.has(node))
+            return false;
+        visited.add(node);
+        recursionStack.add(node);
+        const info = defInfoMap.get(node);
+        if (info) {
+            for (const dep of info.dependencies) {
+                dfs(dep, [...path, node]);
+            }
+        }
+        recursionStack.delete(node);
+        return false;
+    }
+    for (const defName of defInfoMap.keys()) {
+        if (!visited.has(defName)) {
+            dfs(defName, []);
+        }
+    }
+    return cycleNodes;
+};
+const collectNestedTypes = (rootSchema, defs, defNames, rootTypeName) => {
+    const allNestedTypes = [];
+    for (const defName of defNames) {
+        const defSchema = defs[defName];
+        const parentTypeName = toPascalCase(defName);
+        const nestedTypes = findNestedTypesInSchema(defSchema, parentTypeName, defNames);
+        for (const nested of nestedTypes) {
+            nested.file = defName;
+            nested.parentType = parentTypeName;
+            allNestedTypes.push(nested);
+        }
+    }
+    const workflowNestedTypes = findNestedTypesInSchema({ properties: rootSchema.properties, required: rootSchema.required }, rootTypeName, defNames);
+    for (const nested of workflowNestedTypes) {
+        nested.file = "workflow";
+        nested.parentType = rootTypeName;
+        allNestedTypes.push(nested);
+    }
+    const uniqueNestedTypes = new Map();
+    for (const nested of allNestedTypes) {
+        if (!uniqueNestedTypes.has(nested.typeName) && nested.propertyPath.length > 0) {
+            uniqueNestedTypes.set(nested.typeName, nested);
+        }
+    }
+    return [...uniqueNestedTypes.values()];
+};
+const findNestedTypesInSchema = (schema, parentTypeName, defNames, currentPath = []) => {
+    const nestedTypes = [];
+    if (schema === null || typeof schema !== "object")
+        return nestedTypes;
+    const record = schema;
+    if (record.title && typeof record.title === "string") {
+        const title = record.title;
+        if (title !== parentTypeName && !defNames.map((d) => toPascalCase(d)).includes(title)) {
+            nestedTypes.push({
+                typeName: title,
+                parentType: parentTypeName,
+                propertyPath: [...currentPath],
+                file: "",
+            });
+        }
+    }
+    // inline $defs
+    if (record.$defs && typeof record.$defs === "object") {
+        for (const [_defName, defSchema] of Object.entries(record.$defs)) {
+            nestedTypes.push(...findNestedTypesInSchema(defSchema, parentTypeName, defNames, currentPath));
+        }
+    }
+    if (record.properties && typeof record.properties === "object") {
+        for (const [propName, propSchema] of Object.entries(record.properties)) {
+            nestedTypes.push(...findNestedTypesInSchema(propSchema, parentTypeName, defNames, [...currentPath, propName]));
+        }
+    }
+    if (Array.isArray(record.allOf)) {
+        for (const item of record.allOf) {
+            nestedTypes.push(...findNestedTypesInSchema(item, parentTypeName, defNames, currentPath));
+        }
+    }
+    if (record.items) {
+        nestedTypes.push(...findNestedTypesInSchema(record.items, parentTypeName, defNames, [...currentPath, "items"]));
+    }
+    if (record.additionalProperties && typeof record.additionalProperties === "object") {
+        nestedTypes.push(...findNestedTypesInSchema(record.additionalProperties, parentTypeName, defNames, [...currentPath, "additionalProperties"]));
+    }
+    return nestedTypes;
+};
+const generateNestedTypesFile = (nestedTypes) => {
+    const lines = [
+        "/**",
+        " * Auto-generated nested type exports",
+        " * ",
+        " * These types are inline within parent schemas but commonly needed separately.",
+        " * They are extracted using TypeScript indexed access types.",
+        " */",
+        "",
+    ];
+    const byParent = new Map();
+    for (const info of nestedTypes) {
+        if (!byParent.has(info.parentType)) {
+            byParent.set(info.parentType, []);
+        }
+        byParent.get(info.parentType).push(info);
+    }
+    const imports = new Map(); // file -> type name
+    for (const info of nestedTypes) {
+        if (!imports.has(info.file)) {
+            imports.set(info.file, info.parentType);
+        }
+    }
+    for (const [file, typeName] of [...imports.entries()].sort()) {
+        lines.push(`import type { ${typeName} } from './${file}.schema.js';`);
+    }
+    lines.push("");
+    for (const [parentType, types] of [...byParent.entries()].sort()) {
+        lines.push(`// From ${parentType}`);
+        for (const info of types.sort((a, b) => a.typeName.localeCompare(b.typeName))) {
+            if (info.propertyPath.length > 0) {
+                let accessExpr = parentType;
+                for (const prop of info.propertyPath) {
+                    accessExpr = `NonNullable<${accessExpr}['${prop}']>`;
+                }
+                lines.push(`export type ${info.typeName} = ${accessExpr};`);
+            }
+        }
+        lines.push("");
+    }
+    return lines.join("\n");
+};

package/dist/esm/index.js

@@ -1,4 +1,7 @@
 export * from "./Types.js";
+export * from "./core/analyzeSchema.js";
+export * from "./core/emitZod.js";
+export * from "./generators/generateBundle.js";
 export * from "./jsonSchemaToZod.js";
 export * from "./parsers/parseAllOf.js";
 export * from "./parsers/parseAnyOf.js";
@@ -19,9 +22,12 @@ export * from "./parsers/parseSchema.js";
 export * from "./parsers/parseSimpleDiscriminatedOneOf.js";
 export * from "./parsers/parseString.js";
 export * from "./utils/anyOrUnknown.js";
+export * from "./utils/buildRefRegistry.js";
+export * from "./utils/cycles.js";
 export * from "./utils/half.js";
 export * from "./utils/jsdocs.js";
 export * from "./utils/omit.js";
+export * from "./utils/resolveUri.js";
 export * from "./utils/withMessage.js";
 export * from "./zodToJsonSchema.js";
 import { jsonSchemaToZod } from "./jsonSchemaToZod.js";

package/dist/esm/jsonSchemaToZod.js

@@ -1,74 +1,6 @@
-import { parseSchema } from "./parsers/parseSchema.js";
-import { expandJsdocs } from "./utils/jsdocs.js";
-export const jsonSchemaToZod = (schema, { module, name, type, noImport, ...rest } = {}) => {
-    if (type && (!name || module !== "esm")) {
-        throw new Error("Option `type` requires `name` to be set and `module` to be `esm`");
-    }
-    const declarations = new Map();
-    const refNameByPointer = new Map();
-    const usedNames = new Set();
-    const exportRefs = rest.exportRefs ?? true;
-    const withMeta = rest.withMeta ?? true;
-    if (name)
-        usedNames.add(name);
-    const parsedSchema = parseSchema(schema, {
-        module,
-        name,
-        path: [],
-        seen: new Map(),
-        declarations,
-        inProgress: new Set(),
-        refNameByPointer,
-        usedNames,
-        root: schema,
-        currentSchemaName: name,
-        ...rest,
-        withMeta,
-    });
-    const declarationBlock = declarations.size
-        ? Array.from(declarations.entries())
-            .map(([refName, value]) => {
-            const shouldExport = exportRefs && module === "esm";
-            const decl = `${shouldExport ? "export " : ""}const ${refName} = ${value}`;
-            return decl;
-        })
-            .join("\n")
-        : "";
-    const jsdocs = rest.withJsdocs && typeof schema !== "boolean" && schema.description
-        ? expandJsdocs(schema.description)
-        : "";
-    const lines = [];
-    if (module === "cjs" && !noImport) {
-        lines.push(`const { z } = require("zod")`);
-    }
-    if (module === "esm" && !noImport) {
-        lines.push(`import { z } from "zod"`);
-    }
-    if (declarationBlock) {
-        lines.push(declarationBlock);
-    }
-    if (module === "cjs") {
-        const payload = name ? `{ ${JSON.stringify(name)}: ${parsedSchema} }` : parsedSchema;
-        lines.push(`${jsdocs}module.exports = ${payload}`);
-    }
-    else if (module === "esm") {
-        lines.push(`${jsdocs}export ${name ? `const ${name} =` : `default`} ${parsedSchema}`);
-    }
-    else if (name) {
-        lines.push(`${jsdocs}const ${name} = ${parsedSchema}`);
-    }
-    else {
-        lines.push(`${jsdocs}${parsedSchema}`);
-    }
-    let typeLine;
-    if (type && name) {
-        let typeName = typeof type === "string"
-            ? type
-            : `${name[0].toUpperCase()}${name.substring(1)}`;
-        typeLine = `export type ${typeName} = z.infer<typeof ${name}>`;
-    }
-    const joined = lines.filter(Boolean).join("\n\n");
-    const combined = typeLine ? `${joined}\n${typeLine}` : joined;
-    const shouldEndWithNewline = module === "esm" || module === "cjs";
-    return `${combined}${shouldEndWithNewline ? "\n" : ""}`;
+import { analyzeSchema } from "./core/analyzeSchema.js";
+import { emitZod } from "./core/emitZod.js";
+export const jsonSchemaToZod = (schema, options = {}) => {
+    const analysis = analyzeSchema(schema, options);
+    return emitZod(analysis);
 };

package/dist/esm/parsers/parseArray.js

@@ -29,22 +29,41 @@ export const parseArray = (schema, refs) => {
             ...refs,
             path: [...refs.path, "items"],
         })})`;
-    r += withMessage(schema, "minItems", ({ json }) => [
-        `.min(${json}`,
-        ", ",
-        ")",
-    ]);
-    r += withMessage(schema, "maxItems", ({ json }) => [
-        `.max(${json}`,
-        ", ",
-        ")",
-    ]);
+    r += withMessage(schema, "minItems", ({ json }) => ({
+        opener: `.min(${json}`,
+        closer: ")",
+        messagePrefix: ", { error: ",
+        messageCloser: " })",
+    }));
+    r += withMessage(schema, "maxItems", ({ json }) => ({
+        opener: `.max(${json}`,
+        closer: ")",
+        messagePrefix: ", { error: ",
+        messageCloser: " })",
+    }));
     if (schema.uniqueItems === true) {
-        r += withMessage(schema, "uniqueItems", () => [
-            ".unique(",
-            "",
-            ")",
-        ]);
+        r += `.superRefine((arr, ctx) => {
+  const seen = new Set();
+  for (const [index, value] of arr.entries()) {
+    let key;
+    if (value && typeof value === "object") {
+      try {
+        key = JSON.stringify(value);
+      } catch {
+        key = String(value);
+      }
+    } else {
+      key = JSON.stringify(value);
+    }
+
+    if (seen.has(key)) {
+      ctx.addIssue({ code: "custom", message: "Array items must be unique", path: [index] });
+      return;
+    }
+
+    seen.add(key);
+  }
+})`;
     }
     if (schema.contains) {
         const containsSchema = parseSchema(schema.contains, {

package/dist/esm/parsers/parseIfThenElse.js

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