icechunk-js 0.3.2 → 0.4.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 +18 -10
- package/dist/index.cjs +528 -195
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +105 -9
- package/dist/index.d.ts +105 -9
- package/dist/index.js +528 -195
- package/dist/index.js.map +1 -1
- package/package.json +1 -1
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
|
|
48
|
-
The pinned `flatc` compiler is downloaded automatically
|
|
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
|
-
>
|
|
138
|
-
>
|
|
139
|
-
>
|
|
140
|
-
>
|
|
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";
|