@cloudbitmaps/roaring 0.20.0 → 0.21.0

package/dist/lease-guards.d.ts

@@ -2,17 +2,31 @@
  * 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.
+ *
+ * ```
+ *   caller ── next() ──> guarded stream ── next() ──> engine's stream
+ *                         │  check before the first pull
+ *                         │  check again at each chunk (or each item)
+ *                         └─ a throwing check ends the engine's stream, then rejects
+ *   return() / throw() ─────────────────────────────> engine's stream (ended / thrown into)
+ * ```
+ *
+ * A guarded stream is its own iterator and single-use, as the engine's generator it wraps is: it answers `next`,
+ * `return` and `throw`, and iterating it gives it back.
  */
-import type { CodecBitmap } from '@cloudbitmaps/core';
+/** An async iterator that is also its own iterable, with `return` and `throw` always present, as a generator's are. */
+interface GuardedStream<T> extends AsyncIterableIterator<T> {
+    return(value?: unknown): Promise<IteratorResult<T, unknown>>;
+    throw(err: unknown): Promise<IteratorResult<T, unknown>>;
+}
 /** 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;
-}>;
+/** An id stream that is guarded: the per-id stream is an iterator of its own, and `batches()` is guarded too. */
+type GuardedIds = GuardedStream<number> & {
+    batches(): GuardedStream<Uint32Array>;
+};
 /**
  * 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
@@ -21,14 +35,12 @@ type ChunkStream = AsyncIterable<{
  * 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>;
+export declare const guardIdIterable: (inner: AsyncIterable<number>, check: () => void) => GuardedStream<number>;
 /** {@link guardIdIterable} for an `IdStream`, whose `.batches()` is guarded too. */
-export declare const guardIds: (inner: IdStream, check: () => void) => IdStream;
+export declare const guardIds: (inner: IdStream, check: () => void) => GuardedIds;
 /**
- * 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.
+ * A stream of chunks that checks a lease before the first pull and before each item is handed on: an item is one
+ * chunk (a batch of ids, or a chunk an `*Into` writes).
  */
-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 declare const guardItems: <T>(inner: AsyncIterable<T>, check: () => void) => GuardedStream<T>;
 export {};

package/dist/open-charging-storage.d.ts

@@ -10,8 +10,10 @@
  *
  * Two opens are never charged, because the segment's unit already pays for them: the generation the row named when
  * the scan listed it, which every erasure must read to decide membership, and an object this call wrote itself,
- * which it reads back to verify. A refusal here comes from a read, and in an erasure the reads that can be refused
- * come before the deletes.
+ * which it reads back to verify. A refusal here comes from a read. Most of an erasure's reads that can be refused come
+ * before its deletes; two kinds come after one: the look for a holder left once the call has deleted, and the zero-byte
+ * read of a generation the call deleted that the row then names. A refusal of either is thrown in place of the call's
+ * answer, so the call reports the budget, not what it deleted.
  */
 import type { GenKey, IStorageDriver, SegmentRef, StorageDeleteOptions } from '@cloudbitmaps/core';
 export declare class OpenChargingStorage implements IStorageDriver {

package/dist/options.d.ts

@@ -0,0 +1,30 @@
+/**
+ * The shape checks every call that takes an options bag makes before it reads or writes anything: the bag is an
+ * object, it names only keys the call takes, and each switch is a boolean. The per-call key tables stay with the
+ * facade, because each is held to the options type it describes.
+ */
+import { ValidationError } from '@cloudbitmaps/core';
+/** A key of `T` that `K` does not list: a key table missing one fails to compile. */
+type Unlisted<T, K extends readonly PropertyKey[]> = Exclude<keyof T, K[number]>;
+/** The keys of `T`, every one of them, as a table the options check below reads. */
+export declare const keysOf: <T>() => <const K extends readonly (keyof T & string)[]>(keys: K & ([Unlisted<T, K>] extends [never] ? unknown : never)) => readonly string[];
+/** How a value of the wrong kind is named in a message: by its kind, never by its content. */
+export declare const kindOf: (v: unknown) => string;
+/**
+ * Why `options` cannot be a call's options, or `undefined` when it can. `undefined` and `null` read as none; anything
+ * but an object is refused, and so is a key `known` does not list, unless its value is `undefined`, so a spread of
+ * options keeps working; and each of `booleans` present must be a boolean, `null` included. A bag of the wrong shape, a misspelt key or
+ * a switch given as a string would otherwise read as no option at all, and silently widen what the call does: a scope
+ * passed as a string swept every namespace, and `dryRun: 'true'` deleted.
+ */
+export declare function optionsError(options: unknown, op: string, known: readonly string[], booleans?: readonly string[]): ValidationError | undefined;
+/**
+ * The keys of `options` a call takes, each read by name. A spread copies only own enumerable properties, so an option
+ * held in a getter or inherited from a prototype, which TypeScript accepts and {@link optionsError} reads, would pass
+ * the checks and then be dropped: a `dryRun` so held ran a real sweep, and a `namespace` exported every tenant. The
+ * call then reads the copy only, so it runs with exactly what was checked.
+ */
+export declare function picked<T extends object>(options: T | null | undefined, keys: readonly string[]): Partial<T>;
+/** {@link optionsError}, thrown: for a call that rejects, rather than one that returns a stream. */
+export declare function checkOptions(options: unknown, op: string, known: readonly string[], booleans?: readonly string[]): void;
+export {};

package/dist/portable/decode.d.ts

@@ -4,7 +4,7 @@
  * Construction checks every container once, in {@link parsePortableLayout}, which is the same check the native
  * path runs; after that a membership test reads one container rather than materializing the set.
  */
-export declare class PortableRoaringReader {
+declare class PortableRoaringReader {
     private readonly view;
     private readonly containers;
     private constructor();
@@ -51,3 +51,4 @@ export declare class PortableRoaringReader {
 }
 /** Convenience wrapper over {@link PortableRoaringReader.decode}. */
 export declare function decodePortableRoaring(bytes: Uint8Array): PortableRoaringReader;
+export {};

package/dist/portable/layout.d.ts

@@ -4,8 +4,8 @@ export declare const ARRAY = 0;
 /** A container of 65,536 bits. */
 export declare const BITMAP = 1;
 /** A container of `(start, length)` runs. */
-export declare const RUN = 2;
-export type ContainerKind = typeof ARRAY | typeof BITMAP | typeof RUN;
+declare const RUN = 2;
+type ContainerKind = typeof ARRAY | typeof BITMAP | typeof RUN;
 export interface PortableContainer {
     /** High 16 bits of every value in this container. */
     readonly key: number;
@@ -49,3 +49,4 @@ export declare function checkPortableLayout(bytes: Uint8Array): number;
  * @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>;
+export {};

package/dist/testing/conformance.d.ts

@@ -19,8 +19,8 @@ export type StorageDriverCase = 'write-once round trip' | 'collision' | 'collisi
 /**
  * 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` (of an absent key too, with neighbours present), a `list`
- * that is read-after-delete, and a `delete` given `ifVersion` that does what `conditionalDelete` says. `makeDriver`
+ * read, `getTail`'s true total size, idempotent `delete` (of an absent key too, with neighbours present) after which a
+ * read of the key is `NotFoundError` at once, a `list` that is read-after-delete, and a `delete` given `ifVersion` that does what `conditionalDelete` says. `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

package/dist/wire-store.d.ts

@@ -0,0 +1,38 @@
+import type { Clock, IMetricsSink, IKeystore, IRegistryDriver, IStorageDriver, RetryPolicy, RetryingOptions, Rng, StorageChunkSource } from '@cloudbitmaps/core';
+/** The slice of a store's options the wiring reads; `CloudRoaringOptions` satisfies it. */
+interface StoreWiring {
+    readonly storage: unknown;
+    readonly encryption?: {
+        readonly keystore?: IKeystore;
+        readonly required?: boolean;
+    };
+    readonly cache?: {
+        readonly genTtlMs?: number;
+        readonly readerMax?: number;
+        readonly readerMaxBytes?: number;
+    };
+    readonly retry?: (Partial<RetryPolicy> & {
+        readonly onRetry?: (info: {
+            attempt: number;
+            delayMs: number;
+            err: unknown;
+        }) => void;
+    }) | false;
+}
+/** What {@link wireStore} builds for the constructor. */
+interface WiredStore {
+    /** What the engine reads through: the source, wrapped in the read retry unless it is off. */
+    readonly storage: StorageChunkSource;
+    /** The resolved source before the retry wrapper. */
+    readonly source: StorageChunkSource;
+    readonly driver: IStorageDriver | undefined;
+    readonly registry: IRegistryDriver | undefined;
+    /** The read retry the store shares with its lifecycle reads; `undefined` when retry is off. */
+    readonly retryOptions: RetryingOptions | undefined;
+}
+/**
+ * Resolve the storage seam, hand a backend the metrics sink, and wrap the source in the read retry. Refusals come in
+ * that order: a bad `storage` first, then a bad `retry`.
+ */
+export declare function wireStore(options: StoreWiring, clock: Clock, rng: Rng, metrics: IMetricsSink): WiredStore;
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cloudbitmaps/roaring",
-  "version": "0.20.0",
+  "version": "0.21.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.20.0"
+    "@cloudbitmaps/core": "^0.21.0"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",