@quereus/store 4.10.0 → 4.12.0

package/dist/src/common/kv-store.d.ts

@@ -16,7 +16,11 @@ export interface IterateOptions {
     lt?: Uint8Array;
     /** Iterate in reverse order. */
     reverse?: boolean;
-    /** Maximum number of entries to return. */
+    /**
+     * Maximum number of entries to return. Omitted means unbounded and `0` means no
+     * entries; a NEGATIVE limit is not a valid input — backends disagree on it
+     * (`abstract-level` reads `-1` as unbounded, the in-memory store as zero).
+     */
     limit?: number;
 }
 /**
@@ -114,6 +118,14 @@ export interface AtomicBatch {
 /**
  * Abstract key-value store interface.
  * Provides sorted key-value storage with range iteration support.
+ *
+ * BUFFER OWNERSHIP. Every buffer crossing this interface is independent of the store's
+ * internal state: `get` and `iterate` hand back buffers the caller may scribble on
+ * without corrupting stored data, and `put`/`delete` do not retain the caller's buffer,
+ * so mutating it afterwards changes nothing stored. A backend that deserializes per read
+ * (LevelDB, IndexedDB) gets this for free; one holding live buffers (the in-memory store,
+ * a cache wrapper) must copy at the boundary. Tiers 1 and 3 of
+ * `runKVStoreConformance` enforce it.
  */
 export interface KVStore {
     /**
@@ -121,6 +133,34 @@ export interface KVStore {
      * @returns The value, or undefined if not found.
      */
     get(key: Uint8Array): Promise<Uint8Array | undefined>;
+    /**
+     * Point-read several keys at once.
+     *
+     * POSITIONAL. `result[i]` is the value for `keys[i]`, `undefined` when that key is
+     * absent. The result array is always exactly `keys.length` long — a missing key must
+     * never shorten it or shift the ones after it — and a key repeated in `keys` yields
+     * its value at every position it occupies. `getMany([])` resolves to `[]` without
+     * touching backing storage.
+     *
+     * ONE ROUND TRIP WHERE THE BACKEND HAS ONE. This exists because the caller-side
+     * alternative — awaiting `get` per key — serializes N round trips, and on IndexedDB
+     * each `get` opens its own readonly transaction, so resolving the rows behind an
+     * index scan cost one transaction PER ROW. A backend with a native multi-get
+     * (`abstract-level`) or a way to issue every request on one transaction (IndexedDB)
+     * must override; everything else delegates to {@link defaultGetMany}, which is
+     * correct but no faster than the loop it replaces.
+     *
+     * BOUNDED BY THE CALLER. Unlike {@link iterate} there is no internal paging: the
+     * implementation reads exactly the keys it was handed, so the CALLER owns peak
+     * memory and must pass a bounded batch (`StoreTableScan` pages at
+     * `ROW_RESOLUTION_BATCH`).
+     *
+     * Same buffer-ownership rule as {@link get}: the caller may scribble on what it gets
+     * back without corrupting stored data. That extends ACROSS positions — a key repeated
+     * in `keys` must come back as two independent buffers, not one object at two indices,
+     * or scribbling on one silently rewrites the other.
+     */
+    getMany(keys: readonly Uint8Array[]): Promise<(Uint8Array | undefined)[]>;
     /**
      * Put a key-value pair.
      * @param options - Optional per-write durability hint (see {@link WriteOptions}).
@@ -138,6 +178,46 @@ export interface KVStore {
     /**
      * Iterate over key-value pairs in sorted order.
      * Keys are compared lexicographically by bytes.
+     *
+     * BOUNDED PEAK. Peak memory must be independent of how many entries the range
+     * holds. An implementation may buffer a FIXED-SIZE batch — IndexedDB pages 256
+     * entries at a time, `abstract-level` hands back one entry per `next()` — but it
+     * must never read the whole range before yielding the first entry. Reason: a full
+     * table scan calls `iterate(buildFullScanBounds())` with NO limit, and the mobile
+     * backends that run this code have the least memory headroom of any of them.
+     *
+     * A backend whose dataset is already wholly resident in memory by construction
+     * (`InMemoryKVStore`) satisfies this trivially — the requirement bounds reads from
+     * BACKING STORAGE, and such a backend has none.
+     *
+     * EARLY TERMINATION IS CHEAP. A consumer that stops after k entries must cost
+     * roughly k entries of work, not the size of the range: `limit: 10` over a million
+     * rows must not read a million rows. Concretely, reads from backing storage must
+     * stay within `k + (one batch)`, whatever the implementation's batch size is.
+     *
+     * TOTAL WORK IS LINEAR. Draining the whole range must read about one entry per
+     * entry. A paged backend resumes from the LAST KEY SEEN — never by re-reading from
+     * the start and discarding a growing prefix. `limit`/`offset` paging is O(n²) reads
+     * yet still looks fine to a peak-memory check, so this is stated separately.
+     *
+     * EARLY TERMINATION RELEASES RESOURCES. When the consumer `break`s or throws, the
+     * returned iterable's `return()`/`throw()` runs; the implementation must close its
+     * cursor / transaction / statement there — a `try/finally` around the yield loop —
+     * not only on natural exhaustion. After an abandoned iteration the store must still
+     * serve `get`/`iterate` normally and `close()` must still resolve.
+     *
+     * NO SNAPSHOT PROMISE. Batching splits one logical read into several physical ones,
+     * so a write committed mid-scan may become visible partway through a scan where a
+     * single-shot read could not have shown it. `iterate` therefore does NOT promise a
+     * point-in-time view and consumers must not assume one. This is honest about what
+     * the stack already does: `StoreTable`'s scan merges the transaction coordinator's
+     * pending ops over the committed range, and the store stack declares
+     * `readCommittedSnapshot: false`. A real snapshot read is separate, future work.
+     *
+     * Backends without a streaming cursor (a SQL `select` hands back a whole result set)
+     * should page with {@link pagedIterate} rather than re-deriving the resume edge.
+     * `runKVStoreConformance`'s bounded-iteration tier enforces all of the above for any
+     * backend whose adapter supplies a read meter.
      */
     iterate(options?: IterateOptions): AsyncIterable<KVEntry>;
     /**
@@ -154,6 +234,25 @@ export interface KVStore {
      */
     approximateCount(options?: IterateOptions): Promise<number>;
 }
+/**
+ * The {@link KVStore.getMany} every backend without a real batch point-read delegates to:
+ * one `get` per key, issued together and awaited as a group.
+ *
+ * Concurrency is all it buys — the reads still cost one round trip each — but it is the
+ * CORRECT default everywhere, so adding `getMany` to the interface cannot break a backend
+ * and each one opts into a genuine batch when it has one to opt into. Reading through
+ * `store.get` (rather than the backend's internals) also keeps a wrapper's own `get` in
+ * the path, which is what lets `CachedKVStore` and the counting test doubles keep working.
+ *
+ * `Promise.all([])` resolves to `[]`, satisfying the empty-input rule without a special case.
+ *
+ * NOTE: because no `get` is issued for an empty key list, a backend delegating here answers
+ * `getMany([])` with `[]` even after `close()`, where LevelDB and IndexedDB check open first
+ * and reject. Unspecified rather than wrong — every caller guards the empty case before it
+ * reaches a store (`StoreTableBase.readEffectiveRowsByKeys`). Pin one behavior in tier 8 if
+ * a caller ever hands an empty batch to a closed store.
+ */
+export declare function defaultGetMany(store: Pick<KVStore, 'get'>, keys: readonly Uint8Array[]): Promise<(Uint8Array | undefined)[]>;
 /**
  * Factory function to open a KVStore.
  */
@@ -181,7 +280,15 @@ export interface KVStoreOptions {
  *   {prefix}.__stats__            - Unified stats store (row counts for all tables)
  *   __catalog__                   - Catalog store (DDL metadata)
  *
- * Implementations should manage store lifecycle and caching.
+ * An implementation MUST build those names with `buildDataStoreName` /
+ * `buildIndexStoreName` rather than composing its own. It may prefix or escape the result
+ * to reach a legal native name, but that escaping must be INJECTIVE (decodable in
+ * principle) — two distinct logical names must never produce one native name. A native
+ * namespace that genuinely cannot represent a name must REJECT it, never fold it onto
+ * another. `runStoreNameDistinctness` (`@quereus/store/testing`) enforces this behaviorally.
+ *
+ * Implementations should manage store lifecycle and caching. Cache by the BUILT store name,
+ * so two spellings of one logical store cannot produce two cached handles.
  */
 export interface KVStoreProvider {
     /**
@@ -236,14 +343,45 @@ export interface KVStoreProvider {
     closeAll(): Promise<void>;
     /**
      * Delete an index store entirely (when dropping an index).
+     *
+     * "Delete" means ERASE, not "close the handle": see {@link deleteTableStores} for
+     * exactly what an implementation has to accomplish. Closing a cached handle is not
+     * enough — stores are re-opened lazily by name, so the next index created under this
+     * name would read the dropped index's entries.
+     *
      * @param schemaName - The schema name
      * @param tableName - The table name
      * @param indexName - The index name
      */
     deleteIndexStore?(schemaName: string, tableName: string, indexName: string): Promise<void>;
     /**
-     * Delete all stores for a table (data, indexes, stats).
-     * Called when dropping a table.
+     * Delete a table's data store and the named index stores. Called when dropping a table.
+     *
+     * NOT the table's row-count statistics: those live as one ENTRY in the unified
+     * `__stats__` store (see {@link getStatsStore}), which a provider must leave alone —
+     * removing that entry is the caller's business, not a store deletion.
+     *
+     * "Delete" means ERASE the physical storage, not merely drop a cached handle. Three
+     * requirements, all of them behavioral:
+     *
+     *   - Each named store, RE-OPENED afterwards under the same name via
+     *     `getStore`/`getIndexStore`, must read back EMPTY — no entry from a point `get`,
+     *     none from `iterate`. Handles are re-opened lazily by name, so a provider that
+     *     only closes its handle leaves the bytes in place and the next table created
+     *     under that name comes back holding the dropped table's rows.
+     *   - Deleting a store that was never created is a NO-OP, not an error. The engine
+     *     calls these speculatively on its reclaim paths (see
+     *     `StoreModuleBase.reclaimDetachedTable`), including with index names whose stores
+     *     never materialized.
+     *   - Every OTHER store must be untouched — sibling tables, the table's own index
+     *     stores that were not named, and the reserved `__stats__` / `__catalog__` stores.
+     *
+     * Reclaiming bytes on disk is a separate, per-provider concern: a provider may leave an
+     * emptied database directory or an unshrunk file behind and still be correct here.
+     *
+     * Pinned behaviorally by the shared `runStoreReclaimConformance` battery
+     * (`@quereus/store/testing`), which every plugin's `test/conformance.spec.ts`
+     * registers — the way `runStoreNameDistinctness` pins the naming property.
      *
      * `indexNames` is the authoritative list of the table's secondary-index names
      * (from `tableSchema.indexes`). Implementations MUST build exact index store

package/dist/src/common/kv-store.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"kv-store.d.ts","sourceRoot":"","sources":["../../../src/common/kv-store.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"kv-store.d.ts","sourceRoot":"","sources":["../../../src/common/kv-store.ts"],"names":[],"mappings":"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"}

package/dist/src/common/kv-store.js

@@ -2,5 +2,25 @@
  * Abstract key-value store interface.
  * Implemented by LevelDBStore (Node.js) and IndexedDBStore (browser).
  */
-export {};
+/**
+ * The {@link KVStore.getMany} every backend without a real batch point-read delegates to:
+ * one `get` per key, issued together and awaited as a group.
+ *
+ * Concurrency is all it buys — the reads still cost one round trip each — but it is the
+ * CORRECT default everywhere, so adding `getMany` to the interface cannot break a backend
+ * and each one opts into a genuine batch when it has one to opt into. Reading through
+ * `store.get` (rather than the backend's internals) also keeps a wrapper's own `get` in
+ * the path, which is what lets `CachedKVStore` and the counting test doubles keep working.
+ *
+ * `Promise.all([])` resolves to `[]`, satisfying the empty-input rule without a special case.
+ *
+ * NOTE: because no `get` is issued for an empty key list, a backend delegating here answers
+ * `getMany([])` with `[]` even after `close()`, where LevelDB and IndexedDB check open first
+ * and reject. Unspecified rather than wrong — every caller guards the empty case before it
+ * reaches a store (`StoreTableBase.readEffectiveRowsByKeys`). Pin one behavior in tier 8 if
+ * a caller ever hands an empty batch to a closed store.
+ */
+export function defaultGetMany(store, keys) {
+    return Promise.all(keys.map(key => store.get(key)));
+}
 //# sourceMappingURL=kv-store.js.map

package/dist/src/common/kv-store.js.map

@@ -1 +1 @@
-{"version":3,"file":"kv-store.js","sourceRoot":"","sources":["../../../src/common/kv-store.ts"],"names":[],"mappings":"AAAA;;;GAGG"}
+{"version":3,"file":"kv-store.js","sourceRoot":"","sources":["../../../src/common/kv-store.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAoPH;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,cAAc,CAC7B,KAA2B,EAC3B,IAA2B;IAE3B,OAAO,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;AACrD,CAAC"}

package/dist/src/common/memory-store.d.ts

@@ -17,6 +17,7 @@ export declare class InMemoryKVStore implements KVStore {
     private data;
     private closed;
     get(key: Uint8Array): Promise<Uint8Array | undefined>;
+    getMany(keys: readonly Uint8Array[]): Promise<(Uint8Array | undefined)[]>;
     put(key: Uint8Array, value: Uint8Array, _options?: WriteOptions): Promise<void>;
     delete(key: Uint8Array, _options?: WriteOptions): Promise<void>;
     has(key: Uint8Array): Promise<boolean>;

package/dist/src/common/memory-store.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"memory-store.d.ts","sourceRoot":"","sources":["../../../src/common/memory-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAsBhG;;;GAGG;AACH,qBAAa,eAAgB,YAAW,OAAO;IAC7C,OAAO,CAAC,IAAI,CAA6D;IACzE,OAAO,CAAC,MAAM,CAAS;IAEjB,GAAG,CAAC,GAAG,EAAE,UAAU,GAAG,OAAO,CAAC,UAAU,GAAG,SAAS,CAAC;IAWrD,GAAG,CAAC,GAAG,EAAE,UAAU,EAAE,KAAK,EAAE,UAAU,EAAE,QAAQ,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;IAS/E,MAAM,CAAC,GAAG,EAAE,UAAU,EAAE,QAAQ,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;IAK/D,GAAG,CAAC,GAAG,EAAE,UAAU,GAAG,OAAO,CAAC,OAAO,CAAC;IAKrC,OAAO,CAAC,OAAO,CAAC,EAAE,cAAc,GAAG,aAAa,CAAC,OAAO,CAAC;IAkDhE,KAAK,IAAI,UAAU;IA2Bb,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAKtB,gBAAgB,CAAC,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC;IAajE;;OAEG;IACH,KAAK,IAAI,IAAI;IAKb;;OAEG;IACH,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,OAAO,CAAC,SAAS;CAKlB"}
+{"version":3,"file":"memory-store.d.ts","sourceRoot":"","sources":["../../../src/common/memory-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,OAAO,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAsBhG;;;GAGG;AACH,qBAAa,eAAgB,YAAW,OAAO;IAC7C,OAAO,CAAC,IAAI,CAA6D;IACzE,OAAO,CAAC,MAAM,CAAS;IAEjB,GAAG,CAAC,GAAG,EAAE,UAAU,GAAG,OAAO,CAAC,UAAU,GAAG,SAAS,CAAC;IAY3D,OAAO,CAAC,IAAI,EAAE,SAAS,UAAU,EAAE,GAAG,OAAO,CAAC,CAAC,UAAU,GAAG,SAAS,CAAC,EAAE,CAAC;IAMnE,GAAG,CAAC,GAAG,EAAE,UAAU,EAAE,KAAK,EAAE,UAAU,EAAE,QAAQ,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;IAS/E,MAAM,CAAC,GAAG,EAAE,UAAU,EAAE,QAAQ,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;IAK/D,GAAG,CAAC,GAAG,EAAE,UAAU,GAAG,OAAO,CAAC,OAAO,CAAC;IAKrC,OAAO,CAAC,OAAO,CAAC,EAAE,cAAc,GAAG,aAAa,CAAC,OAAO,CAAC;IA0DhE,KAAK,IAAI,UAAU;IA2Bb,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAKtB,gBAAgB,CAAC,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC;IAajE;;OAEG;IACH,KAAK,IAAI,IAAI;IAKb;;OAEG;IACH,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,OAAO,CAAC,SAAS;CAKlB"}

package/dist/src/common/memory-store.js

@@ -9,6 +9,7 @@
  * Keys are stored using hex encoding for correct lexicographic ordering.
  */
 import { bytesToHex } from './bytes.js';
+import { defaultGetMany } from './kv-store.js';
 /**
  * Convert Uint8Array to hex string for Map key storage.
  * Hex encoding preserves lexicographic ordering. Shared with the coordinator's
@@ -42,6 +43,12 @@ export class InMemoryKVStore {
         const stored = this.data.get(keyToHex(key))?.value;
         return stored === undefined ? undefined : new Uint8Array(stored);
     }
+    // Delegates to `this.get` rather than reading `data` directly: there is no round trip
+    // to save here, and going through the method keeps a subclass's overridden `get` (the
+    // counting doubles several specs subclass this with) in the path.
+    getMany(keys) {
+        return defaultGetMany(this, keys);
+    }
     // `_options` is accepted to satisfy the KVStore signature; an in-memory store
     // has no crash window, so the durability hint is a no-op here.
     async put(key, value, _options) {
@@ -62,7 +69,15 @@ export class InMemoryKVStore {
     }
     async *iterate(options) {
         this.checkOpen();
-        // Sort entries by hex key for correct ordering
+        // Sort entries by hex key for correct ordering.
+        // This materializes and sorts the WHOLE map on every call, so even a `limit: 1`
+        // scan is O(n log n) and allocates an n-entry array. That does not violate
+        // KVStore.iterate's bounded-peak requirement — the requirement bounds reads from
+        // backing storage and this store's dataset is already wholly resident — and it is
+        // fine while the memory store backs test-sized data and build-time seeds.
+        // NOTE: if the memory store ever backs large tables with frequent small-limit
+        // scans, keep a sorted key index (or a sorted-insert structure) instead of
+        // re-sorting per call.
         const entries = Array.from(this.data.entries())
             .sort((a, b) => compareHex(a[0], b[0]));
         // Apply reverse if requested

package/dist/src/common/memory-store.js.map

@@ -1 +1 @@
-{"version":3,"file":"memory-store.js","sourceRoot":"","sources":["../../../src/common/memory-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAGxC;;;;GAIG;AACH,MAAM,QAAQ,GAAG,UAAU,CAAC;AAE5B;;;;;;;;GAQG;AACH,SAAS,UAAU,CAAC,CAAS,EAAE,CAAS;IACtC,OAAO,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC;AAC5B,CAAC;AAED;;;GAGG;AACH,MAAM,OAAO,eAAe;IAClB,IAAI,GAAG,IAAI,GAAG,EAAkD,CAAC;IACjE,MAAM,GAAG,KAAK,CAAC;IAEvB,KAAK,CAAC,GAAG,CAAC,GAAe;QACvB,IAAI,CAAC,SAAS,EAAE,CAAC;QACjB,+EAA+E;QAC/E,+EAA+E;QAC/E,8EAA8E;QAC9E,MAAM,MAAM,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,EAAE,KAAK,CAAC;QACnD,OAAO,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,UAAU,CAAC,MAAM,CAAC,CAAC;IACnE,CAAC;IAED,8EAA8E;IAC9E,+DAA+D;IAC/D,KAAK,CAAC,GAAG,CAAC,GAAe,EAAE,KAAiB,EAAE,QAAuB;QACnE,IAAI,CAAC,SAAS,EAAE,CAAC;QACjB,4CAA4C;QAC5C,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE;YAC3B,GAAG,EAAE,IAAI,UAAU,CAAC,GAAG,CAAC;YACxB,KAAK,EAAE,IAAI,UAAU,CAAC,KAAK,CAAC;SAC7B,CAAC,CAAC;IACL,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,GAAe,EAAE,QAAuB;QACnD,IAAI,CAAC,SAAS,EAAE,CAAC;QACjB,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC;IAClC,CAAC;IAED,KAAK,CAAC,GAAG,CAAC,GAAe;QACvB,IAAI,CAAC,SAAS,EAAE,CAAC;QACjB,OAAO,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC;IACtC,CAAC;IAED,KAAK,CAAC,CAAC,OAAO,CAAC,OAAwB;QACrC,IAAI,CAAC,SAAS,EAAE,CAAC;QAEjB,+CAA+C;QAC/C,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC;aAC5C,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QAE1C,6BAA6B;QAC7B,IAAI,OAAO,EAAE,OAAO,EAAE,CAAC;YACrB,OAAO,CAAC,OAAO,EAAE,CAAC;QACpB,CAAC;QAED,mBAAmB;QACnB,MAAM,MAAM,GAAG,OAAO,EAAE,GAAG,CAAC,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;QAChE,MAAM,KAAK,GAAG,OAAO,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;QAC7D,MAAM,MAAM,GAAG,OAAO,EAAE,GAAG,CAAC,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;QAChE,MAAM,KAAK,GAAG,OAAO,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;QAE7D,IAAI,KAAK,GAAG,CAAC,CAAC;QACd,MAAM,KAAK,GAAG,OAAO,EAAE,KAAK,CAAC;QAE7B,MAAM,OAAO,GAAG,OAAO,EAAE,OAAO,CAAC;QACjC,KAAK,MAAM,CAAC,MAAM,EAAE,EAAE,GAAG,EAAE,KAAK,EAAE,CAAC,IAAI,OAAO,EAAE,CAAC;YAC/C,IAAI,OAAO,EAAE,CAAC;gBACZ,+EAA+E;gBAC/E,IAAI,MAAM,KAAK,SAAS,IAAI,MAAM,GAAG,MAAM;oBAAE,SAAS;gBACtD,IAAI,KAAK,KAAK,SAAS,IAAI,MAAM,IAAI,KAAK;oBAAE,SAAS;gBACrD,IAAI,MAAM,KAAK,SAAS,IAAI,MAAM,GAAG,MAAM;oBAAE,MAAM;gBACnD,IAAI,KAAK,KAAK,SAAS,IAAI,MAAM,IAAI,KAAK;oBAAE,MAAM;YACpD,CAAC;iBAAM,CAAC;gBACN,8EAA8E;gBAC9E,IAAI,MAAM,KAAK,SAAS,IAAI,MAAM,GAAG,MAAM;oBAAE,SAAS;gBACtD,IAAI,KAAK,KAAK,SAAS,IAAI,MAAM,IAAI,KAAK;oBAAE,SAAS;gBACrD,IAAI,MAAM,KAAK,SAAS,IAAI,MAAM,GAAG,MAAM;oBAAE,MAAM;gBACnD,IAAI,KAAK,KAAK,SAAS,IAAI,MAAM,IAAI,KAAK;oBAAE,MAAM;YACpD,CAAC;YAED,cAAc;YACd,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,IAAI,KAAK;gBAAE,MAAM;YAEjD,6EAA6E;YAC7E,6EAA6E;YAC7E,gFAAgF;YAChF,+EAA+E;YAC/E,4BAA4B;YAC5B,MAAM,EAAE,GAAG,EAAE,IAAI,UAAU,CAAC,GAAG,CAAC,EAAE,KAAK,EAAE,IAAI,UAAU,CAAC,KAAK,CAAC,EAAE,CAAC;YACjE,KAAK,EAAE,CAAC;QACV,CAAC;IACH,CAAC;IAED,KAAK;QACH,MAAM,GAAG,GAA2E,EAAE,CAAC;QACvF,MAAM,KAAK,GAAG,IAAI,CAAC;QAEnB,OAAO;YACL,GAAG,CAAC,GAAe,EAAE,KAAiB;gBACpC,GAAG,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,EAAE,IAAI,UAAU,CAAC,GAAG,CAAC,EAAE,KAAK,EAAE,IAAI,UAAU,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;YACpF,CAAC;YACD,MAAM,CAAC,GAAe;gBACpB,GAAG,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,GAAG,EAAE,IAAI,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;YACzD,CAAC;YACD,KAAK,CAAC,KAAK;gBACT,KAAK,MAAM,EAAE,IAAI,GAAG,EAAE,CAAC;oBACrB,IAAI,EAAE,CAAC,IAAI,KAAK,KAAK,EAAE,CAAC;wBACtB,MAAM,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,KAAM,CAAC,CAAC;oBACrC,CAAC;yBAAM,CAAC;wBACN,MAAM,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC;oBAC7B,CAAC;gBACH,CAAC;gBACD,GAAG,CAAC,MAAM,GAAG,CAAC,CAAC;YACjB,CAAC;YACD,KAAK;gBACH,GAAG,CAAC,MAAM,GAAG,CAAC,CAAC;YACjB,CAAC;SACF,CAAC;IACJ,CAAC;IAED,KAAK,CAAC,KAAK;QACT,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC;QACnB,IAAI,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC;IACpB,CAAC;IAED,KAAK,CAAC,gBAAgB,CAAC,OAAwB;QAC7C,IAAI,CAAC,SAAS,EAAE,CAAC;QACjB,IAAI,CAAC,OAAO,EAAE,CAAC;YACb,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC;QACxB,CAAC;QACD,yBAAyB;QACzB,IAAI,KAAK,GAAG,CAAC,CAAC;QACd,IAAI,KAAK,EAAE,MAAM,CAAC,IAAI,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC;YAC5C,KAAK,EAAE,CAAC;QACV,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC;IAED;;OAEG;IACH,KAAK;QACH,IAAI,CAAC,SAAS,EAAE,CAAC;QACjB,IAAI,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC;IACpB,CAAC;IAED;;OAEG;IACH,IAAI,IAAI;QACN,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC;IACxB,CAAC;IAEO,SAAS;QACf,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;YAChB,MAAM,IAAI,KAAK,CAAC,2BAA2B,CAAC,CAAC;QAC/C,CAAC;IACH,CAAC;CACF"}
+{"version":3,"file":"memory-store.js","sourceRoot":"","sources":["../../../src/common/memory-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AACxC,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAG/C;;;;GAIG;AACH,MAAM,QAAQ,GAAG,UAAU,CAAC;AAE5B;;;;;;;;GAQG;AACH,SAAS,UAAU,CAAC,CAAS,EAAE,CAAS;IACtC,OAAO,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC;AAC5B,CAAC;AAED;;;GAGG;AACH,MAAM,OAAO,eAAe;IAClB,IAAI,GAAG,IAAI,GAAG,EAAkD,CAAC;IACjE,MAAM,GAAG,KAAK,CAAC;IAEvB,KAAK,CAAC,GAAG,CAAC,GAAe;QACvB,IAAI,CAAC,SAAS,EAAE,CAAC;QACjB,+EAA+E;QAC/E,+EAA+E;QAC/E,8EAA8E;QAC9E,MAAM,MAAM,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,EAAE,KAAK,CAAC;QACnD,OAAO,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,UAAU,CAAC,MAAM,CAAC,CAAC;IACnE,CAAC;IAED,sFAAsF;IACtF,sFAAsF;IACtF,kEAAkE;IAClE,OAAO,CAAC,IAA2B;QACjC,OAAO,cAAc,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;IACpC,CAAC;IAED,8EAA8E;IAC9E,+DAA+D;IAC/D,KAAK,CAAC,GAAG,CAAC,GAAe,EAAE,KAAiB,EAAE,QAAuB;QACnE,IAAI,CAAC,SAAS,EAAE,CAAC;QACjB,4CAA4C;QAC5C,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE;YAC3B,GAAG,EAAE,IAAI,UAAU,CAAC,GAAG,CAAC;YACxB,KAAK,EAAE,IAAI,UAAU,CAAC,KAAK,CAAC;SAC7B,CAAC,CAAC;IACL,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,GAAe,EAAE,QAAuB;QACnD,IAAI,CAAC,SAAS,EAAE,CAAC;QACjB,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC;IAClC,CAAC;IAED,KAAK,CAAC,GAAG,CAAC,GAAe;QACvB,IAAI,CAAC,SAAS,EAAE,CAAC;QACjB,OAAO,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC;IACtC,CAAC;IAED,KAAK,CAAC,CAAC,OAAO,CAAC,OAAwB;QACrC,IAAI,CAAC,SAAS,EAAE,CAAC;QAEjB,gDAAgD;QAChD,gFAAgF;QAChF,2EAA2E;QAC3E,iFAAiF;QACjF,kFAAkF;QAClF,0EAA0E;QAC1E,8EAA8E;QAC9E,2EAA2E;QAC3E,uBAAuB;QACvB,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC;aAC5C,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QAE1C,6BAA6B;QAC7B,IAAI,OAAO,EAAE,OAAO,EAAE,CAAC;YACrB,OAAO,CAAC,OAAO,EAAE,CAAC;QACpB,CAAC;QAED,mBAAmB;QACnB,MAAM,MAAM,GAAG,OAAO,EAAE,GAAG,CAAC,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;QAChE,MAAM,KAAK,GAAG,OAAO,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;QAC7D,MAAM,MAAM,GAAG,OAAO,EAAE,GAAG,CAAC,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;QAChE,MAAM,KAAK,GAAG,OAAO,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;QAE7D,IAAI,KAAK,GAAG,CAAC,CAAC;QACd,MAAM,KAAK,GAAG,OAAO,EAAE,KAAK,CAAC;QAE7B,MAAM,OAAO,GAAG,OAAO,EAAE,OAAO,CAAC;QACjC,KAAK,MAAM,CAAC,MAAM,EAAE,EAAE,GAAG,EAAE,KAAK,EAAE,CAAC,IAAI,OAAO,EAAE,CAAC;YAC/C,IAAI,OAAO,EAAE,CAAC;gBACZ,+EAA+E;gBAC/E,IAAI,MAAM,KAAK,SAAS,IAAI,MAAM,GAAG,MAAM;oBAAE,SAAS;gBACtD,IAAI,KAAK,KAAK,SAAS,IAAI,MAAM,IAAI,KAAK;oBAAE,SAAS;gBACrD,IAAI,MAAM,KAAK,SAAS,IAAI,MAAM,GAAG,MAAM;oBAAE,MAAM;gBACnD,IAAI,KAAK,KAAK,SAAS,IAAI,MAAM,IAAI,KAAK;oBAAE,MAAM;YACpD,CAAC;iBAAM,CAAC;gBACN,8EAA8E;gBAC9E,IAAI,MAAM,KAAK,SAAS,IAAI,MAAM,GAAG,MAAM;oBAAE,SAAS;gBACtD,IAAI,KAAK,KAAK,SAAS,IAAI,MAAM,IAAI,KAAK;oBAAE,SAAS;gBACrD,IAAI,MAAM,KAAK,SAAS,IAAI,MAAM,GAAG,MAAM;oBAAE,MAAM;gBACnD,IAAI,KAAK,KAAK,SAAS,IAAI,MAAM,IAAI,KAAK;oBAAE,MAAM;YACpD,CAAC;YAED,cAAc;YACd,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,IAAI,KAAK;gBAAE,MAAM;YAEjD,6EAA6E;YAC7E,6EAA6E;YAC7E,gFAAgF;YAChF,+EAA+E;YAC/E,4BAA4B;YAC5B,MAAM,EAAE,GAAG,EAAE,IAAI,UAAU,CAAC,GAAG,CAAC,EAAE,KAAK,EAAE,IAAI,UAAU,CAAC,KAAK,CAAC,EAAE,CAAC;YACjE,KAAK,EAAE,CAAC;QACV,CAAC;IACH,CAAC;IAED,KAAK;QACH,MAAM,GAAG,GAA2E,EAAE,CAAC;QACvF,MAAM,KAAK,GAAG,IAAI,CAAC;QAEnB,OAAO;YACL,GAAG,CAAC,GAAe,EAAE,KAAiB;gBACpC,GAAG,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,EAAE,IAAI,UAAU,CAAC,GAAG,CAAC,EAAE,KAAK,EAAE,IAAI,UAAU,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;YACpF,CAAC;YACD,MAAM,CAAC,GAAe;gBACpB,GAAG,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,GAAG,EAAE,IAAI,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;YACzD,CAAC;YACD,KAAK,CAAC,KAAK;gBACT,KAAK,MAAM,EAAE,IAAI,GAAG,EAAE,CAAC;oBACrB,IAAI,EAAE,CAAC,IAAI,KAAK,KAAK,EAAE,CAAC;wBACtB,MAAM,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,KAAM,CAAC,CAAC;oBACrC,CAAC;yBAAM,CAAC;wBACN,MAAM,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC;oBAC7B,CAAC;gBACH,CAAC;gBACD,GAAG,CAAC,MAAM,GAAG,CAAC,CAAC;YACjB,CAAC;YACD,KAAK;gBACH,GAAG,CAAC,MAAM,GAAG,CAAC,CAAC;YACjB,CAAC;SACF,CAAC;IACJ,CAAC;IAED,KAAK,CAAC,KAAK;QACT,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC;QACnB,IAAI,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC;IACpB,CAAC;IAED,KAAK,CAAC,gBAAgB,CAAC,OAAwB;QAC7C,IAAI,CAAC,SAAS,EAAE,CAAC;QACjB,IAAI,CAAC,OAAO,EAAE,CAAC;YACb,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC;QACxB,CAAC;QACD,yBAAyB;QACzB,IAAI,KAAK,GAAG,CAAC,CAAC;QACd,IAAI,KAAK,EAAE,MAAM,CAAC,IAAI,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC;YAC5C,KAAK,EAAE,CAAC;QACV,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC;IAED;;OAEG;IACH,KAAK;QACH,IAAI,CAAC,SAAS,EAAE,CAAC;QACjB,IAAI,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC;IACpB,CAAC;IAED;;OAEG;IACH,IAAI,IAAI;QACN,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC;IACxB,CAAC;IAEO,SAAS;QACf,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;YAChB,MAAM,IAAI,KAAK,CAAC,2BAA2B,CAAC,CAAC;QAC/C,CAAC;IACH,CAAC;CACF"}

package/dist/src/common/paged-iterate.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Shared batch/resume loop for KVStore backends that cannot stream.
+ *
+ * Some backends have no cursor to hold open across a consumer `await`: a SQL
+ * `select` hands back a whole result set, and an IndexedDB readonly transaction
+ * auto-commits while idle. Those backends satisfy {@link KVStore.iterate}'s
+ * bounded-peak requirement by paging — read a fixed-size batch, yield it, resume
+ * just past the last key seen — so peak memory is one batch regardless of how many
+ * entries the range holds.
+ *
+ * The resume edge is the subtle part, and the reason this lives in one place rather
+ * than being re-derived per backend:
+ *   - forward tightens the LOWER bound, reverse tightens the UPPER bound, both
+ *     EXCLUSIVE so no entry is yielded twice;
+ *   - the resume key is captured BEFORE yielding, because entries are handed to the
+ *     consumer by reference and a consumer that mutates a yielded key must not
+ *     perturb where the next batch resumes from;
+ *   - an exhausted edge can collapse the bounds to an empty range, which must read
+ *     as "exhausted" rather than throw.
+ */
+import type { IterateOptions, KVEntry } from './kv-store.js';
+/**
+ * Fetch up to `want` entries for the given bounds.
+ *
+ * `bounds` is already resume-adjusted and carries `reverse`; it never carries
+ * `limit` — the cap is `want`, passed separately so a backend can push it into its
+ * query. Returning FEWER than `want` entries signals the range is exhausted, so an
+ * implementation must return a full batch whenever one is available. Returning MORE
+ * than `want` is a programming error and {@link pagedIterate} throws on it.
+ */
+export type FetchBatch = (bounds: IterateOptions, want: number) => Promise<KVEntry[]>;
+/**
+ * Drive a non-streaming backend as a bounded async iterable: fetch a batch, yield it,
+ * resume past the last key seen. Peak is one batch regardless of range size, and a
+ * consumer that stops after k entries costs at most one batch beyond k.
+ *
+ * @param options - The caller's iterate options (bounds, `reverse`, `limit`).
+ * @param fetchBatch - Backend read for one batch. See {@link FetchBatch}.
+ * @param batchSize - Entries per batch. Defaults to {@link DEFAULT_BATCH_SIZE}.
+ */
+export declare function pagedIterate(options: IterateOptions | undefined, fetchBatch: FetchBatch, batchSize?: number): AsyncIterable<KVEntry>;
+//# sourceMappingURL=paged-iterate.d.ts.map

package/dist/src/common/paged-iterate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"paged-iterate.d.ts","sourceRoot":"","sources":["../../../src/common/paged-iterate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAGH,OAAO,KAAK,EAAE,cAAc,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAK7D;;;;;;;;GAQG;AACH,MAAM,MAAM,UAAU,GAAG,CAAC,MAAM,EAAE,cAAc,EAAE,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC;AA6CtF;;;;;;;;GAQG;AACH,wBAAuB,YAAY,CAClC,OAAO,EAAE,cAAc,GAAG,SAAS,EACnC,UAAU,EAAE,UAAU,EACtB,SAAS,GAAE,MAA2B,GACpC,aAAa,CAAC,OAAO,CAAC,CAoCxB"}

package/dist/src/common/paged-iterate.js

@@ -0,0 +1,113 @@
+/**
+ * Shared batch/resume loop for KVStore backends that cannot stream.
+ *
+ * Some backends have no cursor to hold open across a consumer `await`: a SQL
+ * `select` hands back a whole result set, and an IndexedDB readonly transaction
+ * auto-commits while idle. Those backends satisfy {@link KVStore.iterate}'s
+ * bounded-peak requirement by paging — read a fixed-size batch, yield it, resume
+ * just past the last key seen — so peak memory is one batch regardless of how many
+ * entries the range holds.
+ *
+ * The resume edge is the subtle part, and the reason this lives in one place rather
+ * than being re-derived per backend:
+ *   - forward tightens the LOWER bound, reverse tightens the UPPER bound, both
+ *     EXCLUSIVE so no entry is yielded twice;
+ *   - the resume key is captured BEFORE yielding, because entries are handed to the
+ *     consumer by reference and a consumer that mutates a yielded key must not
+ *     perturb where the next batch resumes from;
+ *   - an exhausted edge can collapse the bounds to an empty range, which must read
+ *     as "exhausted" rather than throw.
+ */
+import { compareBytes } from './bytes.js';
+/** Default entries per batch when the caller does not pick one. */
+const DEFAULT_BATCH_SIZE = 256;
+/** Derive the lower/upper edges of `options`, preferring the inclusive form. */
+function edgesOf(options) {
+    let lower;
+    let upper;
+    if (options?.gte)
+        lower = { key: options.gte, open: false };
+    else if (options?.gt)
+        lower = { key: options.gt, open: true };
+    if (options?.lte)
+        upper = { key: options.lte, open: false };
+    else if (options?.lt)
+        upper = { key: options.lt, open: true };
+    return { lower, upper };
+}
+/**
+ * True when the edges describe a range that can hold nothing: crossed, or a single
+ * point excluded by either edge. Reached on the resume iteration when a batch fills
+ * exactly to a boundary key that also equals an inclusive opposite bound.
+ */
+function isEmptyRange(lower, upper) {
+    if (!lower || !upper)
+        return false;
+    const c = compareBytes(lower.key, upper.key);
+    return c > 0 || (c === 0 && (lower.open || upper.open));
+}
+/** Rebuild an {@link IterateOptions} from explicit edges, dropping `limit`. */
+function boundsOf(lower, upper, reverse) {
+    const bounds = {};
+    if (lower) {
+        if (lower.open)
+            bounds.gt = lower.key;
+        else
+            bounds.gte = lower.key;
+    }
+    if (upper) {
+        if (upper.open)
+            bounds.lt = upper.key;
+        else
+            bounds.lte = upper.key;
+    }
+    if (reverse)
+        bounds.reverse = true;
+    return bounds;
+}
+/**
+ * Drive a non-streaming backend as a bounded async iterable: fetch a batch, yield it,
+ * resume past the last key seen. Peak is one batch regardless of range size, and a
+ * consumer that stops after k entries costs at most one batch beyond k.
+ *
+ * @param options - The caller's iterate options (bounds, `reverse`, `limit`).
+ * @param fetchBatch - Backend read for one batch. See {@link FetchBatch}.
+ * @param batchSize - Entries per batch. Defaults to {@link DEFAULT_BATCH_SIZE}.
+ */
+export async function* pagedIterate(options, fetchBatch, batchSize = DEFAULT_BATCH_SIZE) {
+    if (!Number.isInteger(batchSize) || batchSize < 1) {
+        throw new Error(`pagedIterate: batchSize must be a positive integer, got ${batchSize}`);
+    }
+    const reverse = options?.reverse ?? false;
+    const { lower, upper } = edgesOf(options);
+    let remaining = options?.limit; // undefined ⇒ unbounded
+    let resumeKey; // last key yielded — exclusive resume edge
+    for (;;) {
+        if (remaining !== undefined && remaining <= 0)
+            return;
+        const want = remaining === undefined ? batchSize : Math.min(batchSize, remaining);
+        // Resume just past the last key seen: forward tightens the lower bound,
+        // reverse tightens the upper bound — exclusive so no entry repeats.
+        const effLower = !reverse && resumeKey !== undefined ? { key: resumeKey, open: true } : lower;
+        const effUpper = reverse && resumeKey !== undefined ? { key: resumeKey, open: true } : upper;
+        if (isEmptyRange(effLower, effUpper))
+            return;
+        const batch = await fetchBatch(boundsOf(effLower, effUpper, reverse), want);
+        if (batch.length > want) {
+            throw new Error(`pagedIterate: fetchBatch returned ${batch.length} entries for want=${want}`);
+        }
+        // Capture the resume boundary BEFORE yielding, and as a COPY: entries go to the
+        // consumer by reference, and a consumer that mutates a yielded key must not move
+        // where the next batch resumes from.
+        const nextResumeKey = batch.length > 0 ? new Uint8Array(batch[batch.length - 1].key) : undefined;
+        for (const entry of batch) {
+            yield entry;
+        }
+        if (remaining !== undefined)
+            remaining -= batch.length;
+        if (batch.length < want)
+            return; // range exhausted before filling the batch
+        resumeKey = nextResumeKey;
+    }
+}
+//# sourceMappingURL=paged-iterate.js.map

package/dist/src/common/paged-iterate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"paged-iterate.js","sourceRoot":"","sources":["../../../src/common/paged-iterate.ts"],"names":[],"mappings":"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"}

package/dist/src/common/pk-key-resolution.d.ts

@@ -305,22 +305,35 @@ export declare function keyOrderMatchesCollation(db: Database, column: ColumnSch
  */
 export declare function indexPrefixSeekIsCollationExact(columns: ReadonlyArray<ColumnSchema>, index: TableIndexSchema, keyCollations: ReadonlyArray<string | undefined>, prefixLength: number): boolean;
 /**
- * True when a byte RANGE window over the LEADING column of secondary `index` is SOUND.
+ * True when a byte RANGE window over index-column `position` of secondary `index` is SOUND.
  *
- * Strictly stronger than {@link indexPrefixSeekIsCollationExact} at position 0: the same
- * key-vs-residual collation agreement, PLUS the collation's `orderPreserving` assertion,
- * because a range window also equates memcmp of the key bytes with the residual
+ * Strictly stronger than {@link indexPrefixSeekIsCollationExact} at the same position: the
+ * same key-vs-residual collation agreement, PLUS the collation's `orderPreserving`
+ * assertion, because a range window also equates memcmp of the key bytes with the residual
  * comparator's ORDER. Both halves are {@link keyOrderMatchesCollation}, which admits a
  * semantic-ordering column only when {@link semanticKeyOrderIsFaithful} asserts its key
  * bytes order as the type's `compare` does (and the collation sides agree — a `collate`
  * decoration on the index column still declines it).
  *
+ * `position` is 0 for a standalone leading-column range (see
+ * {@link indexLeadingRangeIsOrderSafe}) and `prefixLength` for the trailing bound of a
+ * prefix-equality + trailing-range seek. The question is identical at either position: the
+ * columns BEFORE it are pinned to one value each, so the window is a contiguous byte region
+ * whose ordering within the prefix is governed solely by this column's key bytes. What the
+ * pinned columns need is the (weaker) EXACTNESS test — {@link indexPrefixSeekIsCollationExact}
+ * over the prefix — which the callers apply alongside this one.
+ *
  * THE shared predicate for the two decision sites: `tryIndexAccessPlan`
  * (store-module-access-plan.ts) marks the range filters handled only when it holds, and
  * `StoreTableScan.analyzeIndexAccess` builds a window only when it holds. They must agree —
  * a plan that claims a filter the scan then declines to window loses the residual Filter and
  * returns the whole table — so they call this rather than each restating it.
  */
+export declare function indexRangeAtPositionIsOrderSafe(db: Database, columns: ReadonlyArray<ColumnSchema>, index: TableIndexSchema, keyCollations: ReadonlyArray<string | undefined>, position: number): boolean;
+/**
+ * {@link indexRangeAtPositionIsOrderSafe} at position 0 — the standalone leading-column
+ * range window, which needs no equality prefix ahead of it.
+ */
 export declare function indexLeadingRangeIsOrderSafe(db: Database, columns: ReadonlyArray<ColumnSchema>, index: TableIndexSchema, keyCollations: ReadonlyArray<string | undefined>): boolean;
 /**
  * How many LEADING primary-key members have key bytes whose memcmp order matches their

package/dist/src/common/pk-key-resolution.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pk-key-resolution.d.ts","sourceRoot":"","sources":["../../../src/common/pk-key-resolution.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAQN,KAAK,WAAW,EAChB,KAAK,QAAQ,EAEb,KAAK,YAAY,EACjB,KAAK,WAAW,EAChB,KAAK,gBAAgB,EACrB,KAAK,QAAQ,EACb,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EAAE,KAAK,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAGvD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAgB,sBAAsB,CACrC,KAAK,EAAE,aAAa,CAAC;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC,EACvC,OAAO,EAAE,aAAa,CAAC,YAAY,CAAC,EACpC,QAAQ,EAAE,MAAM,GACd,CAAC,MAAM,GAAG,SAAS,CAAC,EAAE,CAUxB;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,yBAAyB,CACxC,KAAK,EAAE,gBAAgB,EACvB,OAAO,EAAE,aAAa,CAAC,YAAY,CAAC,GAClC,CAAC,MAAM,GAAG,SAAS,CAAC,EAAE,CAcxB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,WAAW,GAAG,SAAS,GAAG,iBAAiB,GAAG,SAAS,CAQtG;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,WAAW,GAAG,SAAS,GAAG,iBAAiB,GAAG,SAAS,CAGpG;AAaD;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CACrC,KAAK,EAAE,aAAa,CAAC;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC,EACvC,OAAO,EAAE,aAAa,CAAC,YAAY,CAAC,GAClC,CAAC,iBAAiB,GAAG,SAAS,CAAC,EAAE,CAEnC;AAED;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CACxC,KAAK,EAAE,gBAAgB,EACvB,OAAO,EAAE,aAAa,CAAC,YAAY,CAAC,GAClC,CAAC,iBAAiB,GAAG,SAAS,CAAC,EAAE,CAEnC;AAED;;;;;;GAMG;AACH,wBAAgB,0BAA0B,CACzC,UAAU,EAAE,aAAa,CAAC,MAAM,CAAC,EACjC,OAAO,EAAE,aAAa,CAAC,YAAY,CAAC,GAClC,CAAC,iBAAiB,GAAG,SAAS,CAAC,EAAE,CAEnC;AAED;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CACxC,KAAK,EAAE,aAAa,CAAC;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC,EACvC,OAAO,EAAE,aAAa,CAAC,YAAY,CAAC,GAClC,CAAC,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,QAAQ,KAAK,MAAM,CAAC,GAAG,SAAS,CAAC,EAAE,CAKxD;AAED;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,YAAY,GAAG,SAAS,GAAG,OAAO,CAExE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAgB,0BAA0B,CAAC,IAAI,EAAE,WAAW,GAAG,SAAS,GAAG,OAAO,CAGjF;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,wBAAgB,0BAA0B,CAAC,IAAI,EAAE,WAAW,GAAG,SAAS,EAAE,KAAK,EAAE,QAAQ,GAAG,OAAO,CASlG;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,wBAAgB,wBAAwB,CACvC,EAAE,EAAE,QAAQ,EACZ,MAAM,EAAE,YAAY,GAAG,SAAS,EAChC,YAAY,EAAE,MAAM,EACpB,gBAAgB,EAAE,MAAM,GACtB,OAAO,CAmBT;AAuBD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,+BAA+B,CAC9C,OAAO,EAAE,aAAa,CAAC,YAAY,CAAC,EACpC,KAAK,EAAE,gBAAgB,EACvB,aAAa,EAAE,aAAa,CAAC,MAAM,GAAG,SAAS,CAAC,EAChD,YAAY,EAAE,MAAM,GAClB,OAAO,CAQT;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,4BAA4B,CAC3C,EAAE,EAAE,QAAQ,EACZ,OAAO,EAAE,aAAa,CAAC,YAAY,CAAC,EACpC,KAAK,EAAE,gBAAgB,EACvB,aAAa,EAAE,aAAa,CAAC,MAAM,GAAG,SAAS,CAAC,GAC9C,OAAO,CAST;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,6BAA6B,CAC5C,EAAE,EAAE,QAAQ,EACZ,MAAM,EAAE,WAAW,EACnB,eAAe,EAAE,aAAa,CAAC,MAAM,GAAG,SAAS,CAAC,EAClD,iBAAiB,EAAE,MAAM,GACvB,MAAM,CAUR"}
+{"version":3,"file":"pk-key-resolution.d.ts","sourceRoot":"","sources":["../../../src/common/pk-key-resolution.ts"],"names":[],"mappings":"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"}

package/dist/src/common/pk-key-resolution.js

@@ -422,27 +422,42 @@ export function indexPrefixSeekIsCollationExact(columns, index, keyCollations, p
     return true;
 }
 /**
- * True when a byte RANGE window over the LEADING column of secondary `index` is SOUND.
+ * True when a byte RANGE window over index-column `position` of secondary `index` is SOUND.
  *
- * Strictly stronger than {@link indexPrefixSeekIsCollationExact} at position 0: the same
- * key-vs-residual collation agreement, PLUS the collation's `orderPreserving` assertion,
- * because a range window also equates memcmp of the key bytes with the residual
+ * Strictly stronger than {@link indexPrefixSeekIsCollationExact} at the same position: the
+ * same key-vs-residual collation agreement, PLUS the collation's `orderPreserving`
+ * assertion, because a range window also equates memcmp of the key bytes with the residual
  * comparator's ORDER. Both halves are {@link keyOrderMatchesCollation}, which admits a
  * semantic-ordering column only when {@link semanticKeyOrderIsFaithful} asserts its key
  * bytes order as the type's `compare` does (and the collation sides agree — a `collate`
  * decoration on the index column still declines it).
  *
+ * `position` is 0 for a standalone leading-column range (see
+ * {@link indexLeadingRangeIsOrderSafe}) and `prefixLength` for the trailing bound of a
+ * prefix-equality + trailing-range seek. The question is identical at either position: the
+ * columns BEFORE it are pinned to one value each, so the window is a contiguous byte region
+ * whose ordering within the prefix is governed solely by this column's key bytes. What the
+ * pinned columns need is the (weaker) EXACTNESS test — {@link indexPrefixSeekIsCollationExact}
+ * over the prefix — which the callers apply alongside this one.
+ *
  * THE shared predicate for the two decision sites: `tryIndexAccessPlan`
  * (store-module-access-plan.ts) marks the range filters handled only when it holds, and
  * `StoreTableScan.analyzeIndexAccess` builds a window only when it holds. They must agree —
  * a plan that claims a filter the scan then declines to window loses the residual Filter and
  * returns the whole table — so they call this rather than each restating it.
  */
-export function indexLeadingRangeIsOrderSafe(db, columns, index, keyCollations) {
-    const leading = index.columns[0];
-    if (!leading)
+export function indexRangeAtPositionIsOrderSafe(db, columns, index, keyCollations, position) {
+    const spec = index.columns[position];
+    if (!spec)
         return false;
-    return keyOrderMatchesCollation(db, columns[leading.index], keyCollations[0] ?? 'BINARY', indexResidualCollation(columns, index, 0));
+    return keyOrderMatchesCollation(db, columns[spec.index], keyCollations[position] ?? 'BINARY', indexResidualCollation(columns, index, position));
+}
+/**
+ * {@link indexRangeAtPositionIsOrderSafe} at position 0 — the standalone leading-column
+ * range window, which needs no equality prefix ahead of it.
+ */
+export function indexLeadingRangeIsOrderSafe(db, columns, index, keyCollations) {
+    return indexRangeAtPositionIsOrderSafe(db, columns, index, keyCollations, 0);
 }
 /**
  * How many LEADING primary-key members have key bytes whose memcmp order matches their