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 CHANGED
@@ -1,4 +1,4 @@
1
- # Icechunk JavaScript
1
+ # icechunk-js
2
2
 
3
3
  [![npm version](https://img.shields.io/npm/v/icechunk-js.svg)](https://www.npmjs.com/package/icechunk-js)
4
4
  [![Icechunk](https://img.shields.io/badge/Icechunk-008B8B)](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
- - ~50KB bundle, zero native dependencies
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", path: "/temperature" });
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 / If-None-Match headers in `init`.
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://account/container/path` → `https://account.blob.core.windows.net/container/path`
125
- - `abfs://container@account.dfs.core.windows.net/path` → `https://account.blob.core.windows.net/container/path`
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 checked (no tombstone check - assumes read-only).
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
- * Branches with deletion tombstones on their latest ref file are excluded.
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 branchFiles = /* @__PURE__ */ new Map();
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 jsonMatch = path.match(/^refs\/branch\.(.+)\/([^/]+\.json)$/);
2850
- const deletedMatch = path.match(
2851
- /^refs\/branch\.(.+)\/([^/]+\.json)\.deleted$/
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
- throw new Error("Cannot list branches: storage does not support listing");
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 result;
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 = [];