@cloudbitmaps/roaring 0.22.0 → 0.24.0

package/dist/roaring-codec.d.ts

@@ -1,118 +1,49 @@
 /**
- * SafeBitmap — the thin wrapper around the `roaring` (CRoaring) engine that owns the
- * untrusted-bytes boundary.
+ * The codec selection point and the load-input and decode helpers the `CloudRoaring` facade builds on.
  *
- * All (de)serialization uses the **portable** format — the stable, bounds-checked one. The
- * `unsafe_frozen_*` formats are never used (they are explicitly documented as crash/attack
- * vectors). Every deserialize is preceded by a hard size cap and a structural check, because the native
- * portable deserializer bounds its reads and checks nothing else (see `portable/layout.ts`).
+ * The store's codec is the TypeScript Roaring codec (`ts-roaring/bitmap.ts`): the portable format, read and written in
+ * JavaScript with no native addon. Every deserialize is preceded by a hard size cap and a structural check
+ * (`portable/layout.ts`). The `unsafe_frozen_*` formats are never used.
  */
-import roaring from 'roaring';
-import type { CodecBitmap, CodecInterface, EncodedChunk, LoadInput } from '@cloudbitmaps/core';
-declare const RoaringBitmap32: typeof roaring.RoaringBitmap32;
-type RoaringBitmap32 = InstanceType<typeof RoaringBitmap32>;
-export declare class SafeBitmap implements CodecBitmap {
-    private readonly bitmap;
-    private constructor();
-    static empty(): SafeBitmap;
-    static fromValues(values: Iterable<number>): SafeBitmap;
-    /**
-     * Cap the size, check the structure, then deserialize with the **portable** format.
-     * Throws `IntegrityError` if the input exceeds `maxBytes`, is not a well-formed portable bitmap, or fails to
-     * decode — the native addon is never handed unbounded, malformed or unsafe-format input. With `whole`, bytes
-     * after the bitmap's last container are refused too; without it they are ignored, as the native decoder ignores
-     * them.
-     *
-     * The structural check is what makes the decoded bitmap's answers mean anything. The native deserializer
-     * bounds its reads and checks nothing else, so bytes of the right length and the wrong shape (containers or
-     * values out of order, overlapping runs, a cardinality that disagrees with the bits) decode into a bitmap
-     * whose `maximum()`, `has()` and `size` are wrong, and some of those shapes crash the process when used.
-     */
-    static safeDeserialize(bytes: Uint8Array, maxBytes: number, options?: {
-        readonly whole?: boolean;
-    }): SafeBitmap;
-    /** The `roaring` bitmap this wraps, for a caller that was handed it once and keeps no wrapper. */
-    unwrap(): RoaringBitmap32;
-    serialize(): Uint8Array;
-    /**
-     * Convert containers to run-encoding where that is smaller. Representation only — membership is untouched, and
-     * the portable format still round-trips through {@link RoaringCodec.safeDeserialize}.
-     *
-     * Roaring's third container type is a RUN, and no implementation selects it on its own: it takes an explicit
-     * `runOptimize()` pass. Nothing here made that call, so run-shaped ids paid array or bitset prices — measured
-     * at **570×** for a contiguous 1M-id range (128.1 KiB → 0.2 KiB) and **63×** for a 2,000-run shape
-     * (536.5 KiB → 8.5 KiB). Sparse ids come out byte-identical, so this is never a losing trade; roaring keeps
-     * whichever encoding is smaller per container.
-     *
-     * Those two factors are THIS CALL's own before/after on the same ids. They are not the ones the site quotes
-     * (543× and 63×) — those compare the optimized encoding against the best *fixed* representation at its floor,
-     * a different baseline that happens to land near 63× on the run shape too. `pnpm bench:encoding` prints both
-     * columns; don't carry a figure between them without checking which denominator it had.
-     *
-     * Called only when writing an immutable objects generation — see {@link CodecBitmap.optimize} for why the read
-     * path deliberately does not.
-     *
-     * CANONICAL, which `runOptimize()` alone is not. Where a container's run and array encodings are the same size
-     * (cardinality = 2 × runs + 1: three values in one run, five in two), CRoaring keeps whichever kind the
-     * container already has. A chunk built from ids starts as an array and stays one; the same set reached through
-     * `addRange`, an earlier `runOptimize()` or an operation over run containers is a run, and serializes to other
-     * bytes. Undoing run compression first starts every container where one built from ids starts, so the bytes
-     * depend on membership alone. On a bitmap built from ids there is nothing to undo.
-     */
-    optimize(): void;
-    /**
-     * This set as storage chunks, cut from its own containers: {@link optimize} and one `serialize` when called, then
-     * a lazy header walk that copies one container out per step (`containerPayloads`). Per container and per byte,
-     * never per id, and the payloads are the ones {@link SafeBitmap.fromValues} of each chunk's low 16 bits would
-     * serialize to. The walk trusts the bytes it cuts because the native serializer wrote them, from a bitmap that
-     * passed the structural check when it was decoded.
-     */
-    encodeChunks(): Iterable<EncodedChunk>;
-    /**
-     * Largest value, or `undefined` when empty. O(1) — roaring reads it off the last container, so the engine's
-     * per-chunk range assertion costs one call per chunk rather than a walk per id. The last container holds the
-     * largest value only because {@link SafeBitmap.safeDeserialize} refuses bytes whose containers or values are
-     * out of order.
-     */
-    maximum(): number | undefined;
-    add(value: number): void;
-    addMany(values: Iterable<number>): void;
-    remove(value: number): void;
-    removeMany(values: Iterable<number>): void;
-    has(value: number): boolean;
-    get size(): number;
-    get isEmpty(): boolean;
-    clone(): SafeBitmap;
-    /** In-place union: `this = this ∪ other`. */
-    orInPlace(other: CodecBitmap): void;
-    /** In-place difference: `this = this \ other`. */
-    andNotInPlace(other: CodecBitmap): void;
-    /** In-place intersection: `this = this ∩ other`. */
-    andInPlace(other: CodecBitmap): void;
-    /** Ascending iterator over the set values. */
-    [Symbol.iterator](): IterableIterator<number>;
-    toArray(): number[];
-    /** The values as one fresh ascending `Uint32Array`, exported natively. */
-    toUint32Array(): Uint32Array;
-}
+import type { CodecInterface, LoadInput, PortableBitmap } from '@cloudbitmaps/core';
 /**
- * A bare `RoaringBitmap32` of this package's own `roaring`, passed where ids go, loads as `{ bitmap }`: from its
- * containers, through the same check as any bytes, never id by id. Any other input passes through unchanged, and a
- * bitmap from another copy of `roaring` is loaded as the ids it iterates, which is correct and slower.
+ * An iterable that serializes itself to portable Roaring (an object with `Symbol.iterator` and a `serialize` method: a
+ * caller's `RoaringBitmap32` from the `roaring` package, another copy's bitmap, or a bitmap {@link deserializePortable}
+ * returned), passed where ids go, loads as `{ bitmap }`: from its containers, through the same check as any bytes,
+ * never id by id. Its `serialize` decides, even where it disagrees with what it iterates. Any other input passes
+ * through unchanged, so the core's own rules apply to it: a byte array (`Uint8Array`, `Buffer`) is refused as ids even
+ * with a `serialize` of its own, and an object that is not iterable is read as `{ serialized }` or `{ bitmap }` or
+ * refused, whatever else it has.
  */
 export declare function bitmapAsLoadInput(input: LoadInput): LoadInput;
 /**
- * The roaring {@link CodecInterface} — the flagship codec, delegating to {@link SafeBitmap}'s statics. This is
- * the default the `CloudRoaring` facade injects into the engine; `core/` itself never hard-references it once a
- * caller supplies a codec.
+ * The codec the store hands to the engine at every site that injects one (`CloudRoaring`, a load, a pin, an export
+ * and {@link deserializePortable}): the TypeScript codec unless a harness has flipped it with {@link setFlagshipCodec}.
+ * Internal: no public entry exports it, and a store cannot be configured with a codec.
+ */
+export declare function flagshipCodec(): CodecInterface;
+/** Flip the codec the store uses, for the whole process. Test and bench harnesses only; returns the previous one. */
+export declare function setFlagshipCodec(codec: CodecInterface): CodecInterface;
+/**
+ * A decoded bitmap that can only be read: what {@link deserializePortable} returns. Its ids come out ascending when
+ * it is iterated, which is a promise. It is a `PortableBitmap`, so a load takes it as `{ bitmap }`, and the library
+ * keeps no reference to it. What {@link deserializePortable} returns has these members only: a call to any other
+ * throws `TypeError`, it has no `getSerializationSizeInBytes`, and `serialize` takes exactly `'portable'`. Its class
+ * is not part of the contract: do not cast it and do not test it with `instanceof`. Passed to a method of the `roaring`
+ * package from npm in place of a `RoaringBitmap32`, it answers wrongly: decode its bytes first. `JSON.stringify` of one gives `"{}"`; write
+ * `JSON.stringify([...bitmap])`. For the rest of a Roaring library's API, decode its portable bytes with that library.
  */
-export declare const roaringCodec: CodecInterface;
+export interface ReadonlyBitmap extends PortableBitmap, Iterable<number> {
+    /** How many ids it holds. */
+    readonly size: number;
+    /** Whether it holds `id`. */
+    has(id: number): boolean;
+}
 /**
- * Decode portable Roaring bytes you hold into a `RoaringBitmap32`, through the check a `{ serialized }` load makes
- * first: a size cap, a structural check, one whole bitmap, and only then the native decoder.
+ * Decode portable Roaring bytes you hold into a {@link ReadonlyBitmap}, through the check a `{ serialized }` load
+ * makes first: a size cap, a structural check, one whole bitmap, and only then the decoder.
  *
  * @param bytes a `Uint8Array`, which a Node `Buffer` is.
  * @throws {ValidationError} for bytes that are not exactly one well-formed portable bitmap, as a load refuses them.
  */
-export declare function deserializePortable(bytes: Uint8Array): RoaringBitmap32;
-export {};
+export declare function deserializePortable(bytes: Uint8Array): ReadonlyBitmap;

package/package.json

@@ -1,13 +1,12 @@
 {
   "name": "@cloudbitmaps/roaring",
-  "version": "0.22.0",
+  "version": "0.24.0",
   "description": "Distributed, cloud-native Roaring Bitmaps — query and intersect billion-scale integer sets straight out of object storage, from a bounded RAM cache over immutable objects in your own bucket, at a fraction of an always-on cache.",
   "keywords": [
     "roaring",
     "bitmap",
     "roaring-bitmap",
     "roaring-bitmaps",
-    "croaring",
     "bitset",
     "compressed-bitmap",
     "lambda",
@@ -48,7 +47,8 @@
     ".": {
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
-    }
+    },
+    "./package.json": "./package.json"
   },
   "files": [
     "dist",
@@ -64,8 +64,7 @@
     "export-segments": "./dist/bin/export-segments.js"
   },
   "dependencies": {
-    "roaring": "2.7.0",
-    "@cloudbitmaps/core": "^0.22.0"
+    "@cloudbitmaps/core": "0.24.0"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",