@oh-my-pi/omptype 18.16.0 → 18.18.0

package/CHANGELOG.md

@@ -2,6 +2,24 @@
 
 ## [Unreleased]
 
+## [18.17.0] - 2026-11-06
+
+### Breaking Changes
+
+- `fromJsonSchema` returns an opaque whole-document validator (no `.pick()`/`.props`); `format` is annotation-only unless checked via `formats`; bad `$ref` throws `invalid $ref`/`unresolved $ref`.
+
+### Added
+
+- Added `fromJsonSchema(schema, { draft, schemas, formats })`, validating JSON Schema draft 2020-12 and draft 7, including dynamic/remote refs and unevaluated keywords.
+
+### Changed
+
+- Faster `fromJsonSchema` validation, including `$ref`-heavy schemas.
+
+### Fixed
+
+- `fromJsonSchema` falls back to interpreted validation instead of throwing `EvalError` where generated code is forbidden.
+
 ## [18.13.3] - 2026-10-28
 
 ### Changed

package/README.md

@@ -87,6 +87,39 @@ const user = ZodUser.parse({ name: "Ada" });
 `@oh-my-pi/omptype/ark` provides the repository's ArkType compatibility facade
 and re-exports the same `type` and `scope` implementations.
 
+## JSON Schema import
+
+`fromJsonSchema` turns any JSON Schema document into an omptype schema that
+validates exactly as drafts 2020-12 and 7 specify, including `$dynamicRef`,
+`unevaluatedProperties`/`unevaluatedItems`, `$id`/`$anchor` resolution, and
+meta-schema vocabularies:
+
+```ts
+import { fromJsonSchema } from "@oh-my-pi/omptype";
+
+const read = fromJsonSchema(mcpTool.inputSchema, {
+	draft: "2020-12", // semantics where a resource declares no `$schema` ("7" for draft 7)
+	schemas: { "https://example.com/defs.json": defs }, // documents `$ref`s may name
+	formats: { email: value => value.includes("@") }, // `format` only asserts with a check
+});
+read.allows(args); // boolean
+read(args); // args with absent `default`s filled in, or OmpErrors with paths
+```
+
+The first calls are interpreted from a compiled plan; hot schemas switch to
+generated code (tagged unions become a `switch`, simple patterns char-code
+checks). It passes all 1,298 draft 2020-12 and 925 draft 7 core tests of the
+JSON-Schema-Test-Suite. Hot checks from the
+[pi-schema benchmark](https://github.com/earendil-works/pi/tree/main/packages/schema)
+(Node 26, Apple M4 Max, ns per valid check):
+
+| Case                             | omptype | ata | Ajv | TypeBox | pi-schema |
+| -------------------------------- | ------: | --: | --: | ------: | --------: |
+| nested object with tagged unions |  **85** | 131 | 337 |     341 |       305 |
+| union of 5 messages              |  **11** |  24 |  48 |      75 |        60 |
+| MCP tool schema with `$ref`      |  **35** |  40 |  85 |      66 |       113 |
+| recursive `$ref` schema          | **158** | 196 | 246 |     776 |       570 |
+
 ## Performance
 
 Run the benchmark from the repository root:

package/dist/js/compile.js

@@ -240,6 +240,10 @@ class Builder {
             }
             case "sub":
                 return `!(${this.ref(node.schema.run)}(${v}) instanceof AE)`;
+            case "refine":
+                if (node.check !== undefined)
+                    return `(${this.predicate(node.base, v)})&&${this.ref(node.check)}(${v})`;
+                return `!(${this.ref(boundWalk(node))}(${v}) instanceof AE)`;
             default:
                 return `!(${this.ref(boundWalk(node))}(${v}) instanceof AE)`;
         }
@@ -895,6 +899,22 @@ function boundWalk(node) {
 function resolvedRoot(ir) {
     return ir.k === "alias" ? ir.resolve() : ir;
 }
+/** Set once the runtime refuses code generation from strings (strict CSP); the interpreter serves from then on. */
+let jitBlocked = false;
+/** Build with `build`, or `undefined` when code generation from strings is forbidden. */
+function tryBuild(build) {
+    if (jitBlocked)
+        return undefined;
+    try {
+        return build();
+    }
+    catch (error) {
+        if (!(error instanceof EvalError))
+            throw error;
+        jitBlocked = true;
+        return undefined;
+    }
+}
 const compiledCache = new WeakMap();
 const allowsCache = new WeakMap();
 /** Compile `ir` into a specialized validator. */
@@ -908,8 +928,9 @@ export function compile(ir) {
         // fresh one forever. The wrapper resolves to the built validator by call
         // time; the interpreter is a safety net that never triggers post-build.
         const built = {};
-        compiledCache.set(root, value => (built.value === undefined ? walk(root, value) : built.value(value)));
-        const compiled = new Builder().build(root);
+        const deferred = (value) => (built.value === undefined ? walk(root, value) : built.value(value));
+        compiledCache.set(root, deferred);
+        const compiled = tryBuild(() => new Builder().build(root)) ?? ((value) => walk(root, value));
         built.value = compiled;
         compiledCache.set(root, compiled);
         return compiled;
@@ -923,7 +944,8 @@ export function compileAllows(ir) {
     if (validator === undefined) {
         const built = {};
         allowsCache.set(root, ((value) => built.value === undefined ? !(walk(root, value) instanceof OmpErrors) : built.value(value)));
-        const compiled = new Builder().buildAllows(root);
+        const compiled = tryBuild(() => new Builder().buildAllows(root)) ??
+            ((value) => !(walk(root, value) instanceof OmpErrors));
         built.value = compiled;
         allowsCache.set(root, compiled);
         return compiled;

package/dist/js/from-json-schema.js

@@ -1,235 +1,80 @@
 /**
  * JSON Schema → omptype importer.
  *
- * Rebuilds a callable schema from JSON Schema documents — the inverse of
- * `Type.toJsonSchema()` for the dialect omptype (and its Zod/TypeBox
- * adapters) emits: draft-07 and draft-2020-12 structural keywords, string
- * formats, `$defs`/`definitions` references (including recursion), enums,
- * and composition via `anyOf`/`oneOf`/`allOf`.
+ * Validates exactly as JSON Schema drafts 2020-12 and 7 specify: every
+ * keyword including `$dynamicRef`, `unevaluatedProperties`/`unevaluatedItems`,
+ * `$id`/`$anchor` resolution, remote references, and vocabularies declared by
+ * meta-schemas. Validation runs on an eval-free closure engine and moves to
+ * generated code once a schema is hot (see `jsonschema/`).
  *
- * Unknown or non-structural keywords are ignored, matching lenient importer
- * behavior: the result validates every constraint the schema can express in
- * omptype IR and passes the rest through.
+ * The result is a regular omptype schema: callable, composable, emitting the
+ * source document from `toJsonSchema()`, and filling absent properties from
+ * their `default` when called (never in `allows`).
+ *
+ * # Example
+ * ```ts
+ * const read = fromJsonSchema({
+ * 	type: "object",
+ * 	properties: { path: { type: "string" }, offset: { type: "integer", minimum: 0 } },
+ * 	required: ["path"],
+ * });
+ * read.allows({ path: "a.ts" }); // true
+ * read({ offset: -1 }); // OmpErrors: path missing, offset below 0
+ * ```
  */
-import { OmpTypeError } from "./errors.js";
-import { parseLocalRefPointer } from "./local-ref.js";
+import { OmpErrors } from "./errors.js";
 import { IR_BRAND } from "./ir.js";
-import { keywordIR, patternIR } from "./keywords.js";
+import { Validator } from "./jsonschema/validator.js";
 import { type } from "./type.js";
-/** `format` values lowered to built-in keyword validators. */
-const FORMAT_KEYWORDS = {
-    email: "string.email",
-    uuid: "string.uuid",
-    "date-time": "string.date.iso",
-    date: "string.date.iso",
-    ipv4: "string.ip.v4",
-    ipv6: "string.ip.v6",
-    regex: "string.regex",
-};
-class Importer {
-    #root;
-    #aliases = new Map();
-    constructor(root) {
-        this.#root = root;
-    }
-    resolveRef(ref) {
-        const cached = this.#aliases.get(ref);
-        if (cached !== undefined)
-            return cached;
-        let target;
-        if (ref === "#") {
-            target = this.#root;
-        }
-        else {
-            const pointer = parseLocalRefPointer(ref);
-            if (pointer === undefined || pointer.length !== 2 || (pointer[0] !== "$defs" && pointer[0] !== "definitions"))
-                throw new OmpTypeError(`unsupported $ref: ${ref}`);
-            const defs = this.#root[pointer[0]];
-            target = typeof defs === "object" && defs !== null ? defs[pointer[1]] : undefined;
-            if (target === undefined)
-                throw new OmpTypeError(`unresolved $ref: ${ref}`);
-        }
-        // Register the alias before lowering so recursive references resolve
-        // to the same node instead of recursing forever.
-        let lowered;
-        const alias = {
-            k: "alias",
-            name: ref,
-            resolve: () => {
-                lowered ??= this.lower(target);
-                return lowered;
-            },
-        };
-        this.#aliases.set(ref, alias);
-        return alias;
-    }
-    lower(schema) {
-        if (schema === true)
-            return { k: "unknown" };
-        if (schema === false)
-            return { k: "never" };
-        if (typeof schema !== "object" || schema === null) {
-            throw new OmpTypeError("JSON Schema nodes must be booleans or objects");
-        }
-        const node = schema;
-        const desc = typeof node.description === "string" ? node.description : undefined;
-        const ir = this.#lowerNode(node);
-        return desc === undefined ? ir : { ...ir, desc };
-    }
-    #lowerNode(node) {
-        if (typeof node.$ref === "string")
-            return this.resolveRef(node.$ref);
-        if (Array.isArray(node.enum)) {
-            const members = node.enum.map((v) => ({ k: "lit", v }));
-            return members.length === 1 ? members[0] : { k: "union", members };
-        }
-        if ("const" in node)
-            return { k: "lit", v: node.const };
-        const branches = node.anyOf ?? node.oneOf;
-        if (Array.isArray(branches)) {
-            return { k: "union", members: branches.map(branch => this.lower(branch)) };
-        }
-        if (Array.isArray(node.allOf)) {
-            const members = node.allOf.map(branch => this.lower(branch));
-            return members.length === 1 ? members[0] : { k: "intersection", members };
-        }
-        if (typeof node.not === "object" && node.not !== null && Object.keys(node.not).length === 0) {
-            return { k: "never" };
-        }
-        if (Array.isArray(node.type)) {
-            const members = node.type.map(t => this.#lowerTyped(node, String(t)));
-            return members.length === 1 ? members[0] : { k: "union", members };
-        }
-        if (typeof node.type === "string")
-            return this.#lowerTyped(node, node.type);
-        // No explicit type: infer from structural keywords, else accept anything.
-        if (node.properties !== undefined || node.required !== undefined)
-            return this.#lowerObject(node);
-        if (node.items !== undefined || node.prefixItems !== undefined)
-            return this.#lowerArray(node);
-        return { k: "unknown" };
-    }
-    #lowerTyped(node, kind) {
-        switch (kind) {
-            case "null":
-                return { k: "null" };
-            case "boolean":
-                return { k: "boolean" };
-            case "string":
-                return this.#lowerString(node);
-            case "number":
-            case "integer": {
-                const ir = { k: "number" };
-                if (kind === "integer")
-                    ir.int = true;
-                if (typeof node.minimum === "number")
-                    ir.min = node.minimum;
-                if (typeof node.maximum === "number")
-                    ir.max = node.maximum;
-                if (typeof node.exclusiveMinimum === "number") {
-                    ir.min = node.exclusiveMinimum;
-                    ir.xmin = true;
-                }
-                if (typeof node.exclusiveMaximum === "number") {
-                    ir.max = node.exclusiveMaximum;
-                    ir.xmax = true;
-                }
-                if (typeof node.multipleOf === "number")
-                    ir.divisor = node.multipleOf;
-                return ir;
-            }
-            case "object":
-                return this.#lowerObject(node);
-            case "array":
-                return this.#lowerArray(node);
-            default:
-                throw new OmpTypeError(`unsupported JSON Schema type: ${kind}`);
-        }
-    }
-    #lowerString(node) {
-        const base = { k: "string" };
-        if (typeof node.minLength === "number")
-            base.min = node.minLength;
-        if (typeof node.maxLength === "number")
-            base.max = node.maxLength;
-        if (node.format === "uri" || node.format === "url")
-            base.url = true;
-        const members = [];
-        if (typeof node.format === "string") {
-            const keyword = FORMAT_KEYWORDS[node.format];
-            if (keyword !== undefined) {
-                const formatIR = keywordIR(keyword);
-                if (formatIR !== undefined)
-                    members.push(formatIR);
-            }
-        }
-        if (typeof node.pattern === "string")
-            members.push(patternIR(new RegExp(node.pattern)));
-        if (members.length === 0)
-            return base;
-        if (base.min !== undefined || base.max !== undefined || base.url)
-            members.unshift(base);
-        return members.length === 1 ? members[0] : { k: "intersection", members };
-    }
-    #lowerObject(node) {
-        const required = new Set(Array.isArray(node.required) ? node.required.map(String) : []);
-        const props = [];
-        if (typeof node.properties === "object" && node.properties !== null) {
-            for (const [key, value] of Object.entries(node.properties)) {
-                const prop = { key, opt: !required.has(key), val: this.lower(value) };
-                if (typeof value === "object" && value !== null && "default" in value) {
-                    prop.hasDefault = true;
-                    prop.def = value.default;
-                    prop.opt = true;
-                }
-                props.push(prop);
-            }
-        }
-        const extra = node.additionalProperties;
-        return {
-            k: "object",
-            props,
-            extras: extra === false ? "reject" : "keep",
-            ...(typeof extra === "object" && extra !== null ? { index: this.lower(extra) } : {}),
-        };
-    }
-    #lowerArray(node) {
-        if (Array.isArray(node.prefixItems)) {
-            const minItems = typeof node.minItems === "number" ? node.minItems : node.prefixItems.length;
-            const prefix = node.prefixItems.map((item, index) => ({
-                val: this.lower(item),
-                opt: index >= minItems,
-            }));
-            return {
-                k: "tuple",
-                prefix,
-                postfix: [],
-                ...(node.items !== undefined && node.items !== false ? { variadic: this.lower(node.items) } : {}),
-            };
-        }
-        const ir = { k: "array", el: node.items === undefined ? { k: "unknown" } : this.lower(node.items) };
-        if (typeof node.minItems === "number")
-            ir.min = node.minItems;
-        if (typeof node.maxItems === "number")
-            ir.max = node.maxItems;
-        return ir;
-    }
-}
 /**
  * Build a callable omptype schema from a JSON Schema document.
  *
  * # Errors
- * Throws {@link OmpTypeError} on malformed nodes, unresolvable `$ref`s, or
- * types omptype cannot represent.
+ * Throws `OmpTypeError` when a `$ref` is malformed or names a document or
+ * location that neither `schema` nor `options.schemas` contains, when a
+ * `pattern` is not a regular expression, or when a schema node is neither a
+ * boolean nor an object.
  */
-export function fromJsonSchema(schema) {
-    const importer = new Importer(typeof schema === "object" && schema !== null ? schema : {});
+export function fromJsonSchema(schema, options) {
+    // Runs after 64 checks, long after `imported` below exists.
+    const validator = new Validator(schema, options, compiled => {
+        imported.allows = compiled;
+    });
+    const check = validator.check;
+    const node = typeof schema === "object" && schema !== null ? schema : undefined;
+    const refine = {
+        k: "refine",
+        base: { k: "unknown" },
+        check,
+        pred: value => check(value) || toErrors(validator.explain(value), value),
+        expected: "a value matching the JSON Schema",
+        json: node ?? (schema === false ? { not: {} } : {}),
+    };
+    if (typeof node?.description === "string")
+        refine.desc = node.description;
+    const ir = validator.hasDefaults
+        ? { k: "morph", input: refine, fn: value => validator.fillDefaults(value) }
+        : refine;
     const embedded = {
         [IR_BRAND]: true,
-        ir: importer.lower(schema),
+        ir,
         hasSteps: false,
         hasDefault: false,
         run: value => value,
     };
-    return type.raw(embedded);
+    const imported = type.raw(embedded);
+    // The engine's check is the whole boolean path; skip the generic dispatcher.
+    // Once generated code exists, `onCompile` above rebinds `allows` to it.
+    Object.defineProperty(imported, "allows", { value: check, writable: true, configurable: true });
+    return imported;
+}
+function toErrors(issues, value) {
+    if (issues.length === 0)
+        return new OmpErrors([], "a value matching the JSON Schema", value);
+    const errors = new OmpErrors(issues[0].path, issues[0].expected, issues[0].data);
+    for (let index = 1; index < issues.length; index++) {
+        const issue = issues[index];
+        errors.append(new OmpErrors(issue.path, issue.expected, issue.data));
+    }
+    return errors;
 }

package/dist/js/interp.js

@@ -202,6 +202,8 @@ function checkNode(ir, v) {
         case "refine":
             if (!checks(ir.base, v))
                 return false;
+            if (ir.check !== undefined)
+                return ir.check(v);
             try {
                 return ir.pred(v) === true;
             }