Merge pull request #283 from keller-mark/keller-mark/zmetadata-key

Support a zmetadata key option for consolidated stores

Author: keller-mark

.changeset/sweet-beans-lick.md

@@ -0,0 +1,5 @@
+---
+"zarrita": patch
+---
+
+Add support for options.metadataKey in withConsolidated and tryWithConsolidated"

.github/workflows/ci.yml

@@ -27,6 +27,4 @@ jobs:
     steps:
       - uses: actions/checkout@v4
       - uses: biomejs/setup-biome@v2
-        with:
-          version: latest
       - run: biome ci .

biome.json

@@ -1,5 +1,5 @@
 {
-	"$schema": "https://biomejs.dev/schemas/1.7.3/schema.json",
+	"$schema": "https://biomejs.dev/schemas/1.9.4/schema.json",
 	"organizeImports": {
 		"enabled": true
 	},

package.json

@@ -4,7 +4,7 @@
 		"build": "tsc --build",
 		"clean": "pnpm --recursive exec rm -rf dist",
 		"test": "vitest --api",
-		"format": "format .",
+		"format": "biome format .",
 		"lint": "biome ci .",
 		"fix": "biome check --write .",
 		"publint": "pnpm --recursive --filter=\"./packages/**\" exec publint",

packages/zarrita/__tests__/consolidated.test.ts

@@ -123,6 +123,22 @@ describe("tryWithConsolidated", () => {
 		let store = await tryWithConsolidated(new FileSystemStore(root));
 		expect(store).toBeInstanceOf(FileSystemStore);
 	});
+
+	it("supports a zmetadataKey option", async () => {
+		let root = path.join(__dirname, "../../../fixtures/v2/data.zarr");
+		let store = await tryWithConsolidated(new FileSystemStore(root), {
+			metadataKey: ".zmetadata",
+		});
+		expect(store).toHaveProperty("contents");
+	});
+
+	it("falls back to original store if metadataKey is incorrect", async () => {
+		let root = path.join(__dirname, "../../../fixtures/v2/data.zarr");
+		let store = await tryWithConsolidated(new FileSystemStore(root), {
+			metadataKey: ".nonexistent",
+		});
+		expect(store).toBeInstanceOf(FileSystemStore);
+	});
 });
 
 describe("Listable.getRange", () => {

packages/zarrita/src/consolidated.ts

@@ -33,11 +33,13 @@ export interface Listable<Store extends Readable> {
 
 async function get_consolidated_metadata(
 	store: Readable,
+	metadataKeyOption: string | undefined,
 ): Promise<ConsolidatedMetadata> {
-	let bytes = await store.get("/.zmetadata");
+	const metadataKey = metadataKeyOption ?? ".zmetadata";
+	let bytes = await store.get(`/${metadataKey}`);
 	if (!bytes) {
 		throw new NodeNotFoundError("v2 consolidated metadata", {
-			cause: new KeyError("/.zmetadata"),
+			cause: new KeyError(`/${metadataKey}`),
 		});
 	}
 	let meta: ConsolidatedMetadata = json_decode_object(bytes);
@@ -68,13 +70,24 @@ function is_v3(meta: Metadata): meta is ArrayMetadata | GroupMetadata {
 	return "zarr_format" in meta && meta.zarr_format === 3;
 }
 
+/** Options for {@linkcode withConsolidated} and {@linkcode tryWithConsolidated}. */
+export interface WithConsolidatedOptions {
+	/**
+	 * Key to read consolidated metadata from.
+	 *
+	 * @default {".zmetadata"}
+	 */
+	readonly metadataKey?: string;
+}
+
 /**
  * Open a consolidated store.
  *
  * This will open a store with Zarr v2 consolidated metadata (`.zmetadata`).
  * @see {@link https://zarr.readthedocs.io/en/stable/spec/v2.html#consolidated-metadata}
  *
  * @param store The store to open.
+ * @param opts Options object.
  * @returns A listable store.
  *
  * @example
@@ -89,8 +102,9 @@ function is_v3(meta: Metadata): meta is ArrayMetadata | GroupMetadata {
  */
 export async function withConsolidated<Store extends Readable>(
 	store: Store,
+	opts: WithConsolidatedOptions = {},
 ): Promise<Listable<Store>> {
-	let v2_meta = await get_consolidated_metadata(store);
+	let v2_meta = await get_consolidated_metadata(store, opts.metadataKey);
 	let known_meta: Record<AbsolutePath, Metadata> = {};
 	for (let [key, value] of Object.entries(v2_meta.metadata)) {
 		known_meta[`/${key}`] = value;
@@ -142,12 +156,14 @@ export async function withConsolidated<Store extends Readable>(
  * additional network requests when accessing underlying groups and arrays.
  *
  * @param store The store to open.
+ * @param opts Options to pass to withConsolidated.
  * @returns A listable store.
  */
 export async function tryWithConsolidated<Store extends Readable>(
 	store: Store,
+	opts: WithConsolidatedOptions = {},
 ): Promise<Listable<Store> | Store> {
-	return withConsolidated(store).catch((error: unknown) => {
+	return withConsolidated(store, opts).catch((error: unknown) => {
 		rethrow_unless(error, NodeNotFoundError);
 		return store;
 	});