@cloudbitmaps/roaring 0.11.1 → 0.12.0

package/dist/portable/layout.d.ts

@@ -1,3 +1,4 @@
+import type { EncodedChunk } from '@cloudbitmaps/core';
 /** A container of sorted `u16` values. */
 export declare const ARRAY = 0;
 /** A container of 65,536 bits. */
@@ -27,6 +28,24 @@ export declare function parsePortableLayout(bytes: Uint8Array): PortableContaine
  * {@link parsePortableLayout}'s check alone, for a caller that hands the bytes to another decoder afterwards and
  * so has no use for the layout: it allocates nothing per container.
  *
+ * @returns where the bitmap ends: the offset one past its last container's last byte (0 for an empty buffer). A
+ * caller that needs the buffer to be exactly one bitmap compares it with the buffer's length.
  * @throws {IntegrityError} exactly where {@link parsePortableLayout} does.
  */
-export declare function checkPortableLayout(bytes: Uint8Array): void;
+export declare function checkPortableLayout(bytes: Uint8Array): number;
+/**
+ * Each container of the portable bitmap in `bytes`, as the one-container portable bitmap a `.crbm` chunk stores:
+ * its key moved to 0, its cardinality and kind kept, its body copied unchanged. These are exactly the bytes the
+ * native serializer writes for a bitmap holding only that container's low 16 bits, so a chunk cut from a whole
+ * bitmap is the chunk built from its ids, provided the whole bitmap was encoded canonically first.
+ *
+ * Lazy, one container per step, and each container checked as it is copied, by the same rules as
+ * {@link checkPortableLayout} (keys in order, and each body holding what its header says), so a stored chunk is
+ * never one a reader refuses. The bytes are the native serializer's, of a bitmap decoded from bytes that passed the
+ * check, so on every honest input this finds nothing. It is what stands between a store and a bitmap decoded from a
+ * buffer another thread was still writing during the load's call: the check saw the bytes as they were, the decode
+ * as they became.
+ *
+ * @throws {IntegrityError} at the first container that runs past the buffer or does not hold what its header says.
+ */
+export declare function containerPayloads(bytes: Uint8Array): Generator<EncodedChunk>;

package/dist/roaring-codec.d.ts

@@ -1,4 +1,4 @@
-import type { CodecBitmap, CodecInterface } from '@cloudbitmaps/core';
+import type { CodecBitmap, CodecInterface, EncodedChunk, LoadInput } from '@cloudbitmaps/core';
 export declare class SafeBitmap implements CodecBitmap {
     private readonly bitmap;
     private constructor();
@@ -7,14 +7,18 @@ export declare class SafeBitmap implements CodecBitmap {
     /**
      * 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.
+     * 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): SafeBitmap;
+    static safeDeserialize(bytes: Uint8Array, maxBytes: number, options?: {
+        readonly whole?: boolean;
+    }): SafeBitmap;
     serialize(): Uint8Array;
     /**
      * Convert containers to run-encoding where that is smaller. Representation only — membership is untouched, and
@@ -33,8 +37,23 @@ export declare class SafeBitmap implements CodecBitmap {
      *
      * 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
@@ -60,6 +79,12 @@ export declare class SafeBitmap implements CodecBitmap {
     [Symbol.iterator](): IterableIterator<number>;
     toArray(): number[];
 }
+/**
+ * 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.
+ */
+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

package/dist/testing/conformance.d.ts

@@ -1,5 +1,5 @@
 import { SafeBitmap } from '../roaring-codec.js';
-import type { StorageChunkSource, IRegistryDriver, IStorageDriver } from '@cloudbitmaps/core';
+import type { StorageChunkSource, IRegistryDriver, IStorageDriver, SegmentRef } from '@cloudbitmaps/core';
 /**
  * The segment every conformance seeder must write. Exported so a driver's own test file derives the name
  * instead of restating it — a second copy that drifts makes the suite query a segment nobody seeded, which
@@ -15,11 +15,12 @@ export declare function storageChunkSourceConformance(label: string, makeSource:
     bitmap: SafeBitmap;
 }>) => Promise<StorageChunkSource>): void;
 /** The storage-driver cases {@link storageDriverConformance} runs; an emulator that cannot model one skips it by name. */
-export type StorageDriverCase = 'write-once round trip' | 'collision' | 'collision on a large upload' | 'missing object' | 'out-of-range read' | 'tail size' | 'idempotent delete' | 'list read-after-delete';
+export type StorageDriverCase = 'write-once round trip' | 'collision' | 'collision on a large upload' | 'missing object' | 'out-of-range read' | 'tail size' | 'idempotent delete' | 'delete of an absent key beside its neighbours' | 'list read-after-delete';
 /**
  * Contract tests for an {@link IStorageDriver} — the contract its doc comment lists: write-once with
  * `WriteConflictError` on a collision, `NotFoundError` for a missing object, `ValidationError` for an out-of-range
- * read, `getTail`'s true total size, idempotent `delete`, and a `list` that is read-after-delete. `makeDriver` MUST
+ * read, `getTail`'s true total size, idempotent `delete` (of an absent key too, with neighbours present), and a `list`
+ * that is read-after-delete. `makeDriver` MUST
  * return a driver over an empty, isolated keyspace on each call.
  *
  * `skip` names the cases a backend cannot exercise (a local emulator that does not model a contract), so each
@@ -52,3 +53,34 @@ export declare function registryConformance(label: string, makeDriver: () => IRe
  * writes were not fenced at all. These cases are what make the fence testable.
  */
 export declare function registryConcurrency(label: string, makeDrivers: () => readonly [IRegistryDriver, IRegistryDriver]): void;
+/**
+ * What {@link registryDeleteConformance} needs to see past the port: the driver, and the backend behind it.
+ *
+ * `stored` says whether the backend still holds anything for a row, a tombstone included. Through the port a deleted
+ * row and a tombstoned one look the same (`get` answers `null`, `list` skips both); what tells them apart is whether
+ * a later full listing still has an object to read, which is the cost a hard delete exists to remove.
+ */
+export interface RegistryDeleteHarness {
+    readonly driver: IRegistryDriver;
+    /** Whether the backend holds anything for `ref`: a live row, or the tombstone a delete left in its place. */
+    stored(ref: SegmentRef): Promise<boolean>;
+    /**
+     * Put `text` at `ref`'s row, as another writer left it: here, a row as a release before 0.12 wrote it. Omitted by
+     * a registry that persists nothing a test can plant (the in-memory one).
+     */
+    plantRow?(ref: SegmentRef, text: string): Promise<void>;
+}
+/**
+ * Contract tests for what `delete` leaves behind, which differs by driver and is declared by
+ * `capabilities().conditionalDelete`:
+ *
+ * - **`true`**: a delete removes a row whose token carries an incarnation id from the backend for good, and does so
+ *   only while the row is still the version it read. A row a release before 0.12 wrote has a bare decimal token and
+ *   is tombstoned, never removed: a process still on that release, re-creating the name over nothing, would issue
+ *   those same counters again from 0.
+ * - **`false` or absent**: every delete leaves a tombstone, which a later full listing still reads.
+ *
+ * Either way `get` answers `null` afterwards, `list` skips the row, and a name created again is a new incarnation that
+ * refuses every token an earlier one held.
+ */
+export declare function registryDeleteConformance(label: string, make: () => RegistryDeleteHarness): void;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cloudbitmaps/roaring",
-  "version": "0.11.1",
+  "version": "0.12.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",
@@ -65,7 +65,7 @@
   },
   "dependencies": {
     "roaring": "2.7.0",
-    "@cloudbitmaps/core": "^0.11.1"
+    "@cloudbitmaps/core": "^0.12.0"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",