icechunk-js 0.3.2 → 0.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -44,19 +44,27 @@ npm run test
44
44
  npm run typecheck
45
45
  ```
46
46
 
47
- To regenerate FlatBuffers TypeScript after syncing schemas, run `npm run generate:fbs`.
48
- The pinned `flatc` compiler is downloaded automatically if not already available.
49
- The version is set in `scripts/ensure-flatc.sh`.
47
+ To regenerate FlatBuffers TypeScript after syncing schemas, run
48
+ `npm run generate:fbs`. The pinned `flatc` compiler is downloaded automatically
49
+ if not already available. The version is set in `scripts/ensure-flatc.sh`.
50
50
 
51
51
  ## API
52
52
 
53
53
  ### IcechunkStore
54
54
 
55
55
  The main class for zarrita integration. Implements zarrita's `AsyncReadable`
56
- interface with both `get()` and `getRange()` (needed for sharded arrays).
56
+ interface with both `get()` and `getRange()` (needed for sharded arrays). Pass
57
+ zarrita's `withRangeCoalescing` to coalesce concurrent reads against the same
58
+ backing object. This requires zarrita >= 0.7.
59
+
60
+ > **Note:** Range coalescing uses zarrita's merged abort-signal behavior. If one
61
+ > read in a merged batch is aborted, other reads in the same batch may also
62
+ > reject. Avoid sharing an `AbortController` across requests that must cancel
63
+ > independently.
57
64
 
58
65
  ```typescript
59
66
  import { IcechunkStore } from "icechunk-js";
67
+ import { withRangeCoalescing } from "zarrita";
60
68
 
61
69
  // Open from a URL (default: branch "main")
62
70
  const store = await IcechunkStore.open("https://example.com/repo", {
@@ -65,6 +73,7 @@ const store = await IcechunkStore.open("https://example.com/repo", {
65
73
  // snapshot: 'ABC123...',
66
74
  // formatVersion: 'v1', // skip format auto-detection for v1 repos
67
75
  // maxManifestCacheSize: 50, // LRU cache size (default: 100)
76
+ // withRangeCoalescing, // opt into merged range reads
68
77
  // signal: abortController.signal, // cancel initialization
69
78
  // validateChecksums: true, // integrity headers for virtual chunks
70
79
  // azureAccount: 'myaccount', // required for az:// virtual chunks
@@ -133,12 +142,11 @@ Cloud storage URLs in virtual chunk references are automatically translated:
133
142
  For direct access to branches, tags, and checkouts.
134
143
 
135
144
  > **Note:** Over plain HTTP, `listBranches()` and `listTags()` only work
136
- > reliably with v2 repos, which embed refs in the top-level `repo` file. For
137
- > v1 repos, direct `checkoutBranch()` / `checkoutTag()` can work when the
138
- > target ref still lives at the legacy `ref.json` path, but versioned ref
139
- > filenames still require `listPrefix()` discovery, which `HttpStorage` does
140
- > not provide. Use a listing-capable storage backend for full v1 branch/tag
141
- > support.
145
+ > reliably with v2 repos, which embed refs in the top-level `repo` file. For v1
146
+ > repos, direct `checkoutBranch()` / `checkoutTag()` can work when the target
147
+ > ref still lives at the legacy `ref.json` path, but versioned ref filenames
148
+ > still require `listPrefix()` discovery, which `HttpStorage` does not provide.
149
+ > Use a listing-capable storage backend for full v1 branch/tag support.
142
150
 
143
151
  ```typescript
144
152
  import { Repository, HttpStorage } from "icechunk-js";