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

package/dist/esm/parsers/parseString.js

@@ -1,73 +1,313 @@
 import { withMessage } from "../utils/withMessage.js";
 import { parseSchema } from "./parseSchema.js";
-export const parseString = (schema) => {
-    let r = "z.string()";
-    r += withMessage(schema, "format", ({ value }) => {
-        switch (value) {
-            case "email":
-                return [".email(", ")"];
-            case "ip":
-                return [".ip(", ")"];
-            case "ipv4":
-                return ['.ip({ version: "v4"', ", message: ", " })"];
-            case "ipv6":
-                return ['.ip({ version: "v6"', ", message: ", " })"];
-            case "uri":
-                return [".url(", ")"];
-            case "uuid":
-                return [".uuid(", ")"];
-            case "date-time":
-                return [".datetime({ offset: true", ", message: ", " })"];
-            case "time":
-                return [".time(", ")"];
-            case "date":
-                return [".date(", ")"];
-            case "binary":
-                return [".base64(", ")"];
-            case "duration":
-                return [".duration(", ")"];
-        }
-    });
-    r += withMessage(schema, "pattern", ({ json }) => [
-        `.regex(new RegExp(${json})`,
-        ", ",
-        ")",
-    ]);
-    r += withMessage(schema, "minLength", ({ json }) => [
-        `.min(${json}`,
-        ", ",
-        ")",
-    ]);
-    r += withMessage(schema, "maxLength", ({ json }) => [
-        `.max(${json}`,
-        ", ",
-        ")",
-    ]);
+export const parseString = (schema, refs) => {
+    const formatError = schema.errorMessage?.format;
+    const refContext = ensureRefs(refs);
+    const topLevelFormatMap = {
+        email: "z.email",
+        ipv4: "z.ipv4",
+        ipv6: "z.ipv6",
+        uri: "z.url",
+        uuid: "z.uuid",
+        cuid: "z.cuid",
+        cuid2: "z.cuid2",
+        nanoid: "z.nanoid",
+        ulid: "z.ulid",
+        jwt: "z.jwt",
+        e164: "z.e164",
+        base64url: "z.base64url",
+        base64: "z.base64",
+        emoji: "z.emoji",
+        "idn-email": "z.email",
+    };
+    const formatFn = schema.format && topLevelFormatMap[schema.format];
+    const formatParam = formatError !== undefined ? `{ error: ${JSON.stringify(formatError)} }` : "";
+    let r = formatFn ? `${formatFn}(${formatParam})` : "z.string()";
+    const formatHandled = Boolean(formatFn);
+    let formatWasHandled = formatHandled;
+    if (!formatHandled) {
+        r += withMessage(schema, "format", ({ value }) => {
+            switch (value) {
+                case "email":
+                    formatWasHandled = true;
+                    return {
+                        opener: ".email(",
+                        closer: ")",
+                        messagePrefix: "{ error: ",
+                        messageCloser: " })",
+                    };
+                case "ip":
+                    formatWasHandled = true;
+                    return {
+                        opener: ".ip(",
+                        closer: ")",
+                        messagePrefix: "{ error: ",
+                        messageCloser: " })",
+                    };
+                case "ipv4":
+                    formatWasHandled = true;
+                    return {
+                        opener: '.ip({ version: "v4"',
+                        closer: " })",
+                        messagePrefix: ", error: ",
+                        messageCloser: " })",
+                    };
+                case "ipv6":
+                    formatWasHandled = true;
+                    return {
+                        opener: '.ip({ version: "v6"',
+                        closer: " })",
+                        messagePrefix: ", error: ",
+                        messageCloser: " })",
+                    };
+                case "uri":
+                    formatWasHandled = true;
+                    return {
+                        opener: ".url(",
+                        closer: ")",
+                        messagePrefix: "{ error: ",
+                        messageCloser: " })",
+                    };
+                case "uuid":
+                    formatWasHandled = true;
+                    return {
+                        opener: ".uuid(",
+                        closer: ")",
+                        messagePrefix: "{ error: ",
+                        messageCloser: " })",
+                    };
+                case "cuid":
+                    formatWasHandled = true;
+                    return {
+                        opener: ".cuid(",
+                        closer: ")",
+                        messagePrefix: "{ error: ",
+                        messageCloser: " })",
+                    };
+                case "cuid2":
+                    formatWasHandled = true;
+                    return {
+                        opener: ".cuid2(",
+                        closer: ")",
+                        messagePrefix: "{ error: ",
+                        messageCloser: " })",
+                    };
+                case "nanoid":
+                    formatWasHandled = true;
+                    return {
+                        opener: ".nanoid(",
+                        closer: ")",
+                        messagePrefix: "{ error: ",
+                        messageCloser: " })",
+                    };
+                case "ulid":
+                    formatWasHandled = true;
+                    return {
+                        opener: ".ulid(",
+                        closer: ")",
+                        messagePrefix: "{ error: ",
+                        messageCloser: " })",
+                    };
+                case "jwt":
+                    formatWasHandled = true;
+                    return {
+                        opener: ".jwt(",
+                        closer: ")",
+                        messagePrefix: "{ error: ",
+                        messageCloser: " })",
+                    };
+                case "e164":
+                    formatWasHandled = true;
+                    return {
+                        opener: ".e164(",
+                        closer: ")",
+                        messagePrefix: "{ error: ",
+                        messageCloser: " })",
+                    };
+                case "base64url":
+                    formatWasHandled = true;
+                    return {
+                        opener: ".base64url(",
+                        closer: ")",
+                        messagePrefix: "{ error: ",
+                        messageCloser: " })",
+                    };
+                case "emoji":
+                    formatWasHandled = true;
+                    return {
+                        opener: ".emoji(",
+                        closer: ")",
+                        messagePrefix: "{ error: ",
+                        messageCloser: " })",
+                    };
+                case "date-time":
+                    formatWasHandled = true;
+                    return {
+                        opener: ".datetime({ offset: true",
+                        closer: " })",
+                        messagePrefix: ", error: ",
+                        messageCloser: " })",
+                    };
+                case "time":
+                    formatWasHandled = true;
+                    return {
+                        opener: ".time(",
+                        closer: ")",
+                        messagePrefix: "{ error: ",
+                        messageCloser: " })",
+                    };
+                case "date":
+                    formatWasHandled = true;
+                    return {
+                        opener: ".date(",
+                        closer: ")",
+                        messagePrefix: "{ error: ",
+                        messageCloser: " })",
+                    };
+                case "binary":
+                    formatWasHandled = true;
+                    return {
+                        opener: ".base64(",
+                        closer: ")",
+                        messagePrefix: "{ error: ",
+                        messageCloser: " })",
+                    };
+                case "duration":
+                    formatWasHandled = true;
+                    return {
+                        opener: ".duration(",
+                        closer: ")",
+                        messagePrefix: "{ error: ",
+                        messageCloser: " })",
+                    };
+                case "hostname":
+                case "idn-hostname":
+                    formatWasHandled = true;
+                    return {
+                        opener: ".refine((val) => { if (typeof val !== \"string\" || val.length === 0 || val.length > 253) return false; return val.split(\".\").every((label) => label.length > 0 && label.length <= 63 && /^[A-Za-z0-9-]+$/.test(label) && label[0] !== \"-\" && label[label.length - 1] !== \"-\"); }",
+                        closer: ")",
+                        messagePrefix: ", { error: ",
+                        messageCloser: " })",
+                    };
+                case "idn-email":
+                    formatWasHandled = true;
+                    return {
+                        opener: ".email(",
+                        closer: ")",
+                        messagePrefix: "{ error: ",
+                        messageCloser: " })",
+                    };
+                case "uri-reference":
+                case "iri":
+                case "iri-reference":
+                    formatWasHandled = true;
+                    return {
+                        opener: '.refine((val) => { try { new URL(val, "http://example.com"); return true; } catch { return false; } }',
+                        closer: ")",
+                        messagePrefix: ", { error: ",
+                        messageCloser: " })",
+                    };
+                case "json-pointer":
+                    formatWasHandled = true;
+                    return {
+                        opener: ".refine((val) => typeof val === \"string\" && /^(?:\\/(?:[^/~]|~[01])*)*$/.test(val)",
+                        closer: ")",
+                        messagePrefix: ", { error: ",
+                        messageCloser: " })",
+                    };
+                case "relative-json-pointer":
+                    formatWasHandled = true;
+                    return {
+                        opener: ".refine((val) => typeof val === \"string\" && /^(?:0|[1-9][0-9]*)(?:#|(?:\\/(?:[^/~]|~[01])*))*$/.test(val)",
+                        closer: ")",
+                        messagePrefix: ", { error: ",
+                        messageCloser: " })",
+                    };
+                case "uri-template":
+                    formatWasHandled = true;
+                    return {
+                        opener: ".refine((val) => { if (typeof val !== \"string\") return false; const opens = (val.match(/\\{/g) || []).length; const closes = (val.match(/\\}/g) || []).length; return opens === closes; }",
+                        closer: ")",
+                        messagePrefix: ", { error: ",
+                        messageCloser: " })",
+                    };
+                case "regex":
+                    formatWasHandled = true;
+                    return {
+                        opener: ".refine((val) => { try { new RegExp(val); return true; } catch { return false; } }",
+                        closer: ")",
+                        messagePrefix: ", { error: ",
+                        messageCloser: " })",
+                    };
+            }
+        });
+    }
+    if (schema.format && !formatWasHandled) {
+        refContext.onUnknownFormat?.(schema.format, refContext.path);
+    }
+    r += withMessage(schema, "pattern", ({ json }) => ({
+        opener: `.regex(new RegExp(${json})`,
+        closer: ")",
+        messagePrefix: ", { error: ",
+        messageCloser: " })",
+    }));
+    r += withMessage(schema, "minLength", ({ json }) => ({
+        opener: `.min(${json}`,
+        closer: ")",
+        messagePrefix: ", { error: ",
+        messageCloser: " })",
+    }));
+    r += withMessage(schema, "maxLength", ({ json }) => ({
+        opener: `.max(${json}`,
+        closer: ")",
+        messagePrefix: ", { error: ",
+        messageCloser: " })",
+    }));
     r += withMessage(schema, "contentEncoding", ({ value }) => {
         if (value === "base64") {
-            return [".base64(", ")"];
+            return {
+                opener: ".base64(",
+                closer: ")",
+                messagePrefix: "{ error: ",
+                messageCloser: " })",
+            };
         }
     });
     const contentMediaType = withMessage(schema, "contentMediaType", ({ value }) => {
         if (value === "application/json") {
-            return [
-                ".transform((str, ctx) => { try { return JSON.parse(str); } catch (err) { ctx.addIssue({ code: \"custom\", message: \"Invalid JSON\" }); }}",
-                ", ",
-                ")"
-            ];
+            return {
+                opener: '.transform((str, ctx) => { try { return JSON.parse(str); } catch (err) { ctx.addIssue({ code: "custom", message: "Invalid JSON" }); }}',
+                closer: ")",
+                messagePrefix: ", { error: ",
+                messageCloser: " })",
+            };
         }
     });
     if (contentMediaType != "") {
         r += contentMediaType;
         r += withMessage(schema, "contentSchema", ({ value }) => {
             if (value && value instanceof Object) {
-                return [
-                    `.pipe(${parseSchema(value)}`,
-                    ", ",
-                    ")"
-                ];
+                return {
+                    opener: `.pipe(${parseSchema(value, refContext)}`,
+                    closer: ")",
+                    messagePrefix: ", { error: ",
+                    messageCloser: " })",
+                };
             }
         });
     }
     return r;
 };
+function ensureRefs(refs) {
+    if (refs)
+        return refs;
+    return {
+        path: [],
+        seen: new Map(),
+        declarations: new Map(),
+        dependencies: new Map(),
+        inProgress: new Set(),
+        refNameByPointer: new Map(),
+        usedNames: new Set(),
+    };
+}

package/dist/esm/utils/buildRefRegistry.js

@@ -0,0 +1,52 @@
+import { resolveUri } from "./resolveUri.js";
+export 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 ? 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 };
+};

package/dist/esm/utils/cycles.js

@@ -0,0 +1,107 @@
+export 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;
+};
+export const detectCycles = (defNames, deps) => {
+    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;
+        }
+        if (visited.has(node))
+            return;
+        visited.add(node);
+        recursionStack.add(node);
+        const targets = deps.get(node);
+        if (targets) {
+            for (const dep of targets) {
+                dfs(dep, [...path, node]);
+            }
+        }
+        recursionStack.delete(node);
+    }
+    for (const defName of defNames) {
+        if (!visited.has(defName))
+            dfs(defName, []);
+    }
+    return cycleNodes;
+};
+export const computeScc = (defNames, deps) => {
+    // Tarjan's algorithm, keeps mapping for quick "is this ref in my cycle?"
+    const index = new Map();
+    const lowlink = new Map();
+    const stack = [];
+    const onStack = new Set();
+    const componentByName = new Map();
+    const cycleMembers = new Set();
+    let currentIndex = 0;
+    let componentId = 0;
+    const strongConnect = (v) => {
+        index.set(v, currentIndex);
+        lowlink.set(v, currentIndex);
+        currentIndex += 1;
+        stack.push(v);
+        onStack.add(v);
+        const neighbors = deps.get(v);
+        if (neighbors) {
+            for (const w of neighbors) {
+                if (!index.has(w)) {
+                    strongConnect(w);
+                    lowlink.set(v, Math.min(lowlink.get(v), lowlink.get(w)));
+                }
+                else if (onStack.has(w)) {
+                    lowlink.set(v, Math.min(lowlink.get(v), index.get(w)));
+                }
+            }
+        }
+        if (lowlink.get(v) === index.get(v)) {
+            const component = [];
+            let w;
+            do {
+                w = stack.pop();
+                if (w === undefined)
+                    break;
+                onStack.delete(w);
+                component.push(w);
+                componentByName.set(w, componentId);
+            } while (w !== v);
+            if (component.length > 1) {
+                component.forEach((name) => cycleMembers.add(name));
+            }
+            componentId += 1;
+        }
+    };
+    for (const name of defNames) {
+        if (!index.has(name)) {
+            strongConnect(name);
+        }
+    }
+    return { cycleMembers, componentByName };
+};

package/dist/esm/utils/resolveUri.js

@@ -0,0 +1,12 @@
+export 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;
+    }
+};

package/dist/esm/utils/withMessage.js

@@ -4,14 +4,13 @@ export function withMessage(schema, key, get) {
     if (value !== undefined) {
         const got = get({ value, json: JSON.stringify(value) });
         if (got) {
-            const opener = got[0];
-            const prefix = got.length === 3 ? got[1] : "";
-            const closer = got.length === 3 ? got[2] : got[1];
+            const { opener, closer, messagePrefix = "", messageCloser } = got;
             r += opener;
             if (schema.errorMessage?.[key] !== undefined) {
-                r += prefix + JSON.stringify(schema.errorMessage[key]);
+                r += messagePrefix + JSON.stringify(schema.errorMessage[key]);
+                r += messageCloser ?? closer;
+                return r;
             }
-            r;
             r += closer;
         }
     }

package/dist/types/Types.d.ts

@@ -94,6 +94,21 @@ export type Options = {
      * @default false
      */
     strictOneOf?: boolean;
+    /**
+     * Called when a string format is encountered that has no built-in mapping.
+     * Can be used to log or throw on unknown formats.
+     */
+    onUnknownFormat?: (format: string, path: (string | number)[]) => void;
+    /**
+     * Called when a $ref/$dynamicRef cannot be resolved.
+     * Can be used to log or throw on unknown references.
+     */
+    onUnresolvedRef?: (ref: string, path: (string | number)[]) => void;
+    /**
+     * Optional resolver for external $ref URIs.
+     * Return a JsonSchema to register, or undefined if not found.
+     */
+    resolveExternalRef?: (uri: string) => JsonSchema | Promise<JsonSchema> | undefined;
 };
 export type Refs = Options & {
     path: (string | number)[];
@@ -103,10 +118,31 @@ export type Refs = Options & {
     }>;
     root?: JsonSchema;
     declarations?: Map<string, string>;
+    dependencies?: Map<string, Set<string>>;
     inProgress?: Set<string>;
     refNameByPointer?: Map<string, string>;
     usedNames?: Set<string>;
     currentSchemaName?: string;
+    cycleRefNames?: Set<string>;
+    cycleComponentByName?: Map<string, number>;
+    /** Base URI in scope while traversing */
+    currentBaseUri?: string;
+    /** Root/base URI for the document */
+    rootBaseUri?: string;
+    /** Prebuilt registry of resolved URIs/anchors */
+    refRegistry?: Map<string, {
+        schema: JsonSchema;
+        path: (string | number)[];
+        baseUri: string;
+        dynamic?: boolean;
+        anchor?: string;
+    }>;
+    /** Stack of active dynamic anchors (nearest last) */
+    dynamicAnchors?: {
+        name: string;
+        uri: string;
+        path: (string | number)[];
+    }[];
 };
 export type SimpleDiscriminatedOneOfSchema<D extends string = string> = JsonSchemaObject & {
     oneOf: (JsonSchemaObject & {

package/dist/types/core/analyzeSchema.d.ts

@@ -0,0 +1,24 @@
+import { Options, JsonSchema } from "../Types.js";
+export type NormalizedOptions = Options & {
+    exportRefs: boolean;
+    withMeta: boolean;
+};
+export type AnalysisResult = {
+    schema: JsonSchema;
+    options: NormalizedOptions;
+    refNameByPointer: Map<string, string>;
+    usedNames: Set<string>;
+    declarations: Map<string, string>;
+    dependencies: Map<string, Set<string>>;
+    cycleRefNames: Set<string>;
+    cycleComponentByName: Map<string, number>;
+    refRegistry: Map<string, {
+        schema: JsonSchema;
+        path: (string | number)[];
+        baseUri: string;
+        dynamic?: boolean;
+        anchor?: string;
+    }>;
+    rootBaseUri: string;
+};
+export declare const analyzeSchema: (schema: JsonSchema, options?: Options) => AnalysisResult;

package/dist/types/core/emitZod.d.ts

@@ -0,0 +1,2 @@
+import { AnalysisResult } from "./analyzeSchema.js";
+export declare const emitZod: (analysis: AnalysisResult) => string;