@oh-my-pi/omptype 18.16.0 → 18.18.0

package/dist/js/jsonschema/resolve.js

@@ -0,0 +1,321 @@
+/**
+ * Schema resource registry: base URIs, `$id`/`$anchor`/`$dynamicAnchor`
+ * identifiers, dialects, vocabularies, and `$ref` resolution across the root
+ * document and caller-supplied documents.
+ *
+ * Only subschemas under known applicator keywords are indexed, so an `$id`
+ * inside `enum` or an unknown keyword is not an identifier. JSON Pointer
+ * fragments may still point anywhere; their target inherits the base URI of
+ * the nearest indexed ancestor.
+ */
+import { OmpTypeError } from "../errors.js";
+import { parseLocalRefPointer } from "../local-ref.js";
+/** Vocabulary flags gating keyword groups; resources default to all of them. */
+export const VOCAB_APPLICATOR = 1;
+export const VOCAB_VALIDATION = 2;
+export const VOCAB_UNEVALUATED = 4;
+const VOCAB_ALL = VOCAB_APPLICATOR | VOCAB_VALIDATION | VOCAB_UNEVALUATED;
+/** Base URI for documents without an absolute `$id`. */
+const DEFAULT_BASE = "omptype:/schema.json";
+const SCHEMAS = 1;
+const SCHEMA_MAP = 2;
+/**
+ * Keywords holding subschemas: a schema or array of schemas, or a map of names
+ * to schemas. A `Map`, so `then` is no thenable key and `constructor` no hit.
+ */
+const SUBSCHEMA_KEYWORDS = new Map([
+    ["items", SCHEMAS],
+    ["additionalItems", SCHEMAS],
+    ["prefixItems", SCHEMAS],
+    ["contains", SCHEMAS],
+    ["additionalProperties", SCHEMAS],
+    ["propertyNames", SCHEMAS],
+    ["unevaluatedItems", SCHEMAS],
+    ["unevaluatedProperties", SCHEMAS],
+    ["not", SCHEMAS],
+    ["if", SCHEMAS],
+    ["then", SCHEMAS],
+    ["else", SCHEMAS],
+    ["allOf", SCHEMAS],
+    ["anyOf", SCHEMAS],
+    ["oneOf", SCHEMAS],
+    ["contentSchema", SCHEMAS],
+    ["properties", SCHEMA_MAP],
+    ["patternProperties", SCHEMA_MAP],
+    ["$defs", SCHEMA_MAP],
+    ["definitions", SCHEMA_MAP],
+    ["dependentSchemas", SCHEMA_MAP],
+    ["dependencies", SCHEMA_MAP],
+]);
+const VOCABULARIES = {
+    applicator: VOCAB_APPLICATOR,
+    validation: VOCAB_VALIDATION,
+    unevaluated: VOCAB_UNEVALUATED,
+};
+/** Registry of the documents one `fromJsonSchema` call can reference. */
+export class Registry {
+    #resources = new Map();
+    #anchors = new Map();
+    /** Per-registry index: one subschema object can sit at different bases in different registries. */
+    #locations = new Map();
+    /** Caller-supplied documents by fragment-free URI, indexed on first use. */
+    #pending = new Map();
+    #draft;
+    constructor(draft, documents) {
+        this.#draft = draft;
+        if (documents === undefined)
+            return;
+        for (const key in documents) {
+            const uri = stripFragment(parseUri(key) ?? key);
+            this.#pending.set(uri, documents[key]);
+        }
+    }
+    /** Index `schema` as the root document and return its target. */
+    addRoot(schema) {
+        if (typeof schema !== "object" || schema === null) {
+            return {
+                schema,
+                location: { base: DEFAULT_BASE, resource: this.#newResource(DEFAULT_BASE, {}, this.#draft) },
+            };
+        }
+        return this.#addDocument(DEFAULT_BASE, schema);
+    }
+    /** Location recorded for an indexed subschema. */
+    location(schema) {
+        return this.#locations.get(schema);
+    }
+    /**
+     * Resolve `ref` against `base` to a schema and its location.
+     *
+     * # Errors
+     * Throws {@link OmpTypeError} for malformed URI references or fragments, and
+     * for targets no known document contains.
+     */
+    resolve(ref, base) {
+        let uri;
+        let fragment;
+        if (ref.charCodeAt(0) === 35) {
+            uri = base;
+            fragment = ref.slice(1);
+        }
+        else {
+            const absolute = parseUri(ref, base);
+            if (absolute === undefined)
+                throw new OmpTypeError(`invalid $ref: ${ref}`);
+            const hash = absolute.indexOf("#");
+            uri = hash < 0 ? absolute : absolute.slice(0, hash);
+            fragment = hash < 0 ? "" : absolute.slice(hash + 1);
+        }
+        const resource = this.#resource(uri);
+        if (resource === undefined)
+            throw new OmpTypeError(`unresolved $ref: ${ref}`);
+        if (fragment === "")
+            return { schema: resource.root, location: this.#locations.get(resource.root) };
+        if (fragment.charCodeAt(0) === 47)
+            return this.#pointer(resource, fragment, ref);
+        let name;
+        try {
+            name = decodeURIComponent(fragment);
+        }
+        catch {
+            throw new OmpTypeError(`invalid $ref: ${ref}`);
+        }
+        const anchor = this.#anchors.get(`${uri}#${name}`) ?? this.#anchorFromPending(`${uri}#${name}`);
+        if (anchor === undefined)
+            throw new OmpTypeError(`unresolved $ref: ${ref}`);
+        return anchor;
+    }
+    #anchorFromPending(key) {
+        if (this.#pending.size === 0)
+            return undefined;
+        this.#indexPending();
+        return this.#anchors.get(key);
+    }
+    #pointer(resource, fragment, ref) {
+        const tokens = parseLocalRefPointer(`#${fragment}`);
+        if (tokens === undefined)
+            throw new OmpTypeError(`invalid $ref: ${ref}`);
+        let node = resource.root;
+        let location = this.#locations.get(resource.root);
+        for (const token of tokens) {
+            if (Array.isArray(node)) {
+                if (!/^(?:0|[1-9]\d*)$/.test(token) || Number(token) >= node.length) {
+                    throw new OmpTypeError(`unresolved $ref: ${ref}`);
+                }
+                node = node[Number(token)];
+            }
+            else if (typeof node === "object" && node !== null && Object.hasOwn(node, token)) {
+                node = node[token];
+            }
+            else {
+                throw new OmpTypeError(`unresolved $ref: ${ref}`);
+            }
+            if (typeof node === "object" && node !== null)
+                location = this.#locations.get(node) ?? location;
+        }
+        return { schema: node, location };
+    }
+    #resource(uri) {
+        const known = this.#resources.get(uri);
+        if (known !== undefined)
+            return known;
+        const document = this.#pending.get(uri);
+        if (document !== undefined) {
+            this.#pending.delete(uri);
+            if (typeof document === "object" && document !== null)
+                this.#addDocument(uri, document);
+            return this.#resources.get(uri);
+        }
+        // The URI may name a resource embedded in a document not yet indexed.
+        if (this.#pending.size === 0)
+            return undefined;
+        this.#indexPending();
+        return this.#resources.get(uri);
+    }
+    #indexPending() {
+        for (const [uri, document] of this.#pending) {
+            this.#pending.delete(uri);
+            if (typeof document === "object" && document !== null && !this.#resources.has(uri)) {
+                this.#addDocument(uri, document);
+            }
+        }
+    }
+    #addDocument(retrieval, root) {
+        const resource = this.#newResource(retrieval, root, this.#draft);
+        const location = { base: retrieval, resource };
+        this.#index(root, location);
+        const own = this.#locations.get(root) ?? location;
+        return { schema: root, location: own };
+    }
+    #newResource(uri, root, inherited) {
+        const dialect = root.$schema;
+        let draft = inherited;
+        let vocab = VOCAB_ALL;
+        if (typeof dialect === "string") {
+            const resolved = this.#dialect(stripFragment(parseUri(dialect) ?? dialect), 0);
+            if (resolved !== undefined) {
+                draft = resolved.draft ?? inherited;
+                vocab = resolved.vocab;
+            }
+        }
+        const resource = { uri, root, draft, vocab, dynamicAnchors: new Map() };
+        if (!this.#resources.has(uri))
+            this.#resources.set(uri, resource);
+        return resource;
+    }
+    /** Draft and vocabularies a `$schema` URI selects; unknown dialects inherit. */
+    #dialect(uri, depth) {
+        if (/^https?:\/\/json-schema\.org\/draft-0[3-7]\/schema$/.test(uri))
+            return { draft: "7", vocab: VOCAB_ALL };
+        if (/^https?:\/\/json-schema\.org\/draft\/2020-12\/schema$/.test(uri))
+            return { draft: "2020-12", vocab: VOCAB_ALL };
+        if (/^https?:\/\/json-schema\.org\/draft\/2019-09\/schema$/.test(uri))
+            return { draft: "2019-09", vocab: VOCAB_ALL };
+        if (depth > 8)
+            return undefined;
+        const meta = this.#resources.get(uri)?.root ?? this.#pending.get(uri);
+        if (typeof meta !== "object" || meta === null)
+            return undefined;
+        const metaSchema = meta;
+        const parent = typeof metaSchema.$schema === "string" && stripFragment(metaSchema.$schema) !== uri
+            ? this.#dialect(stripFragment(parseUri(metaSchema.$schema) ?? metaSchema.$schema), depth + 1)
+            : undefined;
+        const vocabularies = metaSchema.$vocabulary;
+        if (typeof vocabularies !== "object" || vocabularies === null)
+            return parent;
+        let vocab = 0;
+        for (const vocabulary in vocabularies) {
+            const name = vocabulary.slice(vocabulary.lastIndexOf("/") + 1);
+            vocab |= VOCABULARIES[name] ?? 0;
+            // Draft 2019-09 kept the unevaluated keywords in its applicator vocabulary.
+            if (name === "applicator" && vocabulary.includes("/2019-09/"))
+                vocab |= VOCAB_UNEVALUATED;
+        }
+        return { draft: parent?.draft ?? "2020-12", vocab };
+    }
+    #index(node, parent) {
+        if (typeof node !== "object" || node === null || Array.isArray(node))
+            return;
+        if (this.#locations.has(node))
+            return;
+        const schema = node;
+        let location = parent;
+        const draft7 = parent.resource.draft === "7";
+        const id = schema.$id;
+        let idAnchor;
+        if (typeof id === "string" && !(draft7 && typeof schema.$ref === "string")) {
+            if (id.charCodeAt(0) === 35) {
+                // Draft 7 location-independent identifier: `"$id": "#name"`.
+                idAnchor = id.slice(1);
+            }
+            else {
+                const absolute = parseUri(id, parent.base);
+                if (absolute !== undefined) {
+                    const hash = absolute.indexOf("#");
+                    const uri = hash < 0 ? absolute : absolute.slice(0, hash);
+                    if (hash >= 0 && hash < absolute.length - 1)
+                        idAnchor = absolute.slice(hash + 1);
+                    const resource = node === parent.resource.root && parent.base === parent.resource.uri
+                        ? this.#adoptRoot(parent.resource, uri)
+                        : this.#newResource(uri, schema, parent.resource.draft);
+                    location = { base: uri, resource };
+                }
+            }
+        }
+        this.#locations.set(schema, location);
+        const anchor = schema.$anchor;
+        const dynamicAnchor = schema.$dynamicAnchor;
+        if (idAnchor !== undefined || typeof anchor === "string" || typeof dynamicAnchor === "string") {
+            const target = { schema, location };
+            if (idAnchor !== undefined)
+                this.#anchors.set(`${location.base}#${idAnchor}`, target);
+            if (typeof anchor === "string")
+                this.#anchors.set(`${location.base}#${anchor}`, target);
+            if (typeof dynamicAnchor === "string") {
+                this.#anchors.set(`${location.base}#${dynamicAnchor}`, target);
+                location.resource.dynamicAnchors.set(dynamicAnchor, schema);
+            }
+        }
+        for (const keyword in schema) {
+            const kind = SUBSCHEMA_KEYWORDS.get(keyword);
+            if (kind === undefined)
+                continue;
+            const value = schema[keyword];
+            if (kind === SCHEMAS) {
+                if (Array.isArray(value))
+                    for (const item of value)
+                        this.#index(item, location);
+                else
+                    this.#index(value, location);
+            }
+            else if (typeof value === "object" && value !== null && !Array.isArray(value)) {
+                for (const key in value)
+                    this.#index(value[key], location);
+            }
+        }
+    }
+    /** The document root's own `$id` names the same resource as its retrieval URI. */
+    #adoptRoot(resource, uri) {
+        if (uri === resource.uri)
+            return resource;
+        const adopted = { ...resource, uri };
+        if (!this.#resources.has(uri))
+            this.#resources.set(uri, adopted);
+        // Retrieval URI keeps resolving to the root, now evaluated under its `$id`.
+        this.#resources.set(resource.uri, adopted);
+        return adopted;
+    }
+}
+/** Absolute form of `reference` resolved against `base`, or `undefined` when unparsable. */
+function parseUri(reference, base) {
+    try {
+        return new URL(reference, base).href;
+    }
+    catch {
+        return undefined;
+    }
+}
+function stripFragment(uri) {
+    const hash = uri.indexOf("#");
+    return hash < 0 ? uri : uri.slice(0, hash);
+}

package/dist/js/jsonschema/runtime.js

@@ -0,0 +1,129 @@
+/**
+ * Runtime helpers shared by the closure validators (`closures.ts`) and the
+ * generated ones (`codegen.ts`): JSON value equality, `uniqueItems`,
+ * `multipleOf`, code-point string length, and the pattern cache.
+ */
+const hasOwn = Object.hasOwn;
+/** JSON equality: numbers by value, arrays by order, objects by key set regardless of order. */
+export function jsonEqual(a, b) {
+    if (a === b)
+        return true;
+    if (typeof a !== "object" || typeof b !== "object" || a === null || b === null)
+        return false;
+    const array = Array.isArray(a);
+    if (array !== Array.isArray(b))
+        return false;
+    if (array) {
+        const left = a;
+        const right = b;
+        if (left.length !== right.length)
+            return false;
+        for (let index = 0; index < left.length; index++)
+            if (!jsonEqual(left[index], right[index]))
+                return false;
+        return true;
+    }
+    const left = a;
+    const right = b;
+    let count = 0;
+    for (const key in left) {
+        if (!hasOwn(left, key))
+            continue;
+        if (!hasOwn(right, key) || !jsonEqual(left[key], right[key]))
+            return false;
+        count++;
+    }
+    for (const key in right)
+        if (hasOwn(right, key))
+            count--;
+    return count === 0;
+}
+/** True when `values` contains `value` under {@link jsonEqual}. */
+export function jsonIncludes(values, value) {
+    for (const candidate of values)
+        if (jsonEqual(candidate, value))
+            return true;
+    return false;
+}
+/** `uniqueItems`: no two elements are {@link jsonEqual}. */
+export function uniqueItems(items) {
+    const n = items.length;
+    if (n < 2)
+        return true;
+    let primitive = true;
+    for (let index = 0; index < n; index++) {
+        const item = items[index];
+        if (typeof item === "object" && item !== null) {
+            primitive = false;
+            break;
+        }
+    }
+    // SameValueZero matches JSON equality for primitives (0 equals -0).
+    if (primitive && n > 16)
+        return new Set(items).size === n;
+    for (let i = 1; i < n; i++) {
+        const item = items[i];
+        for (let j = 0; j < i; j++) {
+            if (primitive ? item === items[j] : jsonEqual(item, items[j]))
+                return false;
+        }
+    }
+    return true;
+}
+/**
+ * `multipleOf` with float tolerance: `0.0075` is a multiple of `0.0001` even
+ * though the IEEE quotient is `74.99999999999999`. An overflowing quotient is
+ * a multiple only when `divisor` divides 1 (every integer is a multiple of 0.5).
+ */
+export function isMultipleOf(value, divisor) {
+    const quotient = value / divisor;
+    if (Number.isInteger(quotient))
+        return true;
+    if (!Number.isFinite(quotient))
+        return Number.isInteger(value) && Number.isInteger(1 / divisor);
+    return Math.abs(quotient - Math.round(quotient)) <= Number.EPSILON * Math.abs(quotient);
+}
+/** String length in Unicode code points, as `minLength`/`maxLength` count it. */
+export function codePointLength(value) {
+    let length = value.length;
+    for (let index = 0; index < value.length - 1; index++) {
+        const high = value.charCodeAt(index);
+        if (high < 0xd800 || high > 0xdbff)
+            continue;
+        const low = value.charCodeAt(index + 1);
+        if (low >= 0xdc00 && low <= 0xdfff) {
+            length--;
+            index++;
+        }
+    }
+    return length;
+}
+const patterns = new Map();
+const PATTERN_CACHE_LIMIT = 1024;
+/**
+ * Compile a JSON Schema `pattern` as an ECMAScript regex with the `u` flag,
+ * falling back to legacy syntax for patterns that only parse without it.
+ * Regexes are stateless (no `g`/`y`), so equal sources share one instance.
+ *
+ * # Errors
+ * Throws `SyntaxError` when the source is not a regular expression at all.
+ */
+export function compilePattern(source) {
+    let regex = patterns.get(source);
+    if (regex !== undefined)
+        return regex;
+    try {
+        regex = new RegExp(source, "u");
+    }
+    catch {
+        regex = new RegExp(source);
+    }
+    if (patterns.size >= PATTERN_CACHE_LIMIT)
+        patterns.clear();
+    patterns.set(source, regex);
+    return regex;
+}
+/** Property names inherited by plain objects; reading them needs an own-property check. */
+export function isInheritedName(key) {
+    return key in Object.prototype;
+}

package/dist/js/jsonschema/validator.js

@@ -0,0 +1,106 @@
+/**
+ * JSON Schema validator engine behind `fromJsonSchema`: plans the document,
+ * interprets the plan for the first calls, and swaps in generated code once a
+ * schema proves hot. Where code generation is forbidden (strict CSP) the
+ * interpreter keeps serving every call.
+ */
+import { generate } from "./codegen.js";
+import { Sink, validate } from "./interpret.js";
+import { Planner } from "./plan.js";
+import { Registry } from "./resolve.js";
+/** Calls interpreted before the JIT generates code; generation costs about as much as a hundred interpreted checks. */
+const JIT_THRESHOLD = 64;
+/** A compiled JSON Schema. */
+export class Validator {
+    /** Allocation-free validity test; safe to detach (`const check = validator.check`). */
+    check;
+    /** Whether some `properties` subschema declares a `default` for {@link fillDefaults} to apply. */
+    hasDefaults;
+    #root;
+    /**
+     * `onCompile` receives the steady-state check once the schema turns hot
+     * (generated code, or the interpreter where code generation is forbidden), so
+     * callers holding their own reference can drop the dispatch through `check`.
+     *
+     * # Errors
+     * Throws `OmpTypeError` for unresolvable or malformed `$ref`s, invalid
+     * patterns, and schema nodes that are neither booleans nor objects.
+     */
+    constructor(schema, options = {}, onCompile) {
+        const registry = new Registry(options.draft ?? "2020-12", options.schemas);
+        const planner = new Planner(registry, options.formats);
+        const root = planner.root(schema);
+        this.hasDefaults = planner.sawDefaults;
+        this.#root = root;
+        let calls = 0;
+        let impl = (value) => {
+            if (++calls < JIT_THRESHOLD)
+                return validate(root, value);
+            impl = generate(root) ?? ((input) => validate(root, input));
+            onCompile?.(impl);
+            return impl(value);
+        };
+        this.check = value => impl(value);
+    }
+    /** Every issue that makes `value` invalid (empty when it is valid). */
+    explain(value) {
+        const sink = new Sink();
+        validate(this.#root, value, sink);
+        return sink.issues;
+    }
+    /** `value` with absent declared properties set to their `default`, copied on write. */
+    fillDefaults(value) {
+        return fill(this.#root, value);
+    }
+}
+/** Defaults descend through in-place `$ref`/`allOf`, declared properties, and items. */
+function fill(plan, value) {
+    let out = value;
+    if (plan.refs !== undefined)
+        for (const ref of plan.refs)
+            out = fill(ref, out);
+    if (plan.allOf !== undefined)
+        for (const branch of plan.allOf)
+            out = fill(branch, out);
+    if (typeof out !== "object" || out === null)
+        return out;
+    if (Array.isArray(out)) {
+        const prefix = plan.prefixItems ?? [];
+        if (prefix.length === 0 && plan.items === undefined)
+            return out;
+        let copy;
+        for (let index = 0; index < out.length; index++) {
+            const itemPlan = index < prefix.length ? prefix[index] : plan.items;
+            if (itemPlan === undefined)
+                continue;
+            const item = fill(itemPlan, out[index]);
+            if (item === out[index])
+                continue;
+            copy ??= [...out];
+            copy[index] = item;
+        }
+        return copy ?? out;
+    }
+    if (plan.properties === undefined)
+        return out;
+    const source = out;
+    let copy;
+    for (const { key, plan: propertyPlan } of plan.properties) {
+        if (!Object.hasOwn(source, key) || source[key] === undefined)
+            continue;
+        const filled = fill(propertyPlan, source[key]);
+        if (filled === source[key])
+            continue;
+        copy ??= { ...source };
+        copy[key] = filled;
+    }
+    if (plan.defaults !== undefined) {
+        for (const { key, value: fallback } of plan.defaults) {
+            if (Object.hasOwn(source, key) && source[key] !== undefined)
+                continue;
+            copy ??= { ...source };
+            copy[key] = typeof fallback === "object" && fallback !== null ? structuredClone(fallback) : fallback;
+        }
+    }
+    return copy ?? out;
+}

package/dist/js/typebox.js

@@ -283,7 +283,7 @@ function tRecord(key, value, opts) {
                 return ctx.mustBe("an object with valid record keys");
         return true;
     });
-    return applyMeta(base, opts);
+    return asSchema(applyMeta(base, opts));
 }
 function tOptional(schema, opts) {
     const marker = applyMeta(asRuntime(schema).or(asRuntime(type.raw("undefined"))), opts);
@@ -304,7 +304,7 @@ function tPartial(schema) {
     const props = {};
     for (const key in info.props)
         props[key] = asRuntime(info.props[key])[OPTIONAL_INNER] ? info.props[key] : tOptional(info.props[key]);
-    return tObject(props, { additionalProperties: info.additionalProperties });
+    return asSchema(tObject(props, { additionalProperties: info.additionalProperties }));
 }
 function tRequired(schema) {
     const info = requireObject(schema, "Required");
@@ -312,7 +312,7 @@ function tRequired(schema) {
     for (const key in info.props) {
         props[key] = asRuntime(info.props[key])[OPTIONAL_INNER] ?? info.props[key];
     }
-    return tObject(props, { additionalProperties: info.additionalProperties });
+    return asSchema(tObject(props, { additionalProperties: info.additionalProperties }));
 }
 function tPick(schema, keys) {
     const info = requireObject(schema, "Pick");
@@ -320,7 +320,7 @@ function tPick(schema, keys) {
     for (const key of keys)
         if (typeof key === "string" && info.props[key])
             props[key] = info.props[key];
-    return tObject(props, { additionalProperties: info.additionalProperties });
+    return asSchema(tObject(props, { additionalProperties: info.additionalProperties }));
 }
 function tOmit(schema, keys) {
     const info = requireObject(schema, "Omit");
@@ -329,7 +329,7 @@ function tOmit(schema, keys) {
     for (const key in info.props)
         if (!omitted.has(key))
             props[key] = info.props[key];
-    return tObject(props, { additionalProperties: info.additionalProperties });
+    return asSchema(tObject(props, { additionalProperties: info.additionalProperties }));
 }
 function tComposite(schemas, opts) {
     const props = {};

package/dist/types/from-json-schema.d.ts

@@ -1,9 +1,14 @@
+import { type ValidatorOptions } from "./jsonschema/validator.js";
 import { type BaseType } from "./type.js";
+/** Options for {@link fromJsonSchema}. */
+export type FromJsonSchemaOptions = ValidatorOptions;
 /**
  * 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 declare function fromJsonSchema(schema: unknown): BaseType;
+export declare function fromJsonSchema(schema: unknown, options?: FromJsonSchemaOptions): BaseType;

package/dist/types/ir.d.ts

@@ -158,6 +158,8 @@ export type IR = IRAnalysis & ({
     k: "refine";
     base: IR;
     pred: (value: unknown) => boolean | OmpErrors;
+    /** Allocation-free equivalent of `pred(value) === true` for boolean-only paths (`allows`, unions). */
+    check?: (value: unknown) => boolean;
     expected: string;
     json?: Record<string, unknown>;
     desc?: string;

package/dist/types/jsonschema/codegen.d.ts

@@ -0,0 +1,6 @@
+import { type Plan } from "./plan.js";
+/**
+ * Generate a validator for `root`, or `undefined` when the runtime forbids
+ * code generation from strings.
+ */
+export declare function generate(root: Plan): ((value: unknown) => value is unknown) | undefined;

package/dist/types/jsonschema/interpret.d.ts

@@ -0,0 +1,48 @@
+import { type Plan } from "./plan.js";
+/** One failure found while explaining an invalid value. */
+export interface Issue {
+    readonly path: PropertyKey[];
+    readonly expected: string;
+    readonly data: unknown;
+}
+/** Issue collector for explain mode. */
+export declare class Sink {
+    readonly issues: Issue[];
+    add(expected: string, data: unknown, key?: PropertyKey): void;
+    /** Prefix the paths of issues recorded since `from` with `key`. */
+    prefix(from: number, key: PropertyKey): void;
+}
+/** Locations of the current instance evaluated so far by successful subschemas. */
+export interface Ann {
+    /** Evaluated property names, or `true` once every property is evaluated. */
+    props: Set<string> | true | undefined;
+    /** Every index below this is evaluated (`Infinity` for all). */
+    items: number;
+    /** Indices evaluated by `contains`. */
+    contained: Set<number> | undefined;
+}
+/** Human-readable expectation for a `T_*` mask. */
+export declare function describeTypes(types: number): string;
+/**
+ * Object property whose value selects the only `anyOf`/`oneOf` branch that can
+ * pass: every branch is an object schema requiring the property with distinct
+ * primitive `const`/`enum` values.
+ */
+export interface Discriminator {
+    readonly key: string;
+    /** Tag value → branch index. */
+    readonly branches: Map<unknown, number>;
+}
+/** Follow plans that are a bare single `$ref`. */
+export declare function unwrapRef(plan: Plan): Plan;
+/** True when the plan's only constraint is its `refs`. */
+export declare function isRefOnly(plan: Plan): boolean;
+/** Find a {@link Discriminator} for union branches, if one exists. */
+export declare function findDiscriminator(branches: readonly Plan[]): Discriminator | undefined;
+/**
+ * Whether `value` satisfies `plan`.
+ *
+ * Infinite `$ref` cycles that never descend into the value (`{"$ref": "#"}`)
+ * overflow the stack, as they would in any evaluator.
+ */
+export declare function validate(plan: Plan, value: unknown, sink?: Sink, ann?: Ann): boolean;