icechunk-js 0.3.1 → 0.3.2
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 +23 -10
- package/dist/index.cjs +17 -38
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +5 -3
- package/dist/index.d.ts +5 -3
- package/dist/index.js +17 -38
- package/dist/index.js.map +1 -1
- package/package.json +10 -10
package/README.md
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
#
|
|
1
|
+
# icechunk-js
|
|
2
2
|
|
|
3
3
|
[](https://www.npmjs.com/package/icechunk-js)
|
|
4
4
|
[](https://github.com/earth-mover/icechunk)
|
|
@@ -8,8 +8,7 @@
|
|
|
8
8
|
Read-only JavaScript/TypeScript reader for Icechunk repositories, designed for
|
|
9
9
|
use with [zarrita](https://github.com/manzt/zarrita.js).
|
|
10
10
|
|
|
11
|
-
-
|
|
12
|
-
- Works in browsers, Node.js 18+, Deno, and Bun
|
|
11
|
+
- Pure TypeScript, works in browsers and Node.js 18+
|
|
13
12
|
- Icechunk v1 and v2 format auto-detection
|
|
14
13
|
- All chunk payload types: inline, native, and virtual
|
|
15
14
|
|
|
@@ -29,7 +28,7 @@ import { open, get } from "zarrita";
|
|
|
29
28
|
const store = await IcechunkStore.open("https://bucket.s3.amazonaws.com/repo");
|
|
30
29
|
|
|
31
30
|
// Open an array and read data
|
|
32
|
-
const array = await open(store, { kind: "array"
|
|
31
|
+
const array = await open(store.resolve("/temperature"), { kind: "array" });
|
|
33
32
|
const data = await get(array, [0, 0, null]);
|
|
34
33
|
```
|
|
35
34
|
|
|
@@ -66,6 +65,9 @@ const store = await IcechunkStore.open("https://example.com/repo", {
|
|
|
66
65
|
// snapshot: 'ABC123...',
|
|
67
66
|
// formatVersion: 'v1', // skip format auto-detection for v1 repos
|
|
68
67
|
// maxManifestCacheSize: 50, // LRU cache size (default: 100)
|
|
68
|
+
// signal: abortController.signal, // cancel initialization
|
|
69
|
+
// validateChecksums: true, // integrity headers for virtual chunks
|
|
70
|
+
// azureAccount: 'myaccount', // required for az:// virtual chunks
|
|
69
71
|
});
|
|
70
72
|
|
|
71
73
|
// Open from an existing ReadSession
|
|
@@ -103,7 +105,7 @@ const fetchClient: FetchClient = {
|
|
|
103
105
|
async fetch(url, init) {
|
|
104
106
|
// URL rewriting, pre-signing, or header injection happens here.
|
|
105
107
|
// icechunk-js has already translated s3:// → https:// and built
|
|
106
|
-
// Range
|
|
108
|
+
// Range headers in `init` (plus If-Match when validateChecksums is on).
|
|
107
109
|
const signedUrl = await presign(url);
|
|
108
110
|
return globalThis.fetch(signedUrl, {
|
|
109
111
|
...init,
|
|
@@ -120,17 +122,28 @@ const store = await IcechunkStore.open("https://example.com/repo", {
|
|
|
120
122
|
Cloud storage URLs in virtual chunk references are automatically translated:
|
|
121
123
|
|
|
122
124
|
- `s3://bucket/key` → `https://bucket.s3.amazonaws.com/key`
|
|
123
|
-
- `gs://bucket/key` → `https://storage.googleapis.com/bucket/key`
|
|
124
|
-
- `az://
|
|
125
|
-
|
|
125
|
+
- `gs://bucket/key` (or `gcs://`) → `https://storage.googleapis.com/bucket/key`
|
|
126
|
+
- `az://container/path` (or `azure://`) →
|
|
127
|
+
`https://{azureAccount}.blob.core.windows.net/container/path`
|
|
128
|
+
- `abfs://container@account.dfs.core.windows.net/path` →
|
|
129
|
+
`https://account.blob.core.windows.net/container/path`
|
|
126
130
|
|
|
127
131
|
### Repository
|
|
128
132
|
|
|
129
133
|
For direct access to branches, tags, and checkouts.
|
|
130
134
|
|
|
135
|
+
> **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.
|
|
142
|
+
|
|
131
143
|
```typescript
|
|
132
144
|
import { Repository, HttpStorage } from "icechunk-js";
|
|
133
145
|
|
|
146
|
+
// Replace with the root URL of a real Icechunk repository.
|
|
134
147
|
const storage = new HttpStorage("https://example.com/repo");
|
|
135
148
|
|
|
136
149
|
// Auto-detect format (default)
|
|
@@ -139,7 +152,7 @@ const repo = await Repository.open({ storage });
|
|
|
139
152
|
// Or with format version hint (skips /repo request for v1 stores)
|
|
140
153
|
// const repo = await Repository.open({ storage, formatVersion: 'v1' });
|
|
141
154
|
|
|
142
|
-
// List branches and tags
|
|
155
|
+
// List branches and tags (v2 repos, or storage backends that support listing)
|
|
143
156
|
const branches = await repo.listBranches();
|
|
144
157
|
const tags = await repo.listTags();
|
|
145
158
|
|
|
@@ -153,7 +166,7 @@ const session = await repo.checkoutBranch("main");
|
|
|
153
166
|
|
|
154
167
|
```typescript
|
|
155
168
|
for await (const entry of repo.walkHistory(session)) {
|
|
156
|
-
console.log(entry.id, entry.message, entry.flushedAt);
|
|
169
|
+
console.log(entry.id, entry.message, entry.flushedAt, entry.metadata);
|
|
157
170
|
}
|
|
158
171
|
```
|
|
159
172
|
|
package/dist/index.cjs
CHANGED
|
@@ -2796,7 +2796,7 @@ var Repository = class _Repository {
|
|
|
2796
2796
|
* version has the highest filename. Deletion tombstones are checked.
|
|
2797
2797
|
*
|
|
2798
2798
|
* When listing is not supported (e.g., HTTP storage), only the legacy
|
|
2799
|
-
* ref.json path is
|
|
2799
|
+
* ref.json path is returned (caller must handle NotFoundError on read).
|
|
2800
2800
|
*
|
|
2801
2801
|
* @param dirPrefix - Directory prefix to search
|
|
2802
2802
|
* @param legacyPath - Optional legacy ref.json path to try if listing fails
|
|
@@ -2832,7 +2832,9 @@ var Repository = class _Repository {
|
|
|
2832
2832
|
/**
|
|
2833
2833
|
* List all branches in the repository.
|
|
2834
2834
|
*
|
|
2835
|
-
*
|
|
2835
|
+
* Unlike tags, branches in icechunk v1 have no tombstone mechanism —
|
|
2836
|
+
* deletion removes the ref file outright. A branch is present iff it has
|
|
2837
|
+
* at least one ref file in its directory.
|
|
2836
2838
|
*
|
|
2837
2839
|
* @returns Array of branch names
|
|
2838
2840
|
*/
|
|
@@ -2841,49 +2843,23 @@ var Repository = class _Repository {
|
|
|
2841
2843
|
if (repoInfo) {
|
|
2842
2844
|
return listBranchesFromRepo(repoInfo);
|
|
2843
2845
|
}
|
|
2844
|
-
const
|
|
2846
|
+
const branches = /* @__PURE__ */ new Set();
|
|
2845
2847
|
try {
|
|
2846
2848
|
for await (const path of this.storage.listPrefix(
|
|
2847
2849
|
`${PATHS.REFS}/branch.`
|
|
2848
2850
|
)) {
|
|
2849
|
-
const
|
|
2850
|
-
|
|
2851
|
-
|
|
2852
|
-
);
|
|
2853
|
-
if (deletedMatch) {
|
|
2854
|
-
const branchName = deletedMatch[1];
|
|
2855
|
-
const refFile = `refs/branch.${branchName}/${deletedMatch[2]}`;
|
|
2856
|
-
if (!branchFiles.has(branchName)) {
|
|
2857
|
-
branchFiles.set(branchName, {
|
|
2858
|
-
jsonFiles: [],
|
|
2859
|
-
deletedFiles: /* @__PURE__ */ new Set()
|
|
2860
|
-
});
|
|
2861
|
-
}
|
|
2862
|
-
branchFiles.get(branchName).deletedFiles.add(refFile);
|
|
2863
|
-
} else if (jsonMatch) {
|
|
2864
|
-
const branchName = jsonMatch[1];
|
|
2865
|
-
if (!branchFiles.has(branchName)) {
|
|
2866
|
-
branchFiles.set(branchName, {
|
|
2867
|
-
jsonFiles: [],
|
|
2868
|
-
deletedFiles: /* @__PURE__ */ new Set()
|
|
2869
|
-
});
|
|
2870
|
-
}
|
|
2871
|
-
branchFiles.get(branchName).jsonFiles.push(path);
|
|
2851
|
+
const match = path.match(/^refs\/branch\.(.+)\/([^/]+\.json)$/);
|
|
2852
|
+
if (match) {
|
|
2853
|
+
branches.add(match[1]);
|
|
2872
2854
|
}
|
|
2873
2855
|
}
|
|
2874
|
-
} catch {
|
|
2875
|
-
|
|
2876
|
-
|
|
2877
|
-
const result = [];
|
|
2878
|
-
for (const [branchName, { jsonFiles, deletedFiles }] of branchFiles) {
|
|
2879
|
-
if (jsonFiles.length === 0) continue;
|
|
2880
|
-
jsonFiles.sort();
|
|
2881
|
-
const latestRef = jsonFiles[jsonFiles.length - 1];
|
|
2882
|
-
if (!deletedFiles.has(latestRef)) {
|
|
2883
|
-
result.push(branchName);
|
|
2856
|
+
} catch (error) {
|
|
2857
|
+
if (error instanceof AbortError) {
|
|
2858
|
+
throw error;
|
|
2884
2859
|
}
|
|
2860
|
+
throw new Error("Cannot list branches: storage does not support listing");
|
|
2885
2861
|
}
|
|
2886
|
-
return
|
|
2862
|
+
return [...branches];
|
|
2887
2863
|
}
|
|
2888
2864
|
/**
|
|
2889
2865
|
* List all tags in the repository.
|
|
@@ -2919,7 +2895,10 @@ var Repository = class _Repository {
|
|
|
2919
2895
|
tagFiles.get(tagName).jsonFiles.push(path);
|
|
2920
2896
|
}
|
|
2921
2897
|
}
|
|
2922
|
-
} catch {
|
|
2898
|
+
} catch (error) {
|
|
2899
|
+
if (error instanceof AbortError) {
|
|
2900
|
+
throw error;
|
|
2901
|
+
}
|
|
2923
2902
|
throw new Error("Cannot list tags: storage does not support listing");
|
|
2924
2903
|
}
|
|
2925
2904
|
const result = [];
|