@crewhaus/tool-schema 0.7.0 → 0.8.1

package/dist/lib/schemadiff.js

@@ -21,7 +21,8 @@
  * writer sees the mirror image — a widened type is a breaking change for
  * whoever must now produce it.
  */
-import { deepEqual, isPlainObject, joinPointer, preview } from "./value";
+import { indexShapes } from "./shape-index";
+import { isPlainObject, joinPointer, preview } from "./value";
 function note(ctx, path, keyword, compat, detail) {
     ctx.changes.push({ path, keyword, detail, compat });
 }
@@ -42,7 +43,7 @@ function acceptsType(types, type) {
 }
 /** A bound that may only loosen: `minimum`, `minLength`, `minItems`, ... */
 function diffLowerBound(ctx, path, keyword, before, after) {
-    if (deepEqual(before, after))
+    if (ctx.same.equal(before, after))
         return;
     if (typeof after !== "number") {
         note(ctx, path, keyword, "compatible", `${keyword} removed — the constraint is gone`);
@@ -59,7 +60,7 @@ function diffLowerBound(ctx, path, keyword, before, after) {
 }
 /** A bound that may only loosen upwards: `maximum`, `maxLength`, `maxItems`, ... */
 function diffUpperBound(ctx, path, keyword, before, after) {
-    if (deepEqual(before, after))
+    if (ctx.same.equal(before, after))
         return;
     if (typeof after !== "number") {
         note(ctx, path, keyword, "compatible", `${keyword} removed — the constraint is gone`);
@@ -126,8 +127,32 @@ const ANNOTATIONS = new Set([
     "$defs",
     "definitions",
 ]);
+/**
+ * The values of `values` equal to no value of `others`, in order. By key
+ * when the index covers every value, so two enums of n values cost n and not
+ * n²; otherwise by comparing every pair, as `deepEqual` would.
+ */
+function missingFrom(values, others, same) {
+    const pairwise = () => values.filter((v) => !others.some((w) => same.equal(v, w)));
+    const present = new Set();
+    for (const other of others) {
+        const key = same.key(other);
+        if (key === undefined)
+            return pairwise();
+        present.add(key);
+    }
+    const missing = [];
+    for (const value of values) {
+        const key = same.key(value);
+        if (key === undefined)
+            return pairwise();
+        if (!present.has(key))
+            missing.push(value);
+    }
+    return missing;
+}
 function diffNode(before, after, path, ctx) {
-    if (deepEqual(before, after))
+    if (ctx.same.equal(before, after))
         return;
     // Boolean schemas: `true` accepts everything, `false` accepts nothing.
     if (typeof before === "boolean" || typeof after === "boolean") {
@@ -176,8 +201,8 @@ function diffNode(before, after, path, ctx) {
         note(ctx, path, "enum", "compatible", "enum removed — values are no longer limited");
     }
     else if (aEnum !== null && bEnum !== null) {
-        const removed = aEnum.filter((v) => !bEnum.some((w) => deepEqual(v, w)));
-        const added = bEnum.filter((v) => !aEnum.some((w) => deepEqual(v, w)));
+        const removed = missingFrom(aEnum, bEnum, ctx.same);
+        const added = missingFrom(bEnum, aEnum, ctx.same);
         if (removed.length > 0) {
             note(ctx, path, "enum", "breaking", `enum values removed: ${preview(removed, 80)}`);
         }
@@ -187,7 +212,7 @@ function diffNode(before, after, path, ctx) {
     }
     const aConst = Object.hasOwn(a, "const");
     const bConst = Object.hasOwn(b, "const");
-    if (!deepEqual(a["const"], b["const"]) || aConst !== bConst) {
+    if (!ctx.same.equal(a["const"], b["const"]) || aConst !== bConst) {
         if (bConst && !aConst) {
             note(ctx, path, "const", "breaking", `const added (${preview(b["const"], 60)})`);
         }
@@ -205,8 +230,12 @@ function diffNode(before, after, path, ctx) {
     const bRequired = Array.isArray(b["required"])
         ? b["required"].filter((k) => typeof k === "string")
         : [];
-    const nowRequired = bRequired.filter((k) => !aRequired.includes(k));
-    const noLongerRequired = aRequired.filter((k) => !bRequired.includes(k));
+    // Sets, not a search of the other list per name: two lists of n names, and
+    // n properties added against a list of n, each cost n².
+    const aRequiredSet = new Set(aRequired);
+    const bRequiredSet = new Set(bRequired);
+    const nowRequired = bRequired.filter((k) => !aRequiredSet.has(k));
+    const noLongerRequired = aRequired.filter((k) => !bRequiredSet.has(k));
     if (nowRequired.length > 0) {
         note(ctx, path, "required", "breaking", `now required: ${nowRequired.join(", ")}`);
     }
@@ -228,7 +257,7 @@ function diffNode(before, after, path, ctx) {
     for (const keyword of ["pattern", "format", "multipleOf"]) {
         const beforeValue = a[keyword];
         const afterValue = b[keyword];
-        if (deepEqual(beforeValue, afterValue))
+        if (ctx.same.equal(beforeValue, afterValue))
             continue;
         if (afterValue === undefined) {
             note(ctx, path, keyword, "compatible", `${keyword} removed`);
@@ -267,11 +296,11 @@ function diffNode(before, after, path, ctx) {
     for (const key of Object.keys(bProps)) {
         if (Object.hasOwn(aProps, key))
             continue;
-        const required = bRequired.includes(key);
+        const required = bRequiredSet.has(key);
         note(ctx, joinPointer(propsPath, key), "properties", required ? "breaking" : "compatible", required ? `property "${key}" added and required` : `optional property "${key}" added`);
     }
     // --- additionalProperties
-    if (!deepEqual(a["additionalProperties"], b["additionalProperties"])) {
+    if (!ctx.same.equal(a["additionalProperties"], b["additionalProperties"])) {
         const apPath = joinPointer(path, "additionalProperties");
         if (b["additionalProperties"] === false) {
             note(ctx, apPath, "additionalProperties", "breaking", "extra properties are now rejected");
@@ -290,7 +319,7 @@ function diffNode(before, after, path, ctx) {
     // --- items
     const aItems = a["items"];
     const bItems = b["items"];
-    if (!deepEqual(aItems, bItems)) {
+    if (!ctx.same.equal(aItems, bItems)) {
         const itemsPath = joinPointer(path, "items");
         if (Array.isArray(aItems) || Array.isArray(bItems)) {
             note(ctx, itemsPath, "items", "unknown", "tuple-form items changed — positions are not analyzed");
@@ -307,7 +336,7 @@ function diffNode(before, after, path, ctx) {
     }
     // --- everything compositional
     for (const keyword of COMPOSITIONAL) {
-        if (deepEqual(a[keyword], b[keyword]))
+        if (ctx.same.equal(a[keyword], b[keyword]))
             continue;
         note(ctx, joinPointer(path, keyword), keyword, "unknown", `${keyword} changed — this diff does not reason about composed schemas`);
     }
@@ -319,17 +348,69 @@ function diffNode(before, after, path, ctx) {
     for (const keyword of [...new Set([...Object.keys(a), ...Object.keys(b)])].sort()) {
         if (MODELLED.has(keyword) || ANNOTATIONS.has(keyword))
             continue;
-        if (deepEqual(a[keyword], b[keyword]))
+        if (ctx.same.equal(a[keyword], b[keyword]))
             continue;
         note(ctx, joinPointer(path, keyword), keyword, "unknown", `${keyword} changed — this diff does not model that keyword, so whether a reader survives it is undecided here`);
     }
 }
+/**
+ * The deepest a schema may nest, counting every object and array, for it to
+ * be diffed. Each level is a level of recursion here, and the stack's own
+ * limit moves with the platform and with how warm the code is: a schema
+ * near it came back answered in one process and as a crash in another. A
+ * fixed limit answers the same everywhere. It also bounds the pointers: every
+ * change carries its full path, so a schema differing at every level made a
+ * result the square of its depth. The same limit tool-data puts on a
+ * document.
+ */
+export const MAX_SCHEMA_DEPTH = 256;
+/**
+ * Whether `value` nests deeper than `limit` objects and arrays, read with an
+ * explicit stack and abandoned as soon as it does. An object reached again
+ * (only a caller's own value can share one) is walked again only when it is
+ * reached deeper, so a cycle is too deep rather than endless.
+ */
+export function nestsDeeperThan(value, limit) {
+    const deepest = new Map();
+    const stack = [
+        { node: value, depth: 1 },
+    ];
+    for (let top = stack.pop(); top !== undefined; top = stack.pop()) {
+        const { node, depth } = top;
+        if (typeof node !== "object" || node === null)
+            continue;
+        if (depth > limit)
+            return true;
+        const before = deepest.get(node);
+        if (before !== undefined && before >= depth)
+            continue;
+        deepest.set(node, depth);
+        const children = Array.isArray(node) ? node : Object.values(node);
+        for (let i = 0; i < children.length; i++) {
+            const child = children[i];
+            if (typeof child === "object" && child !== null)
+                stack.push({ node: child, depth: depth + 1 });
+        }
+    }
+    return false;
+}
 /**
  * Diff two schemas and classify each change. See the module comment for what
  * "compatible" means here and for the cases deliberately left `unknown`.
+ * Refuses a schema nested past {@link MAX_SCHEMA_DEPTH}, before reading it.
  */
 export function diffSchemas(before, after) {
-    const ctx = { changes: [] };
+    for (const [side, schema] of [
+        ["before", before],
+        ["after", after],
+    ]) {
+        if (nestsDeeperThan(schema, MAX_SCHEMA_DEPTH)) {
+            throw new Error(`\`${side}\` nests deeper than ${MAX_SCHEMA_DEPTH} levels, the most SchemaDiff compares — diff the nested part on its own`);
+        }
+    }
+    // Every subtree of both schemas numbered once, so the comparisons below at
+    // each level of nesting, and the enum diffs, are lookups rather than walks.
+    const ctx = { changes: [], same: indexShapes([before, after]) };
     diffNode(before, after, "", ctx);
     const counts = {
         compatible: ctx.changes.filter((c) => c.compat === "compatible").length,
@@ -341,7 +422,7 @@ export function diffSchemas(before, after) {
         // Structural identity, not "nothing was found": two schemas differing
         // only in a `description` produce no changes, and saying they are
         // identical would be a different claim from the one made here.
-        identical: deepEqual(before, after),
+        identical: ctx.same.equal(before, after),
         verdict,
         backwardCompatible: verdict === "compatible",
         changes: ctx.changes,

package/dist/lib/shape-index.d.ts

@@ -0,0 +1,22 @@
+export type ShapeIndex = {
+    /** `deepEqual(a, b)`. */
+    readonly equal: (a: unknown, b: unknown) => boolean;
+    /**
+     * A string two indexed values share exactly when `deepEqual` calls them
+     * equal, or undefined for a value the index does not cover.
+     */
+    readonly key: (value: unknown) => string | undefined;
+    /**
+     * The work of numbering: members visited plus signature characters
+     * written. A test reads it, since a map lookup is invisible to a meter
+     * that wraps the array and string methods.
+     */
+    readonly steps: number;
+};
+/** No index: `deepEqual` for every comparison, and no keys. */
+export declare const UNINDEXED: ShapeIndex;
+/**
+ * Number every array and object inside `roots`, or return UNINDEXED when
+ * one of them holds a value the numbers cannot describe.
+ */
+export declare function indexShapes(roots: ReadonlyArray<unknown>): ShapeIndex;

package/dist/lib/shape-index.js

@@ -0,0 +1,157 @@
+/**
+ * `deepEqual` answered by lookup, for the values inside two documents.
+ *
+ * SchemaDiff compared subtrees with `deepEqual` at every level it descended
+ * into — the whole remaining tree once per level, so a schema nested n deep
+ * cost n² — and diffed two enums by testing every value of one against every
+ * value of the other. Here every array and plain object inside the indexed
+ * values gets a number, shared by exactly the subtrees `deepEqual` calls
+ * equal, worked out once from the leaves up. Two subtrees are then equal
+ * when their numbers are, and a value can be looked up in a set.
+ *
+ * The numbers are defined only where `deepEqual` compares JSON shape: null,
+ * booleans, strings, numbers other than NaN, bigints, undefined, dense
+ * arrays, and objects whose prototype is `Object.prototype` or null and
+ * whose own properties are all data properties. Anything else — NaN, which
+ * equals nothing, a function, a Date, a sparse array, a cycle — leaves the
+ * values unindexed, and every comparison goes back to `deepEqual` itself.
+ * So each answer is the one `deepEqual` gives. A value parsed from JSON is
+ * always indexed.
+ */
+import { deepEqual } from "./value";
+/** No index: `deepEqual` for every comparison, and no keys. */
+export const UNINDEXED = { equal: deepEqual, key: () => undefined, steps: 0 };
+/** Thrown while indexing a value `deepEqual` does not compare by shape. */
+const NOT_A_SHAPE = Symbol("not a JSON shape");
+/** The key of a value that is not an object, or NOT_A_SHAPE. */
+function leafKey(value) {
+    if (value === null)
+        return "null";
+    switch (typeof value) {
+        case "undefined":
+            return "u";
+        case "boolean":
+            return value ? "t" : "f";
+        case "number":
+            // `deepEqual` is `===` here: NaN equals nothing, and 0 equals -0.
+            if (Number.isNaN(value))
+                return NOT_A_SHAPE;
+            return `n${value === 0 ? 0 : value}`;
+        case "string":
+            return `s${JSON.stringify(value)}`;
+        case "bigint":
+            return `b${value}`;
+        default:
+            return NOT_A_SHAPE;
+    }
+}
+/**
+ * Number every array and object inside `roots`, or return UNINDEXED when
+ * one of them holds a value the numbers cannot describe.
+ */
+export function indexShapes(roots) {
+    const ids = new Map();
+    const bySignature = new Map();
+    const work = { steps: 0 };
+    const keyOf = (value) => {
+        if (typeof value !== "object" || value === null)
+            return leafKey(value);
+        const id = ids.get(value);
+        return id === undefined ? NOT_A_SHAPE : `o${id}`;
+    };
+    try {
+        for (const root of roots)
+            number(root, ids, bySignature, keyOf, work);
+    }
+    catch (err) {
+        if (err === NOT_A_SHAPE)
+            return UNINDEXED;
+        throw err;
+    }
+    return {
+        equal: (a, b) => {
+            if (typeof a === "object" && a !== null && typeof b === "object" && b !== null) {
+                const left = ids.get(a);
+                const right = ids.get(b);
+                if (left !== undefined && right !== undefined)
+                    return left === right;
+            }
+            return deepEqual(a, b);
+        },
+        key: (value) => {
+            const key = keyOf(value);
+            return key === NOT_A_SHAPE ? undefined : key;
+        },
+        steps: work.steps,
+    };
+}
+/**
+ * Give `root` and everything inside it a number, children before parents,
+ * with an explicit stack: a schema nested tens of thousands deep must not
+ * overflow the call stack here when the comparisons it replaces did not.
+ */
+function number(root, ids, bySignature, keyOf, work) {
+    const frames = [];
+    const open = new Set();
+    const enter = (value) => {
+        if (typeof value !== "object" || value === null) {
+            if (leafKey(value) === NOT_A_SHAPE)
+                throw NOT_A_SHAPE;
+            return;
+        }
+        if (ids.has(value))
+            return;
+        // A cycle: `deepEqual` would recurse until the stack ran out.
+        if (open.has(value))
+            throw NOT_A_SHAPE;
+        if (Array.isArray(value)) {
+            // `deepEqual` skips a hole with `every`, which no number can say.
+            for (let i = 0; i < value.length; i++)
+                if (!(i in value))
+                    throw NOT_A_SHAPE;
+            frames.push({ node: value, keys: null, members: value, next: 0 });
+        }
+        else {
+            const proto = Object.getPrototypeOf(value);
+            if (proto !== Object.prototype && proto !== null)
+                throw NOT_A_SHAPE;
+            const keys = Object.keys(value).sort();
+            const members = [];
+            for (const key of keys) {
+                const property = Object.getOwnPropertyDescriptor(value, key);
+                if (property === undefined || !("value" in property))
+                    throw NOT_A_SHAPE;
+                members.push(property.value);
+            }
+            frames.push({ node: value, keys, members, next: 0 });
+        }
+        open.add(value);
+    };
+    enter(root);
+    while (frames.length > 0) {
+        const frame = frames[frames.length - 1];
+        if (frame.next < frame.members.length) {
+            enter(frame.members[frame.next]);
+            frame.next += 1;
+            continue;
+        }
+        frames.pop();
+        open.delete(frame.node);
+        const parts = [];
+        for (let i = 0; i < frame.members.length; i++) {
+            const key = keyOf(frame.members[i]);
+            if (key === NOT_A_SHAPE)
+                throw NOT_A_SHAPE;
+            const name = frame.keys === null ? undefined : frame.keys[i];
+            parts.push(name === undefined ? key : `${JSON.stringify(name)}:${key}`);
+        }
+        const signature = frame.keys === null ? `[${parts.join(",")}]` : `{${parts.join(",")}}`;
+        work.steps += frame.members.length + signature.length;
+        let id = bySignature.get(signature);
+        if (id === undefined) {
+            id = bySignature.size;
+            bySignature.set(signature, id);
+        }
+        ids.set(frame.node, id);
+    }
+}

package/dist/lib/summarize.js

@@ -108,7 +108,10 @@ function walk(schema, path, required, depth, seenRefs, ctx) {
     }
     const ref = typeof schema["$ref"] === "string" ? schema["$ref"] : null;
     if (ref !== null) {
-        if (seenRefs.includes(ref)) {
+        // The refs being followed on the way down to here, as a set kept in
+        // step with the walk: copying and searching a list at every hop cost a
+        // chain of n refs n² (a ref adds no depth, so nothing else stops it).
+        if (seenRefs.has(ref)) {
             push(ctx, { path, type: `${ref} (recursive)`, required, constraints: "", description: "" });
             return;
         }
@@ -117,7 +120,13 @@ function walk(schema, path, required, depth, seenRefs, ctx) {
             push(ctx, { path, type: ref, required, constraints: "unresolved $ref", description: "" });
             return;
         }
-        walk(target, path, required, depth, [...seenRefs, ref], ctx);
+        seenRefs.add(ref);
+        try {
+            walk(target, path, required, depth, seenRefs, ctx);
+        }
+        finally {
+            seenRefs.delete(ref);
+        }
         return;
     }
     const description = typeof schema["description"] === "string" ? schema["description"] : "";
@@ -136,19 +145,29 @@ function walk(schema, path, required, depth, seenRefs, ctx) {
         return;
     const properties = schema["properties"];
     if (isPlainObject(properties)) {
-        const requiredNames = Array.isArray(schema["required"])
+        // A set: searching the list once per property cost the properties times
+        // the required names, and went on past the last row the table holds.
+        const requiredNames = new Set(Array.isArray(schema["required"])
             ? schema["required"].filter((k) => typeof k === "string")
-            : [];
+            : []);
         for (const key of Object.keys(properties)) {
+            // Once the table is full nothing below adds a row.
+            if (ctx.truncated)
+                return;
             const childPath = path === "" ? key : `${path}.${key}`;
-            walk(properties[key], childPath, requiredNames.includes(key), depth + 1, seenRefs, ctx);
+            walk(properties[key], childPath, requiredNames.has(key), depth + 1, seenRefs, ctx);
         }
     }
     const items = schema["items"];
     if (Array.isArray(items)) {
-        items.forEach((item, index) => {
-            walk(item, `${path}[${index}]`, required, depth + 1, seenRefs, ctx);
-        });
+        for (let index = 0; index < items.length; index++) {
+            if (ctx.truncated)
+                return;
+            // A hole is skipped, as `forEach` skipped it.
+            if (!(index in items))
+                continue;
+            walk(items[index], `${path}[${index}]`, required, depth + 1, seenRefs, ctx);
+        }
     }
     else if (items !== undefined) {
         walk(items, `${path}[]`, required, depth + 1, seenRefs, ctx);
@@ -167,7 +186,7 @@ export function summarizeSchema(schema, options = {}) {
         maxDepth: options.maxDepth ?? DEFAULTS.maxDepth,
         truncated: false,
     };
-    walk(schema, "", false, 0, [], ctx);
+    walk(schema, "", false, 0, new Set(), ctx);
     const rootObject = isPlainObject(schema) ? schema : {};
     return {
         title: typeof rootObject["title"] === "string" ? rootObject["title"] : "",

package/dist/lib/value.d.ts

@@ -80,5 +80,19 @@ export declare function canonicalize(value: unknown): string;
  * the two differ once the value is serialized.
  */
 export declare function deepEqual(a: unknown, b: unknown): boolean;
-/** A single-line, length-capped rendering of a value, for error messages. */
-export declare function preview(value: unknown, maxChars?: number): string;
+/**
+ * A single-line, length-capped rendering of a value, for error messages.
+ *
+ * It reads only as much of the value as the rendering can show: a validator
+ * previews the failing value once per failed check, and serializing the
+ * whole of a 2 MB value to keep 60 characters of it made each check cost
+ * the value's size (a 794-character schema took 81 s). A run of whitespace
+ * folds to one space, so up to eight times `maxChars` is read before the
+ * rendering is called cut. Listing an object's keys costs all of them in
+ * this engine however few are shown, so a caller that previews the same
+ * objects many times (the validator) passes a cache that lives as long as
+ * its walk.
+ */
+export declare function preview(value: unknown, maxChars?: number, cache?: PreviewCache): string;
+/** Renderings already made, by object and length; see `preview`. */
+export type PreviewCache = WeakMap<object, Map<number, string>>;

package/dist/lib/value.js

@@ -222,20 +222,150 @@ export function deepEqual(a, b) {
     }
     return false;
 }
-/** A single-line, length-capped rendering of a value, for error messages. */
-export function preview(value, maxChars = 120) {
-    let text;
-    if (value === undefined) {
-        text = "undefined";
-    }
-    else {
-        try {
-            text = JSON.stringify(value) ?? String(value);
+/** Thrown by `jsonPrefix` for a value JSON.stringify would treat specially. */
+class NotPlainJson extends Error {
+}
+/**
+ * The first `cap` characters of `JSON.stringify(value)`, built without
+ * serializing the rest: a 2 MB string or a 100,000-key object costs what the
+ * prefix costs. `cut` is true when the text stops short of the whole.
+ * Throws NotPlainJson for anything but plain JSON data (a `toJSON` method, a
+ * class instance, a BigInt), which the caller serializes the old way.
+ */
+function jsonPrefix(value, cap) {
+    const parts = [];
+    let length = 0;
+    let cut = false;
+    const push = (piece) => {
+        if (length + piece.length > cap) {
+            parts.push(piece.slice(0, cap - length));
+            length = cap;
+            cut = true;
+            return false;
         }
-        catch {
-            text = String(value);
+        parts.push(piece);
+        length += piece.length;
+        return true;
+    };
+    // A string is escaped from a slice no longer than the room left, so its
+    // cost is the room, not its length.
+    const pushString = (text) => {
+        const room = cap - length;
+        if (text.length <= room)
+            return push(JSON.stringify(text));
+        push(JSON.stringify(text.slice(0, room)).slice(0, -1));
+        cut = true;
+        return false;
+    };
+    const emit = (item) => {
+        if (item === null)
+            return push("null");
+        switch (typeof item) {
+            case "string":
+                return pushString(item);
+            case "number":
+                return push(Number.isFinite(item) ? JSON.stringify(item) : "null");
+            case "boolean":
+                return push(item ? "true" : "false");
+            case "undefined":
+            case "function":
+            case "symbol":
+                // Reached only inside an array; an object property skips these.
+                return push("null");
+            case "object": {
+                if (typeof item.toJSON === "function")
+                    throw new NotPlainJson();
+                if (Array.isArray(item)) {
+                    if (!push("["))
+                        return false;
+                    for (let i = 0; i < item.length; i++) {
+                        if (i > 0 && !push(","))
+                            return false;
+                        if (!emit(item[i]))
+                            return false;
+                    }
+                    return push("]");
+                }
+                const proto = Object.getPrototypeOf(item);
+                if (proto !== Object.prototype && proto !== null)
+                    throw new NotPlainJson();
+                if (!push("{"))
+                    return false;
+                let first = true;
+                // `for...in` with an own check, not Object.keys: it stops when the
+                // prefix is full instead of listing every key first.
+                for (const key in item) {
+                    if (!Object.hasOwn(item, key))
+                        continue;
+                    const member = item[key];
+                    if (member === undefined || typeof member === "function" || typeof member === "symbol") {
+                        continue;
+                    }
+                    if (!first && !push(","))
+                        return false;
+                    first = false;
+                    if (!pushString(key) || !push(":"))
+                        return false;
+                    if (!emit(member))
+                        return false;
+                }
+                return push("}");
+            }
+            default:
+                throw new NotPlainJson();
         }
+    };
+    emit(value);
+    return { text: parts.join(""), cut };
+}
+/**
+ * A single-line, length-capped rendering of a value, for error messages.
+ *
+ * It reads only as much of the value as the rendering can show: a validator
+ * previews the failing value once per failed check, and serializing the
+ * whole of a 2 MB value to keep 60 characters of it made each check cost
+ * the value's size (a 794-character schema took 81 s). A run of whitespace
+ * folds to one space, so up to eight times `maxChars` is read before the
+ * rendering is called cut. Listing an object's keys costs all of them in
+ * this engine however few are shown, so a caller that previews the same
+ * objects many times (the validator) passes a cache that lives as long as
+ * its walk.
+ */
+export function preview(value, maxChars = 120, cache) {
+    const limit = Math.max(0, maxChars);
+    if (cache === undefined || value === null || typeof value !== "object") {
+        return renderPreview(value, limit);
+    }
+    let byLimit = cache.get(value);
+    if (byLimit === undefined) {
+        byLimit = new Map();
+        cache.set(value, byLimit);
+    }
+    let text = byLimit.get(limit);
+    if (text === undefined) {
+        text = renderPreview(value, limit);
+        byLimit.set(limit, text);
+    }
+    return text;
+}
+function renderPreview(value, limit) {
+    const clipped = (text, cut) => !cut && text.length <= limit ? text : `${text.slice(0, Math.max(0, limit - 3))}...`;
+    if (value === undefined)
+        return clipped("undefined", false);
+    try {
+        const { text, cut } = jsonPrefix(value, limit * 8 + 64);
+        return clipped(text.replace(/\s+/g, " "), cut);
+    }
+    catch (err) {
+        if (!(err instanceof NotPlainJson) && !(err instanceof RangeError))
+            throw err;
+    }
+    let text;
+    try {
+        text = JSON.stringify(value) ?? String(value);
+    }
+    catch {
+        text = String(value);
     }
-    text = text.replace(/\s+/g, " ");
-    return text.length <= maxChars ? text : `${text.slice(0, Math.max(0, maxChars - 3))}...`;
+    return clipped(text.replace(/\s+/g, " "), false);
 }