@cloudbitmaps/roaring 0.15.0 → 0.16.0

package/README.md

@@ -69,11 +69,10 @@ name.
 
 ## What it costs
 
-A cold `intersect` of two 500,000-id segments sharing 100 of their 1,999 chunks is expected to make 6 GETs, **$2.40 per
-million**: counted by running the engine and priced at list, not yet measured on a cloud. On a spread layout it reads more
+A cold `intersect` of two 500,000-id segments sharing 100 of their 1,999 chunks made 6 GETs and took 95.03 ms at the median, **$2.40 per
+million** at list prices: measured on S3 in-region, in the run of 2026-10-04, whose client had 128 sockets. On a spread layout it reads more
 bytes than it needs, which cross-region can cost more than the requests it saves. A segment's first `store.load()` is
-**$11.60 per million**, pointer included, from its measured requests at list prices (run of 2026-10-04, in-region, whose
-client had 50 sockets; the client this release builds allows 128, and its effect is not measured). A cold `count()` is one
+expected at **$11.20 per million**, pointer included: counted by running the engine and priced at list, not yet measured on a cloud. A cold `count()` is one
 pointer read: it reads no payload and no object.
 
 The trade is stated plainly. A membership check that misses the cache costs a ranged GET against object storage,

package/dist/bin/export-segments.js

@@ -33,6 +33,7 @@ import {
   estimateCost,
   groundedReport,
   loadSegment,
+  loadSegmentChunks,
   mapWithConcurrency,
   resolveBudget,
   resolvePerOpBudget,
@@ -460,7 +461,8 @@ function bitmapAsLoadInput(input) {
 var roaringCodec = {
   empty: () => SafeBitmap.empty(),
   fromValues: (values) => SafeBitmap.fromValues(values),
-  safeDeserialize: (bytes, maxBytes, options) => SafeBitmap.safeDeserialize(bytes, maxBytes, options)
+  safeDeserialize: (bytes, maxBytes, options) => SafeBitmap.safeDeserialize(bytes, maxBytes, options),
+  owns: (bitmap) => bitmap instanceof SafeBitmap
 };
 
 // src/system-clock.ts
@@ -885,7 +887,7 @@ var CloudRoaring = class _CloudRoaring {
     const metadata = options?.metadata;
     let result;
     try {
-      result = await loadSegment(dest, ids, deps, {
+      const loadOptions = {
         ...options?.allowEmpty === void 0 ? {} : { allowEmpty: options.allowEmpty },
         ...options?.guard === void 0 ? {} : { guard: options.guard },
         ...metadata === void 0 ? {} : { metadata },
@@ -898,7 +900,8 @@ var CloudRoaring = class _CloudRoaring {
         // as a side effect of adding a guard whose entire purpose is preventing data loss. Opt in with `keep`.
         keep: options?.keep ?? KEEP_EVERY_GENERATION,
         ...options?.audit === void 0 ? {} : { audit: options.audit }
-      });
+      };
+      result = ids instanceof CombineChunks ? await loadSegmentChunks(dest, ids.chunks, deps, loadOptions) : await loadSegment(dest, ids, deps, loadOptions);
     } finally {
       this.engine.invalidate(dest);
     }
@@ -1702,6 +1705,32 @@ var EMPTY_IDS = {
   async *batches() {
   }
 };
+var AS_IDS = {
+  none: EMPTY_IDS,
+  failing,
+  intersect: (engine, refs, opts) => withBatches(engine.intersect(refs, opts), () => engine.intersectBatches(refs, opts)),
+  union: (engine, refs, opts) => withBatches(engine.union(refs, opts), () => engine.unionBatches(refs, opts)),
+  andNot: (engine, base, refs, opts) => withBatches(engine.andNot(base, refs, opts), () => engine.andNotBatches(base, refs, opts))
+};
+var NO_CHUNKS = {
+  async *[Symbol.asyncIterator]() {
+  }
+};
+var CombineChunks = class {
+  constructor(chunks) {
+    this.chunks = chunks;
+  }
+  chunks;
+};
+var AS_CHUNKS = {
+  none: NO_CHUNKS,
+  failing: (err) => ({
+    [Symbol.asyncIterator]: () => ({ next: () => Promise.reject(err) })
+  }),
+  intersect: (engine, refs, opts) => engine.intersectChunks(refs, opts),
+  union: (engine, refs, opts) => engine.unionChunks(refs, opts),
+  andNot: (engine, base, refs, opts) => engine.andNotChunks(base, refs, opts)
+};
 var KEEP_EVERY_GENERATION = Number.MAX_SAFE_INTEGER;
 var makeSegment;
 var minting = false;
@@ -2000,17 +2029,20 @@ var Segment = class _Segment {
    * override the store's per-op denial-of-wallet budget for this call (or `false` to lift it).
    */
   intersect(others, options) {
-    if (this.expired() || others.some((o) => o.expired())) return EMPTY_IDS;
+    return this.intersectAs(AS_IDS, others, options);
+  }
+  intersectAs(out, others, options) {
+    if (this.expired() || others.some((o) => o.expired())) return out.none;
     const exclude = this.liveExcludes(options);
     let engine;
     try {
       engine = this.combineEngine([this, ...others, ...exclude]) ?? this.engine;
     } catch (err) {
-      return failing(err);
+      return out.failing(err);
     }
     const refs = [this.ref, ...others.map((o) => o.ref)];
     const opts = this.refsIn(options, exclude);
-    return withBatches(engine.intersect(refs, opts), () => engine.intersectBatches(refs, opts));
+    return out.intersect(engine, refs, opts);
   }
   /**
    * Materialize `this ∩ others…` (minus `exclude`) as a **new generation of `dest`** — `dest`'s previous contents
@@ -2037,7 +2069,12 @@ var Segment = class _Segment {
     this.combineEngine([this, ...others, ...options?.exclude ?? []]);
     return this.timed(
       "intersectInto",
-      () => this.materialize(dest.ref, this.intersect(others, options), "intersectInto", options)
+      () => this.materialize(
+        dest.ref,
+        new CombineChunks(this.intersectAs(AS_CHUNKS, others, options)),
+        "intersectInto",
+        options
+      )
     );
   }
   /**
@@ -2051,26 +2088,29 @@ var Segment = class _Segment {
    * segment once (`unionInto`, or a load) is the cheaper shape.
    */
   union(others, options) {
+    return this.unionAs(AS_IDS, others, options);
+  }
+  unionAs(out, others, options) {
     const live = others.filter((o) => !o.expired());
     if (this.expired()) {
-      if (live.length === 0) return EMPTY_IDS;
-      return live[0].union(live.slice(1), options);
+      if (live.length === 0) return out.none;
+      return live[0].unionAs(out, live.slice(1), options);
     }
     if (live.length === 0 && others.length > 0) {
       const exclude2 = this.liveExcludes(options);
-      return exclude2.length > 0 ? this.andNot([...exclude2], options) : this.union([], options);
+      return exclude2.length > 0 ? this.andNotAs(out, [...exclude2], options) : this.unionAs(out, [], options);
     }
-    if (live.length !== others.length) return this.union(live, options);
+    if (live.length !== others.length) return this.unionAs(out, live, options);
     const exclude = this.liveExcludes(options);
     let engine;
     try {
       engine = this.combineEngine([this, ...others, ...exclude]) ?? this.engine;
     } catch (err) {
-      return failing(err);
+      return out.failing(err);
     }
     const refs = [this.ref, ...others.map((o) => o.ref)];
     const opts = this.refsIn(options, exclude);
-    return withBatches(engine.union(refs, opts), () => engine.unionBatches(refs, opts));
+    return out.union(engine, refs, opts);
   }
   /** Materialize `this ∪ others…` (minus `exclude`) as a **new generation of `dest`** — see {@link intersectInto}. */
   async unionInto(dest, others, options) {
@@ -2078,7 +2118,12 @@ var Segment = class _Segment {
     this.combineEngine([this, ...others, ...options?.exclude ?? []]);
     return this.timed(
       "unionInto",
-      () => this.materialize(dest.ref, this.union(others, options), "unionInto", options)
+      () => this.materialize(
+        dest.ref,
+        new CombineChunks(this.unionAs(AS_CHUNKS, others, options)),
+        "unionInto",
+        options
+      )
     );
   }
   /**
@@ -2097,25 +2142,25 @@ var Segment = class _Segment {
    * the suppression folds into the same pass rather than materializing an intermediate segment first.
    */
   andNot(excludes, options) {
-    if (this.expired()) return EMPTY_IDS;
+    return this.andNotAs(AS_IDS, excludes, options);
+  }
+  andNotAs(out, excludes, options) {
+    if (this.expired()) return out.none;
     const liveExcludes = excludes.filter((e) => !e.expired());
     if (liveExcludes.length === 0 && excludes.length > 0) {
-      return this.union([], options == null ? void 0 : readOptions(options));
+      return this.unionAs(out, [], options == null ? void 0 : readOptions(options));
     }
-    if (liveExcludes.length !== excludes.length) return this.andNot(liveExcludes, options);
+    if (liveExcludes.length !== excludes.length) return this.andNotAs(out, liveExcludes, options);
     let engine;
     try {
       engine = this.combineEngine([this, ...excludes]) ?? this.engine;
     } catch (err) {
-      return failing(err);
+      return out.failing(err);
     }
     const base = this.ref;
     const refs = excludes.map((o) => o.ref);
     const opts = options == null ? void 0 : readOptions(options);
-    return withBatches(
-      engine.andNot(base, refs, opts),
-      () => engine.andNotBatches(base, refs, opts)
-    );
+    return out.andNot(engine, base, refs, opts);
   }
   /** Materialize `this \ (excludes…)` as a **new generation of `dest`** — see {@link intersectInto}. */
   async andNotInto(dest, excludes, options) {
@@ -2123,7 +2168,12 @@ var Segment = class _Segment {
     this.combineEngine([this, ...excludes]);
     return this.timed(
       "andNotInto",
-      () => this.materialize(dest.ref, this.andNot(excludes, options), "andNotInto", options)
+      () => this.materialize(
+        dest.ref,
+        new CombineChunks(this.andNotAs(AS_CHUNKS, excludes, options)),
+        "andNotInto",
+        options
+      )
     );
   }
   /**