Edit release notes and docs (#408)

Author: manzt

.github/release-notes/v0.7.md

@@ -1,24 +1,20 @@
 # v0.7.0
 
 **zarrita** aims to be a delightful little library for working with Zarr in
-TypeScript. Since the v0.5 rewrite, real-world data and use cases have moved
-faster than the library, and our initial abstractions began forcing users to
-reach past the public API to get their work done
+TypeScript. Since the v0.5 rewrite, its abstractions had started forcing users
+past the public API to get real work done
 ([#349](https://github.com/manzt/zarrita.js/issues/349),
 [#310](https://github.com/manzt/zarrita.js/issues/310),
 [#325](https://github.com/manzt/zarrita.js/issues/325),
-[#352](https://github.com/manzt/zarrita.js/issues/352)). You filed issues. It
-took us some time to work out the right shape for the fixes. Thank you for your
-patience.
-
-**v0.7 focuses on extensibility and correctness.** **Extensibility**, because
-most real use cases weren't about writing new stores (you still can, and
-`FetchStore` covers the common case). They were about *layering behavior*
-over an existing store: caching, request batching, auth, virtual-format
-translation. People were already doing that through subclassing and
-hand-rolled proxies. v0.7 makes layering simple and enjoyable.
-**Correctness**, because the other gaps were places where the library
-silently got the wrong answer on real data.
+[#352](https://github.com/manzt/zarrita.js/issues/352)). v0.7 addresses that
+on two fronts: **extensibility** and **correctness**.
+
+Most real use cases weren't about writing new stores — they were about
+*layering behavior* over an existing store: caching, request batching, auth,
+virtual-format translation. People were doing that through subclassing and
+hand-rolled proxies. v0.7 makes layering a first-class operation. The other
+gaps were places where the library silently returned wrong answers on real
+data.
 
 > ⚠️ **Heads up**: v0.7 has one hard break (`zarr.create` options are now
 > camelCase) and one deprecation (`FetchStore`'s `overrides` option, in
@@ -27,26 +23,25 @@ silently got the wrong answer on real data.
 
 ## Extensions
 
-Before v0.7, zarrita had blessed extension points for custom codecs and custom
-stores (implementing `AsyncReadable` from scratch), but nothing for **layering
-behavior on an existing store**. Adding these kinds of features to a
-`FetchStore`, for example, meant subclassing it, wrapping it in a hand-rolled
-`Proxy`, or smuggling per-call state through the `AsyncReadable<Options>`
-generic. Intercepting at the *chunk* layer (instead of the byte layer) meant
-replacing `zarr.Array` with a bare `Proxy` entirely; there was no extension
-point there.
+Before v0.7, zarrita had extension points for custom codecs and custom stores
+(implementing `AsyncReadable` from scratch), but nothing for **layering
+behavior on an existing store**. Adding features to a `FetchStore` meant
+subclassing it, wrapping it in a hand-rolled `Proxy`, or smuggling per-call
+state through the `AsyncReadable<Options>` generic. Intercepting at the
+*chunk* layer meant replacing `zarr.Array` with a bare `Proxy` entirely;
+there was no extension point there at all.
 
-v0.7 introduces two symmetric extension points, one per layer:
+v0.7 introduces two extension points, one per layer:
 
-| Layer     | Intercepts                | Define                      | Compose            |
+| Layer     | Intercepts                | Primitive                   | Composer           |
 | --------- | ------------------------- | --------------------------- | ------------------ |
 | Transport | `store.get(key, range)`   | `zarr.defineStoreExtension` | `zarr.extendStore` |
 | Data      | `array.getChunk(coords)`  | `zarr.defineArrayExtension` | `zarr.extendArray` |
 
 Store extensions handle paths and bytes. Array extensions handle chunk
-coordinates. A factory receives the inner value and user options and returns an
-object of method overrides; everything else is delegated through a `Proxy`, so
-consumers never notice the wrapper. Compose extensions in a pipeline:
+coordinates. A factory receives the inner value and user options and returns
+method overrides; everything else is delegated through a `Proxy`. Compose
+extensions in a pipeline:
 
 ```ts
 let store = await zarr.extendStore(
@@ -59,22 +54,20 @@ let store = await zarr.extendStore(
 let arr = await zarr.open(store, { kind: "array" });
 ```
 
-Three store extensions ship in the box, built on the new primitive rather
-than bolted alongside it:
+Three store extensions ship built on the new primitive:
 
 - **`zarr.withConsolidatedMetadata`**: short-circuits metadata reads from a
-  pre-fetched consolidated blob. Now reads v3 `consolidated_metadata`
-  from the root `zarr.json`, matching zarr-python. A `format` option
-  picks v2, v3, or a fallback order; auto-detects by default. *v3
-  consolidated metadata is not yet part of the official spec; treat
-  it as experimental.*
-- **`zarr.withRangeCoalescing`**: microtask-tick range batcher. Concurrent
-  `getRange` calls within a microtask are grouped by path, coalesced
-  across a byte-gap threshold, and issued as a single request per group.
-  Big win for many-small-chunk workloads.
+  pre-fetched consolidated blob. Now reads v3 `consolidated_metadata` from
+  the root `zarr.json`, matching zarr-python. A `format` option picks v2,
+  v3, or a fallback order; auto-detects by default. *v3 consolidated
+  metadata is not yet part of the official spec; treat it as experimental.*
+- **`zarr.withRangeCoalescing`**: groups concurrent `getRange` calls on the
+  same path within a microtask, merges adjacent ranges under a byte-gap
+  threshold, and issues one request per group. Cuts HTTP round-trips for
+  many-small-chunk reads.
 - **`zarr.withByteCaching`**: byte cache over `get` and `getRange`, with an
-  optional `keyFor` for cache-policy narrowing. The cache container is
-  any object implementing `has`/`get`/`set`; a plain `Map` is the default.
+  optional `keyFor` for narrowing the policy. The cache container is any
+  object implementing `has`/`get`/`set`; a plain `Map` is the default.
 
 ### Virtual-format adapters
 
@@ -129,21 +122,25 @@ cover every failure mode reachable from `zarr.open`, `zarr.get`, and
 | `InvalidSelectionError` | bad rank, out-of-bounds, zero step, dimension-name mismatch, scalar-shape mismatch                        |                               |
 | `UnsupportedError`      | capability limit (sharded set, unimplemented codec encode paths, missing `DataView.prototype.getFloat16`) |                               |
 
+`zarr.isZarritaError` is variadic and narrows to the matching union. No
+tags matches any zarrita error; one or more tags narrows to just those:
+
 ```ts
 try {
   await zarr.open(store, { kind: "array" });
-} catch (e) {
-  if (zarr.isZarritaError(e, "NotFoundError")) {
-    // e.path, e.found available
-  } else if (zarr.isZarritaError(e, "UnknownCodecError")) {
-    // e.codec is the unregistered codec name; register and retry
+} catch (err) {
+  if (zarr.isZarritaError(err, "NotFoundError")) {
+    err; // NotFoundError; err.path, err.found available
+  } else if (zarr.isZarritaError(err, "UnknownCodecError", "CodecPipelineError")) {
+    err; // UnknownCodecError | CodecPipelineError
+  } else if (zarr.isZarritaError(err)) {
+    err; // AnyZarritaError (catch-all for the hierarchy)
   }
 }
 ```
 
-Classes are exported, but the docs steer callers toward `zarr.isZarritaError`
-so `instanceof` checks aren't load-bearing. The class hierarchy can change
-later without breaking tag-based call sites.
+Prefer `zarr.isZarritaError` over `instanceof` so class-hierarchy changes
+stay non-breaking.
 
 ### Quantized data: `cast_value`, `scale_offset`, `fixedscaleoffset`
 
@@ -161,12 +158,12 @@ though the bytes on disk are quantized.
 
 ### Fill values, scalars, and browser autodetect
 
-`NaN`, `Infinity`, and `-Infinity` now round-trip correctly as fill values per
-the Zarr v3 spec (previously they silently serialized as `null`, and missing
-chunks filled with `0`). `get` and `set` work for scalar arrays (`shape=[]`).
-`zarr.open`'s version autodetection no longer fails in browsers when a server
-returns a non-JSON response for a v2 metadata key. Each was a
-silent-wrong-answer bug on real data. Not anymore.
+`NaN`, `Infinity`, and `-Infinity` now round-trip correctly as fill values
+per the Zarr v3 spec (previously they silently serialized as `null`, and
+missing chunks filled with `0`). `get` and `set` work for scalar arrays
+(`shape=[]`). `zarr.open`'s version autodetection no longer fails in
+browsers when a server returns a non-JSON response for a v2 metadata key.
+Each was a silent-wrong-answer bug on real data.
 
 ## Ergonomics
 
@@ -206,9 +203,9 @@ const controller = new AbortController();
 await zarr.get(arr, null, { signal: controller.signal });
 ```
 
-Removing the `Options` generic on `AsyncReadable` (the same change that
-unblocked array extensions) let `signal` become a plain field on `GetOptions`
-instead of opaque per-call state threaded through the store.
+Dropping the `Options` generic on `AsyncReadable` (the same change that
+unblocked array extensions) let `signal` become a plain field on
+`GetOptions` instead of opaque per-call state.
 
 ### Named-dimension selection
 
@@ -259,6 +256,5 @@ Thank you to everyone who contributed to v0.7:
 [@kylebarron](https://github.com/kylebarron),
 [@thewtex](https://github.com/thewtex),
 and [@Wietze](https://github.com/Wietze).
-A special thanks to the downstream maintainers (at vole-core, vizarr,
-and the growing collection of virtual-zarr adapters) whose real
-workloads shaped the extension API long before it existed as code.
+Thanks also to downstream maintainers at vole-core, vizarr, and the
+virtual-zarr adapters, whose workloads shaped the extension API.

docs/cookbook.md

@@ -94,15 +94,15 @@ Consolidated metadata stores the entire hierarchy's metadata in a single
 location, avoiding per-node network requests. This is particularly useful
 with remote stores where each metadata fetch incurs latency.
 
-The `withConsolidated` helper wraps an existing [store](/packages/storage),
-proxying metadata requests with the consolidated metadata, thereby minimizing
-network requests. It supports both Zarr v2 (`.zmetadata`) and v3
-(`consolidated_metadata` in root `zarr.json`).
+The `withConsolidatedMetadata` extension wraps an existing
+[store](/packages/storage), short-circuiting metadata requests from the
+consolidated blob instead of going to the network. It supports both Zarr
+v2 (`.zmetadata`) and v3 (`consolidated_metadata` in root `zarr.json`).
 
 ```js{3}
 import * as zarr from "zarrita";
 
-let store = await zarr.withConsolidated(
+let store = await zarr.withConsolidatedMetadata(
 	new zarr.FetchStore("https://localhost:8080/data.zarr")
 );
 
@@ -111,7 +111,7 @@ let root = await zarr.open(store, { kind: "group" });
 let foo = await zarr.open(root.resolve("foo"), { kind: "array" });
 ```
 
-The store returned from `withConsolidated` is **readonly** and adds
+The store returned from `withConsolidatedMetadata` is **readonly** and adds
 `.contents()` to list the known contents of the hierarchy:
 
 ```js
@@ -123,23 +123,23 @@ format with the `format` option, or provide an array to try formats in order:
 
 ```js
 // v2 only
-let store = await zarr.withConsolidated(rawStore, { format: "v2" });
+let store = await zarr.withConsolidatedMetadata(rawStore, { format: "v2" });
 
 // v3 only
-let store = await zarr.withConsolidated(rawStore, { format: "v3" });
+let store = await zarr.withConsolidatedMetadata(rawStore, { format: "v3" });
 
 // try v3 first, fall back to v2
-let store = await zarr.withConsolidated(rawStore, { format: ["v3", "v2"] });
+let store = await zarr.withConsolidatedMetadata(rawStore, { format: ["v3", "v2"] });
 ```
 
 ::: tip
 
-The `withConsolidated` helper errors out if consolidated metadata is absent.
-Use `tryWithConsolidated` for uncertain cases; it leverages consolidated
-metadata if available.
+`withConsolidatedMetadata` throws if consolidated metadata is absent. Use
+`withMaybeConsolidatedMetadata` when you don't know up front; it uses
+consolidated metadata if available, and otherwise passes through.
 
 ```js
-let store = await zarr.tryWithConsolidated(
+let store = await zarr.withMaybeConsolidatedMetadata(
 	new zarr.FetchStore("https://localhost:8080/data.zarr"),
 );
 ```
@@ -156,48 +156,51 @@ for the ongoing spec discussion.
 :::
 
 
-## Batch and Cache Range Requests
+## Coalesce and Cache Range Requests
 
 When reading chunked data over HTTP, many small range requests can be
-expensive due to per-request latency. The `withRangeBatching` helper wraps a
-store so that concurrent `getRange()` calls within the same microtask tick are
-automatically merged into fewer, larger fetches. Results are cached in an LRU
-cache (assumes immutable data).
+expensive due to per-request latency. zarrita ships two composable store
+extensions for this: `withRangeCoalescing` merges concurrent range reads
+into fewer fetches, and `withByteCaching` caches the results. Either works
+on its own; together they give you batched-and-cached reads.
 
-```js{3-5}
+```js
 import * as zarr from "zarrita";
 
-let store = zarr.withRangeBatching(
+let store = await zarr.extendStore(
   new zarr.FetchStore("https://localhost:8080/data.zarr"),
+  (s) => zarr.withRangeCoalescing(s),
+  (s) => zarr.withByteCaching(s),
 );
 
 let arr = await zarr.open(store, { kind: "array" });
 ```
 
-Adjacent byte ranges separated by less than `coalesceSize` bytes (default
-32 KB) are coalesced into a single request. You can tune this along with the
-LRU cache capacity:
+`withRangeCoalescing` groups concurrent `getRange()` calls on the same path
+within a microtask tick, merges adjacent byte ranges separated by less than
+`coalesceSize` bytes (default 32 KB), and issues one fetch per group. When
+multiple callers each pass their own `AbortSignal` and their requests land
+in the same group, the signals are merged so the shared fetch aborts as
+soon as any caller aborts.
 
 ```js
-let store = zarr.withRangeBatching(
+let store = zarr.withRangeCoalescing(
   new zarr.FetchStore("https://localhost:8080/data.zarr"),
   {
-    coalesceSize: 65536, // merge ranges within 64 KB of each other
-    cacheSize: 512,      // keep up to 512 entries in the LRU cache
+    coalesceSize: 65_536, // merge ranges within 64 KB of each other
+    onFlush(report) {
+      // { path, groupCount, requestCount, bytesFetched }
+      console.log(report);
+    },
   },
 );
 ```
 
-When multiple callers each pass their own `AbortSignal` and their requests
-land in the same batch, the signals are merged via `AbortSignal.any`: the
-shared request aborts as soon as any one caller aborts.
-
-You can inspect batching statistics via `store.stats`:
-
-```js
-store.stats;
-// { hits: 12, misses: 4, batchedRequests: 16, mergedRequests: 4 }
-```
+`withByteCaching` is policy-agnostic: by default it caches every `get()`
+and `getRange()` response in an unbounded `Map`, but you can pass any
+`ByteCache`-compatible container (for example, an LRU) or a `keyFor`
+function to narrow the policy. See the
+[store extensions reference](./store-extensions.md) for the full API.
 
 
 ## Read Data with SharedArrayBuffer <Badge type="tip" text="v2 & v3" />