@cloudbitmaps/roaring 0.19.1 → 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,10 +10,12 @@
  *
  * 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 } from '@cloudbitmaps/core';
+import type { GenKey, IStorageDriver, SegmentRef, StorageDeleteOptions } from '@cloudbitmaps/core';
 export declare class OpenChargingStorage implements IStorageDriver {
     private readonly inner;
     private readonly charge;
@@ -29,6 +31,7 @@ export declare class OpenChargingStorage implements IStorageDriver {
     getRange(key: GenKey, offset: number, length: number): Promise<Uint8Array>;
     /** One `getTail` is one open: a reader takes the footer and the index from it, and reads chunks with `getRange`. */
     getTail(key: GenKey, maxBytes: number): ReturnType<IStorageDriver['getTail']>;
-    delete(key: GenKey): Promise<void>;
+    /** Handed through whole: the erasure's delete of a holder is conditioned on the object it searched. */
+    delete(key: GenKey, options?: StorageDeleteOptions): Promise<void>;
     list(ref: SegmentRef): AsyncIterable<GenKey>;
 }

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

@@ -15,13 +15,13 @@ 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' | 'delete of an absent key beside its neighbours' | 'list read-after-delete' | 'names and namespaces kept apart' | 'generations by number' | 'failed write' | 'missing location' | 'list across pages';
+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' | 'names and namespaces kept apart' | 'generations by number' | 'failed write' | 'missing location' | 'list across pages' | 'conditional 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` (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.
+ * 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
  * skip is visible at the call site, with the reason beside it, rather than hidden in a weakened assertion.
@@ -47,6 +47,13 @@ export declare function storageDriverConformance(label: string, makeDriver: () =
      * driver that drops its continuation token fails. Omitted, the case does not run.
      */
     readonly pagedListSize?: number;
+    /**
+     * What the driver under test reports as `capabilities().conditionalDelete` once it has made a delete given
+     * `ifVersion`, which is when a driver that resolves it lazily has resolved it. Stated at the call site, so a driver
+     * that stops applying the condition fails here rather than being exempted by its own report. Omitted, the case
+     * holds the driver to whatever it reports.
+     */
+    readonly conditionalDelete?: boolean;
 }): void;
 /**
  * Contract tests for an {@link IRegistryDriver}. `makeDriver` MUST return a fresh, empty, isolated driver on
@@ -92,8 +99,8 @@ export interface RegistryDeleteHarness {
     /** 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).
+     * Put `text` at `ref`'s row, as another writer left it: here, a row stamped with an earlier schema. Omitted by a
+     * registry that persists nothing a test can plant (the in-memory one).
      */
     plantRow?(ref: SegmentRef, text: string): Promise<void>;
 }
@@ -101,10 +108,8 @@ export interface RegistryDeleteHarness {
  * 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.
+ * - **`true`**: a delete removes the row from the backend for good, and does so only while the row is still the
+ *   version it read.
  * - **`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

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.19.1",
+  "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.19.1"
+    "@cloudbitmaps/core": "^0.21.0"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",