@cloudbitmaps/roaring 0.25.0 → 0.26.0

package/PRIVACY.md

@@ -173,7 +173,7 @@ A call with a feed reads operands the library never stores, which no erasure can
 Erasure and crypto-shred are **immediate in storage and immediate in the store whose verb performed them**, for
 every read that starts after the verb returns. A read already in progress in that store can still yield an erased id
 from a chunk it had requested before the verb ran: up to 32 chunks for `iterate` and `count`, and up to `concurrency` + 1
-keys (33 by default) for a combine. That is the bound: the chunk or key a read is handing out and what it had already requested, which a `count` that reads chunks (on a source with no index of its own) reaches. A running `iterate` or combine on the library's own sources stops sooner: the verb invalidates the segment, so before the next key it takes the read lists its chunk keys again from the generation current then and drops what it had requested, and so yields the id only from the chunk or key it is handing out. A combine or `iterate` reads ranges of the object, and resolves the segment again before it serves each chunk, one held in its cache included, as a read of that chunk alone does, so the ranges it had already requested are dropped, not served. A pinned read in progress does not move to the rewritten generation: before its next chunk it opens its object again, and fails with `NotFoundError` once the erasure has deleted it, so it yields no more than that bound either. They are not immediate in any *other* store, in the same process or another, and this library ships nothing that could
+keys (33 by default) for a combine or a count of a combine. That is the bound: the chunk or key a read is handing out and what it had already requested, which a `count` that reads chunks (on a source with no index of its own) reaches. A running `iterate` or combine on the library's own sources stops sooner: the verb invalidates the segment, so before the next key it takes the read lists its chunk keys again from the generation current then and drops what it had requested, and so yields the id only from the chunk or key it is handing out. A combine or `iterate` reads ranges of the object, and resolves the segment again before it serves each chunk, one held in its cache included, as a read of that chunk alone does, so the ranges it had already requested are dropped, not served. A pinned read in progress does not move to the rewritten generation: before its next chunk it opens its object again, and fails with `NotFoundError` once the erasure has deleted it, so it yields no more than that bound either. They are not immediate in any *other* store, in the same process or another, and this library ships nothing that could
 make them so — there is no daemon, no bus, and no connection between two stores that happen to point at the same
 bucket.
 

package/README.md

@@ -105,8 +105,8 @@ name.
 
 ## What it costs
 
-A cold `intersect` of two 500,000-id segments sharing 100 of their 1,999 chunks made 6 GETs and took 104.88 ms at the median, **$2.40 per
-million** at list prices: measured on S3 in-region, in the run of 2026-10-13, whose client had 128 sockets. 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 107.87 ms at the median, **$2.40 per
+million** at list prices: measured on S3 in-region, in the run of 2026-10-30, 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 single-part `store.load()` made
 2 PUT + 3 GET, **$11.20 per million** at the default prices, pointer included: the requests are measured on S3 in-region, in the same run. A steady single-part `store.load()` at `keep: 12` that deletes a generation by name costs **$12.00 per million**, for 2 PUT + 5 GET and a free delete, the requests measured on S3 in-region, in the same run. A cold `count()` is one
 pointer read: it reads no payload and no object.

package/dist/bin/export-segments.js

@@ -3572,6 +3572,29 @@ var CALL_KEYS = {
     "allowAbsentOperands",
     "exclude"
   ]),
+  intersectCount: keysOf()([
+    "after",
+    "through",
+    "concurrency",
+    "budget",
+    "allowAbsentOperands",
+    "exclude"
+  ]),
+  unionCount: keysOf()([
+    "after",
+    "through",
+    "concurrency",
+    "budget",
+    "allowAbsentOperands",
+    "exclude"
+  ]),
+  andNotCount: keysOf()([
+    "after",
+    "through",
+    "concurrency",
+    "budget",
+    "allowAbsentOperands"
+  ]),
   into: keysOf()([
     "after",
     "through",
@@ -3649,6 +3672,9 @@ var MISPLACED = {
   range: outside(CALL_KEYS.into, CALL_KEYS.range),
   andNot: outside(CALL_KEYS.into, CALL_KEYS.andNot),
   combine: outside(CALL_KEYS.into, CALL_KEYS.combine),
+  intersectCount: outside(CALL_KEYS.into, CALL_KEYS.intersectCount),
+  unionCount: outside(CALL_KEYS.into, CALL_KEYS.unionCount),
+  andNotCount: outside(CALL_KEYS.into, CALL_KEYS.andNotCount),
   andNotInto: outside(CALL_KEYS.into, CALL_KEYS.andNotInto),
   exportSegments: ["codec"]
 };
@@ -5415,7 +5441,7 @@ function operandsLabel(verb) {
 }
 function refuseNoOperands(verb) {
   throw new ValidationError5(
-    verb === "intersect" ? "intersect requires at least one segment to intersect with; to read every id of one segment, use iterate()" : "intersectInto requires at least one segment to intersect with; to copy this segment into dest, call materializeMany({ operands: { src: thisSegment }, outputs: [{ dest, expr: { or: ['src'] } }], keep })"
+    verb === "intersect" ? "intersect requires at least one segment to intersect with; to read every id of one segment, use iterate()" : verb === "intersectCount" ? "intersectCount requires at least one segment to intersect with; to count one segment, use count()" : "intersectInto requires at least one segment to intersect with; to copy this segment into dest, call materializeMany({ operands: { src: thisSegment }, outputs: [{ dest, expr: { or: ['src'] } }], keep })"
   );
 }
 var AS_IDS = {
@@ -6125,6 +6151,111 @@ var Segment = class _Segment {
     );
     return this.combineInto("andNotInto", dest, excludes, options);
   }
+  /**
+   * How many ids `this ∩ others…` holds (minus `exclude`): the length of what {@link intersect} streams, without
+   * streaming it. Every key all the operands hold is decoded and counted as the stream reads it, and a key only some
+   * operands hold is not read, so the call makes the requests {@link intersect} makes and returns a number instead of
+   * the ids. It is exact: it never answers a key from an index, so it trusts nothing {@link count} trusts.
+   *
+   * The range, `concurrency`, `budget`, `allowAbsentOperands` and `exclude` are {@link intersect}'s; a write option fails
+   * the call with {@link ValidationError} before any request, and so does an empty `others` (to count one segment, use
+   * {@link count}).
+   *
+   * Like a stream, a count that runs while a segment is erased or reloaded can describe two instants, within the bound
+   * the streams state. A union or a difference, and an intersection with an `exclude`, looks at its operands'
+   * generations every `concurrency` keys; an intersection with no `exclude` makes no such look, since it decodes every
+   * key and so shows a move in the chunks it decodes, as its stream does. Either way it plans again above the last key
+   * it took when one moved. A pinned handle counts the generation it pinned, and each pinned operand's object is
+   * looked up once before the first key (one footer read each, which `budget` does not charge, and which the stream
+   * does not make), and again at each look where there is one, so an erasure of what it pinned fails the count with
+   * {@link NotFoundError}; a
+   * fault the look meets other than a transient one, which is retried, is raised as it is. A call that involves a
+   * handle whose lease has ended, or has ended by the next look, throws {@link LeaseExpiredError}.
+   */
+  async intersectCount(others, options) {
+    checkOptions(
+      options,
+      "intersectCount",
+      CALL_KEYS.intersectCount,
+      ["allowAbsentOperands"],
+      MISPLACED.intersectCount
+    );
+    return this.countCombine("intersect", others, options ?? void 0);
+  }
+  /**
+   * How many ids `this ∪ others…` holds (minus `exclude`): the length of what {@link union} streams, without streaming
+   * it. A chunk key only one operand holds, that no `exclude` holds and the range does not cut, is answered from that
+   * operand's index, so a union of segments that mostly do not overlap reads little of them; every other key is
+   * decoded and counted. On handles that are not pinned it makes no more requests than {@link union} does, and reads
+   * fewer bytes when the shared keys are few. An empty `others`, with no `exclude` and no range, is {@link count} of
+   * `this`, answered from the registry row when it can be; when that figure is 0 it adds one registry read, to refuse
+   * a segment that does not exist as the stream does.
+   *
+   * What it trusts: the index, for each key it answers without decoding, as {@link count} does, so a party who can write
+   * an object's index can make that key's figure wrong; a decoded key is exact. A source with no per-chunk counts
+   * decodes every key. It takes the options {@link intersectCount} takes; the erasure bound, the lease checks and the
+   * pinned handles are as for {@link intersectCount}, a pinned operand adding a footer read before the first key and at
+   * each look. An empty `others` on a pinned handle is {@link count} of the pin, with no look.
+   */
+  async unionCount(others, options) {
+    checkOptions(
+      options,
+      "unionCount",
+      CALL_KEYS.unionCount,
+      ["allowAbsentOperands"],
+      MISPLACED.unionCount
+    );
+    return this.countCombine("union", others, options ?? void 0);
+  }
+  /**
+   * How many ids `this \ (excludes…)` holds: the length of what {@link andNot} streams, without streaming it. A chunk
+   * key of `this` that no exclude holds and the range does not cut is answered from its index and not read; a key an
+   * exclude shares is decoded and counted. On handles that are not pinned it makes no more requests than {@link andNot}
+   * does, and reads fewer bytes when the excludes overlap little of `this`. An empty `excludes`, with no range, is
+   * {@link count} of `this` (the stream of it is the whole of `this`), answered from the registry row when it can be,
+   * with one registry read added when that figure is 0.
+   *
+   * It takes the options {@link andNot} takes (every one of {@link intersectCount}'s but `exclude`, which a count of a
+   * difference has no use for, since `excludes` is its subtraction) and trusts what {@link unionCount} trusts. The
+   * erasure bound, the lease checks and the pinned handles are as for {@link intersectCount}.
+   */
+  async andNotCount(excludes, options) {
+    checkOptions(
+      options,
+      "andNotCount",
+      CALL_KEYS.andNotCount,
+      ["allowAbsentOperands"],
+      MISPLACED.andNotCount
+    );
+    return this.countCombine("andNot", excludes, options ?? void 0);
+  }
+  /** The one body of the three count methods, after each has checked its own options. */
+  async countCombine(verb, operands, options) {
+    const name = `${verb}Count`;
+    const exclude = verb === "andNot" ? NO_SEGMENTS : this.excludesOf(options);
+    const others = segmentList(
+      operands,
+      verb === "andNot" ? `${name}: \`excludes\`` : `${name}: \`others\``
+    );
+    if (verb === "intersect" && others.length === 0) refuseNoOperands("intersectCount");
+    const handles = [this, ...others, ...exclude];
+    this.assertSegments(name, verb === "andNot" ? "an exclude" : "an operand", others);
+    this.assertSegments(name, "an exclude", exclude);
+    this.assertLeases(handles);
+    const engine = this.combineEngine(handles) ?? this.engine;
+    const read = options == null ? void 0 : readOptions(options);
+    const guard2 = handles.some((h) => h.leaseHold !== void 0) ? () => this.assertLeases(handles) : void 0;
+    const opts = guard2 === void 0 ? read : { ...read, guard: guard2 };
+    const refs = others.map((o) => o.ref);
+    if (verb === "andNot") return engine.combineCount([this.ref], refs, "all", verb, opts);
+    return engine.combineCount(
+      [this.ref, ...refs],
+      exclude.map((o) => o.ref),
+      verb === "union" ? "any" : "all",
+      verb,
+      opts
+    );
+  }
   /**
    * The one body of the three combines, read as ids or as chunks. `operands` is `others` for `intersect` and
    * `union`, and `excludes` for `andNot`, which takes no `exclude` option.