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

package/dist/cjs/parsers/parseSchema.js

@@ -19,9 +19,12 @@ const parseOneOf_js_1 = require("./parseOneOf.js");
 const parseSimpleDiscriminatedOneOf_js_1 = require("./parseSimpleDiscriminatedOneOf.js");
 const parseNullable_js_1 = require("./parseNullable.js");
 const anyOrUnknown_js_1 = require("../utils/anyOrUnknown.js");
+const resolveUri_js_1 = require("../utils/resolveUri.js");
+const buildRefRegistry_js_1 = require("../utils/buildRefRegistry.js");
 const parseSchema = (schema, refs = { seen: new Map(), path: [] }, blockMeta) => {
     // Ensure ref bookkeeping exists so $ref declarations and getter-based recursion work
     refs.root = refs.root ?? schema;
+    refs.rootBaseUri = refs.rootBaseUri ?? "root:///";
     refs.declarations = refs.declarations ?? new Map();
     refs.dependencies = refs.dependencies ?? new Map();
     refs.inProgress = refs.inProgress ?? new Set();
@@ -29,8 +32,20 @@ const parseSchema = (schema, refs = { seen: new Map(), path: [] }, blockMeta) =>
     refs.usedNames = refs.usedNames ?? new Set();
     if (typeof schema !== "object")
         return schema ? (0, anyOrUnknown_js_1.anyOrUnknown)(refs) : "z.never()";
+    const parentBase = refs.currentBaseUri ?? refs.rootBaseUri ?? "root:///";
+    const baseUri = typeof schema.$id === "string"
+        ? (0, resolveUri_js_1.resolveUri)(parentBase, schema.$id)
+        : parentBase;
+    const dynamicAnchors = Array.isArray(refs.dynamicAnchors) ? [...refs.dynamicAnchors] : [];
+    if (typeof schema.$dynamicAnchor === "string") {
+        dynamicAnchors.push({
+            name: schema.$dynamicAnchor,
+            uri: baseUri,
+            path: refs.path,
+        });
+    }
     if (refs.parserOverride) {
-        const custom = refs.parserOverride(schema, refs);
+        const custom = refs.parserOverride(schema, { ...refs, currentBaseUri: baseUri, dynamicAnchors });
         if (typeof custom === "string") {
             return custom;
         }
@@ -50,14 +65,14 @@ const parseSchema = (schema, refs = { seen: new Map(), path: [] }, blockMeta) =>
         refs.seen.set(schema, seen);
     }
     if (exports.its.a.ref(schema)) {
-        const parsedRef = parseRef(schema, refs);
+        const parsedRef = parseRef(schema, { ...refs, currentBaseUri: baseUri, dynamicAnchors });
         seen.r = parsedRef;
         return parsedRef;
     }
-    let parsed = selectParser(schema, refs);
+    let parsed = selectParser(schema, { ...refs, currentBaseUri: baseUri, dynamicAnchors });
     if (!blockMeta) {
         if (!refs.withoutDescribes) {
-            parsed = addDescribes(schema, parsed, refs);
+            parsed = addDescribes(schema, parsed, { ...refs, currentBaseUri: baseUri, dynamicAnchors });
         }
         if (!refs.withoutDefaults) {
             parsed = addDefaults(schema, parsed);
@@ -69,17 +84,20 @@ const parseSchema = (schema, refs = { seen: new Map(), path: [] }, blockMeta) =>
 };
 exports.parseSchema = parseSchema;
 const parseRef = (schema, refs) => {
-    const resolved = resolveRef(refs.root, schema.$ref);
+    const refValue = schema.$dynamicRef ?? schema.$ref;
+    const resolved = resolveRef(schema, refValue, refs);
     if (!resolved) {
+        refs.onUnresolvedRef?.(refValue, refs.path);
         return (0, anyOrUnknown_js_1.anyOrUnknown)(refs);
     }
-    const { schema: target, path } = resolved;
-    const refName = getOrCreateRefName(schema.$ref, path, refs);
+    const { schema: target, path, pointerKey } = resolved;
+    const refName = getOrCreateRefName(pointerKey, path, refs);
     if (!refs.declarations.has(refName) && !refs.inProgress.has(refName)) {
         refs.inProgress.add(refName);
         const declaration = (0, exports.parseSchema)(target, {
             ...refs,
             path,
+            currentBaseUri: resolved.baseUri,
             currentSchemaName: refName,
             root: refs.root,
         });
@@ -132,23 +150,93 @@ const addDescribes = (schema, parsed, refs) => {
     }
     return parsed;
 };
-const resolveRef = (root, ref) => {
-    if (!root || !ref.startsWith("#/"))
-        return undefined;
-    const rawSegments = ref
-        .slice(2)
-        .split("/")
-        .filter((segment) => segment.length > 0)
-        .map(decodePointerSegment);
-    let current = root;
-    for (const segment of rawSegments) {
-        if (typeof current !== "object" || current === null)
-            return undefined;
-        current = current[segment];
-    }
-    return { schema: current, path: rawSegments };
+const resolveRef = (schemaNode, ref, refs) => {
+    const base = refs.currentBaseUri ?? refs.rootBaseUri ?? "root:///";
+    // Handle dynamicRef lookup via dynamicAnchors stack
+    const isDynamic = typeof schemaNode.$dynamicRef === "string";
+    if (isDynamic && refs.dynamicAnchors && ref.startsWith("#")) {
+        const name = ref.slice(1);
+        for (let i = refs.dynamicAnchors.length - 1; i >= 0; i -= 1) {
+            const entry = refs.dynamicAnchors[i];
+            if (entry.name === name) {
+                const key = `${entry.uri}#${name}`;
+                const target = refs.refRegistry?.get(key);
+                if (target) {
+                    return { schema: target.schema, path: target.path, baseUri: target.baseUri, pointerKey: key };
+                }
+            }
+        }
+    }
+    // Resolve URI against base
+    const resolvedUri = (0, resolveUri_js_1.resolveUri)(base, ref);
+    const [uriBase, fragment] = resolvedUri.split("#");
+    const key = fragment ? `${uriBase}#${fragment}` : uriBase;
+    let regEntry = refs.refRegistry?.get(key);
+    if (regEntry) {
+        return { schema: regEntry.schema, path: regEntry.path, baseUri: regEntry.baseUri, pointerKey: key };
+    }
+    // Legacy recursive ref: treat as dynamic to __recursive__
+    if (schemaNode.$recursiveRef) {
+        const recursiveKey = `${base}#__recursive__`;
+        regEntry = refs.refRegistry?.get(recursiveKey);
+        if (regEntry) {
+            return {
+                schema: regEntry.schema,
+                path: regEntry.path,
+                baseUri: regEntry.baseUri,
+                pointerKey: recursiveKey,
+            };
+        }
+    }
+    // External resolver hook
+    const extBase = uriBaseFromRef(resolvedUri);
+    if (refs.resolveExternalRef && extBase && !isLocalBase(extBase, refs.rootBaseUri ?? "")) {
+        const loaded = refs.resolveExternalRef(extBase);
+        if (loaded) {
+            // If async resolver is used synchronously here, it will be ignored; keep simple sync for now
+            const schema = loaded.then ? undefined : loaded;
+            if (schema) {
+                const { registry } = (0, buildRefRegistry_js_1.buildRefRegistry)(schema, extBase);
+                registry.forEach((entry, k) => refs.refRegistry?.set(k, entry));
+                regEntry = refs.refRegistry?.get(key);
+                if (regEntry) {
+                    return {
+                        schema: regEntry.schema,
+                        path: regEntry.path,
+                        baseUri: regEntry.baseUri,
+                        pointerKey: key,
+                    };
+                }
+            }
+        }
+    }
+    // Backward compatibility: JSON Pointer into root
+    if (refs.root && ref.startsWith("#/")) {
+        const rawSegments = ref
+            .slice(2)
+            .split("/")
+            .filter((segment) => segment.length > 0)
+            .map(decodePointerSegment);
+        let current = refs.root;
+        for (const segment of rawSegments) {
+            if (typeof current !== "object" || current === null)
+                return undefined;
+            current = current[segment];
+        }
+        return { schema: current, path: rawSegments, baseUri: base, pointerKey: ref };
+    }
+    return undefined;
 };
 const decodePointerSegment = (segment) => segment.replace(/~1/g, "/").replace(/~0/g, "~");
+const uriBaseFromRef = (resolvedUri) => {
+    const hashIdx = resolvedUri.indexOf("#");
+    return hashIdx === -1 ? resolvedUri : resolvedUri.slice(0, hashIdx);
+};
+const isLocalBase = (base, rootBase) => {
+    if (!rootBase)
+        return false;
+    return base === rootBase;
+};
 const getOrCreateRefName = (pointer, path, refs) => {
     if (refs.refNameByPointer?.has(pointer)) {
         return refs.refNameByPointer.get(pointer);
@@ -159,12 +247,24 @@ const getOrCreateRefName = (pointer, path, refs) => {
     return preferred;
 };
 const buildNameFromPath = (path, used) => {
-    const filtered = path.filter((segment) => segment !== "$defs" && segment !== "definitions" && segment !== "properties");
+    const filtered = path
+        .map((segment, idx) => {
+        if (idx === 0 && (segment === "$defs" || segment === "definitions")) {
+            return undefined; // root-level defs prefix is redundant for naming
+        }
+        if (segment === "properties")
+            return undefined; // skip noisy properties segment
+        if (segment === "$defs" || segment === "definitions")
+            return "Defs";
+        return segment;
+    })
+        .filter((segment) => segment !== undefined);
     const base = filtered.length
         ? filtered
             .map((segment) => typeof segment === "number"
             ? `Ref${segment}`
             : segment
+                .toString()
                 .replace(/[^a-zA-Z0-9_$]/g, " ")
                 .split(" ")
                 .filter(Boolean)
@@ -266,7 +366,7 @@ exports.its = {
         nullable: (x) => x.nullable === true,
         multipleType: (x) => Array.isArray(x.type),
         not: (x) => x.not !== undefined,
-        ref: (x) => typeof x.$ref === "string",
+        ref: (x) => typeof x.$ref === "string" || typeof x.$dynamicRef === "string",
         const: (x) => x.const !== undefined,
         primitive: (x, p) => x.type === p,
         conditional: (x) => Boolean("if" in x && x.if && "then" in x && "else" in x && x.then && x.else),

package/dist/cjs/utils/buildRefRegistry.js

@@ -0,0 +1,56 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildRefRegistry = void 0;
+const resolveUri_js_1 = require("./resolveUri.js");
+const buildRefRegistry = (schema, rootBaseUri = "root:///", opts = {}) => {
+    const registry = new Map();
+    const walk = (node, baseUri, path) => {
+        if (typeof node !== "object" || node === null)
+            return;
+        const obj = node;
+        const nextBase = obj.$id ? (0, resolveUri_js_1.resolveUri)(baseUri, obj.$id) : baseUri;
+        // Legacy recursive anchor
+        if (obj.$recursiveAnchor === true) {
+            const name = "__recursive__";
+            registry.set(`${nextBase}#${name}`, {
+                schema: node,
+                path,
+                baseUri: nextBase,
+                dynamic: true,
+                anchor: name,
+            });
+        }
+        // Register base entry
+        registry.set(nextBase, { schema: node, path, baseUri: nextBase });
+        if (typeof obj.$anchor === "string") {
+            registry.set(`${nextBase}#${obj.$anchor}`, {
+                schema: node,
+                path,
+                baseUri: nextBase,
+                anchor: obj.$anchor,
+            });
+        }
+        if (typeof obj.$dynamicAnchor === "string") {
+            const name = obj.$dynamicAnchor;
+            registry.set(`${nextBase}#${name}`, {
+                schema: node,
+                path,
+                baseUri: nextBase,
+                dynamic: true,
+                anchor: name,
+            });
+        }
+        for (const key in obj) {
+            const value = obj[key];
+            if (Array.isArray(value)) {
+                value.forEach((v, i) => walk(v, nextBase, [...path, key, i]));
+            }
+            else if (typeof value === "object" && value !== null) {
+                walk(value, nextBase, [...path, key]);
+            }
+        }
+    };
+    walk(schema, rootBaseUri, []);
+    return { registry, rootBaseUri };
+};
+exports.buildRefRegistry = buildRefRegistry;

package/dist/cjs/utils/resolveUri.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveUri = void 0;
+const resolveUri = (base, ref) => {
+    try {
+        // If ref is absolute, new URL will accept it; otherwise resolves against base
+        return new URL(ref, base).toString();
+    }
+    catch {
+        // Fallback: simple concatenation to avoid throwing; keep ref as-is
+        if (ref.startsWith("#"))
+            return `${base}${ref}`;
+        return ref;
+    }
+};
+exports.resolveUri = resolveUri;

package/dist/esm/Types.js

@@ -1,2 +1 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
+export {};

package/dist/esm/cli.js

@@ -1,10 +1,8 @@
 #!/usr/bin/env node
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-const jsonSchemaToZod_js_1 = require("./jsonSchemaToZod.js");
-const fs_1 = require("fs");
-const path_1 = require("path");
-const cliTools_js_1 = require("./utils/cliTools.js");
+import { jsonSchemaToZod } from "./jsonSchemaToZod.js";
+import { writeFileSync, mkdirSync } from "fs";
+import { dirname } from "path";
+import { parseArgs, parseOrReadJSON, readPipe } from "./utils/cliTools.js";
 const params = {
     input: {
         shorthand: "i",
@@ -48,10 +46,10 @@ const params = {
     },
 };
 async function main() {
-    const args = (0, cliTools_js_1.parseArgs)(params, process.argv, true);
-    const input = args.input || (await (0, cliTools_js_1.readPipe)());
-    const jsonSchema = (0, cliTools_js_1.parseOrReadJSON)(input);
-    const zodSchema = (0, jsonSchemaToZod_js_1.jsonSchemaToZod)(jsonSchema, {
+    const args = parseArgs(params, process.argv, true);
+    const input = args.input || (await readPipe());
+    const jsonSchema = parseOrReadJSON(input);
+    const zodSchema = jsonSchemaToZod(jsonSchema, {
         name: args.name,
         depth: args.depth,
         module: args.module || "esm",
@@ -60,8 +58,8 @@ async function main() {
         withJsdocs: args.withJsdocs,
     });
     if (args.output) {
-        (0, fs_1.mkdirSync)((0, path_1.dirname)(args.output), { recursive: true });
-        (0, fs_1.writeFileSync)(args.output, zodSchema);
+        mkdirSync(dirname(args.output), { recursive: true });
+        writeFileSync(args.output, zodSchema);
     }
     else {
         console.log(zodSchema);

package/dist/esm/core/analyzeSchema.js

@@ -0,0 +1,58 @@
+import { parseSchema } from "../parsers/parseSchema.js";
+import { detectCycles, computeScc } from "../utils/cycles.js";
+import { buildRefRegistry } from "../utils/buildRefRegistry.js";
+export 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 } = 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,
+    };
+    parseSchema(schema, pass1);
+    const names = Array.from(declarations.keys());
+    const cycleRefNames = detectCycles(names, dependencies);
+    const { componentByName } = computeScc(names, dependencies);
+    return {
+        schema,
+        options: normalized,
+        refNameByPointer,
+        usedNames,
+        declarations,
+        dependencies,
+        cycleRefNames,
+        cycleComponentByName: componentByName,
+        refRegistry,
+        rootBaseUri,
+    };
+};

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" : ""}`;
+};