@cloudbitmaps/roaring 0.24.0 → 0.26.0

package/dist/bitmap.d.ts

@@ -0,0 +1,223 @@
+/** What {@link RoaringBitmap.deserialize} takes as its second argument. */
+export interface RoaringBitmapDeserializeOptions {
+    /**
+     * A cap on the input's size in bytes, lower than the one every decode has (537,403,396, the most any canonical
+     * 32-bit bitmap serializes to). Bytes over it are refused before any is read. It can only lower the cap: a value
+     * above it, or one that is not a non-negative integer, is a `ValidationError`.
+     */
+    readonly maxBytes?: number;
+}
+/**
+ * A mutable set of integers from 0 to 4,294,967,295 (unsigned 32-bit ids) with set algebra and the portable Roaring
+ * serialization. It is not designed for subclassing, and `JSON.stringify` of one gives `"{}"`: write
+ * `JSON.stringify([...bitmap])` or `bitmap.toArray()`. Passed to a method of the `roaring` package from npm in place of a
+ * `RoaringBitmap32`, it answers wrongly without throwing in JavaScript (TypeScript refuses the call): decode its
+ * `serialize()` bytes with that package instead.
+ *
+ * Every id argument is checked: a value that is not an integer in range (a fraction, `NaN`, a string, `null`, a
+ * negative, one too large) throws `ValidationError`, whose message never repeats it, and the bitmap is unchanged.
+ * Iterating while changing the bitmap is unsupported: collect first with `toUint32Array()`, or iterate a `clone()`.
+ * Everything is synchronous.
+ */
+export declare class RoaringBitmap implements Iterable<number> {
+    #private;
+    /**
+     * A bitmap of `values`: an array or another iterable of ids, a `Uint32Array` (read in place when it already ascends,
+     * else sorted on a copy; it is never changed or kept), or another `RoaringBitmap` (a copy-on-write `clone()`).
+     * With no argument it is empty.
+     *
+     * @throws {ValidationError} for an id that is not an integer from 0 to 4294967295; for a value that is not an
+     * iterable (`null`, a number, a string, an object, an `ArrayBuffer`); and for a `Uint8Array`, `Uint8ClampedArray` or
+     * `Buffer`, which would read each byte as an id: call {@link RoaringBitmap.deserialize} for bytes.
+     */
+    constructor(values?: Iterable<number>);
+    /**
+     * Decode portable Roaring bytes you hold, through the check a `{ serialized }` load makes first: a size cap, a
+     * structural check and one whole bitmap, and only then the decoder. The result owns its storage: it keeps nothing
+     * of `bytes`, so a large input that is decoded and then reduced can be freed.
+     *
+     * @param bytes a `Uint8Array`, which a Node `Buffer` is.
+     * @param options `{ maxBytes }` lowers the size cap below the default of 537,403,396 bytes.
+     * @throws {ValidationError} for something that is not a `Uint8Array`; an empty or detached one (an empty buffer is
+     * not a bitmap: `new RoaringBitmap()` is the empty set); one over the cap or `maxBytes`; bytes that are not exactly
+     * one well-formed portable bitmap, including bytes after its last container; a second argument that is not
+     * `undefined` or an object whose only key is `maxBytes` (a format argument such as `'portable'` is one); and a
+     * `maxBytes` that is not an integer from 0 to the cap.
+     */
+    static deserialize(bytes: Uint8Array, options?: RoaringBitmapDeserializeOptions): RoaringBitmap;
+    /** How many ids it holds. */
+    get size(): number;
+    /** Whether it holds no id. */
+    get isEmpty(): boolean;
+    /**
+     * Whether it holds `id`.
+     *
+     * @throws {ValidationError} for a value that is not an integer from 0 to 4294967295.
+     */
+    has(id: number): boolean;
+    /** The smallest id, or `undefined` when it is empty. */
+    minimum(): number | undefined;
+    /** The largest id, or `undefined` when it is empty. */
+    maximum(): number | undefined;
+    /**
+     * Add one id; returns this bitmap, for chaining.
+     *
+     * @throws {ValidationError} for a value that is not an integer from 0 to 4294967295, and for a second argument:
+     * use {@link RoaringBitmap.addMany} to add several.
+     */
+    add(id: number): this;
+    /**
+     * Add every id of `values` (an iterable of ids, or a `Uint32Array`); returns this bitmap. Nothing is added if any
+     * of them is refused.
+     *
+     * @throws {ValidationError} as the constructor does.
+     */
+    addMany(values: Iterable<number>): this;
+    /**
+     * Remove one id; whether it was there.
+     *
+     * @throws {ValidationError} for a value that is not an integer from 0 to 4294967295, and for a second argument:
+     * use {@link RoaringBitmap.removeMany} to remove several.
+     */
+    remove(id: number): boolean;
+    /**
+     * Remove every id of `values` (an iterable of ids, or a `Uint32Array`); returns this bitmap. Nothing is removed if
+     * any of them is refused.
+     *
+     * @throws {ValidationError} as the constructor does.
+     */
+    removeMany(values: Iterable<number>): this;
+    /** Remove every id. */
+    clear(): void;
+    /**
+     * A copy. It is copy-on-write: the copy costs the key list and one flag per container, not the ids, and the first
+     * write to a container on either side copies that container once.
+     */
+    clone(): RoaringBitmap;
+    /**
+     * Keep only the ids `other` also holds; returns this bitmap. `other` is not changed, and may be this bitmap.
+     *
+     * @throws {ValidationError} if `other` is not a `RoaringBitmap` of this copy of the package.
+     */
+    andInPlace(other: RoaringBitmap): this;
+    /**
+     * Add the ids `other` holds; returns this bitmap. `other` is not changed, and may be this bitmap.
+     *
+     * @throws {ValidationError} if `other` is not a `RoaringBitmap` of this copy of the package.
+     */
+    orInPlace(other: RoaringBitmap): this;
+    /**
+     * Remove the ids `other` holds; returns this bitmap. `other` is not changed, and may be this bitmap.
+     *
+     * @throws {ValidationError} if `other` is not a `RoaringBitmap` of this copy of the package.
+     */
+    andNotInPlace(other: RoaringBitmap): this;
+    /**
+     * Flip the ids `other` holds: keep those only this bitmap holds, add those only `other` holds; returns this bitmap.
+     * `other` is not changed, and may be this bitmap (the result is then empty).
+     *
+     * @throws {ValidationError} if `other` is not a `RoaringBitmap` of this copy of the package.
+     */
+    xorInPlace(other: RoaringBitmap): this;
+    /**
+     * How many ids both bitmaps hold, without building the intersection. Neither bitmap changes; `other` may be this one.
+     *
+     * @throws {ValidationError} if `other` is not a `RoaringBitmap` of this copy of the package.
+     */
+    andCardinality(other: RoaringBitmap): number;
+    /**
+     * How many ids either bitmap holds. Neither bitmap changes; `other` may be this one.
+     *
+     * @throws {ValidationError} if `other` is not a `RoaringBitmap` of this copy of the package.
+     */
+    orCardinality(other: RoaringBitmap): number;
+    /**
+     * How many ids exactly one of the bitmaps holds. Neither bitmap changes; `other` may be this one.
+     *
+     * @throws {ValidationError} if `other` is not a `RoaringBitmap` of this copy of the package.
+     */
+    xorCardinality(other: RoaringBitmap): number;
+    /**
+     * How many ids this bitmap holds that `other` lacks. Neither bitmap changes; `other` may be this one.
+     *
+     * @throws {ValidationError} if `other` is not a `RoaringBitmap` of this copy of the package.
+     */
+    andNotCardinality(other: RoaringBitmap): number;
+    /**
+     * Whether the bitmaps share an id. Neither bitmap changes; `other` may be this one.
+     *
+     * @throws {ValidationError} if `other` is not a `RoaringBitmap` of this copy of the package.
+     */
+    intersects(other: RoaringBitmap): boolean;
+    /**
+     * Whether every id of this bitmap is in `other` (an empty bitmap is a subset of every bitmap, itself included). Neither
+     * bitmap changes. Unlike the `roaring` package, which answers `false`, a value that is not a bitmap is refused.
+     *
+     * @throws {ValidationError} if `other` is not a `RoaringBitmap` of this copy of the package.
+     */
+    isSubset(other: RoaringBitmap): boolean;
+    /**
+     * Whether both bitmaps hold exactly the same ids, whatever the kinds of their containers or the bytes they would
+     * serialize to. Neither bitmap changes.
+     *
+     * @throws {ValidationError} if `other` is not a `RoaringBitmap` of this copy of the package.
+     */
+    isEqual(other: RoaringBitmap): boolean;
+    /**
+     * The ids both bitmaps hold, as a new bitmap. Neither operand changes, and the result holds storage of its own.
+     *
+     * @throws {ValidationError} if an operand is not a `RoaringBitmap` of this copy of the package.
+     */
+    static and(a: RoaringBitmap, b: RoaringBitmap): RoaringBitmap;
+    /**
+     * The ids either bitmap holds, as a new bitmap. Neither operand changes. A container only `a` holds is shared with
+     * the result copy-on-write, so the next write to it, on either side, copies it once.
+     *
+     * @throws {ValidationError} if an operand is not a `RoaringBitmap` of this copy of the package.
+     */
+    static or(a: RoaringBitmap, b: RoaringBitmap): RoaringBitmap;
+    /**
+     * The ids exactly one of the bitmaps holds, as a new bitmap. Neither operand changes (see {@link RoaringBitmap.or}
+     * for what is shared).
+     *
+     * @throws {ValidationError} if an operand is not a `RoaringBitmap` of this copy of the package.
+     */
+    static xor(a: RoaringBitmap, b: RoaringBitmap): RoaringBitmap;
+    /**
+     * The ids of `a` that `b` lacks, as a new bitmap. Neither operand changes (see {@link RoaringBitmap.or} for what is
+     * shared).
+     *
+     * @throws {ValidationError} if an operand is not a `RoaringBitmap` of this copy of the package.
+     */
+    static andNot(a: RoaringBitmap, b: RoaringBitmap): RoaringBitmap;
+    /**
+     * The union of every bitmap of `bitmaps`, as a new bitmap that owns its storage (an empty list gives the empty set).
+     * No operand changes, and none is flagged: the result accumulates in containers of its own.
+     *
+     * @throws {ValidationError} if `bitmaps` is not an iterable, or holds anything that is not a `RoaringBitmap` of this
+     * copy of the package; nothing is combined then.
+     */
+    static orMany(bitmaps: Iterable<RoaringBitmap>): RoaringBitmap;
+    /** The ids in ascending order, each once. A bitmap that changes during the walk gives unspecified ids, and no error. */
+    [Symbol.iterator](): IterableIterator<number>;
+    /** The ids as a new ascending array. A bitmap too large to allocate as one throws the runtime's `RangeError`. */
+    toArray(): number[];
+    /** The ids as a new ascending `Uint32Array` the caller owns, never a view of the bitmap's storage. */
+    toUint32Array(): Uint32Array;
+    /**
+     * The portable Roaring bytes, in a new `Uint8Array`. Call {@link RoaringBitmap.runOptimize} first when the bitmap was
+     * decoded from bytes another writer made: its run containers stay as they were, and a bitmap that serializes over
+     * the size cap is refused by a load.
+     *
+     * @param format `'portable'`, the only format there is, or nothing.
+     * @throws {ValidationError} for any other argument.
+     */
+    serialize(format?: 'portable'): Uint8Array;
+    /**
+     * Re-encode every container in the smallest form (a run container only where it is strictly smaller than the plain
+     * one), so `serialize()` afterwards depends on the set alone. Membership is unchanged.
+     *
+     * @returns whether the bitmap holds at least one run container afterwards, not whether anything changed.
+     */
+    runOptimize(): boolean;
+}

package/dist/index.d.ts

@@ -29,7 +29,6 @@ import type { DestroyResult, EraseDeps } from '@cloudbitmaps/core';
 import type { SegmentInfo } from '@cloudbitmaps/core';
 import type { PreflightResult } from '@cloudbitmaps/core';
 import type { Expr, MaterializeManyFeedRecord, MaterializeManyStats } from '@cloudbitmaps/core';
-import { deserializePortable } from './roaring-codec.js';
 /**
  * Crypto-shred one segment. It cannot be undone through the library (a registry restore to a point before it can).
  * `confirmSegment` must equal `ref.segment` (a guard against an accidental destroy). A non-encrypted segment is
@@ -1092,8 +1091,8 @@ export declare class CloudRoaring {
      * with `serialize('portable')` such as `roaring`'s `RoaringBitmap32`, or `{ serialized }`, portable Roaring bytes.
      * A bitmap is checked (size cap, structure, safe deserializer) before the first request, written from its own
      * containers with no per-id work, and gives the generation chunk for chunk what its ids would. An
-     * iterable with a `serialize` method (a `RoaringBitmap32`, another copy's bitmap, or a bitmap `deserializePortable`
-     * returned) passed as ids loads as `{ bitmap }` and is not iterated. A `Uint8Array` or `Buffer` passed as ids is
+     * iterable with a `serialize` method (a `RoaringBitmap32`, another copy's bitmap, or a `RoaringBitmap`
+     * of this package) passed as ids loads as `{ bitmap }` and is not iterated. A `Uint8Array` or `Buffer` passed as ids is
      * refused with `ValidationError`, since each byte would load as an id, even when it has a `serialize` of its own:
      * pass bytes as `{ serialized }`.
      *
@@ -1499,7 +1498,7 @@ export declare class CloudRoaring {
     /**
      * **Export ("eject") every registered segment's current generation** through the injected `sink`, using only
      * public read APIs — so your data is readable **without CloudRoaring** (the exit path; see the README's "Your
-     * data stays yours"). `format: 'roaring'` (default) writes one **portable RoaringBitmap32** per segment
+     * data stays yours"). `format: 'roaring'` (default) writes one **portable Roaring bitmap** per segment
      * (loadable by any roaring library); `'ndjson'` writes newline-delimited ids (zero-dependency, streaming).
      * Enumerates via the store's **own** registry (needs one — throws {@link UnsupportedError} otherwise) so the
      * enumeration and the read path provably share one registry. Encrypted segments are decrypted transparently
@@ -2129,6 +2128,59 @@ export declare class Segment {
      * {@link ValidationError} before any request.
      */
     andNotInto(dest: Segment, excludes: Segment[], options?: CombineOptions): Promise<MaterializeResult>;
+    /**
+     * 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}.
+     */
+    intersectCount(others: Segment[], options?: CombineOptions): Promise<number>;
+    /**
+     * 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.
+     */
+    unionCount(others: Segment[], options?: CombineOptions): Promise<number>;
+    /**
+     * 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}.
+     */
+    andNotCount(excludes: Segment[], options?: CombineOptions): Promise<number>;
+    /** The one body of the three count methods, after each has checked its own options. */
+    private countCombine;
     /**
      * 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.
@@ -2139,7 +2191,7 @@ export declare class Segment {
 }
 export { MemoryStorage, LocalFsStorage, InProcessKeystore } from '@cloudbitmaps/core/node';
 export type { InProcessKeystoreOptions, LocalFsStorageOptions, MemoryStorageOptions, } from '@cloudbitmaps/core/node';
-export { deserializePortable };
-export type { ReadonlyBitmap } from './roaring-codec.js';
+export { RoaringBitmap } from './bitmap.js';
+export type { RoaringBitmapDeserializeOptions } from './bitmap.js';
 export { excludingReservedRows, readRetentionPolicy, CloudRoaringError, ValidationError, WriteConflictError, IntegrityError, NotFoundError, UnsupportedError, CapabilityError, TransientError, KeyUnavailableError, BudgetExceededError, LeaseExpiredError, LeaseLimitError, StaleOperandError, errorKind, CountingMetricsSink, RecordingAuditSink, } from '@cloudbitmaps/core';
 export type { AuditEvent, Budget, BudgetOption, Clock, ConsistencyErrorEntry, ConsistencyIssue, ConsistencyReport, DestroyResult, DropResult, Entropy, EraseDeps, ErrorKind, ExportFailure, ExportFormat, ExportManifest, ExportOptions, ExportSink, ExportSkipped, ExportWriter, ExportedSegment, Expr, GenerationEntry, GenerationMetadata, IAuditSink, IMetricsSink, LoadGuard, LoadInput, LoadOptions, LoadRefusal, LoadResult, MaterializeManyFeedRecord, MaterializeManyOperandStats, MaterializeManyOutputStats, MaterializeManyStats, MetricEvent, MetricOpName, MetricsSnapshot, PinnedAt, PortableBitmap, PreflightCheck, PreflightResult, RetentionPolicy, RetireEntry, RetireExpiredOptions, RetireExpiredResult, RetryPolicy, Rng, RollbackResult, SegmentInfo, SegmentRef, SetRetentionResult, } from '@cloudbitmaps/core';