@instruments/materialgraph 0.2.0 → 0.4.0

package/validation.js

@@ -0,0 +1,241 @@
+/**
+ * The SDK's shared wire-validation primitives — the vocabulary every hand-rolled
+ * mirror of a canonical Zod schema is built from.
+ *
+ * The SDK publishes with ZERO runtime dependencies, so it cannot call
+ * `schema.parse()` on anything. Where a wire payload must be proven rather than
+ * trusted, it is checked with these helpers and the result is pinned against the
+ * real schema in `contract-parity.test.ts`. Each helper mirrors one Zod
+ * construct, named for it, so a reviewer can read the mirror against the schema
+ * line by line.
+ *
+ * Every helper takes the same three shapes: the value, a `what` path used in the
+ * diagnostic (`results[3].verdict.cells[0].state`), and a {@link ValidationFailure}
+ * owned by the calling module — so one payload's failures all read alike without
+ * this file knowing what a Match frame or a Run event is.
+ */
+import { MaterialGraphError } from "./errors.js";
+export function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** A `z.object({…})`. */
+export function requireRecord(value, what, fail) {
+    if (!isRecord(value))
+        throw fail(`${what} is not a JSON object`);
+    return value;
+}
+/** A `z.string()`. */
+export function requireString(value, what, fail) {
+    if (typeof value !== "string")
+        throw fail(`${what} is not a string`);
+    return value;
+}
+/** A `z.string().min(1)`. */
+export function requireNonEmptyString(value, what, fail) {
+    const text = requireString(value, what, fail);
+    if (text.length === 0)
+        throw fail(`${what} is an empty string`);
+    return text;
+}
+/** A `z.string().optional()`: absent is fine, present-but-wrong is not. */
+export function requireOptionalString(value, what, fail) {
+    if (value === undefined)
+        return;
+    requireString(value, what, fail);
+}
+/** A `z.string().nullable()`. */
+export function requireNullableString(value, what, fail) {
+    if (value === null)
+        return null;
+    return requireString(value, what, fail);
+}
+/** A `z.string().min(1).nullable()`. */
+export function requireNullableNonEmptyString(value, what, fail) {
+    if (value === null)
+        return null;
+    return requireNonEmptyString(value, what, fail);
+}
+/** A `z.boolean()`. */
+export function requireBoolean(value, what, fail) {
+    if (typeof value !== "boolean")
+        throw fail(`${what} is not a boolean`);
+    return value;
+}
+/** A `z.boolean().optional()`. */
+export function requireOptionalBoolean(value, what, fail) {
+    if (value === undefined)
+        return;
+    requireBoolean(value, what, fail);
+}
+/**
+ * A `z.number()`. Zod 4 rejects `NaN` AND `±Infinity` for it, and `1e999` parses
+ * out of JSON as `Infinity`, so finiteness is a reachable check.
+ */
+export function requireNumber(value, what, fail) {
+    if (typeof value !== "number" || !Number.isFinite(value)) {
+        throw fail(`${what} is not a finite number`);
+    }
+    return value;
+}
+/** A `z.number().optional()`. */
+export function requireOptionalNumber(value, what, fail) {
+    if (value === undefined)
+        return;
+    requireNumber(value, what, fail);
+}
+/** A `z.number().nullable()`. */
+export function requireNullableNumber(value, what, fail) {
+    if (value === null)
+        return null;
+    return requireNumber(value, what, fail);
+}
+/**
+ * A `z.number().min(min).max(max)`. `NaN` and both infinities fail the
+ * comparisons, exactly as the bounded Zod schema rejects them.
+ */
+export function requireBoundedNumber(value, what, fail, min, max) {
+    if (typeof value !== "number" || !(value >= min && value <= max)) {
+        throw fail(`${what} is not a number within [${min}, ${max}]`);
+    }
+    return value;
+}
+/** A `z.number().min(min).max(max).nullable()`. */
+export function requireNullableBoundedNumber(value, what, fail, min, max) {
+    if (value === null)
+        return null;
+    return requireBoundedNumber(value, what, fail, min, max);
+}
+/**
+ * A bare `z.number().int()` — integer, finite, and within the SAFE range, with
+ * NO lower bound.
+ *
+ * Measured against the pinned Zod (4.4.3), `.int()` is exactly
+ * `Number.isSafeInteger`: it accepts `0`, `-1`, and `±MAX_SAFE_INTEGER`, and
+ * rejects `1.5`, `±2**53`, `NaN`, and `±Infinity`.
+ *
+ * Two ways to get this wrong, both of which break parity in a different
+ * direction. Adding a `min: 0` REJECTS a negative the schema accepts — a client
+ * refusing a legitimate response. Using `Number.isInteger` ACCEPTS `2**53`,
+ * which the schema rejects — so `requireIntegerAtLeast` is not this helper with
+ * the bound dropped, and the safe-range test is why.
+ */
+export function requireSafeInteger(value, what, fail) {
+    if (!Number.isSafeInteger(value))
+        throw fail(`${what} is not a safe integer`);
+    return requireNumber(value, what, fail);
+}
+/** A `z.number().int().min(min)` — the integer constraint AND the lower bound. */
+export function requireIntegerAtLeast(value, what, fail, min) {
+    const numeric = requireNumber(value, what, fail);
+    if (!Number.isInteger(numeric))
+        throw fail(`${what} is not an integer`);
+    if (numeric < min)
+        throw fail(`${what} is below the minimum of ${min}`);
+    return numeric;
+}
+/** A `z.enum([…])` — CLOSED, exactly like the canonical member list. */
+export function requireEnum(value, allowed, what, fail) {
+    const text = requireString(value, what, fail);
+    if (!allowed.includes(text)) {
+        throw fail(`${what} is not one of ${allowed.join(" | ")} (${text})`);
+    }
+    return text;
+}
+/** A `z.enum([…]).nullable()`. */
+export function requireNullableEnum(value, allowed, what, fail) {
+    if (value === null)
+        return null;
+    return requireEnum(value, allowed, what, fail);
+}
+/** A `z.array(…)`. */
+export function requireArray(value, what, fail) {
+    if (!Array.isArray(value))
+        throw fail(`${what} is not an array`);
+    return value;
+}
+/**
+ * A `z.array(…).default([])`: an OMITTED array is valid and materialises as
+ * `[]`; a present non-array is not.
+ */
+export function requireDefaultedArray(value, what, fail) {
+    if (value === undefined)
+        return [];
+    return requireArray(value, what, fail);
+}
+/** A `z.array(z.string()).min(1)` — non-empty, and every element a string. */
+export function requireNonEmptyStringArray(value, what, fail) {
+    const items = requireArray(value, what, fail);
+    if (items.length === 0)
+        throw fail(`${what} is empty`);
+    return items.map((item, index) => requireString(item, `${what}[${index}]`, fail));
+}
+/**
+ * A `z.json()` — a JSON value, recursively: `string | number | boolean | null`,
+ * an array of them, or an object of them, at ANY depth.
+ *
+ * WHY THIS EXISTS, given it can never fire over the wire. Every SDK response
+ * has already been through `JSON.parse`, so a `Date`, `bigint`, `undefined`, or
+ * function CANNOT be present by construction — this check is unreachable in
+ * practice. It is here for PARITY: the canonical `sourceImageAnalysisResultSchema`
+ * uses `z.json()` precisely because those four break differently on the way to
+ * `jsonb` (a `bigint` throws in `JSON.stringify`, an `undefined` is silently
+ * dropped, and a `Date` round-trips as an ISO *string* — a different type read
+ * back than written). The mirror has to reject what the schema rejects or the
+ * parity test is lying. Do not delete this as dead code.
+ */
+export function requireJsonValue(value, what, fail) {
+    if (value === null)
+        return null;
+    if (typeof value === "string" || typeof value === "boolean")
+        return value;
+    if (typeof value === "number") {
+        // `z.json()`'s number leaf rejects NaN and ±Infinity, and `1e999` parses out
+        // of JSON as `Infinity` — so finiteness IS reachable, unlike the rest.
+        if (!Number.isFinite(value))
+            throw fail(`${what} is not a finite number`);
+        return value;
+    }
+    if (Array.isArray(value)) {
+        return value.map((item, index) => requireJsonValue(item, `${what}[${index}]`, fail));
+    }
+    if (isRecord(value)) {
+        // A PLAIN object only. `isRecord` alone is not enough: it answers true for a
+        // `Date`, a `Map`, and any class instance, none of which have own enumerable
+        // entries — so recursing over them would silently accept them as `{}` while
+        // `z.json()` rejects them outright. A `Date` reaching `jsonb` is exactly the
+        // failure this check exists to stop.
+        const prototype = Object.getPrototypeOf(value);
+        if (prototype !== Object.prototype && prototype !== null) {
+            throw fail(`${what} is not a JSON value`);
+        }
+        return Object.fromEntries(Object.entries(value).map(([key, item]) => [
+            key,
+            requireJsonValue(item, `${what}.${key}`, fail),
+        ]));
+    }
+    throw fail(`${what} is not a JSON value`);
+}
+/**
+ * A `z.record(z.string(), z.json())` — a PLAIN JSON object of JSON values.
+ *
+ * Deliberately NOT `requireRecord` + walk the entries. That combination has a
+ * top-level hole: `Object.entries(new Date())` and `Object.entries(new Map())`
+ * are both `[]`, so there is nothing to recurse over and the value is accepted
+ * as `{}` — while `z.record(z.string(), z.json())` rejects both outright. A
+ * "non-array object" guard would close those two and still miss a class instance
+ * with real own properties, which canonical also rejects. Only a prototype test
+ * matches, and {@link requireJsonValue} already applies it at every depth — so
+ * this delegates there and then narrows to an object, rather than reimplementing
+ * the test and acquiring the same hole one level up.
+ *
+ * `requireRecord` is left alone: its other callers mirror `z.object({…})`, which
+ * genuinely does accept any record, and tightening a shared helper under them
+ * would be a change none of them asked for.
+ */
+export function requireJsonRecord(value, what, fail) {
+    const json = requireJsonValue(value, what, fail);
+    if (json === null || typeof json !== "object" || Array.isArray(json)) {
+        throw fail(`${what} is not a JSON object`);
+    }
+    return json;
+}