@cloudbitmaps/roaring 0.16.0 → 0.17.0

package/dist/lease-guards.d.ts

@@ -0,0 +1,34 @@
+/**
+ * The checks a stream makes of a lease: before its first pull, and each time it reads a chunk. Kept apart from the store
+ * so each can be held on its own, and so a stream of another shape (a rank read, a plain iterable of ids) is wrapped by
+ * the same function.
+ */
+import type { CodecBitmap } from '@cloudbitmaps/core';
+/** What an id stream is, as far as a guard is concerned: ids, and the same ids a chunk at a time. */
+interface IdStream extends AsyncIterable<number> {
+    batches(): AsyncIterable<Uint32Array>;
+}
+/** A combine's chunks, as an `*Into` writes them. */
+type ChunkStream = AsyncIterable<{
+    chunkKey: number;
+    bitmap: CodecBitmap;
+}>;
+/**
+ * A stream of ascending ids that checks a lease before it first pulls, and each time it reads a chunk after that: once
+ * the engine has the next chunk and before an id of it is yielded, so nothing of a chunk fetched past the lease is
+ * served. Ids ascend, so a chunk is entered when `id >>> 16` changes. The check before the first pull is what stops a
+ * stream built while the lease was live, and pulled after it ended, ending empty without ever checking. A throw ends the
+ * engine's reads. Used only when a handle in the call holds a lease: a call with none returns the engine's stream
+ * untouched. It takes any async iterable of ids, so a stream with no `.batches()` (a rank read) is wrapped the same way.
+ */
+export declare const guardIdIterable: (inner: AsyncIterable<number>, check: () => void) => AsyncIterable<number>;
+/** {@link guardIdIterable} for an `IdStream`, whose `.batches()` is guarded too. */
+export declare const guardIds: (inner: IdStream, check: () => void) => IdStream;
+/**
+ * A stream of chunks (a batch of ids, or a chunk an `*Into` writes) that checks a lease before the first pull and before
+ * each item is handed on: an item is one chunk.
+ */
+export declare const guardItems: <T>(inner: AsyncIterable<T>, check: () => void) => AsyncIterable<T>;
+/** A chunk stream (what an `*Into` writes) that checks a lease before the first pull and before each chunk. */
+export declare const guardChunks: (inner: ChunkStream, check: () => void) => ChunkStream;
+export {};

package/dist/roaring-codec.d.ts

@@ -1,4 +1,16 @@
+/**
+ * SafeBitmap — the thin wrapper around the `roaring` (CRoaring) engine that owns the
+ * untrusted-bytes boundary.
+ *
+ * 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`).
+ */
+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();
@@ -19,6 +31,8 @@ export declare class SafeBitmap implements CodecBitmap {
     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
@@ -93,3 +107,12 @@ export declare function bitmapAsLoadInput(input: LoadInput): LoadInput;
  * caller supplies a codec.
  */
 export declare const roaringCodec: CodecInterface;
+/**
+ * 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.
+ *
+ * @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 {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cloudbitmaps/roaring",
-  "version": "0.16.0",
+  "version": "0.17.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.16.0"
+    "@cloudbitmaps/core": "^0.17.0"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",