Document zarrita entry and open module in JSDoc (#405)

* Decompose withRangeBatching into withRangeCoalescing + withCaching

Drop withRangeBatching entirely. Split it into two primitives:

  - withRangeCoalescing: microtask-tick batcher with no cache state.
    Emits onFlush callbacks with immutable FlushReport objects for
    observability instead of a top-level .stats getter.
  - withCaching: byte cache keyed by a user-supplied CacheKey policy
    function. Returns undefined to skip caching, a string to store
    under. Ships cacheKeys.getsOnly (default), getsAndRanges, and
    getsAndShardIndices as built-in policies.

Add a minimal ByteCache interface (has / get / set). Plain Map
satisfies it and is the default when no cache option is supplied;
users who want bounded eviction can drop in any ByteCache-compatible
container.

All APIs were unreleased, so no deprecation shims.

* Document zarrita entry and open module in JSDoc

Adopt Deno std library's JSDoc conventions on the zarrita public API,
starting with the package entry point and the `open` module. The goal is
hover-driven discoverability in editors: a user landing on `zarr.open`
in VS Code should see a summary, a runnable example, and links to
related symbols without leaving the tooltip.

Both files gain `@module` blocks with a short pitch and an end-to-end
example lifted from the cookbook. `open`, `open.v2`, and `open.v3` get
full JSDoc with `@example Usage` blocks, `@param`/`@returns`, `@throws`
for the two errors the fallback path actually surfaces, and `@category
Read` so future TypeDoc output can group symbols. Symbol references use
`{@linkcode}` to render monospace in hovers; URL references stay on
`{@link}`.

Overload signatures each carry a short doc stub with `@category` rather
than a single doc on the implementation. VS Code resolves hovers
per-matched overload, so a stub on each one is the cheapest way to keep
all three call forms documented without duplicating the full block three
times.

This is the first of several passes — remaining core modules (`create`,
`hierarchy`, indexing, extensions, errors, codecs, typedarray) and the
`@zarrita/storage` entry files will follow the same conventions in later
commits.

Author: manzt

packages/zarrita/src/index.ts

@@ -1,3 +1,29 @@
+/**
+ * A minimal, modular Zarr implementation for JavaScript.
+ *
+ * Zarrita reads and writes chunked, n-dimensional arrays backed by pluggable
+ * stores (HTTP, filesystem, in-memory, ...) and supports both Zarr v2 and v3
+ * on-disk formats. The API is deliberately small: open an {@linkcode Array}
+ * or {@linkcode Group} from a store, then read or write chunks with
+ * {@linkcode get} and {@linkcode set}.
+ *
+ * ```ts
+ * import * as zarr from "zarrita";
+ *
+ * const store = new zarr.FetchStore("https://example.com/data.zarr");
+ * const arr = await zarr.open(store, { kind: "array" });
+ *
+ * // Read a 2D sub-region into an ndarray-like view.
+ * const region = await zarr.get(arr, [zarr.slice(0, 10), null]);
+ * console.log(region.shape, region.data);
+ * ```
+ *
+ * See the {@link https://manzt.github.io/zarrita.js/ | cookbook} for more
+ * recipes (creation, consolidated metadata, store extensions, slicing).
+ *
+ * @module
+ */
+
 // re-export all the storage interface types
 export type * from "@zarrita/storage";
 // re-export fetch store from storage

packages/zarrita/src/open.ts

@@ -1,3 +1,25 @@
+/**
+ * Open Zarr arrays and groups from a {@link Readable} store.
+ *
+ * The main entry point is {@linkcode open}, which auto-detects whether the
+ * target node is a Zarr v2 or v3 array/group. Use {@linkcode open.v2} or
+ * {@linkcode open.v3} to pin a specific format.
+ *
+ * ```ts
+ * import * as zarr from "zarrita";
+ *
+ * const store = new zarr.FetchStore("https://example.com/data.zarr");
+ *
+ * // Auto-detect version and node kind.
+ * const node = await zarr.open(store);
+ *
+ * // Or narrow to an array (throws NotFoundError if it's a group).
+ * const arr = await zarr.open(store, { kind: "array" });
+ * ```
+ *
+ * @module
+ */
+
 import type { Readable } from "@zarrita/storage";
 import { InvalidMetadataError, NotFoundError } from "./errors.js";
 import type { ArrayExtension } from "./extension/define-array.js";
@@ -208,16 +230,59 @@ type OpenOptions = {
 	signal?: AbortSignal;
 };
 
+/**
+ * Open a Zarr array or group, auto-detecting the on-disk format version.
+ *
+ * Tries Zarr v3 and v2 in the order most likely to succeed for the given
+ * store (based on previous opens), falling back to the other version on
+ * {@linkcode NotFoundError} or {@linkcode InvalidMetadataError}. Pass `kind`
+ * to require a specific node type, or use {@linkcode open.v2} /
+ * {@linkcode open.v3} to pin the format.
+ *
+ * @example Usage
+ * ```ts
+ * import * as zarr from "zarrita";
+ *
+ * const store = new zarr.FetchStore("https://example.com/data.zarr");
+ * const arr = await zarr.open(store, { kind: "array" });
+ * console.log(arr.shape, arr.dtype);
+ * ```
+ *
+ * @example Child node of a group
+ * ```ts
+ * import * as zarr from "zarrita";
+ *
+ * const store = new zarr.FetchStore("https://example.com/data.zarr");
+ * const group = await zarr.open(store, { kind: "group" });
+ * const child = await zarr.open(group.resolve("temperature"), { kind: "array" });
+ * ```
+ *
+ * @param location A {@linkcode Readable} store, or a {@linkcode Location}
+ *   pointing at a node within a store.
+ * @param options Open options. Set `kind` to `"array"` or `"group"` to
+ *   require that node type, or pass an `AbortSignal` to cancel the request.
+ * @returns The opened {@linkcode Array} or {@linkcode Group}.
+ * @throws {NotFoundError} If no array or group exists at the location, or if
+ *   the node kind does not match `options.kind`.
+ * @throws {InvalidMetadataError} If metadata is present but malformed.
+ * @category Read
+ */
 export function open<Store extends Readable>(
 	location: Location<Store> | Store,
 	options: OpenOptions & { kind: "group" },
 ): Promise<Group<Store>>;
-
+/**
+ * Open a Zarr array or group, auto-detecting the on-disk format version.
+ * @category Read
+ */
 export function open<Store extends Readable>(
 	location: Location<Store> | Store,
 	options: OpenOptions & { kind: "array" },
 ): Promise<Array<DataType, Store>>;
-
+/**
+ * Open a Zarr array or group, auto-detecting the on-disk format version.
+ * @category Read
+ */
 export function open<Store extends Readable>(
 	location: Location<Store> | Store,
 	options?: OpenOptions,
@@ -240,5 +305,32 @@ export async function open<Store extends Readable>(
 	});
 }
 
+/**
+ * Open a Zarr v2 array or group, ignoring any v3 metadata that may coexist.
+ *
+ * @example Usage
+ * ```ts
+ * import * as zarr from "zarrita";
+ *
+ * const store = new zarr.FetchStore("https://example.com/legacy.zarr");
+ * const arr = await zarr.open.v2(store, { kind: "array" });
+ * ```
+ *
+ * @category Read
+ */
 open.v2 = openV2;
+
+/**
+ * Open a Zarr v3 array or group, ignoring any v2 metadata that may coexist.
+ *
+ * @example Usage
+ * ```ts
+ * import * as zarr from "zarrita";
+ *
+ * const store = new zarr.FetchStore("https://example.com/data.zarr");
+ * const group = await zarr.open.v3(store, { kind: "group" });
+ * ```
+ *
+ * @category Read
+ */
 open.v3 = openV3;