zarr-metadata 0.7.0 → 0.9.0

package/src/chunk-grid/regular.ts

@@ -0,0 +1,42 @@
+/** The core `regular` chunk grid: syntax and semantics. */
+import type { PathedIssue } from "../errors.js";
+import { configurationMissing, fieldParts, isIntArray } from "../guards.js";
+import type { ChunkGridVerdict } from "./index.js";
+
+/** Configuration of the core `regular` chunk grid. */
+export interface RegularChunkGridConfiguration {
+  chunk_shape: number[];
+}
+
+export function regularIssues(rawGrid: unknown, shape: number[] | undefined): ChunkGridVerdict {
+  const issues: PathedIssue[] = [];
+  let chunkSizes: number[][] | undefined;
+  const configuration = fieldParts(rawGrid)?.configuration;
+  if (configurationMissing(rawGrid)) {
+    issues.push({
+      path: [],
+      message: '"regular" requires a configuration with "chunk_shape"',
+      kind: "missing_key",
+    });
+  } else if (configuration !== undefined && !Object.hasOwn(configuration, "chunk_shape")) {
+    issues.push({
+      path: ["configuration", "chunk_shape"],
+      message: "missing required key",
+      kind: "missing_key",
+    });
+  }
+  const configured = configuration?.["chunk_shape"];
+  if (isIntArray(configured)) {
+    if (shape !== undefined && configured.length !== shape.length) {
+      issues.push({
+        path: ["configuration", "chunk_shape"],
+        message: `expected one length per dimension of shape (${shape.length})`,
+        kind: "invalid_value",
+      });
+      // wrong arity: unusable as division context
+    } else {
+      chunkSizes = configured.map((length) => [length]);
+    }
+  }
+  return { issues, chunkSizes };
+}

package/src/codec/index.ts

@@ -0,0 +1,76 @@
+/**
+ * The codecs this package interprets, one module per codec, plus the
+ * pipeline walker that threads dimensional context between codecs
+ * (mirroring zarr-python's chunk-spec threading): a valid transpose
+ * permutes the per-dimension chunk sizes for the codecs after it, and any
+ * codec this package cannot reason about — `reshape` may change a chunk's
+ * rank, and unknown codecs may do anything — invalidates the dimensional
+ * context for the rest of the pipeline instead of letting stale
+ * array-level facts produce false verdicts.
+ *
+ * Other codecs' required fields (blosc, gzip, zstd, ...) are deliberately
+ * NOT known here: they are registry-schema facts enforced by schema-driven
+ * tooling, and a second hardcoded source of truth would drift.
+ */
+import type { PathedIssue } from "../errors.js";
+import { configurationMissing, fieldParts, type Path } from "../guards.js";
+import { shardingIndexedIssues } from "./sharding-indexed.js";
+import { transposeIssues } from "./transpose.js";
+
+export type { ShardingIndexedCodecConfiguration } from "./sharding-indexed.js";
+export type { TransposeCodecConfiguration } from "./transpose.js";
+
+/** The dimensional facts threaded between the codecs of one pipeline. */
+export interface PipelineContext {
+  /** Array dimensionality at this point; undefined when unknowable. */
+  dims: number | undefined;
+  /**
+   * Distinct chunk lengths per dimension this pipeline may encode — what a
+   * sharding codec's inner chunks must divide. A regular grid contributes
+   * one size per dimension; a rectilinear grid may contribute several.
+   */
+  chunkSizes: number[][] | undefined;
+}
+
+/** The spent/unknowable context. */
+export const DROPPED: PipelineContext = { dims: undefined, chunkSizes: undefined };
+
+/** Walk one codec pipeline, threading the dimensional context. */
+export function pipelineIssues(
+  pipeline: unknown[],
+  path: Path,
+  initialDims: number | undefined,
+  initialChunkSizes: number[][] | undefined,
+): PathedIssue[] {
+  const issues: PathedIssue[] = [];
+  let context: PipelineContext = { dims: initialDims, chunkSizes: initialChunkSizes };
+  pipeline.forEach((entry, index) => {
+    const parts = fieldParts(entry);
+    if (parts === undefined) {
+      context = DROPPED; // structurally invalid entry: no further reasoning
+      return;
+    }
+    const configMissing = configurationMissing(entry);
+    if (parts.name === "transpose") {
+      const result = transposeIssues(parts.configuration, configMissing, path, index, context);
+      issues.push(...result.issues);
+      context = result.context;
+    } else if (parts.name === "sharding_indexed") {
+      const result = shardingIndexedIssues(
+        parts.configuration,
+        configMissing,
+        path,
+        index,
+        context,
+        pipelineIssues,
+      );
+      issues.push(...result.issues);
+      context = result.context;
+    } else {
+      // A codec this package cannot reason about: stale array-level facts
+      // must not judge the codecs after it.
+      context = DROPPED;
+    }
+  });
+  return issues;
+}

package/src/codec/sharding-indexed.ts

@@ -0,0 +1,113 @@
+/** The core `sharding_indexed` codec: syntax and semantics. */
+import type { PathedIssue } from "../errors.js";
+import { isIntArray, type Path } from "../guards.js";
+import { DROPPED, type PipelineContext } from "./index.js";
+
+/** Configuration of the core `sharding_indexed` codec. */
+export interface ShardingIndexedCodecConfiguration {
+  chunk_shape: number[];
+  codecs: unknown[];
+  index_codecs: unknown[];
+  index_location?: "start" | "end";
+}
+
+type Walk = (
+  pipeline: unknown[],
+  path: Path,
+  dims: number | undefined,
+  chunkSizes: number[][] | undefined,
+) => PathedIssue[];
+
+/**
+ * Judge one sharding entry: it requires `chunk_shape`, `codecs`, and
+ * `index_codecs`; its chunk_shape must match the array's dimensionality
+ * and evenly divide every chunk it shards. The inner pipeline is walked
+ * with the shard's own chunk context (`index_codecs` encode the shard
+ * index, whose shape differs — no dimensional context applies there), and
+ * the array -> bytes boundary spends the context for whatever follows.
+ */
+export function shardingIndexedIssues(
+  configuration: Record<string, unknown> | undefined,
+  configMissing: boolean,
+  path: Path,
+  index: number,
+  context: PipelineContext,
+  walk: Walk,
+): { issues: PathedIssue[]; context: PipelineContext } {
+  const issues: PathedIssue[] = [];
+  if (configMissing) {
+    issues.push({
+      path: [...path, index],
+      message:
+        '"sharding_indexed" requires a configuration with "chunk_shape", "codecs", and "index_codecs"',
+      kind: "missing_key",
+    });
+    return { issues, context: DROPPED };
+  }
+  if (configuration !== undefined) {
+    for (const key of ["chunk_shape", "codecs", "index_codecs"]) {
+      if (!Object.hasOwn(configuration, key)) {
+        issues.push({
+          path: [...path, index, "configuration", key],
+          message: "missing required key",
+          kind: "missing_key",
+        });
+      }
+    }
+  }
+  const chunkShape = configuration?.["chunk_shape"];
+  if (!isIntArray(chunkShape)) {
+    // Still walk a present inner pipeline (entries deserve their own
+    // verdicts) before the context becomes unknowable.
+    const inner = configuration?.["codecs"];
+    if (Array.isArray(inner)) {
+      issues.push(
+        ...walk(inner, [...path, index, "configuration", "codecs"], undefined, undefined),
+      );
+    }
+    return { issues, context: DROPPED };
+  }
+  const chunkShapePath = [...path, index, "configuration", "chunk_shape"];
+  if (context.dims !== undefined && chunkShape.length !== context.dims) {
+    issues.push({
+      path: chunkShapePath,
+      message: `expected one length per array dimension (${context.dims})`,
+      kind: "invalid_value",
+    });
+  } else if (
+    context.chunkSizes !== undefined &&
+    chunkShape.length === context.chunkSizes.length &&
+    chunkShape.every((length) => length > 0)
+  ) {
+    let violation: { axis: number; size: number } | undefined;
+    context.chunkSizes.forEach((sizes, axis) => {
+      if (violation !== undefined) return;
+      const bad = sizes.find((size) => size % (chunkShape[axis] as number) !== 0);
+      if (bad !== undefined) violation = { axis, size: bad };
+    });
+    if (violation !== undefined) {
+      const { axis, size } = violation;
+      const sizesNow = context.chunkSizes;
+      const uniform = sizesNow.every((sizes) => sizes.length === 1);
+      issues.push({
+        path: chunkShapePath,
+        message: uniform
+          ? `expected ${JSON.stringify(chunkShape)} to evenly divide the outer chunk shape ${JSON.stringify(sizesNow.map((sizes) => sizes[0]))}`
+          : `expected ${JSON.stringify(chunkShape)} to evenly divide every chunk size of the grid (dimension ${axis} has chunk size ${size})`,
+        kind: "invalid_value",
+      });
+    }
+  }
+  const inner = configuration?.["codecs"];
+  if (Array.isArray(inner)) {
+    issues.push(
+      ...walk(
+        inner,
+        [...path, index, "configuration", "codecs"],
+        chunkShape.length,
+        chunkShape.map((length) => [length]),
+      ),
+    );
+  }
+  return { issues, context: DROPPED };
+}

package/src/codec/transpose.ts

@@ -0,0 +1,80 @@
+/** The core `transpose` codec: syntax and semantics. */
+import type { PathedIssue } from "../errors.js";
+import { isIntArray, type Path } from "../guards.js";
+import { DROPPED, type PipelineContext } from "./index.js";
+
+/** Configuration of the core `transpose` codec. */
+export interface TransposeCodecConfiguration {
+  order: number[];
+}
+
+function isPermutation(order: number[]): boolean {
+  const seen = new Set(order);
+  return seen.size === order.length && order.every((entry) => entry >= 0 && entry < order.length);
+}
+
+/**
+ * Judge one transpose entry: it requires a configuration with `order`,
+ * which must be a permutation with one entry per array dimension. A sound
+ * transpose permutes the context's chunk sizes; an unsound one makes the
+ * downstream context unknowable.
+ */
+export function transposeIssues(
+  configuration: Record<string, unknown> | undefined,
+  configMissing: boolean,
+  path: Path,
+  index: number,
+  context: PipelineContext,
+): { issues: PathedIssue[]; context: PipelineContext } {
+  const issues: PathedIssue[] = [];
+  if (configMissing) {
+    issues.push({
+      path: [...path, index],
+      message: '"transpose" requires a configuration with "order"',
+      kind: "missing_key",
+    });
+    return { issues, context: DROPPED };
+  }
+  if (configuration !== undefined && !Object.hasOwn(configuration, "order")) {
+    issues.push({
+      path: [...path, index, "configuration", "order"],
+      message: "missing required key",
+      kind: "missing_key",
+    });
+    return { issues, context: DROPPED };
+  }
+  const order = configuration?.["order"];
+  if (!isIntArray(order)) {
+    return { issues, context: DROPPED }; // shape errors are the schema layer's
+  }
+  const orderPath = [...path, index, "configuration", "order"];
+  let sound = true;
+  if (!isPermutation(order)) {
+    sound = false;
+    issues.push({
+      path: orderPath,
+      message: `expected a permutation of the integers 0..${order.length - 1}`,
+      kind: "invalid_value",
+    });
+  }
+  if (context.dims !== undefined && order.length !== context.dims) {
+    sound = false;
+    issues.push({
+      path: orderPath,
+      message: `expected one entry per array dimension (${context.dims})`,
+      kind: "invalid_value",
+    });
+  }
+  if (!sound) return { issues, context: DROPPED };
+  const sizes = context.chunkSizes;
+  return {
+    issues,
+    context: {
+      dims: context.dims,
+      chunkSizes:
+        sizes !== undefined && order.length === sizes.length
+          ? order.map((axis) => sizes[axis] as number[])
+          : undefined,
+    },
+  };
+}

package/src/data-type/bool.ts

@@ -0,0 +1,8 @@
+import { named, simple, type DataTypeDescriptor } from "./descriptor.js";
+
+/** The core `bool` data type. */
+export const bool: DataTypeDescriptor = {
+  matches: named("bool"),
+  fillIssues: (fill) =>
+    typeof fill === "boolean" ? [] : simple('expected a boolean fill value for data type "bool"'),
+};

package/src/data-type/bytes.ts

@@ -0,0 +1,26 @@
+import { isByteArray, named, simple, type DataTypeDescriptor } from "./descriptor.js";
+
+/**
+ * Fill value of the `bytes` data type: an array of integers in `[0, 255]`
+ * (one per byte) or a standard-alphabet base64 string.
+ */
+export type BytesFillValue = number[] | string;
+
+const BASE64 = /^[A-Za-z0-9+/]*={0,2}$/;
+
+/** Whether `value` is standard-alphabet base64 (padded length a multiple of 4). */
+export function isBase64(value: string): boolean {
+  return value.length % 4 === 0 && BASE64.test(value);
+}
+
+/** The zarr-extensions `bytes` data type (variable-length raw bytes). */
+export const bytes: DataTypeDescriptor = {
+  matches: named("bytes"),
+  fillIssues: (fill) => {
+    if (isByteArray(fill)) return [];
+    if (typeof fill === "string" && isBase64(fill)) return [];
+    return simple(
+      'expected an array of integers in [0, 255] or a base64 string for data type "bytes"',
+    );
+  },
+};

package/src/data-type/complex128.ts

@@ -0,0 +1,4 @@
+import { complexDataType } from "./descriptor.js";
+
+/** The core `complex128` data type (components are float64). */
+export const complex128 = complexDataType("complex128", 16);

package/src/data-type/complex64.ts

@@ -0,0 +1,4 @@
+import { complexDataType } from "./descriptor.js";
+
+/** The core `complex64` data type (components are float32). */
+export const complex64 = complexDataType("complex64", 8);

package/src/data-type/descriptor.ts

@@ -0,0 +1,115 @@
+/**
+ * The data type descriptor interface and the shared fill-value machinery
+ * the per-type modules build on. One module per supported data type;
+ * `index.ts` assembles them into the dispatch the semantic layer uses.
+ */
+import type { IssueKind, PathedIssue } from "../errors.js";
+
+/** Context handed to a descriptor's fill check. */
+export interface FillContext {
+  /** The data_type field's configuration, when present and an object. */
+  configuration: Record<string, unknown> | undefined;
+  /** Recursion depth (struct fields may nest structs). */
+  depth: number;
+  /**
+   * Recursive check for compound types: issues for `fill` judged against
+   * the data type named by `dataTypeField`, pathed relative to that fill.
+   */
+  fillIssuesFor(dataTypeField: unknown, fill: unknown, depth: number): PathedIssue[];
+}
+
+/** Everything the semantic layer knows about one data type. */
+export interface DataTypeDescriptor {
+  /** Whether this module owns the given `data_type` name. */
+  matches(name: string): boolean;
+  /** Required configuration members, when the type needs a configuration. */
+  requiredConfigKeys?: readonly string[];
+  /** Name-level validity beyond ownership (e.g. r<N>'s multiple-of-8 rule). */
+  nameIssue?(name: string): string | undefined;
+  /** Fill-value issues, pathed relative to the fill value itself. */
+  fillIssues(fill: unknown, name: string, context: FillContext): PathedIssue[];
+}
+
+export function issue(
+  path: ReadonlyArray<string | number>,
+  message: string,
+  kind: IssueKind = "invalid_value",
+): PathedIssue {
+  return { path, message, kind };
+}
+
+/** A single unpathed issue — the common case for scalar types. */
+export function simple(message: string): PathedIssue[] {
+  return [issue([], message)];
+}
+
+export function named(matchName: string): (name: string) => boolean {
+  return (name) => name === matchName;
+}
+
+// --- shared fill forms ------------------------------------------------------
+
+/** A float fill value: a JSON number, a non-finite sentinel, or a hex string. */
+export type FloatFillValue = number | "NaN" | "Infinity" | "-Infinity" | string;
+
+/** A complex fill value: `[real, imaginary]`, each a float fill form. */
+export type ComplexFillValue = [FloatFillValue, FloatFillValue];
+
+export function isFloatFill(value: unknown, hexDigits: number): boolean {
+  if (typeof value === "number") return true;
+  if (typeof value !== "string") return false;
+  if (value === "NaN" || value === "Infinity" || value === "-Infinity") return true;
+  return new RegExp(`^0x[0-9a-fA-F]{${hexDigits}}$`).test(value);
+}
+
+export function floatFillMessage(name: string, hexDigits: number): string {
+  return (
+    `expected a number, "NaN", "Infinity", "-Infinity", or a ` +
+    `${hexDigits}-hex-digit "0x..." string for data type ${JSON.stringify(name)}`
+  );
+}
+
+export function isByteArray(value: unknown): value is number[] {
+  return (
+    Array.isArray(value) &&
+    Object.keys(value).length === value.length &&
+    value.every((item) => Number.isInteger(item) && (item as number) >= 0 && (item as number) <= 255)
+  );
+}
+
+// --- per-family factories ---------------------------------------------------
+
+export function intDataType(name: string, low: number, high: number): DataTypeDescriptor {
+  return {
+    matches: named(name),
+    fillIssues: (fill) =>
+      Number.isInteger(fill) && (fill as number) >= low && (fill as number) <= high
+        ? []
+        : simple(`expected an integer in [${low}, ${high}] for data type ${JSON.stringify(name)}`),
+  };
+}
+
+export function floatDataType(name: string, hexDigits: number): DataTypeDescriptor {
+  return {
+    matches: named(name),
+    fillIssues: (fill) =>
+      isFloatFill(fill, hexDigits) ? [] : simple(floatFillMessage(name, hexDigits)),
+  };
+}
+
+export function complexDataType(name: string, componentHexDigits: number): DataTypeDescriptor {
+  return {
+    matches: named(name),
+    fillIssues: (fill) => {
+      const ok =
+        Array.isArray(fill) &&
+        fill.length === 2 &&
+        fill.every((part) => isFloatFill(part, componentHexDigits));
+      return ok
+        ? []
+        : simple(
+            `expected a two-element [real, imaginary] array for data type ${JSON.stringify(name)}`,
+          );
+    },
+  };
+}

package/src/data-type/float16.ts

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

package/src/data-type/float32.ts

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

package/src/data-type/float64.ts

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

package/src/data-type/index.ts

@@ -0,0 +1,129 @@
+/**
+ * The data types this package interprets, one module per type, assembled
+ * into the dispatch the semantic layer uses: the core scalars, the r<N>
+ * raw-bits family, and the established zarr-extensions conventions
+ * (string, bytes, numpy.datetime64/timedelta64, struct). Unrecognized
+ * names yield no verdicts — the name space is open — and other types'
+ * required fields remain registry-schema facts.
+ */
+import type { PathedIssue } from "../errors.js";
+import { configurationMissing, fieldParts } from "../guards.js";
+import { bool } from "./bool.js";
+import { bytes } from "./bytes.js";
+import { complex64 } from "./complex64.js";
+import { complex128 } from "./complex128.js";
+import { issue, type DataTypeDescriptor, type FillContext } from "./descriptor.js";
+import { float16 } from "./float16.js";
+import { float32 } from "./float32.js";
+import { float64 } from "./float64.js";
+import { int8 } from "./int8.js";
+import { int16 } from "./int16.js";
+import { int32 } from "./int32.js";
+import { int64 } from "./int64.js";
+import { numpyDatetime64 } from "./numpy-datetime64.js";
+import { numpyTimedelta64 } from "./numpy-timedelta64.js";
+import { raw } from "./raw.js";
+import { string } from "./string.js";
+import { struct } from "./struct.js";
+import { uint8 } from "./uint8.js";
+import { uint16 } from "./uint16.js";
+import { uint32 } from "./uint32.js";
+import { uint64 } from "./uint64.js";
+
+export type {
+  ComplexFillValue,
+  DataTypeDescriptor,
+  FillContext,
+  FloatFillValue,
+} from "./descriptor.js";
+export type { BytesFillValue } from "./bytes.js";
+export type {
+  NumpyDatetime64Configuration,
+  NumpyDatetime64FillValue,
+  NumpyTimeUnit,
+} from "./numpy-datetime64.js";
+export type { RawBytesFillValue } from "./raw.js";
+export type { StringFillValue } from "./string.js";
+export type { StructConfiguration, StructField } from "./struct.js";
+
+const DESCRIPTORS: readonly DataTypeDescriptor[] = [
+  bool,
+  int8, int16, int32, int64,
+  uint8, uint16, uint32, uint64,
+  float16, float32, float64,
+  complex64, complex128,
+  raw,
+  string, bytes,
+  numpyDatetime64, numpyTimedelta64,
+  struct,
+];
+
+function descriptorFor(name: string): DataTypeDescriptor | undefined {
+  return DESCRIPTORS.find((descriptor) => descriptor.matches(name));
+}
+
+// struct fields may nest structs; matches the structural layer's cap.
+const MAX_FILL_DEPTH = 64;
+
+function fillIssuesFor(dataTypeField: unknown, fill: unknown, depth: number): PathedIssue[] {
+  if (depth >= MAX_FILL_DEPTH) return [];
+  const parts = fieldParts(dataTypeField);
+  if (parts === undefined) return [];
+  const descriptor = descriptorFor(parts.name);
+  if (descriptor === undefined) return []; // unrecognized: no verdict
+  const context: FillContext = { configuration: parts.configuration, depth, fillIssuesFor };
+  return descriptor.fillIssues(fill, parts.name, context);
+}
+
+/**
+ * Interpret a document's `data_type` field against its `fill_value`:
+ * name-level rules, required configuration members, and the fill's JSON
+ * shape (recursively, for struct). Issues are pathed from the document
+ * root (`data_type` / `fill_value`).
+ */
+export function dataTypeVerdict(
+  rawField: unknown,
+  fillPresent: boolean,
+  fill: unknown,
+): PathedIssue[] {
+  const parts = fieldParts(rawField);
+  if (parts === undefined) return [];
+  const descriptor = descriptorFor(parts.name);
+  if (descriptor === undefined) return [];
+  const issues: PathedIssue[] = [];
+  const nameProblem = descriptor.nameIssue?.(parts.name);
+  if (nameProblem !== undefined) {
+    issues.push(issue(["data_type"], nameProblem));
+  }
+  const required = descriptor.requiredConfigKeys;
+  if (required !== undefined) {
+    if (configurationMissing(rawField)) {
+      issues.push(
+        issue(
+          ["data_type"],
+          `${JSON.stringify(parts.name)} requires a configuration with ${required
+            .map((key) => JSON.stringify(key))
+            .join(" and ")}`,
+          "missing_key",
+        ),
+      );
+    } else if (parts.configuration !== undefined) {
+      for (const key of required) {
+        if (!Object.hasOwn(parts.configuration, key)) {
+          issues.push(
+            issue(["data_type", "configuration", key], "missing required key", "missing_key"),
+          );
+        }
+      }
+    }
+  }
+  if (fillPresent) {
+    issues.push(
+      ...fillIssuesFor(rawField, fill, 0).map((inner) => ({
+        ...inner,
+        path: ["fill_value", ...inner.path],
+      })),
+    );
+  }
+  return issues;
+}

package/src/data-type/int16.ts

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

package/src/data-type/int32.ts

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

package/src/data-type/int64.ts

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

package/src/data-type/int8.ts

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

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

@@ -0,0 +1,33 @@
+import { named, simple, type DataTypeDescriptor } from "./descriptor.js";
+
+/** Time unit codes used by numpy.datetime64 / numpy.timedelta64. */
+export type NumpyTimeUnit =
+  | "Y" | "M" | "W" | "D" | "h" | "m" | "s"
+  | "ms" | "us" | "μs" | "ns" | "ps" | "fs" | "as" | "generic";
+
+/** Configuration of the numpy temporal data types. */
+export interface NumpyDatetime64Configuration {
+  unit: NumpyTimeUnit;
+  scale_factor: number;
+}
+
+/**
+ * Fill value of the numpy temporal data types: an integer count of
+ * `unit * scale_factor` since the epoch, or the `"NaT"` sentinel.
+ */
+export type NumpyDatetime64FillValue = number | "NaT";
+
+/** Descriptor factory shared by numpy.datetime64 and numpy.timedelta64. */
+export function numpyTemporalDataType(name: string): DataTypeDescriptor {
+  return {
+    matches: named(name),
+    requiredConfigKeys: ["unit", "scale_factor"],
+    fillIssues: (fill) =>
+      Number.isInteger(fill) || fill === "NaT"
+        ? []
+        : simple(`expected an integer or "NaT" for data type ${JSON.stringify(name)}`),
+  };
+}
+
+/** The zarr-extensions `numpy.datetime64` data type. */
+export const numpyDatetime64 = numpyTemporalDataType("numpy.datetime64");