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

package/CHANGELOG.md

@@ -1,9 +1,31 @@
 # @gabrielbryk/json-schema-to-zod
 
-## 2.7.4
+## 2.9.0
+
+### Minor Changes
+
+- 0ef12db: - Extract analyzer/emitter core, refactor bundle generation to avoid recursion and preserve inline defs/definitions.
+  - Add scoped naming for inline $defs, lazy cross-ref handling, and nested types emission.
+  - Expand bundle test coverage with snapshots, inline-def fixtures, and nested-type extraction.
+
+### Patch Changes
+
+- b8f6248: - Commit remaining utility, ref resolution test, and config updates.
+- 7d257dd: - Ensure dist/esm emits real ESM with NodeNext settings and type:module, and update tests to run under ESM by providing createRequire shims.
+
+## 2.8.0
+
+### Minor Changes
+
+- 0065ee8: - Add support for JSON Schema `dependentRequired` on objects with optional custom error message.
+  - Extend format handling and add bigint format helpers while warning on unknown string formats.
 
 ### Patch Changes
 
+- 3d57690: - Make $ref handling cycle-aware with SCC-based ordering and minimal z.lazy usage.
+  - Add workflow spec fixture to compiled-output tests to guard against TDZ issues.
+  - Fix parseString to build a full Refs context when missing, keeping type checks happy.
+- 3d57690: - Switch ESM/typings builds to NodeNext resolution and ensure relative imports include .js extensions for Node ESM compatibility.
 - 82aa953: Fix patternProperties validation under Zod v4 by preserving regex patterns and handling missing `ctx.path`.
 - a501e7d: Adjust release workflow to rely on the default npm from setup-node and drop unused tokens.
 - 43f2abc: Update object record generation to use `z.record(z.string(), …)` for Zod v4 compatibility.

package/dist/cjs/core/analyzeSchema.js

@@ -0,0 +1,62 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.analyzeSchema = void 0;
+const parseSchema_js_1 = require("../parsers/parseSchema.js");
+const cycles_js_1 = require("../utils/cycles.js");
+const buildRefRegistry_js_1 = require("../utils/buildRefRegistry.js");
+const analyzeSchema = (schema, options = {}) => {
+    const { module, name, type, ...rest } = options;
+    if (type && (!name || module !== "esm")) {
+        throw new Error("Option `type` requires `name` to be set and `module` to be `esm`");
+    }
+    const normalized = {
+        module,
+        name,
+        type,
+        ...rest,
+        exportRefs: rest.exportRefs ?? true,
+        withMeta: rest.withMeta ?? true,
+    };
+    const refNameByPointer = new Map();
+    const usedNames = new Set();
+    if (name) {
+        usedNames.add(name);
+    }
+    const declarations = new Map();
+    const dependencies = new Map();
+    const { registry: refRegistry, rootBaseUri } = (0, buildRefRegistry_js_1.buildRefRegistry)(schema);
+    const pass1 = {
+        module,
+        name,
+        path: [],
+        seen: new Map(),
+        declarations,
+        dependencies,
+        inProgress: new Set(),
+        refNameByPointer,
+        usedNames,
+        root: schema,
+        currentSchemaName: name,
+        refRegistry,
+        rootBaseUri,
+        ...rest,
+        withMeta: normalized.withMeta,
+    };
+    (0, parseSchema_js_1.parseSchema)(schema, pass1);
+    const names = Array.from(declarations.keys());
+    const cycleRefNames = (0, cycles_js_1.detectCycles)(names, dependencies);
+    const { componentByName } = (0, cycles_js_1.computeScc)(names, dependencies);
+    return {
+        schema,
+        options: normalized,
+        refNameByPointer,
+        usedNames,
+        declarations,
+        dependencies,
+        cycleRefNames,
+        cycleComponentByName: componentByName,
+        refRegistry,
+        rootBaseUri,
+    };
+};
+exports.analyzeSchema = analyzeSchema;

package/dist/cjs/core/emitZod.js

@@ -0,0 +1,141 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.emitZod = void 0;
+const parseSchema_js_1 = require("../parsers/parseSchema.js");
+const jsdocs_js_1 = require("../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)]);
+};
+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 = (0, parseSchema_js_1.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
+        ? (0, jsdocs_js_1.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" : ""}`;
+};
+exports.emitZod = emitZod;

package/dist/cjs/generators/generateBundle.js

@@ -0,0 +1,355 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateSchemaBundle = void 0;
+const analyzeSchema_js_1 = require("../core/analyzeSchema.js");
+const emitZod_js_1 = require("../core/emitZod.js");
+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 = (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);
+        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 };
+};
+exports.generateSchemaBundle = generateSchemaBundle;
+// ---------------------------------------------------------------------------
+// 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/cjs/index.js

@@ -15,6 +15,9 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./Types.js"), exports);
+__exportStar(require("./core/analyzeSchema.js"), exports);
+__exportStar(require("./core/emitZod.js"), exports);
+__exportStar(require("./generators/generateBundle.js"), exports);
 __exportStar(require("./jsonSchemaToZod.js"), exports);
 __exportStar(require("./parsers/parseAllOf.js"), exports);
 __exportStar(require("./parsers/parseAnyOf.js"), exports);
@@ -35,9 +38,12 @@ __exportStar(require("./parsers/parseSchema.js"), exports);
 __exportStar(require("./parsers/parseSimpleDiscriminatedOneOf.js"), exports);
 __exportStar(require("./parsers/parseString.js"), exports);
 __exportStar(require("./utils/anyOrUnknown.js"), exports);
+__exportStar(require("./utils/buildRefRegistry.js"), exports);
+__exportStar(require("./utils/cycles.js"), exports);
 __exportStar(require("./utils/half.js"), exports);
 __exportStar(require("./utils/jsdocs.js"), exports);
 __exportStar(require("./utils/omit.js"), exports);
+__exportStar(require("./utils/resolveUri.js"), exports);
 __exportStar(require("./utils/withMessage.js"), exports);
 __exportStar(require("./zodToJsonSchema.js"), exports);
 const jsonSchemaToZod_js_1 = require("./jsonSchemaToZod.js");