zarr-metadata 0.1.0

package/dist/validation.js

@@ -0,0 +1,784 @@
+/**
+ * Structural validation for Zarr metadata documents.
+ *
+ * A faithful port of `zarr_metadata.model._validation` (the Python reference
+ * implementation). Validators check JSON structure (key presence, value
+ * shapes, and fixed literals like `zarr_format`), not domain validity. Each
+ * concept gets a `validate*` function returning every problem found, an
+ * `is*` type guard, and a `parse*` function that narrows or throws
+ * `MetadataValidationError`.
+ *
+ * Two Python behaviors have no JS analog and are intentionally absent:
+ *
+ * - tuple-vs-list canonicalization (`arrays_to_tuples`): JSON arrays are
+ *   plain arrays in JS, so there is nothing to normalize;
+ * - int-vs-float literal spelling (`zarr_format: 3.0` vs `3`): `JSON.parse`
+ *   collapses both to the number `3`, so JS cannot reject the float
+ *   spelling. The shared conformance corpus avoids fixtures that hinge on
+ *   this distinction.
+ *
+ * Three behaviors are deliberate TS-side hardening divergences:
+ *
+ * - a "mapping" means a plain object (prototype `null` or
+ *   `Object.prototype`). Python accepts any `Mapping`; here `Date`, `Map`,
+ *   `Set`, and class instances are rejected as non-JSON rather than
+ *   validated as empty objects and mis-serialized later. Unobservable for
+ *   `JSON.parse` output;
+ * - an array must be dense with index-only own properties: holes (which
+ *   `every`/`forEach` would silently skip) and extra own properties like a
+ *   `toJSON` method (which `JSON.stringify` would honor, serializing
+ *   something other than what was validated) are rejected. Unobservable
+ *   for `JSON.parse` output;
+ * - containers (and the group ↔ consolidated-metadata document recursion)
+ *   nested deeper than `MAX_JSON_DEPTH` are reported as a problem instead
+ *   of overflowing the stack. This one IS observable for JSON text —
+ *   `JSON.parse` accepts documents nested past the cap, where Python
+ *   reports no problem (or raises `RecursionError` far deeper) — so the
+ *   corpus must never contain fixtures that exceed the cap.
+ */
+import { MetadataValidationError, treeOf, } from "./errors.js";
+import { ARRAY_METADATA_REQUIRED_KEYS_V2, ZARR_V2_ARRAY_DIMENSION_SEPARATOR, ZARR_V2_ARRAY_ORDER, ARRAY_METADATA_STANDARD_KEYS_V2, GROUP_METADATA_REQUIRED_KEYS_V2, GROUP_METADATA_STANDARD_KEYS_V2, } from "./v2.js";
+import { ARRAY_METADATA_REQUIRED_KEYS_V3, ARRAY_METADATA_STANDARD_KEYS_V3, GROUP_METADATA_REQUIRED_KEYS_V3, GROUP_METADATA_STANDARD_KEYS_V3, ZARR_V3_CONSOLIDATED_METADATA_KEY, } from "./v3.js";
+// Validators internally accumulate flat pathed issues (cheap to emit and to
+// prefix while recursing); the public functions assemble them into the
+// ErrorTree consumers see.
+function problem(path, message, kind) {
+    return { path, message, kind };
+}
+function prefix(head, issues) {
+    return issues.map((issue) => ({ ...issue, path: [head, ...issue.path] }));
+}
+/**
+ * Maximum container nesting depth accepted by `validateJson` (and, through
+ * it, every document validator) before validation reports a problem instead
+ * of recursing further. Mirrors `zarr.core.json_parse.MAX_JSON_DEPTH`; no
+ * real metadata document approaches it. The cap also terminates validation
+ * of circular object graphs.
+ */
+export const MAX_JSON_DEPTH = 64;
+/**
+ * Whether `value` is a plain object: prototype `null` or `Object.prototype`.
+ *
+ * The mapping notion for every validator. Stricter than `typeof "object"`
+ * on purpose: `Date`, `Map`, `Set`, and class instances have no own
+ * enumerable JSON content, so treating them as mappings would validate an
+ * empty object and then serialize something else entirely.
+ */
+function isPlainObject(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return false;
+    const proto = Object.getPrototypeOf(value);
+    return proto === null || proto === Object.prototype;
+}
+/** Whether `doc` has `key` as an OWN property (`in` would consult the prototype). */
+function has(doc, key) {
+    return Object.hasOwn(doc, key);
+}
+/**
+ * Whether `value` is a dense array whose own enumerable keys are exactly its
+ * indices.
+ *
+ * The array notion for every validator. Holes would be silently skipped by
+ * `every`/`forEach` (validating elements nobody looked at), and extra own
+ * properties — an own `toJSON` above all — would make `JSON.stringify` emit
+ * something other than what was validated. Both are impossible in
+ * `JSON.parse` output and rejected here.
+ */
+function isDenseArray(value) {
+    if (!Array.isArray(value))
+        return false;
+    const keys = Object.keys(value);
+    return keys.length === value.length && keys.every((key, index) => key === String(index));
+}
+function show(value) {
+    if (value === undefined)
+        return "undefined";
+    if (typeof value === "bigint")
+        return `${value}n`;
+    try {
+        const rendered = JSON.stringify(value);
+        return rendered === undefined ? String(value) : rendered;
+    }
+    catch {
+        // JSON.stringify can throw (e.g. a BigInt nested in a container); the
+        // renderer must never fail on the values it exists to describe.
+        return String(value);
+    }
+}
+/** Return every reason `value` is not JSON-serializable (recursively). */
+function jsonProblems(value) {
+    return validateJsonAtDepth(value, 0);
+}
+function validateJsonAtDepth(value, depth) {
+    if (typeof value === "number") {
+        if (Number.isFinite(value))
+            return [];
+        return [problem([], `non-finite number ${value} is not JSON`, "invalid_value")];
+    }
+    if (typeof value === "string" || typeof value === "boolean" || value === null) {
+        return [];
+    }
+    const problems = [];
+    if (Array.isArray(value)) {
+        if (depth >= MAX_JSON_DEPTH) {
+            return [problem([], `maximum nesting depth of ${MAX_JSON_DEPTH} exceeded`, "invalid_value")];
+        }
+        if (!isDenseArray(value)) {
+            return [
+                problem([], "array has holes or non-index own properties", "invalid_type"),
+            ];
+        }
+        value.forEach((item, index) => {
+            problems.push(...prefix(index, validateJsonAtDepth(item, depth + 1)));
+        });
+        return problems;
+    }
+    if (isPlainObject(value)) {
+        if (depth >= MAX_JSON_DEPTH) {
+            return [problem([], `maximum nesting depth of ${MAX_JSON_DEPTH} exceeded`, "invalid_value")];
+        }
+        for (const [key, item] of Object.entries(value)) {
+            problems.push(...prefix(key, validateJsonAtDepth(item, depth + 1)));
+        }
+        return problems;
+    }
+    return [problem([], `not a JSON-serializable value: ${show(value)}`, "invalid_type")];
+}
+/** One `missing_key` problem per required key absent from `doc`. */
+function missingKeys(required, doc) {
+    return [...required]
+        .filter((key) => !(has(doc, key)))
+        .sort()
+        .map((key) => problem([key], "missing required key", "missing_key"));
+}
+/** One problem per member outside a closed document's declared shape. */
+function unexpectedKeys(allowed, doc) {
+    return Object.keys(doc)
+        .filter((key) => !allowed.includes(key))
+        .map((key) => problem([key], "unexpected document member", "invalid_value"));
+}
+/** One `invalid_value` problem if `doc[key]` is present but not `expected`. */
+function checkLiteral(doc, key, expected) {
+    if (has(doc, key) && (typeof doc[key] !== typeof expected || doc[key] !== expected)) {
+        return [
+            problem([key], `expected ${show(expected)}, got ${show(doc[key])}`, "invalid_value"),
+        ];
+    }
+    return [];
+}
+/** Validate v3 top-level unknown-field JSON payloads. */
+function validateExtensionFieldsV3(doc, standardKeys, additionalReservedKeys = []) {
+    const reserved = new Set([...standardKeys, ...additionalReservedKeys]);
+    const problems = [];
+    for (const [key, value] of Object.entries(doc)) {
+        if (reserved.has(key))
+            continue;
+        problems.push(...prefix(key, jsonProblems(value)));
+    }
+    return problems;
+}
+/**
+ * Return every reason `value` is not a v3 metadata field.
+ *
+ * A metadata field is a bare name string or an object containing `name` and
+ * optional `configuration` and `must_understand` members.
+ */
+function metadataFieldV3Problems(value, options = {}) {
+    const { allowMustUnderstandFalse = true } = options;
+    if (typeof value === "string")
+        return [];
+    if (!isPlainObject(value)) {
+        return [
+            problem([], "expected a metadata field (string or extension object)", "invalid_type"),
+        ];
+    }
+    const problems = [];
+    const allowedKeys = new Set(["name", "configuration", "must_understand"]);
+    for (const key of Object.keys(value)) {
+        if (!allowedKeys.has(key)) {
+            problems.push(problem([key], "unexpected metadata field member", "invalid_value"));
+        }
+    }
+    if (typeof value["name"] !== "string") {
+        problems.push(problem(["name"], "expected a string name", "invalid_type"));
+    }
+    if (has(value, "configuration")) {
+        const configuration = value["configuration"];
+        if (!isPlainObject(configuration)) {
+            problems.push(problem(["configuration"], "expected a mapping", "invalid_type"));
+        }
+        else {
+            for (const [key, item] of Object.entries(configuration)) {
+                problems.push(...prefix("configuration", prefix(key, jsonProblems(item))));
+            }
+        }
+    }
+    if (has(value, "must_understand")) {
+        const mustUnderstand = value["must_understand"];
+        if (typeof mustUnderstand !== "boolean") {
+            problems.push(problem(["must_understand"], "expected a boolean", "invalid_type"));
+        }
+        else if (!allowMustUnderstandFalse && !mustUnderstand) {
+            problems.push(problem(["must_understand"], "false is not supported at this extension point", "invalid_value"));
+        }
+    }
+    return problems;
+}
+/**
+ * Whether `value` is an array of integers.
+ *
+ * `Number.isInteger` rejects booleans, non-finite numbers, and non-integral
+ * floats, mirroring the Python bool-is-not-int rule.
+ */
+function isIntSequence(value) {
+    return isDenseArray(value) && value.every((item) => Number.isInteger(item));
+}
+/**
+ * Validate a dimension sequence (`shape` / `chunks`) if present in `doc`.
+ * Dimension lengths are non-negative integers.
+ */
+function validateDimSequence(doc, key) {
+    if (!(has(doc, key)))
+        return [];
+    const value = doc[key];
+    if (!isIntSequence(value)) {
+        return [problem([key], "expected a sequence of int", "invalid_type")];
+    }
+    if (value.some((item) => item < 0)) {
+        return [problem([key], "expected non-negative integers", "invalid_value")];
+    }
+    return [];
+}
+/**
+ * Whether `value` is shaped like a v2 dtype: a string or field records.
+ *
+ * A field record is a `[name, dtype]` or `[name, dtype, shape]` array, where
+ * `dtype` is itself a string or nested field records and `shape` is an array
+ * of int. The string content is NOT interpreted — whether the string names a
+ * real dtype is domain validity, not structure.
+ */
+function isDtypeV2(value, depth = 0) {
+    if (typeof value === "string")
+        return true;
+    if (!isDenseArray(value))
+        return false;
+    // A dtype nested past the depth cap is rejected wholesale rather than
+    // recursed into; this is the same hardening rule as validateJson's.
+    if (depth >= MAX_JSON_DEPTH)
+        return false;
+    for (const record of value) {
+        if (typeof record === "string" || !isDenseArray(record))
+            return false;
+        if (record.length !== 2 && record.length !== 3)
+            return false;
+        if (typeof record[0] !== "string")
+            return false;
+        if (!isDtypeV2(record[1], depth + 1))
+            return false;
+        if (record.length === 3 && !isIntSequence(record[2]))
+            return false;
+    }
+    return true;
+}
+/** Whether `value` is shaped like a v2 codec config: an object with a string `id`. */
+function isCodecV2(value) {
+    return isPlainObject(value) && typeof value["id"] === "string";
+}
+/** Validate a v2 codec's required shape and JSON-valued configuration. */
+function validateCodecV2(value) {
+    if (!isCodecV2(value)) {
+        return [problem([], "expected a codec configuration with a string 'id'", "invalid_type")];
+    }
+    return jsonProblems(value);
+}
+/**
+ * Validate an `attributes` value: a JSON object.
+ *
+ * Unlike the other validators (which return value-relative locs for the
+ * caller to prefix), this emits the already-parent-relative `["attributes"]`
+ * loc, since it is only ever called with a document's `attributes` value.
+ */
+function validateAttributes(value) {
+    if (!isPlainObject(value)) {
+        return [problem(["attributes"], "expected a mapping with string keys", "invalid_type")];
+    }
+    const problems = [];
+    for (const [key, item] of Object.entries(value)) {
+        problems.push(...prefix("attributes", prefix(key, jsonProblems(item))));
+    }
+    return problems;
+}
+/**
+ * Return every reason `value` is not a structurally-valid v3 array doc.
+ *
+ * Checks structure, not domain validity. Unknown top-level keys are allowed
+ * (they are extension fields).
+ */
+function arrayMetadataV3Problems(value) {
+    if (!isPlainObject(value)) {
+        return [problem([], "expected a mapping", "invalid_type")];
+    }
+    const doc = value;
+    const problems = missingKeys(ARRAY_METADATA_REQUIRED_KEYS_V3, doc);
+    problems.push(...validateExtensionFieldsV3(doc, ARRAY_METADATA_STANDARD_KEYS_V3));
+    problems.push(...checkLiteral(doc, "zarr_format", 3));
+    problems.push(...checkLiteral(doc, "node_type", "array"));
+    problems.push(...validateDimSequence(doc, "shape"));
+    if (has(doc, "fill_value")) {
+        problems.push(...prefix("fill_value", jsonProblems(doc["fill_value"])));
+    }
+    for (const key of ["data_type", "chunk_grid", "chunk_key_encoding"]) {
+        if (has(doc, key)) {
+            problems.push(...prefix(key, metadataFieldV3Problems(doc[key], { allowMustUnderstandFalse: false })));
+        }
+    }
+    for (const key of ["codecs", "storage_transformers"]) {
+        if (has(doc, key)) {
+            const entries = doc[key];
+            if (!isDenseArray(entries)) {
+                problems.push(problem([key], "expected a sequence", "invalid_type"));
+            }
+            else {
+                if (key === "codecs" && entries.length === 0) {
+                    problems.push(problem(["codecs"], "expected at least one codec", "invalid_value"));
+                }
+                entries.forEach((entry, index) => {
+                    problems.push(...prefix(key, prefix(index, metadataFieldV3Problems(entry))));
+                });
+            }
+        }
+    }
+    if (has(doc, "attributes")) {
+        problems.push(...validateAttributes(doc["attributes"]));
+    }
+    if (has(doc, "dimension_names")) {
+        // Simple typed sequences (dimension_names, shape, chunks) report a single
+        // field-level loc, not per-bad-item locs; per-index locs are reserved for
+        // the metadata-field lists (codecs, storage_transformers).
+        const names = doc["dimension_names"];
+        if (!isDenseArray(names)) {
+            problems.push(problem(["dimension_names"], "expected a sequence", "invalid_type"));
+        }
+        else if (!names.every((item) => item === null || typeof item === "string")) {
+            problems.push(problem(["dimension_names"], "expected items of str or None", "invalid_type"));
+        }
+        else if (isIntSequence(doc["shape"]) && names.length !== doc["shape"].length) {
+            problems.push(problem(["dimension_names"], "expected one name per dimension of shape", "invalid_value"));
+        }
+    }
+    return problems;
+}
+/**
+ * Return every reason `value` is not a valid inline consolidated envelope.
+ *
+ * Locs are value-relative (the caller prefixes with `consolidated_metadata`
+ * where appropriate). Entries recurse into the array and group document
+ * validators.
+ */
+function consolidatedMetadataV3Problems(value) {
+    return validateConsolidatedMetadataV3AtDepth(value, 0);
+}
+function validateConsolidatedMetadataV3AtDepth(value, depth) {
+    // The group <-> consolidated document recursion consumes native stack per
+    // level, so it carries the same depth budget as the JSON-value walk.
+    if (depth >= MAX_JSON_DEPTH) {
+        return [problem([], `maximum nesting depth of ${MAX_JSON_DEPTH} exceeded`, "invalid_value")];
+    }
+    if (!isPlainObject(value)) {
+        return [problem([], "expected a mapping", "invalid_type")];
+    }
+    const env = value;
+    const problems = ["kind", "must_understand", "metadata"]
+        .filter((key) => !(has(env, key)))
+        .map((key) => problem([key], "missing required key", "missing_key"));
+    problems.push(...unexpectedKeys(["kind", "must_understand", "metadata"], env));
+    problems.push(...checkLiteral(env, "kind", "inline"));
+    if (has(env, "must_understand") && env["must_understand"] !== false) {
+        problems.push(problem(["must_understand"], "expected False", "invalid_value"));
+    }
+    if (has(env, "metadata")) {
+        const entries = env["metadata"];
+        if (!isPlainObject(entries)) {
+            problems.push(problem(["metadata"], "expected a mapping", "invalid_type"));
+        }
+        else {
+            for (const [key, entry] of Object.entries(entries)) {
+                const nodeType = isPlainObject(entry) ? entry["node_type"] : undefined;
+                if (nodeType === "array") {
+                    problems.push(...prefix("metadata", prefix(key, arrayMetadataV3Problems(entry))));
+                }
+                else if (nodeType === "group") {
+                    problems.push(...prefix("metadata", prefix(key, validateGroupMetadataV3AtDepth(entry, depth + 1))));
+                }
+                else {
+                    problems.push(problem(["metadata", key, "node_type"], "expected 'array' or 'group'", "invalid_value"));
+                }
+            }
+        }
+    }
+    return problems;
+}
+/**
+ * Return every reason `value` is not a structurally-valid v3 group doc.
+ *
+ * Checks structure, not domain validity. Unknown top-level keys are allowed
+ * (extension fields); a `consolidated_metadata` key, if present, is
+ * deep-validated (envelope and entries).
+ */
+function groupMetadataV3Problems(value) {
+    return validateGroupMetadataV3AtDepth(value, 0);
+}
+function validateGroupMetadataV3AtDepth(value, depth) {
+    if (!isPlainObject(value)) {
+        return [problem([], "expected a mapping", "invalid_type")];
+    }
+    const doc = value;
+    const problems = missingKeys(GROUP_METADATA_REQUIRED_KEYS_V3, doc);
+    problems.push(...validateExtensionFieldsV3(doc, GROUP_METADATA_STANDARD_KEYS_V3, [
+        ZARR_V3_CONSOLIDATED_METADATA_KEY,
+    ]));
+    problems.push(...checkLiteral(doc, "zarr_format", 3));
+    problems.push(...checkLiteral(doc, "node_type", "group"));
+    if (has(doc, "attributes")) {
+        problems.push(...validateAttributes(doc["attributes"]));
+    }
+    if (has(doc, ZARR_V3_CONSOLIDATED_METADATA_KEY) &&
+        doc[ZARR_V3_CONSOLIDATED_METADATA_KEY] !== null) {
+        // consolidated_metadata: null (a historical zarr-python bug) is
+        // structurally accepted so those stores remain readable.
+        problems.push(...prefix(ZARR_V3_CONSOLIDATED_METADATA_KEY, validateConsolidatedMetadataV3AtDepth(doc[ZARR_V3_CONSOLIDATED_METADATA_KEY], depth + 1)));
+    }
+    return problems;
+}
+/**
+ * Return every reason `value` is not a structurally-valid v3 metadata
+ * document of either node type (the complete `zarr.json` grammar).
+ *
+ * Dispatches on `node_type`: `"array"` and `"group"` route to the
+ * corresponding document validator; anything else is itself the problem.
+ * This dispatcher has no direct Python analog (consumers there pick a
+ * validator per node type); it exists for consumers handed an arbitrary
+ * `zarr.json`, like editor tooling.
+ */
+function metadataV3Problems(value) {
+    if (!isPlainObject(value)) {
+        return [problem([], "expected a mapping", "invalid_type")];
+    }
+    const nodeType = value["node_type"];
+    if (nodeType === "array")
+        return arrayMetadataV3Problems(value);
+    if (nodeType === "group")
+        return groupMetadataV3Problems(value);
+    if (!(has(value, "node_type"))) {
+        return [problem(["node_type"], "missing required key", "missing_key")];
+    }
+    return [
+        problem(["node_type"], `expected 'array' or 'group', got ${show(nodeType)}`, "invalid_value"),
+    ];
+}
+/**
+ * Return every reason `value` is not a structurally-valid v2 array doc.
+ *
+ * Checks structure, not domain validity: `dtype` must be a string or field
+ * records, but the string content is not interpreted; `compressor` and
+ * `filters` are required keys that may be `null`, and otherwise must be
+ * codec configurations (objects with a string `id`).
+ */
+function arrayMetadataV2Problems(value) {
+    if (!isPlainObject(value)) {
+        return [problem([], "expected a mapping", "invalid_type")];
+    }
+    const doc = value;
+    const problems = missingKeys(ARRAY_METADATA_REQUIRED_KEYS_V2, doc);
+    problems.push(...unexpectedKeys(ARRAY_METADATA_STANDARD_KEYS_V2, doc));
+    problems.push(...checkLiteral(doc, "zarr_format", 2));
+    const shapeProblems = validateDimSequence(doc, "shape");
+    const chunksProblems = validateDimSequence(doc, "chunks");
+    problems.push(...shapeProblems, ...chunksProblems);
+    if (shapeProblems.length === 0 &&
+        chunksProblems.length === 0 &&
+        isIntSequence(doc["shape"]) &&
+        isIntSequence(doc["chunks"]) &&
+        doc["shape"].length !== doc["chunks"].length) {
+        problems.push(problem(["chunks"], "expected the same number of dimensions as shape", "invalid_value"));
+    }
+    if (has(doc, "dtype") && !isDtypeV2(doc["dtype"])) {
+        problems.push(problem(["dtype"], "expected a v2 dtype string or a sequence of field records", "invalid_type"));
+    }
+    if (has(doc, "order") && !ZARR_V2_ARRAY_ORDER.includes(doc["order"])) {
+        problems.push(problem(["order"], `expected 'C' or 'F', got ${show(doc["order"])}`, "invalid_value"));
+    }
+    if (has(doc, "compressor") && doc["compressor"] !== null) {
+        problems.push(...prefix("compressor", validateCodecV2(doc["compressor"])));
+    }
+    if (has(doc, "filters")) {
+        const filters = doc["filters"];
+        if (filters !== null && (!isDenseArray(filters) || !filters.every(isCodecV2))) {
+            problems.push(problem(["filters"], "expected null or a sequence of codec configurations with string 'id's", "invalid_type"));
+        }
+        else if (filters !== null && isDenseArray(filters)) {
+            if (filters.length === 0) {
+                problems.push(problem(["filters"], "expected at least one filter", "invalid_value"));
+            }
+            filters.forEach((item, index) => {
+                problems.push(...prefix("filters", prefix(index, jsonProblems(item))));
+            });
+        }
+    }
+    if (has(doc, "dimension_separator") &&
+        !ZARR_V2_ARRAY_DIMENSION_SEPARATOR.includes(doc["dimension_separator"])) {
+        problems.push(problem(["dimension_separator"], `expected '.' or '/', got ${show(doc["dimension_separator"])}`, "invalid_value"));
+    }
+    if (has(doc, "fill_value")) {
+        problems.push(...prefix("fill_value", jsonProblems(doc["fill_value"])));
+    }
+    if (has(doc, "attributes")) {
+        problems.push(...validateAttributes(doc["attributes"]));
+    }
+    return problems;
+}
+/**
+ * Return every reason `value` is not a structurally-valid v2 group doc.
+ *
+ * Validates the in-memory merged form: the `.zgroup` fields plus an optional
+ * `attributes` mapping folded in from `.zattrs`.
+ */
+function groupMetadataV2Problems(value) {
+    if (!isPlainObject(value)) {
+        return [problem([], "expected a mapping", "invalid_type")];
+    }
+    const doc = value;
+    const problems = missingKeys(GROUP_METADATA_REQUIRED_KEYS_V2, doc);
+    problems.push(...unexpectedKeys(GROUP_METADATA_STANDARD_KEYS_V2, doc));
+    problems.push(...checkLiteral(doc, "zarr_format", 2));
+    if (has(doc, "attributes")) {
+        problems.push(...validateAttributes(doc["attributes"]));
+    }
+    return problems;
+}
+/**
+ * Return every reason `value` is not a structurally-valid `.zmetadata` doc
+ * (v2 consolidated metadata).
+ *
+ * Ported from `ZarrV2ConsolidatedMetadata.from_json` in the Python reference
+ * implementation. Entries are validated as JSON trees, not as per-node
+ * documents: which nodes had a `.zattrs` file at all is information the
+ * canonical representation must keep, and interpreting entries into node
+ * documents is consumer work.
+ */
+function consolidatedMetadataV2Problems(value) {
+    if (!isPlainObject(value)) {
+        return [problem([], "expected a mapping", "invalid_type")];
+    }
+    const doc = value;
+    const problems = ["zarr_consolidated_format", "metadata"]
+        .filter((key) => !(has(doc, key)))
+        .map((key) => problem([key], "missing required key", "missing_key"));
+    problems.push(...unexpectedKeys(["zarr_consolidated_format", "metadata"], doc));
+    problems.push(...checkLiteral(doc, "zarr_consolidated_format", 1));
+    if (has(doc, "metadata")) {
+        const entries = doc["metadata"];
+        if (!isPlainObject(entries)) {
+            problems.push(problem(["metadata"], "expected a mapping with string keys", "invalid_type"));
+        }
+        else {
+            for (const [key, item] of Object.entries(entries)) {
+                problems.push(...prefix("metadata", prefix(key, jsonProblems(item))));
+            }
+        }
+    }
+    return problems;
+}
+function storeGet(mapping, key) {
+    if (mapping instanceof Map) {
+        return mapping.get(key);
+    }
+    const record = mapping;
+    return Object.hasOwn(record, key) ? record[key] : undefined;
+}
+/**
+ * Decode the JSON document stored at `key` in `mapping`.
+ *
+ * Ported from the Python reference's `load_store_json`. Every ingestion
+ * failure surfaces as `MetadataValidationError`: a missing store key is a
+ * `missing_key` problem and undecodable bytes or malformed JSON are an
+ * `invalid_json` problem, rather than leaking a decode exception to
+ * callers. `JSON.parse` already rejects the non-standard `NaN`/`Infinity`
+ * constants Python has to opt out of explicitly.
+ *
+ * One intentional divergence: bytes must be UTF-8 (RFC 8259's mandated
+ * interchange encoding). Python's `json.loads` auto-detects UTF-16/32 and
+ * would accept such documents; here they are reported as `invalid_json`.
+ */
+export function loadStoreJson(mapping, key) {
+    const raw = storeGet(mapping, key);
+    if (raw === undefined) {
+        throw new MetadataValidationError(treeOf([problem([key], "missing store key", "missing_key")]));
+    }
+    try {
+        const text = typeof raw === "string" ? raw : new TextDecoder("utf-8", { fatal: true }).decode(raw);
+        return JSON.parse(text);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new MetadataValidationError(treeOf([problem([key], `invalid JSON: ${message}`, "invalid_json")]));
+    }
+}
+/**
+ * Encode a metadata document as strict RFC 8259 JSON bytes.
+ *
+ * Ported from the Python reference's `dump_store_json` (`allow_nan=False`):
+ * a non-JSON value — a non-finite number, a `Map`, a `BigInt` — throws
+ * `MetadataValidationError` instead of being silently rewritten to `null`
+ * the way bare `JSON.stringify` would.
+ */
+export function dumpStoreJson(value, options = {}) {
+    const problems = jsonProblems(value);
+    if (problems.length > 0)
+        throw new MetadataValidationError(treeOf(problems));
+    return new TextEncoder().encode(JSON.stringify(value, null, options.indent));
+}
+// ---------------------------------------------------------------------------
+// Public API. Each document kind gets four entry points built on one
+// internal problems function:
+//
+//   validate*(value)  -> ErrorTree            (empty tree = valid)
+//   is*(value)        -> type guard
+//   parse*(value)     -> narrowed document, or throws MetadataValidationError
+//   safeParse*(value) -> ParseResult<T> discriminated union
+// ---------------------------------------------------------------------------
+function toResult(value, problems) {
+    return problems.length === 0
+        ? { success: true, value: value }
+        : { success: false, errors: treeOf(problems) };
+}
+function toParsed(value, problems) {
+    if (problems.length > 0)
+        throw new MetadataValidationError(treeOf(problems));
+    return value;
+}
+/** Every reason `value` is not JSON-serializable, as an error tree. */
+export function validateJson(value) {
+    return treeOf(jsonProblems(value));
+}
+/** Whether `value` is a JSON structure (recursively). */
+export function isJson(value) {
+    return jsonProblems(value).length === 0;
+}
+/** Return `value` narrowed to `JSONValue`, or throw `MetadataValidationError`. */
+export function parseJson(value) {
+    return toParsed(value, jsonProblems(value));
+}
+export function safeParseJson(value) {
+    return toResult(value, jsonProblems(value));
+}
+/** Every reason `value` is not a v3 metadata field, as an error tree. */
+export function validateMetadataFieldV3(value, options = {}) {
+    return treeOf(metadataFieldV3Problems(value, options));
+}
+/** Whether `value` is a v3 metadata field: a bare name or a named config. */
+export function isMetadataFieldV3(value) {
+    return metadataFieldV3Problems(value).length === 0;
+}
+export function parseMetadataFieldV3(value) {
+    return toParsed(value, metadataFieldV3Problems(value));
+}
+export function safeParseMetadataFieldV3(value) {
+    return toResult(value, metadataFieldV3Problems(value));
+}
+/** Every reason `value` is not a v3 array document, as an error tree. */
+export function validateArrayMetadataV3(value) {
+    return treeOf(arrayMetadataV3Problems(value));
+}
+export function isArrayMetadataV3(value) {
+    return arrayMetadataV3Problems(value).length === 0;
+}
+export function parseArrayMetadataV3(value) {
+    return toParsed(value, arrayMetadataV3Problems(value));
+}
+export function safeParseArrayMetadataV3(value) {
+    return toResult(value, arrayMetadataV3Problems(value));
+}
+/** Every reason `value` is not a v3 group document, as an error tree. */
+export function validateGroupMetadataV3(value) {
+    return treeOf(groupMetadataV3Problems(value));
+}
+export function isGroupMetadataV3(value) {
+    return groupMetadataV3Problems(value).length === 0;
+}
+export function parseGroupMetadataV3(value) {
+    return toParsed(value, groupMetadataV3Problems(value));
+}
+export function safeParseGroupMetadataV3(value) {
+    return toResult(value, groupMetadataV3Problems(value));
+}
+/** Every reason `value` is not an inline consolidated envelope, as an error tree. */
+export function validateConsolidatedMetadataV3(value) {
+    return treeOf(consolidatedMetadataV3Problems(value));
+}
+export function isConsolidatedMetadataV3(value) {
+    return consolidatedMetadataV3Problems(value).length === 0;
+}
+export function parseConsolidatedMetadataV3(value) {
+    return toParsed(value, consolidatedMetadataV3Problems(value));
+}
+export function safeParseConsolidatedMetadataV3(value) {
+    return toResult(value, consolidatedMetadataV3Problems(value));
+}
+/**
+ * Every reason `value` is not a v3 metadata document of either node type
+ * (the complete `zarr.json` grammar, dispatching on `node_type`), as an
+ * error tree.
+ */
+export function validateMetadataV3(value) {
+    return treeOf(metadataV3Problems(value));
+}
+export function isMetadataV3(value) {
+    return metadataV3Problems(value).length === 0;
+}
+export function parseMetadataV3(value) {
+    return toParsed(value, metadataV3Problems(value));
+}
+export function safeParseMetadataV3(value) {
+    return toResult(value, metadataV3Problems(value));
+}
+/** Every reason `value` is not a merged v2 array document, as an error tree. */
+export function validateArrayMetadataV2(value) {
+    return treeOf(arrayMetadataV2Problems(value));
+}
+export function isArrayMetadataV2(value) {
+    return arrayMetadataV2Problems(value).length === 0;
+}
+export function parseArrayMetadataV2(value) {
+    return toParsed(value, arrayMetadataV2Problems(value));
+}
+export function safeParseArrayMetadataV2(value) {
+    return toResult(value, arrayMetadataV2Problems(value));
+}
+/** Every reason `value` is not a merged v2 group document, as an error tree. */
+export function validateGroupMetadataV2(value) {
+    return treeOf(groupMetadataV2Problems(value));
+}
+export function isGroupMetadataV2(value) {
+    return groupMetadataV2Problems(value).length === 0;
+}
+export function parseGroupMetadataV2(value) {
+    return toParsed(value, groupMetadataV2Problems(value));
+}
+export function safeParseGroupMetadataV2(value) {
+    return toResult(value, groupMetadataV2Problems(value));
+}
+/** Every reason `value` is not a `.zmetadata` document, as an error tree. */
+export function validateConsolidatedMetadataV2(value) {
+    return treeOf(consolidatedMetadataV2Problems(value));
+}
+export function isConsolidatedMetadataV2(value) {
+    return consolidatedMetadataV2Problems(value).length === 0;
+}
+export function parseConsolidatedMetadataV2(value) {
+    return toParsed(value, consolidatedMetadataV2Problems(value));
+}
+export function safeParseConsolidatedMetadataV2(value) {
+    return toResult(value, consolidatedMetadataV2Problems(value));
+}
+//# sourceMappingURL=validation.js.map