icechunk-js 0.4.0 → 0.5.1

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/dist/index.d.cts CHANGED
@@ -159,12 +159,20 @@ interface ChunkRef {
159
159
  /** Last modified timestamp (seconds since epoch) for virtual chunks */
160
160
  checksumLastModified: number;
161
161
  }
162
- /** Chunk references for a single array */
162
+ /**
163
+ * Chunk references for a single array, resolved lazily from the manifest's
164
+ * FlatBuffer. Keeping refs in the buffer avoids building a JS object per chunk,
165
+ * which would OOM on large virtual shards.
166
+ */
163
167
  interface ArrayManifest {
164
168
  /** Node ID of the array */
165
169
  nodeId: ObjectId8;
166
- /** Chunk references, sorted by index */
167
- refs: ChunkRef[];
170
+ /** Number of chunk refs (sorted by index). */
171
+ readonly numRefs: number;
172
+ /** Coordinate index of ref `i`, for the binary search in `findChunkRef`. */
173
+ refIndex(i: number): number[];
174
+ /** Materialize the full `ChunkRef` at position `i`. */
175
+ refAt(i: number): ChunkRef;
168
176
  }
169
177
  /** Manifest containing chunk references for multiple arrays */
170
178
  interface Manifest {
@@ -576,7 +584,15 @@ interface IcechunkStoreOptions {
576
584
  * - Route through a proxy
577
585
  */
578
586
  fetchClient?: FetchClient;
579
- /** Maximum number of manifests to cache in the LRU cache (default: 100) */
587
+ /**
588
+ * Maximum number of manifests to keep in the LRU cache (default: 100).
589
+ *
590
+ * This bounds the *number* of cached manifests, not their total bytes. Each
591
+ * entry retains a whole decompressed manifest shard — hundreds of MB for
592
+ * fine-level virtual stores — so a single oversized shard, or a few held at
593
+ * once, can still dominate memory. Lower this when reading stores with very
594
+ * large manifests.
595
+ */
580
596
  maxManifestCacheSize?: number;
581
597
  /**
582
598
  * Zarrita-backed range coalescing function for chunk payload reads.
package/dist/index.d.ts CHANGED
@@ -159,12 +159,20 @@ interface ChunkRef {
159
159
  /** Last modified timestamp (seconds since epoch) for virtual chunks */
160
160
  checksumLastModified: number;
161
161
  }
162
- /** Chunk references for a single array */
162
+ /**
163
+ * Chunk references for a single array, resolved lazily from the manifest's
164
+ * FlatBuffer. Keeping refs in the buffer avoids building a JS object per chunk,
165
+ * which would OOM on large virtual shards.
166
+ */
163
167
  interface ArrayManifest {
164
168
  /** Node ID of the array */
165
169
  nodeId: ObjectId8;
166
- /** Chunk references, sorted by index */
167
- refs: ChunkRef[];
170
+ /** Number of chunk refs (sorted by index). */
171
+ readonly numRefs: number;
172
+ /** Coordinate index of ref `i`, for the binary search in `findChunkRef`. */
173
+ refIndex(i: number): number[];
174
+ /** Materialize the full `ChunkRef` at position `i`. */
175
+ refAt(i: number): ChunkRef;
168
176
  }
169
177
  /** Manifest containing chunk references for multiple arrays */
170
178
  interface Manifest {
@@ -576,7 +584,15 @@ interface IcechunkStoreOptions {
576
584
  * - Route through a proxy
577
585
  */
578
586
  fetchClient?: FetchClient;
579
- /** Maximum number of manifests to cache in the LRU cache (default: 100) */
587
+ /**
588
+ * Maximum number of manifests to keep in the LRU cache (default: 100).
589
+ *
590
+ * This bounds the *number* of cached manifests, not their total bytes. Each
591
+ * entry retains a whole decompressed manifest shard — hundreds of MB for
592
+ * fine-level virtual stores — so a single oversized shard, or a few held at
593
+ * once, can still dominate memory. Lower this when reading stores with very
594
+ * large manifests.
595
+ */
580
596
  maxManifestCacheSize?: number;
581
597
  /**
582
598
  * Zarrita-backed range coalescing function for chunk payload reads.