zarr-metadata 0.7.0 → 0.9.0

package/src/data-type/numpy-timedelta64.ts

@@ -0,0 +1,9 @@
+import { numpyTemporalDataType } from "./numpy-datetime64.js";
+
+export type {
+  NumpyDatetime64Configuration as NumpyTimedelta64Configuration,
+  NumpyDatetime64FillValue as NumpyTimedelta64FillValue,
+} from "./numpy-datetime64.js";
+
+/** The zarr-extensions `numpy.timedelta64` data type. */
+export const numpyTimedelta64 = numpyTemporalDataType("numpy.timedelta64");

package/src/data-type/raw.ts

@@ -0,0 +1,31 @@
+import { isByteArray, simple, type DataTypeDescriptor } from "./descriptor.js";
+
+/** Fill value of the `r<N>` raw-bits data types: one integer per byte. */
+export type RawBytesFillValue = number[];
+
+const RAW = /^r([1-9][0-9]*)$/;
+
+/**
+ * The core `r<N>` raw-bits data type family. The name itself carries a
+ * rule — N must be a positive multiple of 8 — and the fill value must
+ * hold exactly N/8 bytes.
+ */
+export const raw: DataTypeDescriptor = {
+  matches: (name) => RAW.test(name),
+  nameIssue: (name) => {
+    const bits = Number((RAW.exec(name) as RegExpExecArray)[1]);
+    return bits % 8 === 0
+      ? undefined
+      : `expected "r<N>" with N a positive multiple of 8, got ${JSON.stringify(name)}`;
+  },
+  fillIssues: (fill, name) => {
+    const bits = Number((RAW.exec(name) as RegExpExecArray)[1]);
+    if (bits % 8 !== 0) return []; // the name issue already covers this document
+    const expectedBytes = bits / 8;
+    return isByteArray(fill) && fill.length === expectedBytes
+      ? []
+      : simple(
+          `expected an array of ${expectedBytes} integers in [0, 255] for data type ${JSON.stringify(name)}`,
+        );
+  },
+};

package/src/data-type/string.ts

@@ -0,0 +1,11 @@
+import { named, simple, type DataTypeDescriptor } from "./descriptor.js";
+
+/** Fill value of the `string` data type: a JSON unicode string. */
+export type StringFillValue = string;
+
+/** The zarr-extensions `string` data type (variable-length UTF-8). */
+export const string: DataTypeDescriptor = {
+  matches: named("string"),
+  fillIssues: (fill) =>
+    typeof fill === "string" ? [] : simple('expected a string fill value for data type "string"'),
+};

package/src/data-type/struct.ts

@@ -0,0 +1,55 @@
+import { isPlainObject } from "../guards.js";
+import { issue, named, simple, type DataTypeDescriptor } from "./descriptor.js";
+
+/** One field of a `struct` data type; `data_type` recurses (structs may nest). */
+export interface StructField {
+  name: string;
+  data_type: unknown;
+}
+
+/** Configuration of the `struct` data type. */
+export interface StructConfiguration {
+  fields: StructField[];
+}
+
+/**
+ * The zarr-extensions `struct` data type (heterogeneous record). Its fill
+ * value is a JSON object mapping every field name to that field's fill
+ * value, each judged recursively against the field's own data type.
+ */
+export const struct: DataTypeDescriptor = {
+  matches: named("struct"),
+  requiredConfigKeys: ["fields"],
+  fillIssues: (fill, _name, context) => {
+    if (!isPlainObject(fill)) {
+      return simple('expected an object mapping field names to fill values for data type "struct"');
+    }
+    const fields = context.configuration?.["fields"];
+    if (!Array.isArray(fields)) return []; // config shape is the schema layer's problem
+    const declared = new Map<string, unknown>();
+    for (const field of fields) {
+      if (isPlainObject(field) && typeof field["name"] === "string") {
+        declared.set(field["name"], field["data_type"]);
+      }
+    }
+    if (declared.size !== fields.length) return []; // malformed fields: schema layer's problem
+    const issues = [];
+    for (const [fieldName, dataType] of declared) {
+      if (!Object.hasOwn(fill, fieldName)) {
+        issues.push(issue([fieldName], "missing required key", "missing_key"));
+        continue;
+      }
+      issues.push(
+        ...context
+          .fillIssuesFor(dataType, fill[fieldName], context.depth + 1)
+          .map((inner) => ({ ...inner, path: [fieldName, ...inner.path] })),
+      );
+    }
+    for (const key of Object.keys(fill)) {
+      if (!declared.has(key)) {
+        issues.push(issue([key], "unexpected member (no such struct field)"));
+      }
+    }
+    return issues;
+  },
+};

package/src/data-type/uint16.ts

@@ -0,0 +1,4 @@
+import { intDataType } from "./descriptor.js";
+
+/** The core `uint16` data type. */
+export const uint16 = intDataType("uint16", 0, 65535);

package/src/data-type/uint32.ts

@@ -0,0 +1,4 @@
+import { intDataType } from "./descriptor.js";
+
+/** The core `uint32` data type. */
+export const uint32 = intDataType("uint32", 0, 4294967295);

package/src/data-type/uint64.ts

@@ -0,0 +1,4 @@
+import { intDataType } from "./descriptor.js";
+
+/** The core `uint64` data type. */
+export const uint64 = intDataType("uint64", 0, 18446744073709551615);

package/src/data-type/uint8.ts

@@ -0,0 +1,4 @@
+import { intDataType } from "./descriptor.js";
+
+/** The core `uint8` data type. */
+export const uint8 = intDataType("uint8", 0, 255);

package/src/guards.ts

@@ -0,0 +1,48 @@
+/**
+ * Shared value guards for the content modules (chunk grids, codecs, data
+ * types) and the semantics orchestrator. The structural document layer
+ * (validation.ts) keeps its own copies deliberately: it is the
+ * corpus-governed layer and stays self-contained.
+ */
+
+export type Path = ReadonlyArray<string | number>;
+
+export function isPlainObject(value: unknown): value is Record<string, unknown> {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+  const proto: unknown = Object.getPrototypeOf(value);
+  return proto === null || proto === Object.prototype;
+}
+
+export function isIntArray(value: unknown): value is number[] {
+  return (
+    Array.isArray(value) &&
+    Object.keys(value).length === value.length &&
+    value.every((item) => Number.isInteger(item))
+  );
+}
+
+/** The `{name, configuration}` of a metadata field, when extractable. */
+export function fieldParts(
+  field: unknown,
+): { name: string; configuration: Record<string, unknown> | undefined } | undefined {
+  if (typeof field === "string") return { name: field, configuration: undefined };
+  if (isPlainObject(field) && typeof field["name"] === "string") {
+    const configuration = field["configuration"];
+    return {
+      name: field["name"],
+      configuration: isPlainObject(configuration) ? configuration : undefined,
+    };
+  }
+  return undefined;
+}
+
+/**
+ * Whether a metadata field genuinely lacks a `configuration` member (a
+ * malformed one — `configuration: 5` — is the structural layer's
+ * complaint, not the semantic layer's).
+ */
+export function configurationMissing(field: unknown): boolean {
+  return (
+    typeof field === "string" || (isPlainObject(field) && !Object.hasOwn(field, "configuration"))
+  );
+}

package/src/index.ts

@@ -20,6 +20,28 @@ export {
   type ParseResult,
   type PathedIssue,
 } from "./errors.js";
+export type {
+  ChunkGridVerdict,
+  RectilinearChunkGridConfiguration,
+  RectilinearDimSpec,
+  RegularChunkGridConfiguration,
+} from "./chunk-grid/index.js";
+export type {
+  ShardingIndexedCodecConfiguration,
+  TransposeCodecConfiguration,
+} from "./codec/index.js";
+export type {
+  BytesFillValue,
+  ComplexFillValue,
+  FloatFillValue,
+  NumpyDatetime64Configuration,
+  NumpyDatetime64FillValue,
+  NumpyTimeUnit,
+  RawBytesFillValue,
+  StringFillValue,
+  StructConfiguration,
+  StructField,
+} from "./data-type/index.js";
 export * from "./schemas.js";
 export * from "./semantics.js";
 export type { StandardSchemaV1 } from "./standard-schema.js";