zarr-metadata 0.1.0

package/dist/standard-schema.js

@@ -0,0 +1,11 @@
+/**
+ * The Standard Schema V1 interface (https://standardschema.dev), vendored.
+ *
+ * Standard Schema is the interoperability contract implemented by Zod,
+ * Valibot, ArkType, and consumed by tRPC, form libraries, and others. The
+ * spec is designed to be copied into implementing libraries so they stay
+ * dependency-free; the test suite checks this copy against the official
+ * `@standard-schema/spec` types (a devDependency) so it cannot drift.
+ */
+export {};
+//# sourceMappingURL=standard-schema.js.map

package/dist/standard-schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"standard-schema.js","sourceRoot":"","sources":["../src/standard-schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG"}

package/dist/v2.d.ts

@@ -0,0 +1,104 @@
+/**
+ * Zarr v2 metadata document types.
+ *
+ * See https://zarr-specs.readthedocs.io/en/latest/v2/v2.0.html
+ */
+import type { JSONValue } from "./common.js";
+/**
+ * The v2 dtype representation.
+ *
+ * Either a numpy-style dtype string (e.g. `"<f8"`, `"|S10"`) or an array of
+ * field records describing a structured dtype. Each field record is either a
+ * 2-tuple `[name, datatype]` or a 3-tuple `[name, datatype, shape]` (the
+ * 3-tuple form indicates a subarray field). A field datatype may itself be
+ * another structured dtype.
+ *
+ * See https://zarr-specs.readthedocs.io/en/latest/v2/v2.0.html#data-type-encoding
+ */
+export type ZarrV2DataTypeMetadata = string | Array<[string, ZarrV2DataTypeMetadata] | [string, ZarrV2DataTypeMetadata, number[]]>;
+/** `"C"` (row-major) or `"F"` (column-major) — the in-chunk byte layout. */
+export declare const ZARR_V2_ARRAY_ORDER: readonly ["C", "F"];
+export type ZarrV2ArrayOrder = (typeof ZARR_V2_ARRAY_ORDER)[number];
+/** `"."` (legacy default) or `"/"` (nested directories). */
+export declare const ZARR_V2_ARRAY_DIMENSION_SEPARATOR: readonly [".", "/"];
+export type ZarrV2ArrayDimensionSeparator = (typeof ZARR_V2_ARRAY_DIMENSION_SEPARATOR)[number];
+/**
+ * A numcodecs configuration object, used as a v2 compressor or filter.
+ *
+ * The required `id` field names the codec; codec-specific parameters
+ * (e.g. `cname`, `clevel` for blosc) appear as extra fields.
+ */
+export type ZarrV2CodecMetadata = {
+    id: string;
+} & {
+    [key: string]: JSONValue;
+};
+/**
+ * On-disk `.zarray` file content.
+ *
+ * User attributes live in a sibling `.zattrs` file and are NOT part of this
+ * type; see `ZarrV2ZAttrsJSON`.
+ */
+export type ZarrV2ZArrayJSON = {
+    zarr_format: 2;
+    shape: number[];
+    chunks: number[];
+    dtype: ZarrV2DataTypeMetadata;
+    compressor: ZarrV2CodecMetadata | null;
+    fill_value: JSONValue;
+    order: ZarrV2ArrayOrder;
+    filters: ZarrV2CodecMetadata[] | null;
+    dimension_separator?: ZarrV2ArrayDimensionSeparator;
+};
+/**
+ * Zarr v2 array metadata document, in-memory merged form: the `.zarray`
+ * fields plus the sibling `.zattrs` attributes folded in as `attributes`.
+ */
+export type ZarrV2ArrayMetadataJSON = ZarrV2ZArrayJSON & {
+    attributes?: {
+        [key: string]: JSONValue;
+    };
+};
+/** On-disk `.zgroup` file content. The spec defines exactly one field. */
+export type ZarrV2ZGroupJSON = {
+    zarr_format: 2;
+};
+/**
+ * Zarr v2 group metadata document, in-memory merged form: the `.zgroup`
+ * field plus the sibling `.zattrs` attributes folded in as `attributes`.
+ */
+export type ZarrV2GroupMetadataJSON = ZarrV2ZGroupJSON & {
+    attributes?: {
+        [key: string]: JSONValue;
+    };
+};
+/** On-disk `.zattrs` file content: a JSON object of user attributes. */
+export type ZarrV2ZAttrsJSON = {
+    [key: string]: JSONValue;
+};
+/**
+ * `.zmetadata` file contents (v2 consolidated metadata).
+ *
+ * NOT a spec artifact: a reference-implementation convention. The `metadata`
+ * map uses flat path keys (`"foo/bar/.zarray"`, `"foo/.zattrs"`, ...)
+ * pointing to the JSON contents of the file at that path.
+ */
+export type ZarrV2ConsolidatedMetadataJSON = {
+    zarr_consolidated_format: 1;
+    metadata: {
+        [key: string]: JSONValue;
+    };
+};
+export declare const ZARR_V2_ARRAY_METADATA_STORE_KEY = ".zarray";
+export declare const ZARR_V2_GROUP_METADATA_STORE_KEY = ".zgroup";
+export declare const ZARR_V2_ATTRIBUTES_STORE_KEY = ".zattrs";
+export declare const ZARR_V2_CONSOLIDATED_METADATA_STORE_KEY = ".zmetadata";
+/** The standard top-level keys of a merged v2 array metadata document. */
+export declare const ARRAY_METADATA_REQUIRED_KEYS_V2: readonly ["zarr_format", "shape", "chunks", "dtype", "compressor", "fill_value", "order", "filters"];
+export declare const ARRAY_METADATA_OPTIONAL_KEYS_V2: readonly ["dimension_separator", "attributes"];
+export declare const ARRAY_METADATA_STANDARD_KEYS_V2: readonly ["zarr_format", "shape", "chunks", "dtype", "compressor", "fill_value", "order", "filters", "dimension_separator", "attributes"];
+/** The standard top-level keys of a merged v2 group metadata document. */
+export declare const GROUP_METADATA_REQUIRED_KEYS_V2: readonly ["zarr_format"];
+export declare const GROUP_METADATA_OPTIONAL_KEYS_V2: readonly ["attributes"];
+export declare const GROUP_METADATA_STANDARD_KEYS_V2: readonly ["zarr_format", "attributes"];
+//# sourceMappingURL=v2.d.ts.map

package/dist/v2.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"v2.d.ts","sourceRoot":"","sources":["../src/v2.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAG7C;;;;;;;;;;GAUG;AACH,MAAM,MAAM,sBAAsB,GAC9B,MAAM,GACN,KAAK,CAAC,CAAC,MAAM,EAAE,sBAAsB,CAAC,GAAG,CAAC,MAAM,EAAE,sBAAsB,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC;AAEzF,4EAA4E;AAC5E,eAAO,MAAM,mBAAmB,qBAAsB,CAAC;AACvD,MAAM,MAAM,gBAAgB,GAAG,CAAC,OAAO,mBAAmB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEpE,4DAA4D;AAC5D,eAAO,MAAM,iCAAiC,qBAAsB,CAAC;AACrE,MAAM,MAAM,6BAA6B,GAAG,CAAC,OAAO,iCAAiC,CAAC,CAAC,MAAM,CAAC,CAAC;AAE/F;;;;;GAKG;AACH,MAAM,MAAM,mBAAmB,GAAG;IAAE,EAAE,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,CAAC;AAEhF;;;;;GAKG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC7B,WAAW,EAAE,CAAC,CAAC;IACf,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,KAAK,EAAE,sBAAsB,CAAC;IAC9B,UAAU,EAAE,mBAAmB,GAAG,IAAI,CAAC;IACvC,UAAU,EAAE,SAAS,CAAC;IACtB,KAAK,EAAE,gBAAgB,CAAC;IACxB,OAAO,EAAE,mBAAmB,EAAE,GAAG,IAAI,CAAC;IACtC,mBAAmB,CAAC,EAAE,6BAA6B,CAAC;CACrD,CAAC;AAEF;;;GAGG;AACH,MAAM,MAAM,uBAAuB,GAAG,gBAAgB,GAAG;IACvD,UAAU,CAAC,EAAE;QAAE,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAAA;KAAE,CAAC;CAC3C,CAAC;AAEF,0EAA0E;AAC1E,MAAM,MAAM,gBAAgB,GAAG;IAC7B,WAAW,EAAE,CAAC,CAAC;CAChB,CAAC;AAEF;;;GAGG;AACH,MAAM,MAAM,uBAAuB,GAAG,gBAAgB,GAAG;IACvD,UAAU,CAAC,EAAE;QAAE,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAAA;KAAE,CAAC;CAC3C,CAAC;AAEF,wEAAwE;AACxE,MAAM,MAAM,gBAAgB,GAAG;IAAE,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,CAAC;AAE5D;;;;;;GAMG;AACH,MAAM,MAAM,8BAA8B,GAAG;IAC3C,wBAAwB,EAAE,CAAC,CAAC;IAC5B,QAAQ,EAAE;QAAE,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAAA;KAAE,CAAC;CACxC,CAAC;AAEF,eAAO,MAAM,gCAAgC,YAAY,CAAC;AAC1D,eAAO,MAAM,gCAAgC,YAAY,CAAC;AAC1D,eAAO,MAAM,4BAA4B,YAAY,CAAC;AACtD,eAAO,MAAM,uCAAuC,eAAe,CAAC;AAEpE,0EAA0E;AAC1E,eAAO,MAAM,+BAA+B,sGAS1C,CAAC;AACH,eAAO,MAAM,+BAA+B,gDAG1C,CAAC;AACH,eAAO,MAAM,+BAA+B,2IAGlC,CAAC;AAEX,0EAA0E;AAC1E,eAAO,MAAM,+BAA+B,0BAAwE,CAAC;AACrH,eAAO,MAAM,+BAA+B,yBAAuE,CAAC;AACpH,eAAO,MAAM,+BAA+B,wCAGlC,CAAC"}

package/dist/v2.js

@@ -0,0 +1,41 @@
+/**
+ * Zarr v2 metadata document types.
+ *
+ * See https://zarr-specs.readthedocs.io/en/latest/v2/v2.0.html
+ */
+import { exactKeys } from "./keys.js";
+/** `"C"` (row-major) or `"F"` (column-major) — the in-chunk byte layout. */
+export const ZARR_V2_ARRAY_ORDER = ["C", "F"];
+/** `"."` (legacy default) or `"/"` (nested directories). */
+export const ZARR_V2_ARRAY_DIMENSION_SEPARATOR = [".", "/"];
+export const ZARR_V2_ARRAY_METADATA_STORE_KEY = ".zarray";
+export const ZARR_V2_GROUP_METADATA_STORE_KEY = ".zgroup";
+export const ZARR_V2_ATTRIBUTES_STORE_KEY = ".zattrs";
+export const ZARR_V2_CONSOLIDATED_METADATA_STORE_KEY = ".zmetadata";
+/** The standard top-level keys of a merged v2 array metadata document. */
+export const ARRAY_METADATA_REQUIRED_KEYS_V2 = exactKeys()([
+    "zarr_format",
+    "shape",
+    "chunks",
+    "dtype",
+    "compressor",
+    "fill_value",
+    "order",
+    "filters",
+]);
+export const ARRAY_METADATA_OPTIONAL_KEYS_V2 = exactKeys()([
+    "dimension_separator",
+    "attributes",
+]);
+export const ARRAY_METADATA_STANDARD_KEYS_V2 = [
+    ...ARRAY_METADATA_REQUIRED_KEYS_V2,
+    ...ARRAY_METADATA_OPTIONAL_KEYS_V2,
+];
+/** The standard top-level keys of a merged v2 group metadata document. */
+export const GROUP_METADATA_REQUIRED_KEYS_V2 = exactKeys()(["zarr_format"]);
+export const GROUP_METADATA_OPTIONAL_KEYS_V2 = exactKeys()(["attributes"]);
+export const GROUP_METADATA_STANDARD_KEYS_V2 = [
+    ...GROUP_METADATA_REQUIRED_KEYS_V2,
+    ...GROUP_METADATA_OPTIONAL_KEYS_V2,
+];
+//# sourceMappingURL=v2.js.map

package/dist/v2.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"v2.js","sourceRoot":"","sources":["../src/v2.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EAAE,SAAS,EAA4C,MAAM,WAAW,CAAC;AAiBhF,4EAA4E;AAC5E,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,GAAG,EAAE,GAAG,CAAU,CAAC;AAGvD,4DAA4D;AAC5D,MAAM,CAAC,MAAM,iCAAiC,GAAG,CAAC,GAAG,EAAE,GAAG,CAAU,CAAC;AAiErE,MAAM,CAAC,MAAM,gCAAgC,GAAG,SAAS,CAAC;AAC1D,MAAM,CAAC,MAAM,gCAAgC,GAAG,SAAS,CAAC;AAC1D,MAAM,CAAC,MAAM,4BAA4B,GAAG,SAAS,CAAC;AACtD,MAAM,CAAC,MAAM,uCAAuC,GAAG,YAAY,CAAC;AAEpE,0EAA0E;AAC1E,MAAM,CAAC,MAAM,+BAA+B,GAAG,SAAS,EAA2C,CAAC;IAClG,aAAa;IACb,OAAO;IACP,QAAQ;IACR,OAAO;IACP,YAAY;IACZ,YAAY;IACZ,OAAO;IACP,SAAS;CACV,CAAC,CAAC;AACH,MAAM,CAAC,MAAM,+BAA+B,GAAG,SAAS,EAA2C,CAAC;IAClG,qBAAqB;IACrB,YAAY;CACb,CAAC,CAAC;AACH,MAAM,CAAC,MAAM,+BAA+B,GAAG;IAC7C,GAAG,+BAA+B;IAClC,GAAG,+BAA+B;CAC1B,CAAC;AAEX,0EAA0E;AAC1E,MAAM,CAAC,MAAM,+BAA+B,GAAG,SAAS,EAA2C,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC;AACrH,MAAM,CAAC,MAAM,+BAA+B,GAAG,SAAS,EAA2C,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC;AACpH,MAAM,CAAC,MAAM,+BAA+B,GAAG;IAC7C,GAAG,+BAA+B;IAClC,GAAG,+BAA+B;CAC1B,CAAC"}

package/dist/v3.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Zarr v3 metadata document types.
+ *
+ * See https://zarr-specs.readthedocs.io/en/latest/v3/core/index.html
+ */
+import type { JSONValue, ZarrV3MetadataFieldJSON } from "./common.js";
+/**
+ * The JSON value of an unknown top-level v3 metadata field.
+ *
+ * An object carrying the literal member `must_understand: false` may be
+ * ignored. Every other JSON shape implicitly requires understanding;
+ * recognition itself belongs to the reader rather than this structural type.
+ */
+export type ZarrV3ExtensionField = JSONValue;
+/**
+ * Zarr v3 array metadata document (the `zarr.json` content for an array).
+ *
+ * Extra keys may contain arbitrary JSON values (extension fields).
+ *
+ * See https://zarr-specs.readthedocs.io/en/latest/v3/core/index.html#array-metadata
+ */
+export type ZarrV3ArrayMetadataJSON = {
+    zarr_format: 3;
+    node_type: "array";
+    data_type: ZarrV3MetadataFieldJSON;
+    shape: number[];
+    chunk_grid: ZarrV3MetadataFieldJSON;
+    chunk_key_encoding: ZarrV3MetadataFieldJSON;
+    fill_value: JSONValue;
+    codecs: ZarrV3MetadataFieldJSON[];
+    attributes?: {
+        [key: string]: JSONValue;
+    };
+    storage_transformers?: ZarrV3MetadataFieldJSON[];
+    dimension_names?: (string | null)[];
+} & {
+    [key: string]: JSONValue;
+};
+/**
+ * Zarr v3 group metadata document (the `zarr.json` content for a group).
+ *
+ * Extra keys may contain arbitrary JSON values (extension fields).
+ *
+ * See https://zarr-specs.readthedocs.io/en/latest/v3/core/index.html#group-metadata
+ */
+export type ZarrV3GroupMetadataJSON = {
+    zarr_format: 3;
+    node_type: "group";
+    attributes?: {
+        [key: string]: JSONValue;
+    };
+} & {
+    [key: string]: JSONValue;
+};
+/**
+ * Either v3 document form of `zarr.json`, discriminated by `node_type`.
+ */
+export type ZarrV3MetadataJSON = ZarrV3ArrayMetadataJSON | ZarrV3GroupMetadataJSON;
+/**
+ * Inline consolidated metadata embedded in a v3 group.
+ *
+ * There is no Zarr v3 specification for consolidated metadata; this models
+ * the inline-on-group convention used by the reference Python implementation
+ * (and zarrs), where consolidated metadata is embedded as an extension field
+ * on a group's `zarr.json`.
+ */
+export type ZarrV3ConsolidatedMetadataJSON = {
+    kind: "inline";
+    must_understand: false;
+    metadata: {
+        [key: string]: ZarrV3ArrayMetadataJSON | ZarrV3GroupMetadataJSON;
+    };
+};
+/**
+ * The store key both v3 node types persist their metadata document under.
+ * The document's `node_type` field distinguishes an array from a group.
+ */
+export declare const ZARR_V3_METADATA_STORE_KEY = "zarr.json";
+/** The key under which consolidated metadata is embedded in a v3 group document. */
+export declare const ZARR_V3_CONSOLIDATED_METADATA_KEY = "consolidated_metadata";
+/** The standard top-level keys of a v3 array metadata document. */
+export declare const ARRAY_METADATA_REQUIRED_KEYS_V3: readonly ["zarr_format", "node_type", "data_type", "shape", "chunk_grid", "chunk_key_encoding", "fill_value", "codecs"];
+export declare const ARRAY_METADATA_OPTIONAL_KEYS_V3: readonly ["attributes", "storage_transformers", "dimension_names"];
+export declare const ARRAY_METADATA_STANDARD_KEYS_V3: readonly ["zarr_format", "node_type", "data_type", "shape", "chunk_grid", "chunk_key_encoding", "fill_value", "codecs", "attributes", "storage_transformers", "dimension_names"];
+/** The standard top-level keys of a v3 group metadata document. */
+export declare const GROUP_METADATA_REQUIRED_KEYS_V3: readonly ["zarr_format", "node_type"];
+export declare const GROUP_METADATA_OPTIONAL_KEYS_V3: readonly ["attributes"];
+export declare const GROUP_METADATA_STANDARD_KEYS_V3: readonly ["zarr_format", "node_type", "attributes"];
+//# sourceMappingURL=v3.d.ts.map

package/dist/v3.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"v3.d.ts","sourceRoot":"","sources":["../src/v3.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAC;AAGtE;;;;;;GAMG;AACH,MAAM,MAAM,oBAAoB,GAAG,SAAS,CAAC;AAE7C;;;;;;GAMG;AACH,MAAM,MAAM,uBAAuB,GAAG;IACpC,WAAW,EAAE,CAAC,CAAC;IACf,SAAS,EAAE,OAAO,CAAC;IACnB,SAAS,EAAE,uBAAuB,CAAC;IACnC,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,UAAU,EAAE,uBAAuB,CAAC;IACpC,kBAAkB,EAAE,uBAAuB,CAAC;IAC5C,UAAU,EAAE,SAAS,CAAC;IACtB,MAAM,EAAE,uBAAuB,EAAE,CAAC;IAClC,UAAU,CAAC,EAAE;QAAE,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAAA;KAAE,CAAC;IAC1C,oBAAoB,CAAC,EAAE,uBAAuB,EAAE,CAAC;IACjD,eAAe,CAAC,EAAE,CAAC,MAAM,GAAG,IAAI,CAAC,EAAE,CAAC;CACrC,GAAG;IAAE,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,CAAC;AAEjC;;;;;;GAMG;AACH,MAAM,MAAM,uBAAuB,GAAG;IACpC,WAAW,EAAE,CAAC,CAAC;IACf,SAAS,EAAE,OAAO,CAAC;IACnB,UAAU,CAAC,EAAE;QAAE,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAAA;KAAE,CAAC;CAC3C,GAAG;IAAE,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,CAAC;AAEjC;;GAEG;AACH,MAAM,MAAM,kBAAkB,GAAG,uBAAuB,GAAG,uBAAuB,CAAC;AAEnF;;;;;;;GAOG;AACH,MAAM,MAAM,8BAA8B,GAAG;IAC3C,IAAI,EAAE,QAAQ,CAAC;IACf,eAAe,EAAE,KAAK,CAAC;IACvB,QAAQ,EAAE;QAAE,CAAC,GAAG,EAAE,MAAM,GAAG,uBAAuB,GAAG,uBAAuB,CAAA;KAAE,CAAC;CAChF,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,0BAA0B,cAAc,CAAC;AAEtD,oFAAoF;AACpF,eAAO,MAAM,iCAAiC,0BAA0B,CAAC;AAEzE,mEAAmE;AACnE,eAAO,MAAM,+BAA+B,yHAS1C,CAAC;AACH,eAAO,MAAM,+BAA+B,oEAI1C,CAAC;AACH,eAAO,MAAM,+BAA+B,kLAGlC,CAAC;AAEX,mEAAmE;AACnE,eAAO,MAAM,+BAA+B,uCAG1C,CAAC;AACH,eAAO,MAAM,+BAA+B,yBAAuE,CAAC;AACpH,eAAO,MAAM,+BAA+B,qDAGlC,CAAC"}

package/dist/v3.js

@@ -0,0 +1,44 @@
+/**
+ * Zarr v3 metadata document types.
+ *
+ * See https://zarr-specs.readthedocs.io/en/latest/v3/core/index.html
+ */
+import { exactKeys } from "./keys.js";
+/**
+ * The store key both v3 node types persist their metadata document under.
+ * The document's `node_type` field distinguishes an array from a group.
+ */
+export const ZARR_V3_METADATA_STORE_KEY = "zarr.json";
+/** The key under which consolidated metadata is embedded in a v3 group document. */
+export const ZARR_V3_CONSOLIDATED_METADATA_KEY = "consolidated_metadata";
+/** The standard top-level keys of a v3 array metadata document. */
+export const ARRAY_METADATA_REQUIRED_KEYS_V3 = exactKeys()([
+    "zarr_format",
+    "node_type",
+    "data_type",
+    "shape",
+    "chunk_grid",
+    "chunk_key_encoding",
+    "fill_value",
+    "codecs",
+]);
+export const ARRAY_METADATA_OPTIONAL_KEYS_V3 = exactKeys()([
+    "attributes",
+    "storage_transformers",
+    "dimension_names",
+]);
+export const ARRAY_METADATA_STANDARD_KEYS_V3 = [
+    ...ARRAY_METADATA_REQUIRED_KEYS_V3,
+    ...ARRAY_METADATA_OPTIONAL_KEYS_V3,
+];
+/** The standard top-level keys of a v3 group metadata document. */
+export const GROUP_METADATA_REQUIRED_KEYS_V3 = exactKeys()([
+    "zarr_format",
+    "node_type",
+]);
+export const GROUP_METADATA_OPTIONAL_KEYS_V3 = exactKeys()(["attributes"]);
+export const GROUP_METADATA_STANDARD_KEYS_V3 = [
+    ...GROUP_METADATA_REQUIRED_KEYS_V3,
+    ...GROUP_METADATA_OPTIONAL_KEYS_V3,
+];
+//# sourceMappingURL=v3.js.map

package/dist/v3.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"v3.js","sourceRoot":"","sources":["../src/v3.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EAAE,SAAS,EAA4C,MAAM,WAAW,CAAC;AAgEhF;;;GAGG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAG,WAAW,CAAC;AAEtD,oFAAoF;AACpF,MAAM,CAAC,MAAM,iCAAiC,GAAG,uBAAuB,CAAC;AAEzE,mEAAmE;AACnE,MAAM,CAAC,MAAM,+BAA+B,GAAG,SAAS,EAA2C,CAAC;IAClG,aAAa;IACb,WAAW;IACX,WAAW;IACX,OAAO;IACP,YAAY;IACZ,oBAAoB;IACpB,YAAY;IACZ,QAAQ;CACT,CAAC,CAAC;AACH,MAAM,CAAC,MAAM,+BAA+B,GAAG,SAAS,EAA2C,CAAC;IAClG,YAAY;IACZ,sBAAsB;IACtB,iBAAiB;CAClB,CAAC,CAAC;AACH,MAAM,CAAC,MAAM,+BAA+B,GAAG;IAC7C,GAAG,+BAA+B;IAClC,GAAG,+BAA+B;CAC1B,CAAC;AAEX,mEAAmE;AACnE,MAAM,CAAC,MAAM,+BAA+B,GAAG,SAAS,EAA2C,CAAC;IAClG,aAAa;IACb,WAAW;CACZ,CAAC,CAAC;AACH,MAAM,CAAC,MAAM,+BAA+B,GAAG,SAAS,EAA2C,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC;AACpH,MAAM,CAAC,MAAM,+BAA+B,GAAG;IAC7C,GAAG,+BAA+B;IAClC,GAAG,+BAA+B;CAC1B,CAAC"}

package/dist/validation.d.ts

@@ -0,0 +1,136 @@
+/**
+ * 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 type { JSONValue, ZarrV3MetadataFieldJSON } from "./common.js";
+import { type ErrorTree, type ParseResult } from "./errors.js";
+import { type ZarrV2ArrayMetadataJSON, type ZarrV2ConsolidatedMetadataJSON, type ZarrV2GroupMetadataJSON } from "./v2.js";
+import { type ZarrV3ArrayMetadataJSON, type ZarrV3ConsolidatedMetadataJSON, type ZarrV3GroupMetadataJSON, type ZarrV3MetadataJSON } from "./v3.js";
+/**
+ * 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 declare const MAX_JSON_DEPTH = 64;
+/**
+ * A key-value store fragment holding metadata documents as bytes or text:
+ * either a `Map` or a plain object keyed by store key.
+ */
+export type StoreMapping = ReadonlyMap<string, Uint8Array | string> | Record<string, Uint8Array | string | 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 declare function loadStoreJson(mapping: StoreMapping, key: string): unknown;
+/**
+ * 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 declare function dumpStoreJson(value: unknown, options?: {
+    indent?: number | string;
+}): Uint8Array;
+/** Every reason `value` is not JSON-serializable, as an error tree. */
+export declare function validateJson(value: unknown): ErrorTree;
+/** Whether `value` is a JSON structure (recursively). */
+export declare function isJson(value: unknown): value is JSONValue;
+/** Return `value` narrowed to `JSONValue`, or throw `MetadataValidationError`. */
+export declare function parseJson(value: unknown): JSONValue;
+export declare function safeParseJson(value: unknown): ParseResult<JSONValue>;
+/** Every reason `value` is not a v3 metadata field, as an error tree. */
+export declare function validateMetadataFieldV3(value: unknown, options?: {
+    allowMustUnderstandFalse?: boolean;
+}): ErrorTree;
+/** Whether `value` is a v3 metadata field: a bare name or a named config. */
+export declare function isMetadataFieldV3(value: unknown): value is ZarrV3MetadataFieldJSON;
+export declare function parseMetadataFieldV3(value: unknown): ZarrV3MetadataFieldJSON;
+export declare function safeParseMetadataFieldV3(value: unknown): ParseResult<ZarrV3MetadataFieldJSON>;
+/** Every reason `value` is not a v3 array document, as an error tree. */
+export declare function validateArrayMetadataV3(value: unknown): ErrorTree;
+export declare function isArrayMetadataV3(value: unknown): value is ZarrV3ArrayMetadataJSON;
+export declare function parseArrayMetadataV3(value: unknown): ZarrV3ArrayMetadataJSON;
+export declare function safeParseArrayMetadataV3(value: unknown): ParseResult<ZarrV3ArrayMetadataJSON>;
+/** Every reason `value` is not a v3 group document, as an error tree. */
+export declare function validateGroupMetadataV3(value: unknown): ErrorTree;
+export declare function isGroupMetadataV3(value: unknown): value is ZarrV3GroupMetadataJSON;
+export declare function parseGroupMetadataV3(value: unknown): ZarrV3GroupMetadataJSON;
+export declare function safeParseGroupMetadataV3(value: unknown): ParseResult<ZarrV3GroupMetadataJSON>;
+/** Every reason `value` is not an inline consolidated envelope, as an error tree. */
+export declare function validateConsolidatedMetadataV3(value: unknown): ErrorTree;
+export declare function isConsolidatedMetadataV3(value: unknown): value is ZarrV3ConsolidatedMetadataJSON;
+export declare function parseConsolidatedMetadataV3(value: unknown): ZarrV3ConsolidatedMetadataJSON;
+export declare function safeParseConsolidatedMetadataV3(value: unknown): ParseResult<ZarrV3ConsolidatedMetadataJSON>;
+/**
+ * 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 declare function validateMetadataV3(value: unknown): ErrorTree;
+export declare function isMetadataV3(value: unknown): value is ZarrV3MetadataJSON;
+export declare function parseMetadataV3(value: unknown): ZarrV3MetadataJSON;
+export declare function safeParseMetadataV3(value: unknown): ParseResult<ZarrV3MetadataJSON>;
+/** Every reason `value` is not a merged v2 array document, as an error tree. */
+export declare function validateArrayMetadataV2(value: unknown): ErrorTree;
+export declare function isArrayMetadataV2(value: unknown): value is ZarrV2ArrayMetadataJSON;
+export declare function parseArrayMetadataV2(value: unknown): ZarrV2ArrayMetadataJSON;
+export declare function safeParseArrayMetadataV2(value: unknown): ParseResult<ZarrV2ArrayMetadataJSON>;
+/** Every reason `value` is not a merged v2 group document, as an error tree. */
+export declare function validateGroupMetadataV2(value: unknown): ErrorTree;
+export declare function isGroupMetadataV2(value: unknown): value is ZarrV2GroupMetadataJSON;
+export declare function parseGroupMetadataV2(value: unknown): ZarrV2GroupMetadataJSON;
+export declare function safeParseGroupMetadataV2(value: unknown): ParseResult<ZarrV2GroupMetadataJSON>;
+/** Every reason `value` is not a `.zmetadata` document, as an error tree. */
+export declare function validateConsolidatedMetadataV2(value: unknown): ErrorTree;
+export declare function isConsolidatedMetadataV2(value: unknown): value is ZarrV2ConsolidatedMetadataJSON;
+export declare function parseConsolidatedMetadataV2(value: unknown): ZarrV2ConsolidatedMetadataJSON;
+export declare function safeParseConsolidatedMetadataV2(value: unknown): ParseResult<ZarrV2ConsolidatedMetadataJSON>;
+//# sourceMappingURL=validation.d.ts.map

package/dist/validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../src/validation.ts"],"names":[],"mappings":"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"}