@cloudbitmaps/roaring 0.14.0 → 0.15.0

package/dist/index.d.ts

@@ -136,14 +136,17 @@ export interface CacheOptions {
     /**
      * Ceiling on how many segments' `.crbm` readers (each holding a parsed index) the store keeps open at once
      * (default 1024) — the steady-state memory bound for a long-running server that reads across many segments.
-     * Past it the least-recently-used segment's reader is evicted; re-opening it later is one cheap tail GET.
+     * Past it the least-recently-used segment's reader is evicted; re-opening it later is one cheap tail GET. A reader of a small generation, one whose whole object came with its tail read,
+     * also holds its chunk bytes, so a read of it makes no chunk request until the reader is evicted or the pointer refresh
+     * moves it on; a store with no timed refresh (`genTtlMs: 0`, or no registry) keeps none.
      * Applies whenever the store builds its own read path — a backend or a bare `IStorageDriver`. A pre-built
      * `StorageChunkSource` manages its own reader cache.
      */
     readonly readerMax?: number;
     /**
-     * Aggregate byte ceiling on what the open readers hold, their parsed `.crbm` indices and the metadata a
-     * generation carries (default 64 MiB) — the byte half
+     * Aggregate byte ceiling on what the open readers hold, their parsed `.crbm` indices, the metadata a
+     * generation carries, and the chunk bytes a reader keeps when its tail read returned a whole object whose chunks
+     * total at most this ceiling divided by {@link CacheOptions.readerMax} (default 64 MiB) — the byte half
      * of the memory bound, complementing the {@link CacheOptions.readerMax} *count* bound. A wide/dense segment's
      * parsed index can reach about 1.3 MB, so a count-only bound could let the open readers pin over a GB and blow a small
      * heap (e.g. a 128 MB Lambda); this evicts the least-recently-used reader once the summed index footprint
@@ -959,11 +962,15 @@ export declare class CloudRoaring {
  */
 export interface BaseCombineOptions extends IdRange {
     /**
-     * Max chunk keys resolved concurrently — bounds the Storage footprint (about `concurrency × operands` chunks in
-     * flight). A positive integer; default 32. The window opens 8 keys wide (or `concurrency`, if lower) and widens
-     * as keys are taken, so a read that stops early fetches no more than a few keys ahead; one that runs to the end
-     * spends nearly all of its round trips at the full width. A read that stops early has requested up to
-     * `concurrency` keys per operand past the last one it used.
+     * How far ahead each operand is read: a positive integer, default 32. The library's own stores read each operand as
+     * one stream of coalesced ranges (chunks that sit near each other are one request), and `concurrency` is how many
+     * range requests a stream holds ahead of the read, in flight or landed and not yet used. So about
+     * `concurrency × operands` requests are in flight at most, and, since a range is at most 1 MiB (one chunk, when a chunk
+     * is larger), about `concurrency × operands` MiB are held, whatever the segment's size. The stream opens 4 ranges wide
+     * (or `concurrency`, if lower) and widens as ranges are taken, so a read that stops early has asked for little past
+     * where it stopped, and a read that fits one range makes one request however many chunks it needs. A source that
+     * reads chunk by chunk (a custom one) is read as before: `concurrency` chunk keys at once, opening 8 wide. A running
+     * stream holds its operand's reader outside the reader cache's bounds until it ends or the segment moves on.
      */
     readonly concurrency?: number;
     /** Override the store's per-op denial-of-wallet budget for this call (`false` lifts it). */
@@ -1318,8 +1325,9 @@ export declare class Segment {
     /**
      * Chunk-skipping intersection: stream the ids in **this** segment AND every segment in `others`, ascending.
      * Fetches only the Storage chunks present in *all* operands (a key absent from any operand contributes nothing
-     * and is never downloaded), streaming under a bounded in-flight window — so the Storage footprint stays small
-     * (Lambda-friendly) regardless of segment size. Pass `concurrency` to tune that window (a positive integer, 32 by default).
+     * and is never downloaded), reading each operand's as coalesced ranges under a bounded in-flight window — so the Storage
+     * footprint stays small (Lambda-friendly) regardless of segment size. Pass `concurrency` to tune that window (the range
+     * requests held ahead per operand: a positive integer, 32 by default).
      * AND is commutative, so `a.intersect([b])` and `b.intersect([a])` yield the same ids. Pass `budget` to
      * override the store's per-op denial-of-wallet budget for this call (or `false` to lift it).
      */

package/dist/index.js

@@ -1983,8 +1983,9 @@ var Segment = class _Segment {
   /**
    * Chunk-skipping intersection: stream the ids in **this** segment AND every segment in `others`, ascending.
    * Fetches only the Storage chunks present in *all* operands (a key absent from any operand contributes nothing
-   * and is never downloaded), streaming under a bounded in-flight window — so the Storage footprint stays small
-   * (Lambda-friendly) regardless of segment size. Pass `concurrency` to tune that window (a positive integer, 32 by default).
+   * and is never downloaded), reading each operand's as coalesced ranges under a bounded in-flight window — so the Storage
+   * footprint stays small (Lambda-friendly) regardless of segment size. Pass `concurrency` to tune that window (the range
+   * requests held ahead per operand: a positive integer, 32 by default).
    * AND is commutative, so `a.intersect([b])` and `b.intersect([a])` yield the same ids. Pass `budget` to
    * override the store's per-op denial-of-wallet budget for this call (or `false` to lift it).
    */