@gabrielbryk/json-schema-to-zod 2.7.3 → 2.8.0

package/.github/workflows/release.yml

@@ -28,9 +28,6 @@ jobs:
           cache: pnpm
           registry-url: https://registry.npmjs.org
 
-      - name: Update npm (trusted publishing requires >=11.5.1)
-        run: npm install -g npm@latest
-
       - name: Install dependencies
         run: pnpm install --frozen-lockfile
 
@@ -46,5 +43,3 @@ jobs:
           publish: pnpm changeset publish --access public
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          NPM_TOKEN: ""
-          NODE_AUTH_TOKEN: ""

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # @gabrielbryk/json-schema-to-zod
 
+## 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.
+
 ## 2.7.3
 
 ### Patch Changes

package/dist/cjs/generators/generateBundle.js

@@ -0,0 +1,311 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateSchemaBundle = void 0;
+const jsonSchemaToZod_js_1 = require("../jsonSchemaToZod.js");
+const generateSchemaBundle = (schema, options = {}) => {
+    const module = options.module ?? "esm";
+    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);
+    if (!schema || typeof schema !== "object") {
+        throw new Error("generateSchemaBundle requires an object schema");
+    }
+    const defs = schema.$defs || schema.definitions || {};
+    const defNames = Object.keys(defs);
+    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 files = [];
+    // Generate individual $def files
+    for (const defName of defNames) {
+        const info = defInfoMap.get(defName);
+        const usedRefs = new Set();
+        const defSchemaWithDefs = {
+            ...defs[defName],
+            $defs: defs,
+        };
+        const zodSchema = (0, jsonSchemaToZod_js_1.jsonSchemaToZod)(defSchemaWithDefs, {
+            ...options,
+            module,
+            name: info.schemaName,
+            type: info.typeName,
+            parserOverride: createRefHandler(defName, defInfoMap, usedRefs, defs, options),
+        });
+        const finalSchema = buildSchemaFile(zodSchema, usedRefs, defInfoMap, module);
+        const fileName = options.splitDefs?.fileName?.(defName, { isRoot: false }) ?? `${defName}.schema.ts`;
+        files.push({ fileName, contents: finalSchema });
+    }
+    // Generate root schema if requested
+    if (options.splitDefs?.includeRoot ?? true) {
+        const usedRefs = new Set();
+        const workflowSchemaWithDefs = {
+            ...schema,
+        };
+        const workflowZodSchema = (0, jsonSchemaToZod_js_1.jsonSchemaToZod)(workflowSchemaWithDefs, {
+            ...options,
+            module,
+            name: rootName,
+            type: rootTypeName,
+            parserOverride: createRefHandler(null, defInfoMap, usedRefs, defs, options),
+        });
+        const finalWorkflow = buildSchemaFile(workflowZodSchema, usedRefs, defInfoMap, module);
+        const rootFile = options.splitDefs?.fileName?.("root", { isRoot: true }) ?? "workflow.schema.ts";
+        files.push({ fileName: rootFile, contents: finalWorkflow });
+    }
+    // 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 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];
+                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;
+                    return refInfo.schemaName;
+                }
+            }
+            const unknown = options.refResolution?.onUnknownRef?.({ ref: refPath, currentDef: currentDefName });
+            if (unknown)
+                return unknown;
+            return options.useUnknown ? "z.unknown()" : "z.any()";
+        }
+        // Inline $defs within a schema
+        if (schema["$defs"] && typeof schema["$defs"] === "object") {
+            return (0, jsonSchemaToZod_js_1.jsonSchemaToZod)(schema, {
+                ...options,
+                module: options.module ?? "esm",
+                parserOverride: createRefHandler(currentDefName, defInfoMap, usedRefs, allDefs, options),
+            });
+        }
+        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 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" && record.type === "object") {
+        const title = record.title;
+        if (title !== parentTypeName && !defNames.map((d) => toPascalCase(d)).includes(title)) {
+            nestedTypes.push({
+                typeName: title,
+                parentType: parentTypeName,
+                propertyPath: [...currentPath],
+                file: "",
+            });
+        }
+    }
+    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));
+    }
+    if (record.additionalProperties && typeof record.additionalProperties === "object") {
+        nestedTypes.push(...findNestedTypesInSchema(record.additionalProperties, parentTypeName, defNames, currentPath));
+    }
+    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 Set();
+    for (const info of nestedTypes) {
+        imports.add(info.file);
+    }
+    for (const file of [...imports].sort()) {
+        const typeName = file === "workflow" ? "Workflow" : toPascalCase(file);
+        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,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./Types.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,6 +36,7 @@ __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/cycles.js"), exports);
 __exportStar(require("./utils/half.js"), exports);
 __exportStar(require("./utils/jsdocs.js"), exports);
 __exportStar(require("./utils/omit.js"), exports);

package/dist/cjs/jsonSchemaToZod.js

@@ -3,33 +3,59 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.jsonSchemaToZod = void 0;
 const parseSchema_js_1 = require("./parsers/parseSchema.js");
 const jsdocs_js_1 = require("./utils/jsdocs.js");
+const cycles_js_1 = require("./utils/cycles.js");
 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);
+    // Pass 1: collect declarations/dependencies to detect cycles before emitting
+    const pass1 = {
+        module,
+        name,
+        path: [],
+        seen: new Map(),
+        declarations: new Map(),
+        dependencies: new Map(),
+        inProgress: new Set(),
+        refNameByPointer,
+        usedNames,
+        root: schema,
+        currentSchemaName: name,
+        ...rest,
+        withMeta,
+    };
+    (0, parseSchema_js_1.parseSchema)(schema, pass1);
+    const names = Array.from(pass1.declarations.keys());
+    const cycleRefNames = (0, cycles_js_1.detectCycles)(names, pass1.dependencies);
+    const { componentByName } = (0, cycles_js_1.computeScc)(names, pass1.dependencies);
+    // Pass 2: generate with cycle awareness
+    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: componentByName,
         ...rest,
         withMeta,
     });
     const declarationBlock = declarations.size
-        ? Array.from(declarations.entries())
+        ? orderDeclarations(Array.from(declarations.entries()), dependencies)
             .map(([refName, value]) => {
             const shouldExport = exportRefs && module === "esm";
             const decl = `${shouldExport ? "export " : ""}const ${refName} = ${value}`;
@@ -76,3 +102,71 @@ const jsonSchemaToZod = (schema, { module, name, type, noImport, ...rest } = {})
     return `${combined}${shouldEndWithNewline ? "\n" : ""}`;
 };
 exports.jsonSchemaToZod = jsonSchemaToZod;
+function orderDeclarations(entries, dependencies) {
+    const valueByName = new Map(entries);
+    const depGraph = new Map();
+    // Seed with explicit dependencies recorded during parsing
+    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);
+    }
+    // Also infer deps by scanning declaration bodies for referenced names
+    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)) {
+            // Cycle detected; break it but still include the node.
+            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)]);
+}

package/dist/cjs/parsers/parseArray.js

@@ -32,22 +32,41 @@ const parseArray = (schema, refs) => {
             ...refs,
             path: [...refs.path, "items"],
         })})`;
-    r += (0, withMessage_js_1.withMessage)(schema, "minItems", ({ json }) => [
-        `.min(${json}`,
-        ", ",
-        ")",
-    ]);
-    r += (0, withMessage_js_1.withMessage)(schema, "maxItems", ({ json }) => [
-        `.max(${json}`,
-        ", ",
-        ")",
-    ]);
+    r += (0, withMessage_js_1.withMessage)(schema, "minItems", ({ json }) => ({
+        opener: `.min(${json}`,
+        closer: ")",
+        messagePrefix: ", { error: ",
+        messageCloser: " })",
+    }));
+    r += (0, withMessage_js_1.withMessage)(schema, "maxItems", ({ json }) => ({
+        opener: `.max(${json}`,
+        closer: ")",
+        messagePrefix: ", { error: ",
+        messageCloser: " })",
+    }));
     if (schema.uniqueItems === true) {
-        r += (0, withMessage_js_1.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 = (0, parseSchema_js_1.parseSchema)(schema.contains, {

package/dist/cjs/parsers/parseIfThenElse.js

@@ -17,7 +17,8 @@ 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