Add composable store middleware system

Stores in zarrita can now be wrapped with composable middleware using
`wrapStore`. Each middleware intercepts store methods via Proxy and can
add new methods, with automatic delegation for anything not overridden.
Middleware supports a dual API — direct `withX(store, opts)` and curried
`withX(opts)` for use with the new `createStore` pipeline.

For middleware whose options depend on the store's request options type
(e.g., `mergeOptions` in range batching), `wrapStore.generic` uses a
higher-kinded type encoding via the `GenericOptions` interface to flow
the store's `O` type through to the options at the call site.

`withConsolidated` and `tryWithConsolidated` are renamed to
`withConsolidation` and `withMaybeConsolidation` for consistency. The old
names are re-exported with `@deprecated` JSDoc. `BatchedRangeStore` class
is replaced by `withRangeBatching` built on `wrapStore.generic`.

```ts
let store = await createStore(
  new FetchStore("https://..."),
  withConsolidation({ format: "v3" }),
  withRangeBatching(),
);

store.contents(); // from consolidation
store.stats;      // from batching
```

Author: manzt

.changeset/middleware-store-wrappers.md

@@ -0,0 +1,62 @@
+---
+"zarrita": minor
+---
+
+Introduce composable store middleware via `wrapStore`
+
+**New APIs:**
+
+- `wrapStore(factory)` — define a store middleware with dual API (direct + curried) and automatic Proxy delegation. Supports sync and async factories.
+- `wrapStore.generic<OptsLambda>()(factory)` — for middleware whose options depend on the store's request options type (e.g., `mergeOptions`). Uses `GenericOptions` interface for higher-kinded type encoding.
+- `createStore(store, ...middleware)` — compose middleware in a pipeline. Returns `Promise` to support async middleware like `withConsolidation`.
+
+**Renamed:**
+
+- `withConsolidated` → `withConsolidation`
+- `tryWithConsolidated` → `withMaybeConsolidation`
+- `WithConsolidatedOptions` → `ConsolidationOptions`
+- `BatchedRangeStoreOptions` → `RangeBatchingOptions`
+- `Stats` → `RangeBatchingStats`
+
+**Migration:**
+
+The previous exports are still available but deprecated. Update your imports:
+
+```ts
+// Before
+import { withConsolidated, tryWithConsolidated, withRangeBatching } from "zarrita";
+
+// After
+import { withConsolidation, withMaybeConsolidation, withRangeBatching } from "zarrita";
+
+// Pipeline composition
+let store = await createStore(
+  new FetchStore("https://..."),
+  withConsolidation({ format: "v3" }),
+  withRangeBatching(),
+);
+```
+
+**Defining custom middleware:**
+
+```ts
+import { wrapStore } from "zarrita";
+
+const withCaching = wrapStore(
+  (store, opts: { maxSize?: number }) => {
+    let cache = new Map();
+    return {
+      async get(key, options) {
+        let hit = cache.get(key);
+        if (hit) return hit;
+        let result = await store.get(key, options);
+        if (result) cache.set(key, result);
+        return result;
+      },
+      clear() { cache.clear(); },
+    };
+  },
+);
+```
+
+`BatchedRangeStore` class has been removed in favor of `withRangeBatching` built on `wrapStore`.

packages/zarrita/__tests__/batched-fetch.test.ts

@@ -1,6 +1,6 @@
 import type { AbsolutePath, RangeQuery } from "@zarrita/storage";
 import { describe, expect, it, vi } from "vitest";
-import { withRangeBatching } from "../src/batched-fetch.js";
+import { withRangeBatching } from "../src/middleware/batched-fetch.js";
 
 /**
  * Create a fake store with controllable getRange.

packages/zarrita/__tests__/consolidated.test.ts

@@ -2,17 +2,20 @@ import * as path from "node:path";
 import * as url from "node:url";
 import { FileSystemStore } from "@zarrita/storage";
 import { assert, describe, expect, it } from "vitest";
-import { tryWithConsolidated, withConsolidated } from "../src/consolidated.js";
 import { NodeNotFoundError } from "../src/errors.js";
 import { Array as ZarrArray } from "../src/hierarchy.js";
+import {
+	withConsolidation,
+	withMaybeConsolidation,
+} from "../src/middleware/consolidated.js";
 import { open } from "../src/open.js";
 
 let __dirname = path.dirname(url.fileURLToPath(import.meta.url));
 
-describe("withConsolidated", () => {
+describe("withConsolidation", () => {
 	it("loads consolidated metadata", async () => {
 		let root = path.join(__dirname, "../../../fixtures/v2/data.zarr");
-		let store = await withConsolidated(new FileSystemStore(root));
+		let store = await withConsolidation(new FileSystemStore(root));
 		let map = new Map(store.contents().map((x) => [x.path, x.kind]));
 		expect(map).toMatchInlineSnapshot(`
 			Map {
@@ -50,7 +53,7 @@ describe("withConsolidated", () => {
 
 	it("loads chunk data from underlying store", async () => {
 		let root = path.join(__dirname, "../../../fixtures/v2/data.zarr");
-		let store = await withConsolidated(new FileSystemStore(root));
+		let store = await withConsolidation(new FileSystemStore(root));
 		// biome-ignore lint/style/noNonNullAssertion: Fine for a test
 		let entry = store
 			.contents()
@@ -88,7 +91,7 @@ describe("withConsolidated", () => {
 
 	it("loads and navigates from root", async () => {
 		let path_root = path.join(__dirname, "../../../fixtures/v2/data.zarr");
-		let store = await withConsolidated(new FileSystemStore(path_root));
+		let store = await withConsolidation(new FileSystemStore(path_root));
 		let grp = await open(store, { kind: "group" });
 		expect(grp.kind).toBe("group");
 		let arr = await open(grp.resolve("1d.chunked.i2"), { kind: "array" });
@@ -101,22 +104,22 @@ describe("withConsolidated", () => {
 			"../../../fixtures/v2/data.zarr/3d.contiguous.i2",
 		);
 		let try_open = () =>
-			withConsolidated(new FileSystemStore(root), { format: "v2" });
+			withConsolidation(new FileSystemStore(root), { format: "v2" });
 		await expect(try_open).rejects.toThrowError(NodeNotFoundError);
 		await expect(try_open).rejects.toThrowErrorMatchingInlineSnapshot(
 			"[NodeNotFoundError: Node not found: v2 consolidated metadata]",
 		);
 	});
 });
 
-describe("withConsolidated (v3)", () => {
+describe("withConsolidation (v3)", () => {
 	let v3root = path.join(
 		__dirname,
 		"../../../fixtures/v3/data.zarr/consolidated",
 	);
 
 	it("loads v3 consolidated metadata", async () => {
-		let store = await withConsolidated(new FileSystemStore(v3root), {
+		let store = await withConsolidation(new FileSystemStore(v3root), {
 			format: "v3",
 		});
 		let map = new Map(store.contents().map((x) => [x.path, x.kind]));
@@ -132,7 +135,7 @@ describe("withConsolidated (v3)", () => {
 	});
 
 	it("loads chunk data from underlying store", async () => {
-		let store = await withConsolidated(new FileSystemStore(v3root), {
+		let store = await withConsolidation(new FileSystemStore(v3root), {
 			format: "v3",
 		});
 		let grp = await open(store, { kind: "group" });
@@ -155,7 +158,7 @@ describe("withConsolidated (v3)", () => {
 	});
 
 	it("loads and navigates from root", async () => {
-		let store = await withConsolidated(new FileSystemStore(v3root), {
+		let store = await withConsolidation(new FileSystemStore(v3root), {
 			format: "v3",
 		});
 		let grp = await open(store, { kind: "group" });
@@ -168,18 +171,18 @@ describe("withConsolidated (v3)", () => {
 	it("throws if v3 consolidated metadata is missing", async () => {
 		let root = path.join(__dirname, "../../../fixtures/v2/data.zarr");
 		let try_open = () =>
-			withConsolidated(new FileSystemStore(root), { format: "v3" });
+			withConsolidation(new FileSystemStore(root), { format: "v3" });
 		await expect(try_open).rejects.toThrowError(NodeNotFoundError);
 	});
 });
 
-describe("withConsolidated (format array)", () => {
+describe("withConsolidation (format array)", () => {
 	it("tries formats in order", async () => {
 		let root = path.join(
 			__dirname,
 			"../../../fixtures/v3/data.zarr/consolidated",
 		);
-		let store = await withConsolidated(new FileSystemStore(root), {
+		let store = await withConsolidation(new FileSystemStore(root), {
 			format: ["v3", "v2"],
 		});
 		let contents = store.contents();
@@ -190,18 +193,18 @@ describe("withConsolidated (format array)", () => {
 
 	it("falls back to second format", async () => {
 		let root = path.join(__dirname, "../../../fixtures/v2/data.zarr");
-		let store = await withConsolidated(new FileSystemStore(root), {
+		let store = await withConsolidation(new FileSystemStore(root), {
 			format: ["v3", "v2"],
 		});
 		let contents = store.contents();
 		expect(contents.length).toBeGreaterThan(0);
 	});
 });
 
-describe("tryWithConsolidated", () => {
+describe("withMaybeConsolidation", () => {
 	it("creates Listable from consolidated store", async () => {
 		let root = path.join(__dirname, "../../../fixtures/v2/data.zarr");
-		let store = await tryWithConsolidated(new FileSystemStore(root));
+		let store = await withMaybeConsolidation(new FileSystemStore(root));
 		expect(store).toHaveProperty("contents");
 	});
 
@@ -210,21 +213,21 @@ describe("tryWithConsolidated", () => {
 			__dirname,
 			"../../../fixtures/v2/data.zarr/3d.contiguous.i2",
 		);
-		let store = await tryWithConsolidated(new FileSystemStore(root));
+		let store = await withMaybeConsolidation(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), {
+		let store = await withMaybeConsolidation(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), {
+		let store = await withMaybeConsolidation(new FileSystemStore(root), {
 			metadataKey: ".nonexistent",
 		});
 		expect(store).toBeInstanceOf(FileSystemStore);
@@ -233,12 +236,12 @@ describe("tryWithConsolidated", () => {
 
 describe("Listable.getRange", () => {
 	it("does not expose getRange if the underlying store does not support it", async () => {
-		let store = await tryWithConsolidated(new Map());
+		let store = await withMaybeConsolidation(new Map());
 		expect("getRange" in store).toBeFalsy();
 	});
 	it("retrieves a byte range from an underlying store", async () => {
 		let root = path.join(__dirname, "../../../fixtures/v2/data.zarr");
-		let store = await tryWithConsolidated(new FileSystemStore(root));
+		let store = await withMaybeConsolidation(new FileSystemStore(root));
 		assert(typeof store.getRange === "function");
 	});
 });

packages/zarrita/__tests__/middleware-types.test.ts

@@ -0,0 +1,92 @@
+import type { AbsolutePath, AsyncReadable } from "@zarrita/storage";
+import { expectType } from "tintype";
+import { describe, test } from "vitest";
+import * as zarr from "../src/index.js";
+import { wrapStore } from "../src/middleware/define.js";
+
+describe("createStore", () => {
+	test("no middleware returns store as-is", () => {
+		let store = zarr.createStore(new zarr.FetchStore(""));
+		expectType(store).toMatchInlineSnapshot(`Promise<zarr.FetchStore>`);
+	});
+});
+
+describe("wrapStore", () => {
+	test("simple: extensions appear, store methods preserved", () => {
+		let withCustom = wrapStore(
+			(store: AsyncReadable, _opts: { flag: boolean }) => {
+				return {
+					async get(key: AbsolutePath) {
+						return store.get(key);
+					},
+					hello(): string {
+						return "world";
+					},
+				};
+			},
+		);
+		let store = withCustom(new zarr.FetchStore(""), { flag: true });
+		expectType(store).toMatchInlineSnapshot(
+			`zarr.FetchStore & { hello: () => string }`,
+		);
+	});
+
+	test("generic: store Options flows into opts parameter", () => {
+		interface ThingOptions<O> {
+			storeOptions?: O;
+			retries?: number;
+		}
+
+		let withThing = wrapStore(
+			<O>(store: AsyncReadable<O>, opts: ThingOptions<O>) => {
+				return {
+					async get(key: AbsolutePath, options?: O) {
+						return store.get(key, options ?? opts.storeOptions);
+					},
+					retries: opts.retries ?? 3,
+				};
+			},
+		);
+
+		let store = withThing(new zarr.FetchStore(""), {
+			storeOptions: { signal: AbortSignal.timeout(1000) },
+			retries: 5,
+		});
+		expectType(store).toMatchInlineSnapshot(
+			`zarr.FetchStore & { retries: number }`,
+		);
+	});
+
+	test("chaining preserves Options through wrappers", () => {
+		let withA = wrapStore(
+			(store: AsyncReadable, _opts: { a: number }) => {
+				return {
+					async get(key: AbsolutePath) {
+						return store.get(key);
+					},
+					methodA(): number {
+						return 1;
+					},
+				};
+			},
+		);
+		let withB = wrapStore(
+			(store: AsyncReadable, _opts: { b: string }) => {
+				return {
+					async get(key: AbsolutePath) {
+						return store.get(key);
+					},
+					methodB(): string {
+						return "hello";
+					},
+				};
+			},
+		);
+		let store = withB(withA(new zarr.FetchStore(""), { a: 1 }), { b: "x" });
+		expectType(store).toMatchInlineSnapshot(`
+			zarr.FetchStore & { methodA: () => number } & {
+				methodB: () => string;
+			}
+		`);
+	});
+});