@cloudbitmaps/roaring 0.22.0 → 0.23.0

package/dist/roaring-codec.d.ts

@@ -1,16 +1,4 @@
-/**
- * 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>;
+import type { CodecBitmap, CodecInterface, EncodedChunk, LoadInput, PortableBitmap } from '@cloudbitmaps/core';
 export declare class SafeBitmap implements CodecBitmap {
     private readonly bitmap;
     private constructor();
@@ -31,8 +19,6 @@ 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
@@ -96,9 +82,10 @@ export declare class SafeBitmap implements CodecBitmap {
     toUint32Array(): Uint32Array;
 }
 /**
- * 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.
+ * A bare `RoaringBitmap32` of this package's own `roaring`, 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. 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;
 /**
@@ -108,11 +95,25 @@ export declare function bitmapAsLoadInput(input: LoadInput): LoadInput;
  */
 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.
+ * 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 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 {@link ReadonlyBitmap}, 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 {};
+export declare function deserializePortable(bytes: Uint8Array): ReadonlyBitmap;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cloudbitmaps/roaring",
-  "version": "0.22.0",
+  "version": "0.23.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",
@@ -48,7 +48,8 @@
     ".": {
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
-    }
+    },
+    "./package.json": "./package.json"
   },
   "files": [
     "dist",
@@ -65,7 +66,7 @@
   },
   "dependencies": {
     "roaring": "2.7.0",
-    "@cloudbitmaps/core": "^0.22.0"
+    "@cloudbitmaps/core": "0.23.0"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",