@crewhaus/tool-schema 0.7.0

package/dist/lib/compare.js

@@ -0,0 +1,298 @@
+/**
+ * Comparing a value against an expected value — the primitive under
+ * `DeepEqual`, `CompareGolden` and `MatchSubset`.
+ *
+ * A snapshot comparison is only useful if it can be told to overlook the
+ * parts that legitimately move: a generated id, a timestamp, the order of a
+ * result set, the last bit of a float. Those three knobs (`ignorePaths`,
+ * `ignoreArrayOrder`, `epsilon`) are what separate a golden test that holds
+ * for a year from one that is deleted in a week.
+ *
+ * Every difference is reported with a JSON Pointer, and the walk is
+ * deterministic: object keys in sorted order, array items in index order.
+ */
+import { canonicalize, isPlainObject, joinPointer, preview, typeOf } from "./value";
+export const DEFAULT_COMPARE_OPTIONS = {
+    ignorePaths: [],
+    ignoreArrayOrder: false,
+    epsilon: 0,
+    subset: false,
+    maxDifferences: 50,
+};
+/**
+ * Unordered array matching is O(n*m) comparisons. Past this length the cost
+ * stops being worth it and the comparison falls back to positional, saying
+ * so in the result rather than silently changing meaning.
+ */
+export const UNORDERED_ARRAY_LIMIT = 200;
+function compilePattern(pointer) {
+    const body = pointer.startsWith("/") ? pointer.slice(1) : pointer;
+    return body === "" ? [] : body.split("/");
+}
+function pathSegments(pointer) {
+    return pointer === "" ? [] : pointer.slice(1).split("/");
+}
+/** True when `pointer` is matched by one of the compiled ignore patterns. */
+export function matchesAnyPattern(pointer, patterns) {
+    const segments = pathSegments(pointer);
+    return patterns.some((pattern) => matchPattern(segments, pattern));
+}
+function matchPattern(segments, pattern) {
+    let s = 0;
+    for (let p = 0; p < pattern.length; p++) {
+        const token = pattern[p];
+        if (token === "**")
+            return true;
+        if (s >= segments.length)
+            return false;
+        if (token !== "*" && token !== segments[s])
+            return false;
+        s += 1;
+    }
+    return s === segments.length;
+}
+function record(ctx, diff) {
+    if (ctx.differences.length >= ctx.opts.maxDifferences) {
+        ctx.truncated = true;
+        return;
+    }
+    ctx.differences.push(diff);
+}
+function numbersEqual(a, b, epsilon) {
+    if (a === b)
+        return true;
+    if (!Number.isFinite(a) || !Number.isFinite(b))
+        return false;
+    return epsilon > 0 && Math.abs(a - b) <= epsilon;
+}
+/** Compare without recording anything — used to pair up unordered items. */
+function equalUnder(actual, expected, ctx, path) {
+    const probe = {
+        opts: { ...ctx.opts, maxDifferences: 1 },
+        patterns: ctx.patterns,
+        differences: [],
+        truncated: false,
+        ignored: [],
+        orderedFallbacks: [],
+    };
+    walk(actual, expected, path, probe);
+    return probe.differences.length === 0;
+}
+function walk(actual, expected, path, ctx) {
+    if (matchesAnyPattern(path, ctx.patterns)) {
+        if (!ctx.ignored.includes(path))
+            ctx.ignored.push(path);
+        return;
+    }
+    const expectedType = typeOf(expected);
+    const actualType = typeOf(actual);
+    if (typeof expected === "number" && typeof actual === "number") {
+        if (!numbersEqual(actual, expected, ctx.opts.epsilon)) {
+            record(ctx, {
+                path,
+                kind: "value",
+                message: ctx.opts.epsilon > 0
+                    ? `${actual} differs from ${expected} by more than ${ctx.opts.epsilon}`
+                    : `expected ${expected}, found ${actual}`,
+                expected,
+                actual,
+            });
+        }
+        return;
+    }
+    // `integer` and `number` are the same JSON type for comparison purposes.
+    const normalize = (t) => (t === "integer" ? "number" : t);
+    if (normalize(expectedType) !== normalize(actualType)) {
+        record(ctx, {
+            path,
+            kind: "type",
+            message: `expected ${normalize(expectedType)}, found ${normalize(actualType)} (${preview(actual, 60)})`,
+            expected,
+            actual,
+        });
+        return;
+    }
+    if (Array.isArray(expected) && Array.isArray(actual)) {
+        compareArrays(actual, expected, path, ctx);
+        return;
+    }
+    if (isPlainObject(expected) && isPlainObject(actual)) {
+        compareObjects(actual, expected, path, ctx);
+        return;
+    }
+    if (expected !== actual) {
+        record(ctx, {
+            path,
+            kind: "value",
+            message: `expected ${preview(expected, 60)}, found ${preview(actual, 60)}`,
+            expected,
+            actual,
+        });
+    }
+}
+function compareArrays(actual, expected, path, ctx) {
+    const tooLong = actual.length > UNORDERED_ARRAY_LIMIT || expected.length > UNORDERED_ARRAY_LIMIT;
+    if (ctx.opts.ignoreArrayOrder && tooLong && !ctx.orderedFallbacks.includes(path)) {
+        ctx.orderedFallbacks.push(path);
+    }
+    if (ctx.opts.ignoreArrayOrder && !tooLong) {
+        compareArraysUnordered(actual, expected, path, ctx);
+        return;
+    }
+    if (actual.length !== expected.length) {
+        record(ctx, {
+            path,
+            kind: "length",
+            message: `expected ${expected.length} items, found ${actual.length}`,
+            expected: expected.length,
+            actual: actual.length,
+        });
+    }
+    const shared = Math.min(actual.length, expected.length);
+    for (let i = 0; i < shared; i++) {
+        walk(actual[i], expected[i], joinPointer(path, i), ctx);
+    }
+}
+/**
+ * Pair the two arrays up greedily: each expected item takes the first
+ * unclaimed actual item it equals.
+ *
+ * With `epsilon` at 0, equality is an equivalence relation, so greedy pairing
+ * finds a complete matching whenever one exists. With a non-zero `epsilon` it
+ * is not — `1.0` and `1.2` are each within 0.15 of `1.1` but not of each
+ * other — and greedy can claim an item a later one needed, reporting a
+ * difference where a perfect pairing existed. That is the deliberate trade
+ * for keeping this O(n*m) rather than running a full bipartite matching; the
+ * report errs towards naming a difference, never towards hiding one.
+ */
+function compareArraysUnordered(actual, expected, path, ctx) {
+    const taken = new Set();
+    const unmatchedExpected = [];
+    for (let e = 0; e < expected.length; e++) {
+        let matched = false;
+        for (let a = 0; a < actual.length; a++) {
+            if (taken.has(a))
+                continue;
+            if (!equalUnder(actual[a], expected[e], ctx, path))
+                continue;
+            taken.add(a);
+            matched = true;
+            break;
+        }
+        if (!matched)
+            unmatchedExpected.push(e);
+    }
+    for (const e of unmatchedExpected) {
+        record(ctx, {
+            path: joinPointer(path, e),
+            kind: "missing",
+            message: `no item in the actual array matches expected[${e}] (${preview(expected[e], 60)})`,
+            expected: expected[e],
+            actual: undefined,
+        });
+    }
+    for (let a = 0; a < actual.length; a++) {
+        if (taken.has(a))
+            continue;
+        record(ctx, {
+            path: joinPointer(path, a),
+            kind: "unexpected",
+            message: `actual[${a}] (${preview(actual[a], 60)}) has no counterpart in expected`,
+            expected: undefined,
+            actual: actual[a],
+        });
+    }
+}
+function compareObjects(actual, expected, path, ctx) {
+    for (const key of Object.keys(expected).sort()) {
+        const childPath = joinPointer(path, key);
+        if (!Object.hasOwn(actual, key)) {
+            if (matchesAnyPattern(childPath, ctx.patterns)) {
+                if (!ctx.ignored.includes(childPath))
+                    ctx.ignored.push(childPath);
+                continue;
+            }
+            record(ctx, {
+                path: childPath,
+                kind: "missing",
+                message: `expected property "${key}" is absent`,
+                expected: expected[key],
+                actual: undefined,
+            });
+            continue;
+        }
+        walk(actual[key], expected[key], childPath, ctx);
+    }
+    if (ctx.opts.subset)
+        return;
+    for (const key of Object.keys(actual).sort()) {
+        if (Object.hasOwn(expected, key))
+            continue;
+        const childPath = joinPointer(path, key);
+        if (matchesAnyPattern(childPath, ctx.patterns)) {
+            if (!ctx.ignored.includes(childPath))
+                ctx.ignored.push(childPath);
+            continue;
+        }
+        record(ctx, {
+            path: childPath,
+            kind: "unexpected",
+            message: `unexpected property "${key}" (${preview(actual[key], 60)})`,
+            expected: undefined,
+            actual: actual[key],
+        });
+    }
+}
+/**
+ * Compare `actual` against `expected` under the given options and return
+ * every difference found, each addressed by JSON Pointer.
+ *
+ * With `ignoreArrayOrder`, item paths refer to positions in the array they
+ * came from — an unmatched expected item is reported at its index in
+ * *expected*, an unmatched actual item at its index in *actual* — because
+ * with order ignored there is no single index that means both.
+ */
+export function compareValues(actual, expected, options = {}) {
+    const opts = { ...DEFAULT_COMPARE_OPTIONS, ...options };
+    const ctx = {
+        opts,
+        patterns: opts.ignorePaths.map(compilePattern),
+        differences: [],
+        truncated: false,
+        ignored: [],
+        orderedFallbacks: [],
+    };
+    walk(actual, expected, "", ctx);
+    return {
+        equal: ctx.differences.length === 0,
+        differences: ctx.differences,
+        truncated: ctx.truncated,
+        ignored: ctx.ignored,
+        orderedFallbacks: ctx.orderedFallbacks,
+    };
+}
+/**
+ * The first place two values differ, walking objects in sorted key order and
+ * arrays by index, or `null` when they are structurally equal. This is the
+ * one line a failing equality check should print.
+ */
+export function firstDifference(actual, expected) {
+    const result = compareValues(actual, expected, { maxDifferences: 1 });
+    return result.differences[0] ?? null;
+}
+/**
+ * Group values that canonicalize identically. Used for duplicate detection,
+ * where "identical" must ignore key order.
+ */
+export function groupByCanonical(items, key) {
+    const groups = new Map();
+    items.forEach((item, index) => {
+        const id = canonicalize(key(item));
+        const bucket = groups.get(id);
+        if (bucket === undefined)
+            groups.set(id, [index]);
+        else
+            bucket.push(index);
+    });
+    return groups;
+}

package/dist/lib/formats.d.ts

@@ -0,0 +1,115 @@
+/**
+ * String format checks, written out rather than borrowed.
+ *
+ * Every one of these is a *stated subset*, not a full grammar. The rule this
+ * file follows: reject what is definitely wrong, accept what is definitely
+ * right, and say in the doc comment which grey areas fall which way — so a
+ * harness gating on `ValidateFormat` knows exactly what it bought. A format
+ * check that quietly disagrees with the reader downstream is worse than no
+ * check at all.
+ */
+/** Every format name {@link checkFormat} understands. */
+export declare const FORMAT_NAMES: readonly ["email", "uri", "uri-reference", "hostname", "ipv4", "ipv6", "uuid", "date", "time", "date-time", "json-pointer", "regex"];
+export type FormatName = (typeof FORMAT_NAMES)[number];
+/** Result of one format check: valid, or invalid with the reason why. */
+export type FormatResult = {
+    valid: boolean;
+    reason: string | null;
+};
+/** True when `name` is one this module implements. */
+export declare function isFormatName(name: string): name is FormatName;
+/**
+ * A DNS hostname: dot-separated labels, each 1-63 characters of letters,
+ * digits and hyphens, not starting or ending with a hyphen; 253 characters
+ * total at most.
+ *
+ * Deliberate choices: a trailing dot (the DNS root) is rejected, underscores
+ * are rejected (legal in some DNS records, not in a hostname), and no
+ * internationalized form is decoded — a Unicode domain must arrive already
+ * punycoded.
+ */
+export declare function isHostname(value: string): FormatResult;
+/**
+ * Dotted-quad IPv4. Four decimal octets 0-255, no leading zeros — `01.2.3.4`
+ * is rejected, because a leading zero means octal to some parsers and
+ * decimal to others, and that ambiguity has been a source of SSRF bugs.
+ */
+export declare function isIpv4(value: string): FormatResult;
+/**
+ * IPv6, including `::` compression and a dotted-quad IPv4 tail
+ * (`::ffff:192.0.2.1`). A zone identifier (`fe80::1%eth0`) is rejected: it
+ * addresses an interface, not a host, and is not part of the `ipv6` format.
+ */
+export declare function isIpv6(value: string): FormatResult;
+/**
+ * A UUID in the 8-4-4-4-12 hex form, any case.
+ *
+ * Any version and variant is accepted, including the nil UUID — this checks
+ * the shape, not that the value came from a v4 generator. Braces and a
+ * `urn:uuid:` prefix are rejected.
+ */
+export declare function isUuid(value: string): FormatResult;
+/** Days in a month, honouring the Gregorian leap-year rule. */
+export declare function daysInMonth(year: number, month: number): number;
+/**
+ * RFC 3339 `full-date`: `YYYY-MM-DD`, calendar-checked, so `2023-02-30` and
+ * `2023-13-01` are rejected and `2024-02-29` is accepted. No other layout is
+ * accepted; `2023-1-1` fails.
+ */
+export declare function isDate(value: string): FormatResult;
+/**
+ * RFC 3339 `full-time`: `HH:MM:SS`, an optional fractional part, and a
+ * mandatory offset of `Z`, `z`, or `+HH:MM` / `-HH:MM`.
+ *
+ * A seconds value of 60 is accepted, because RFC 3339 allows it for leap
+ * seconds. An offset with minutes over 59 is rejected.
+ */
+export declare function isTime(value: string): FormatResult;
+/**
+ * RFC 3339 `date-time`: a date, a `T` (or lowercase `t`) separator, and a
+ * time with an offset. A space separator, as SQL writes it, is rejected —
+ * this is the strict interchange form.
+ */
+export declare function isDateTime(value: string): FormatResult;
+/**
+ * An email address, in the form services actually accept: a dot-separated
+ * local part of unquoted ASCII characters and a hostname domain.
+ *
+ * Deliberately narrower than RFC 5322: quoted local parts, comments,
+ * IP-literal domains (`a@[192.0.2.1]`) and non-ASCII are all rejected. A
+ * domain with no dot (`a@localhost`) is rejected too, since a bare host is
+ * never a deliverable address in practice.
+ */
+export declare function isEmail(value: string): FormatResult;
+/**
+ * An absolute URI: a scheme (`[A-Za-z][A-Za-z0-9+.-]*`), a colon, and a
+ * non-empty remainder with no whitespace or control characters.
+ *
+ * This is the absolute-URI shape check, not the full RFC 3986 grammar: the
+ * authority, path, query and fragment are not parsed. `/path` and
+ * `page.html` are rejected — use `uri-reference` for those.
+ */
+export declare function isUri(value: string): FormatResult;
+/**
+ * A URI reference: either an absolute URI or a relative one. Only whitespace,
+ * control characters and a second `#` are rejected; anything else a browser
+ * would resolve is accepted.
+ */
+export declare function isUriReference(value: string): FormatResult;
+/** RFC 6901 JSON Pointer: empty, or `/`-led tokens where `~` is followed by 0 or 1. */
+export declare function isJsonPointer(value: string): FormatResult;
+/** A string that compiles as a JavaScript regular expression. */
+export declare function isRegex(value: string): FormatResult;
+/**
+ * Check one string against one format name. An unknown format name is a
+ * caller error and throws; every implemented format returns a result.
+ */
+export declare function checkFormat(value: string, format: FormatName): FormatResult;
+/**
+ * The formats a value matches, narrowest first — see
+ * {@link FORMAT_SPECIFICITY}. Used by `ValidateFormat` to tell a caller what
+ * their value *does* look like when it fails the format they asked for, and
+ * by schema inference, which narrows the list further before labelling a
+ * field.
+ */
+export declare function matchingFormats(value: string): FormatName[];