Simplify middleware API to direct-only form

The original middleware system supported a "dual" API where each middleware
could be called directly (withX(store, opts)) or curried (withX(opts)(store))
for use in createStore pipelines. The curried form couldn't properly infer
generic store options (e.g., RequestInit from FetchStore), leading to unknown
types in callbacks like mergeOptions.

This replaces the curried approach with a simpler pattern inspired by
fetch-extras: pipelines use arrow functions (s => withX(s, opts)) which
naturally give TypeScript the store type for full inference. The curried
overloads, _dual helper, and related disambiguation types are removed.

Also renames wrapStore → defineStoreMiddleware and createStore → storeFrom
for clarity, constrains factories to AsyncReadable (all middleware is async),
and adds Partial<AsyncReadable> return constraint for autocomplete in the
factory body.

Author: manzt

.changeset/middleware-store-wrappers.md

@@ -2,13 +2,13 @@
 "zarrita": minor
 ---
 
-Introduce composable store middleware via `wrapStore`
+Introduce composable store middleware via `defineStoreMiddleware`
 
 **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`.
+- `zarr.defineStoreMiddleware(factory)` — define a store middleware with automatic Proxy delegation. The factory receives an `AsyncReadable` store and options, returning overrides and extensions. Supports sync and async factories.
+- `zarr.defineStoreMiddleware.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.
+- `zarr.storeFrom(store, ...middleware)` — compose middleware in a pipeline. Each middleware is `(store) => newStore`. Returns `Promise` to support async middleware like `withConsolidation`.
 
 **Renamed:**
 
@@ -23,26 +23,22 @@ Introduce composable store middleware via `wrapStore`
 The previous exports are still available but deprecated. Update your imports:
 
 ```ts
-// Before
-import { withConsolidated, tryWithConsolidated, withRangeBatching } from "zarrita";
+import * as zarr from "zarrita";
 
-// After
-import { withConsolidation, withMaybeConsolidation, withRangeBatching } from "zarrita";
-
-// Pipeline composition
-let store = await createStore(
-  new FetchStore("https://..."),
-  withConsolidation({ format: "v3" }),
-  withRangeBatching(),
+// Pipeline composition (use arrow functions for full type inference)
+let store = await zarr.storeFrom(
+  new zarr.FetchStore("https://..."),
+  zarr.withConsolidation,
+  (s) => zarr.withRangeBatching(s, { mergeOptions: (batch) => batch[0] }),
 );
 ```
 
 **Defining custom middleware:**
 
 ```ts
-import { wrapStore } from "zarrita";
+import * as zarr from "zarrita";
 
-const withCaching = wrapStore(
+const withCaching = zarr.defineStoreMiddleware(
   (store, opts: { maxSize?: number }) => {
     let cache = new Map();
     return {
@@ -59,4 +55,4 @@ const withCaching = wrapStore(
 );
 ```
 
-`BatchedRangeStore` class has been removed in favor of `withRangeBatching` built on `wrapStore`.
+`BatchedRangeStore` class has been removed in favor of `withRangeBatching` built on `zarr.defineStoreMiddleware`.

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

@@ -2,18 +2,53 @@ 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";
+import { defineStoreMiddleware } from "../src/middleware/define.js";
 
-describe("createStore", () => {
+describe("storeFrom", () => {
 	test("no middleware returns store as-is", () => {
-		let store = zarr.createStore(new zarr.FetchStore(""));
+		let store = zarr.storeFrom(new zarr.FetchStore(""));
 		expectType(store).toMatchInlineSnapshot(`Promise<zarr.FetchStore>`);
 	});
+
+	test("direct form in pipeline infers store options", () => {
+		let store = zarr.storeFrom(new zarr.FetchStore(""), (s) =>
+			zarr.withRangeBatching(s, {
+				mergeOptions: (batch) => {
+					expectType(batch).toMatchInlineSnapshot(
+						`ReadonlyArray<RequestInit | undefined>`,
+					);
+					return batch[0];
+				},
+			}),
+		);
+		expectType(store).toMatchInlineSnapshot(`
+			Promise<
+				zarr.FetchStore & { stats: Readonly<zarr.RangeBatchingStats> }
+			>
+		`);
+	});
+
+	test("no-config middleware can be passed uncalled", () => {
+		function check() {
+			return zarr.storeFrom(
+				new zarr.FetchStore(""),
+				zarr.withConsolidation,
+				(s) => zarr.withRangeBatching(s, { mergeOptions: (batch) => batch[0] }),
+			);
+		}
+		expectType(check).toMatchInlineSnapshot(`
+			() => Promise<
+				zarr.FetchStore & {
+					contents: () => { path: AbsolutePath; kind: "array" | "group" }[];
+				} & { stats: Readonly<zarr.RangeBatchingStats> }
+			>
+		`);
+	});
 });
 
-describe("wrapStore", () => {
+describe("defineStoreMiddleware", () => {
 	test("simple: extensions appear, store methods preserved", () => {
-		let withCustom = wrapStore(
+		let withCustom = defineStoreMiddleware(
 			(store: AsyncReadable, _opts: { flag: boolean }) => {
 				return {
 					async get(key: AbsolutePath) {
@@ -37,7 +72,7 @@ describe("wrapStore", () => {
 			retries?: number;
 		}
 
-		let withThing = wrapStore(
+		let withThing = defineStoreMiddleware(
 			<O>(store: AsyncReadable<O>, opts: ThingOptions<O>) => {
 				return {
 					async get(key: AbsolutePath, options?: O) {
@@ -58,26 +93,30 @@ describe("wrapStore", () => {
 	});
 
 	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 withA = defineStoreMiddleware(
+			(store: AsyncReadable, _opts: { a: number }) => {
+				return {
+					async get(key: AbsolutePath) {
+						return store.get(key);
+					},
+					methodA(): number {
+						return 1;
+					},
+				};
+			},
+		);
+		let withB = defineStoreMiddleware(
+			(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 } & {

packages/zarrita/src/index.ts

@@ -41,9 +41,9 @@ export {
 	withMaybeConsolidation,
 	withMaybeConsolidation as tryWithConsolidated,
 } from "./middleware/consolidation.js";
-export { createStore } from "./middleware/create-store.js";
+export { createStore as storeFrom } from "./middleware/create-store.js";
 export type { GenericOptions } from "./middleware/define.js";
-export { wrapStore } from "./middleware/define.js";
+export { defineStoreMiddleware } from "./middleware/define.js";
 export type {
 	RangeBatchingOptions,
 	RangeBatchingStats,

packages/zarrita/src/middleware/consolidation.ts

@@ -1,4 +1,4 @@
-import type { AbsolutePath, Readable } from "@zarrita/storage";
+import type { AbsolutePath, AsyncReadable, Readable } from "@zarrita/storage";
 import { JsonDecodeError, KeyError, NodeNotFoundError } from "../errors.js";
 import type {
 	ArrayMetadata,
@@ -15,7 +15,7 @@ import {
 	jsonEncodeObject,
 	rethrowUnless,
 } from "../util.js";
-import { wrapStore } from "./define.js";
+import { defineStoreMiddleware } from "./define.js";
 
 type ConsolidatedMetadataV2 = {
 	metadata: Record<string, ArrayMetadataV2 | GroupMetadataV2>;
@@ -198,16 +198,16 @@ export type Listable<Store extends Readable> = Store & {
  * let store = await zarr.withConsolidation(rawStore, { format: "v3" });
  *
  * // In a pipeline
- * let store = await zarr.createStore(
+ * let store = await zarr.storeFrom(
  *   new zarr.FetchStore("https://..."),
- *   zarr.withConsolidation({ format: "v3" }),
+ *   (s) => zarr.withConsolidation(s, { format: "v3" }),
  * );
  *
  * store.contents(); // [{ path: "/", kind: "group" }, ...]
  * ```
  */
-export const withConsolidation = wrapStore(
-	async (store: Readable, opts: ConsolidationOptions = {}) => {
+export const withConsolidation = defineStoreMiddleware(
+	async (store, opts: ConsolidationOptions = {}) => {
 		let formats = resolveFormats(store, opts.format);
 		let lastError: unknown;
 		for (let format of formats) {
@@ -263,7 +263,7 @@ export const withConsolidation = wrapStore(
  * Like {@linkcode withConsolidation}, but falls back to the original store if
  * no consolidated metadata is found (instead of throwing).
  */
-export async function withMaybeConsolidation<Store extends Readable>(
+export async function withMaybeConsolidation<Store extends AsyncReadable>(
 	store: Store,
 	opts: ConsolidationOptions = {},
 ): Promise<Listable<Store> | Store> {

packages/zarrita/src/middleware/create-store.ts

@@ -1,29 +1,29 @@
-import type { Readable } from "@zarrita/storage";
+import type { AsyncReadable } from "@zarrita/storage";
 
-export function createStore<S extends Readable>(store: S): Promise<S>;
-export function createStore<S extends Readable, A>(
+export function createStore<S extends AsyncReadable>(store: S): Promise<S>;
+export function createStore<S extends AsyncReadable, A>(
 	store: S,
 	m1: (store: S) => A,
 ): Promise<Awaited<A>>;
-export function createStore<S extends Readable, A, B>(
+export function createStore<S extends AsyncReadable, A, B>(
 	store: S,
 	m1: (store: S) => A,
 	m2: (store: Awaited<A>) => B,
 ): Promise<Awaited<B>>;
-export function createStore<S extends Readable, A, B, C>(
+export function createStore<S extends AsyncReadable, A, B, C>(
 	store: S,
 	m1: (store: S) => A,
 	m2: (store: Awaited<A>) => B,
 	m3: (store: Awaited<B>) => C,
 ): Promise<Awaited<C>>;
-export function createStore<S extends Readable, A, B, C, D>(
+export function createStore<S extends AsyncReadable, A, B, C, D>(
 	store: S,
 	m1: (store: S) => A,
 	m2: (store: Awaited<A>) => B,
 	m3: (store: Awaited<B>) => C,
 	m4: (store: Awaited<C>) => D,
 ): Promise<Awaited<D>>;
-export function createStore<S extends Readable, A, B, C, D, E>(
+export function createStore<S extends AsyncReadable, A, B, C, D, E>(
 	store: S,
 	m1: (store: S) => A,
 	m2: (store: Awaited<A>) => B,
@@ -32,7 +32,7 @@ export function createStore<S extends Readable, A, B, C, D, E>(
 	m5: (store: Awaited<D>) => E,
 ): Promise<Awaited<E>>;
 export async function createStore(
-	store: Readable,
+	store: AsyncReadable,
 	...middlewares: ((store: unknown) => unknown)[]
 ): Promise<unknown> {
 	let result: unknown = store;