@quereus/store 4.14.0 → 4.16.0

package/dist/src/testing/kv-counting-store.js

@@ -0,0 +1,226 @@
+/**
+ * Shared counting test doubles for KVStore-backed specs — test-support, ships in
+ * `@quereus/store/testing`.
+ *
+ * Several specs in this package (and this package's benchmark suite) each need a `KVStore`
+ * that counts what passes through it: on the read side entries pulled from `iterate()`,
+ * `get()` calls, `getMany()` round trips and the keys they carried; on the write side
+ * point writes, `write()` round trips and the operations those carried. This file is the
+ * one shared implementation — see {@link CountingKVStore}'s doc comment for the two
+ * subtleties in how it has to be built.
+ */
+import { defaultGetMany } from '../common/kv-store.js';
+import { buildDataStoreName, buildIndexStoreName, CATALOG_STORE_NAME, STATS_STORE_NAME } from '../common/key-builder.js';
+import { InMemoryKVStore } from '../common/memory-store.js';
+import { DelegatingKVStore } from './kv-delegating-store.js';
+/**
+ * A {@link WriteBatch} that counts what its owning {@link CountingKVStore} commits.
+ *
+ * Exists because {@link DelegatingKVStore.batch} hands back the INNER store's batch, whose
+ * `put`/`delete`/`write` never pass back through the wrapper — so counting the commit path
+ * takes a wrapper here, not merely new fields on the store.
+ *
+ * Operations are attributed to the `write()` that carried them, not to the moment they were
+ * queued: `pending` accumulates and is handed to the owner when `write()` fires, so a batch
+ * that is queued and then `clear()`ed (or abandoned without writing) contributes nothing.
+ * The hand-off happens BEFORE awaiting the inner write, so a commit that fails still counts
+ * as a round trip issued — which is what a caller measuring storage traffic is asking about.
+ */
+class CountingWriteBatch {
+    inner;
+    onWrite;
+    /** Operations queued since construction or since the last `write()` / `clear()`. */
+    pending = 0;
+    constructor(inner, onWrite) {
+        this.inner = inner;
+        this.onWrite = onWrite;
+    }
+    put(key, value) {
+        this.pending++;
+        this.inner.put(key, value);
+    }
+    delete(key) {
+        this.pending++;
+        this.inner.delete(key);
+    }
+    write() {
+        const carried = this.pending;
+        this.pending = 0;
+        this.onWrite(carried);
+        return this.inner.write();
+    }
+    clear() {
+        this.pending = 0;
+        this.inner.clear();
+    }
+}
+/**
+ * Counts what passes through a wrapped {@link KVStore}. On the read side: entries pulled
+ * from `iterate()`, `get()` calls, `getMany()` round trips, and the keys those round trips
+ * carried. On the write side: point writes issued outside any batch, `write()` round trips,
+ * and the operations those carried.
+ *
+ * `getMany` routes through `defaultGetMany(this, keys)` rather than forwarding straight to
+ * `this.inner.getMany(keys)`. That is deliberate, not an oversight. `defaultGetMany` issues
+ * one `get(key)` per key against whatever object it is handed; passing `this` (the wrapper)
+ * means each of those `get` calls lands on THIS class's own overridden, counted `get()`
+ * (which in turn calls `this.inner.get`) — so a single `getMany` of N keys also advances
+ * `getCount` by N, matching how the specs built against this class assert. Forwarding to
+ * `this.inner.getMany(keys)` would run `defaultGetMany` with `this = inner`, bypassing the
+ * wrapper's `get()` entirely and leaving `getCount` unchanged after a batched read — a subtle
+ * break because most of the affected assertions are upper bounds (`.at.most(...)`), not exact
+ * equalities, so the bug would pass silently in most specs and only fail the one exact-equal
+ * assertion that happens to pin it.
+ *
+ * The trade-off this creates: `getManyCalls` / `getManyKeyCount` measure batching AT THE CALL
+ * BOUNDARY into this wrapper (did the caller invoke `getMany` once with N keys, vs. N calls to
+ * `get`) — not the wrapped backend's own internal round-trip count. That is the right thing to
+ * measure for the specs this class serves today, which are proving the ENGINE batches its
+ * reads, not that the wrapped backend has a native multi-get. A future benchmark reaching for
+ * this class to measure a REAL backend's own native batching needs to know that distinction.
+ *
+ * The write side has the SAME call-boundary caveat, and one structural requirement:
+ * `batch()` is overridden to return a {@link CountingWriteBatch}, because the base class's
+ * `batch()` hands out the inner store's batch directly and nothing queued on it would ever
+ * reach this wrapper. The write counters are deliberately split direct-vs-batched — a commit
+ * path that queues N operations and issues ONE `write()` is a different physical cost from
+ * one that issues N point writes, and a single combined "writes" number could not tell them
+ * apart. The four read counters and the four write counters are independent; a workload
+ * touches both.
+ */
+export class CountingKVStore extends DelegatingKVStore {
+    /** Entries pulled from the inner store's `iterate()`. */
+    iterateEntryCount = 0;
+    /** `get()` calls. */
+    getCount = 0;
+    /** `getMany()` calls — round trips, as observed at this counting boundary. */
+    getManyCalls = 0;
+    /** Keys carried by those `getMany()` calls. */
+    getManyKeyCount = 0;
+    /** Puts issued one at a time, outside any batch. */
+    directPutCount = 0;
+    /** Deletes issued one at a time, outside any batch. */
+    directDeleteCount = 0;
+    /** `WriteBatch.write()` calls — the write-side round-trip count. */
+    batchWriteCalls = 0;
+    /** Put/delete operations those `write()` calls carried. */
+    batchOpCount = 0;
+    /** Zero every counter, read and write. */
+    reset() {
+        this.iterateEntryCount = 0;
+        this.getCount = 0;
+        this.getManyCalls = 0;
+        this.getManyKeyCount = 0;
+        this.directPutCount = 0;
+        this.directDeleteCount = 0;
+        this.batchWriteCalls = 0;
+        this.batchOpCount = 0;
+    }
+    async get(key) {
+        this.getCount++;
+        return this.inner.get(key);
+    }
+    async getMany(keys) {
+        this.getManyCalls++;
+        this.getManyKeyCount += keys.length;
+        // Must route through the wrapper's own `get` — see the class doc comment above.
+        return defaultGetMany(this, keys);
+    }
+    async *iterate(options) {
+        for await (const entry of this.inner.iterate(options)) {
+            this.iterateEntryCount++;
+            yield entry;
+        }
+    }
+    put(key, value, options) {
+        this.directPutCount++;
+        return this.inner.put(key, value, options);
+    }
+    delete(key, options) {
+        this.directDeleteCount++;
+        return this.inner.delete(key, options);
+    }
+    // NOTE: only the per-store `WriteBatch` path is counted, never `AtomicBatch`. Nothing
+    // counted reaches the atomic path today — `createCountingProvider` exposes no
+    // `beginAtomicBatch`, so the transaction coordinator always takes its per-store
+    // fallback — and an `AtomicBatch` wrapper nothing exercises is dead weight. If the
+    // counting provider ever gains a shared commit domain, wrap `AtomicBatch` at the same
+    // time: until then such a commit would report zero writes rather than fail loudly.
+    batch() {
+        return new CountingWriteBatch(this.inner.batch(), (opsCarried) => {
+            this.batchWriteCalls++;
+            this.batchOpCount += opsCarried;
+        });
+    }
+}
+/**
+ * A {@link KVStoreProvider} whose stores are {@link CountingKVStore}s, so a spec can assert
+ * on the read traffic (`iterate`/`get`/`getMany`) and the write traffic (point writes and
+ * batch commits) StoreModule generates, without reaching into a real backend.
+ *
+ * Store names come from the shared builders (`buildDataStoreName` / `buildIndexStoreName`,
+ * the reserved `__stats__` / `__catalog__` constants) — the same rule every real provider
+ * is held to by `runStoreNameDistinctness`. Hand-composing them here would lose the
+ * builders' lowercasing, so a mixed-case table name would land on a store no real backend
+ * would have used.
+ *
+ * @param countedStores - Map the counted stores are recorded into, keyed by BUILT store
+ * name: `schema.table` (every table's data store) and, when `scope` is `'all'`, also
+ * `schema.table_idx_index` (secondary indexes), `__stats__`, and `__catalog__`. The caller
+ * reads counters back out of this map after driving a query.
+ * @param scope - `'data'` (default): only each table's data store is counted; index,
+ * stats, and catalog stores stay plain, uncounted `InMemoryKVStore`s the caller never
+ * sees. `'all'`: every store the provider hands out is counted into `countedStores`.
+ */
+// NOTE: implements no `deleteIndexStore` / `deleteTableStores` (both optional on the
+// interface), so a spec that drops a table or index and recreates it under the same name
+// reads the dropped store's entries back. Every spec using this provider today creates its
+// tables once; if one starts exercising drop-then-recreate, implement them (erase, don't
+// just drop the handle) rather than working around it in the spec.
+export function createCountingProvider(countedStores, scope = 'data') {
+    const auxStores = new Map();
+    const aux = (key) => {
+        let s = auxStores.get(key);
+        if (!s) {
+            s = new InMemoryKVStore();
+            auxStores.set(key, s);
+        }
+        return s;
+    };
+    const counted = (key) => {
+        let s = countedStores.get(key);
+        if (!s) {
+            s = new CountingKVStore(new InMemoryKVStore());
+            countedStores.set(key, s);
+        }
+        return s;
+    };
+    const maybeCounted = (key) => (scope === 'all' ? counted(key) : aux(key));
+    return {
+        async getStore(schemaName, tableName) {
+            return counted(buildDataStoreName(schemaName, tableName));
+        },
+        async getIndexStore(schemaName, tableName, indexName) {
+            return maybeCounted(buildIndexStoreName(schemaName, tableName, indexName));
+        },
+        // One unified stats store for every table, as the interface specifies — the
+        // schema/table arguments are ignored.
+        async getStatsStore() {
+            return maybeCounted(STATS_STORE_NAME);
+        },
+        async getCatalogStore() {
+            return maybeCounted(CATALOG_STORE_NAME);
+        },
+        async closeStore() { },
+        async closeIndexStore() { },
+        async closeAll() {
+            for (const s of countedStores.values())
+                await s.close();
+            for (const s of auxStores.values())
+                await s.close();
+            countedStores.clear();
+            auxStores.clear();
+        },
+    };
+}
+//# sourceMappingURL=kv-counting-store.js.map

package/dist/src/testing/kv-counting-store.js.map

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

package/dist/src/testing/kv-delegating-store.d.ts

@@ -0,0 +1,28 @@
+/**
+ * The pass-through {@link KVStore} base every test double in this package extends —
+ * test-support, ships in `@quereus/store/testing`.
+ *
+ * Lives on its own rather than beside any one double because it is not specific to what
+ * any of them model: the counting store here, and the buffering / rescanning / getMany-
+ * misbehaving doubles in `test/kv-store-doubles.ts`, all subclass it and override exactly
+ * the one method whose behavior they are demonstrating.
+ */
+import type { IterateOptions, KVEntry, KVStore, WriteBatch, WriteOptions } from '../common/kv-store.js';
+/**
+ * Forwards every {@link KVStore} method to an inner store. Subclasses override only
+ * the one method whose behavior they are modeling.
+ */
+export declare class DelegatingKVStore implements KVStore {
+    protected readonly inner: KVStore;
+    constructor(inner: KVStore);
+    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>;
+    iterate(options?: IterateOptions): AsyncIterable<KVEntry>;
+    batch(): WriteBatch;
+    close(): Promise<void>;
+    approximateCount(options?: IterateOptions): Promise<number>;
+}
+//# sourceMappingURL=kv-delegating-store.d.ts.map

package/dist/src/testing/kv-delegating-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"kv-delegating-store.d.ts","sourceRoot":"","sources":["../../../src/testing/kv-delegating-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAExG;;;GAGG;AACH,qBAAa,iBAAkB,YAAW,OAAO;IACpC,SAAS,CAAC,QAAQ,CAAC,KAAK,EAAE,OAAO;gBAAd,KAAK,EAAE,OAAO;IAE7C,GAAG,CAAC,GAAG,EAAE,UAAU,GAAG,OAAO,CAAC,UAAU,GAAG,SAAS,CAAC;IAIrD,OAAO,CAAC,IAAI,EAAE,SAAS,UAAU,EAAE,GAAG,OAAO,CAAC,CAAC,UAAU,GAAG,SAAS,CAAC,EAAE,CAAC;IAIzE,GAAG,CAAC,GAAG,EAAE,UAAU,EAAE,KAAK,EAAE,UAAU,EAAE,OAAO,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;IAI9E,MAAM,CAAC,GAAG,EAAE,UAAU,EAAE,OAAO,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;IAI9D,GAAG,CAAC,GAAG,EAAE,UAAU,GAAG,OAAO,CAAC,OAAO,CAAC;IAItC,OAAO,CAAC,OAAO,CAAC,EAAE,cAAc,GAAG,aAAa,CAAC,OAAO,CAAC;IAIzD,KAAK,IAAI,UAAU;IAInB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAItB,gBAAgB,CAAC,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC;CAG3D"}

package/dist/src/testing/kv-delegating-store.js

@@ -0,0 +1,47 @@
+/**
+ * The pass-through {@link KVStore} base every test double in this package extends —
+ * test-support, ships in `@quereus/store/testing`.
+ *
+ * Lives on its own rather than beside any one double because it is not specific to what
+ * any of them model: the counting store here, and the buffering / rescanning / getMany-
+ * misbehaving doubles in `test/kv-store-doubles.ts`, all subclass it and override exactly
+ * the one method whose behavior they are demonstrating.
+ */
+/**
+ * Forwards every {@link KVStore} method to an inner store. Subclasses override only
+ * the one method whose behavior they are modeling.
+ */
+export class DelegatingKVStore {
+    inner;
+    constructor(inner) {
+        this.inner = inner;
+    }
+    get(key) {
+        return this.inner.get(key);
+    }
+    getMany(keys) {
+        return this.inner.getMany(keys);
+    }
+    put(key, value, options) {
+        return this.inner.put(key, value, options);
+    }
+    delete(key, options) {
+        return this.inner.delete(key, options);
+    }
+    has(key) {
+        return this.inner.has(key);
+    }
+    iterate(options) {
+        return this.inner.iterate(options);
+    }
+    batch() {
+        return this.inner.batch();
+    }
+    close() {
+        return this.inner.close();
+    }
+    approximateCount(options) {
+        return this.inner.approximateCount(options);
+    }
+}
+//# sourceMappingURL=kv-delegating-store.js.map

package/dist/src/testing/kv-delegating-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"kv-delegating-store.js","sourceRoot":"","sources":["../../../src/testing/kv-delegating-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH;;;GAGG;AACH,MAAM,OAAO,iBAAiB;IACE;IAA/B,YAA+B,KAAc;QAAd,UAAK,GAAL,KAAK,CAAS;IAAG,CAAC;IAEjD,GAAG,CAAC,GAAe;QAClB,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAC5B,CAAC;IAED,OAAO,CAAC,IAA2B;QAClC,OAAO,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IACjC,CAAC;IAED,GAAG,CAAC,GAAe,EAAE,KAAiB,EAAE,OAAsB;QAC7D,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,EAAE,OAAO,CAAC,CAAC;IAC5C,CAAC;IAED,MAAM,CAAC,GAAe,EAAE,OAAsB;QAC7C,OAAO,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;IACxC,CAAC;IAED,GAAG,CAAC,GAAe;QAClB,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAC5B,CAAC;IAED,OAAO,CAAC,OAAwB;QAC/B,OAAO,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;IACpC,CAAC;IAED,KAAK;QACJ,OAAO,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;IAC3B,CAAC;IAED,KAAK;QACJ,OAAO,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;IAC3B,CAAC;IAED,gBAAgB,CAAC,OAAwB;QACxC,OAAO,IAAI,CAAC,KAAK,CAAC,gBAAgB,CAAC,OAAO,CAAC,CAAC;IAC7C,CAAC;CACD"}

package/dist/src/testing/memory-provider.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Shared in-memory {@link KVStoreProvider} test double — test-support, ships in
+ * `@quereus/store/testing`.
+ *
+ * Nearly every spec in this package's `test/` directory (and this package's benchmark
+ * suite) opens with its own private copy of an all-`InMemoryKVStore` provider. This is the
+ * one shared implementation, built to the same conventions as its sibling
+ * {@link createCountingProvider}:
+ *
+ *   - Store names come from {@link buildDataStoreName} / {@link buildIndexStoreName} and the
+ *     reserved {@link CATALOG_STORE_NAME} / {@link STATS_STORE_NAME} constants — never
+ *     hand-composed template strings, which drop the builders' lowercasing.
+ *   - {@link KVStoreProvider.getStatsStore} returns ONE unified `__stats__` store for every
+ *     table, as the interface specifies (its schema/table arguments are documented as
+ *     ignored) — not the per-table `schema.table.__stats__` spelling most local copies use.
+ *   - `options.costProfile` is spread in only when present, so a provider built with no
+ *     options (or `{}`) has no `costProfile` property at all, matching what a genuine
+ *     pre-profile third-party provider looks like.
+ *
+ * Unlike {@link createCountingProvider} — which deliberately omits `deleteIndexStore` /
+ * `deleteTableStores` — this provider implements both, and they ERASE rather than merely
+ * drop the map entry: see {@link erase} for why a live handle still needs its bytes cleared.
+ * `renameTableStores` is deliberately NOT implemented; `StoreModule` falls back to a generic
+ * copy for a provider without it (`test/rename-store-copy-fallback.spec.ts`), and nothing
+ * that needs this provider today renames.
+ *
+ * Neither is `beginAtomicBatch`, and that one is not a gap to fill later: separate
+ * `InMemoryKVStore`s share no commit domain, so there is nothing for a cross-store batch to
+ * make atomic. The consequence is worth knowing before reading numbers off this provider —
+ * `StoreModuleBase` sets `atomicProvider` from that method's presence and commits per store
+ * here, where a LevelDB-family provider commits in one physical write. A benchmark putting
+ * this provider next to LevelDB is comparing two commit PATHS, not one path over two
+ * backends.
+ */
+import type { KVStoreProvider } from '../common/kv-store.js';
+import type { KVCostProfile } from '../common/cost-profile.js';
+/** Options accepted by {@link createInMemoryProvider}. */
+export interface InMemoryProviderOptions {
+    /**
+     * Forwarded verbatim as the provider's declared `costProfile`. Omitted (the default)
+     * means the returned provider has no `costProfile` property at all — see the class doc
+     * comment above for why that shape matters to `resolveCostProfile`'s parity path.
+     */
+    readonly costProfile?: KVCostProfile;
+}
+/**
+ * Build an all-`InMemoryKVStore` {@link KVStoreProvider}. Every distinct built store name
+ * gets its own `InMemoryKVStore`, created lazily on first access.
+ */
+export declare function createInMemoryProvider(options?: InMemoryProviderOptions): KVStoreProvider;
+//# sourceMappingURL=memory-provider.d.ts.map

package/dist/src/testing/memory-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-provider.d.ts","sourceRoot":"","sources":["../../../src/testing/memory-provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAC7D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAI/D,0DAA0D;AAC1D,MAAM,WAAW,uBAAuB;IACvC;;;;OAIG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,aAAa,CAAC;CACrC;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,CAAC,EAAE,uBAAuB,GAAG,eAAe,CAqFzF"}

package/dist/src/testing/memory-provider.js

@@ -0,0 +1,124 @@
+/**
+ * Shared in-memory {@link KVStoreProvider} test double — test-support, ships in
+ * `@quereus/store/testing`.
+ *
+ * Nearly every spec in this package's `test/` directory (and this package's benchmark
+ * suite) opens with its own private copy of an all-`InMemoryKVStore` provider. This is the
+ * one shared implementation, built to the same conventions as its sibling
+ * {@link createCountingProvider}:
+ *
+ *   - Store names come from {@link buildDataStoreName} / {@link buildIndexStoreName} and the
+ *     reserved {@link CATALOG_STORE_NAME} / {@link STATS_STORE_NAME} constants — never
+ *     hand-composed template strings, which drop the builders' lowercasing.
+ *   - {@link KVStoreProvider.getStatsStore} returns ONE unified `__stats__` store for every
+ *     table, as the interface specifies (its schema/table arguments are documented as
+ *     ignored) — not the per-table `schema.table.__stats__` spelling most local copies use.
+ *   - `options.costProfile` is spread in only when present, so a provider built with no
+ *     options (or `{}`) has no `costProfile` property at all, matching what a genuine
+ *     pre-profile third-party provider looks like.
+ *
+ * Unlike {@link createCountingProvider} — which deliberately omits `deleteIndexStore` /
+ * `deleteTableStores` — this provider implements both, and they ERASE rather than merely
+ * drop the map entry: see {@link erase} for why a live handle still needs its bytes cleared.
+ * `renameTableStores` is deliberately NOT implemented; `StoreModule` falls back to a generic
+ * copy for a provider without it (`test/rename-store-copy-fallback.spec.ts`), and nothing
+ * that needs this provider today renames.
+ *
+ * Neither is `beginAtomicBatch`, and that one is not a gap to fill later: separate
+ * `InMemoryKVStore`s share no commit domain, so there is nothing for a cross-store batch to
+ * make atomic. The consequence is worth knowing before reading numbers off this provider —
+ * `StoreModuleBase` sets `atomicProvider` from that method's presence and commits per store
+ * here, where a LevelDB-family provider commits in one physical write. A benchmark putting
+ * this provider next to LevelDB is comparing two commit PATHS, not one path over two
+ * backends.
+ */
+import { buildDataStoreName, buildIndexStoreName, CATALOG_STORE_NAME, STATS_STORE_NAME } from '../common/key-builder.js';
+import { InMemoryKVStore } from '../common/memory-store.js';
+/**
+ * Build an all-`InMemoryKVStore` {@link KVStoreProvider}. Every distinct built store name
+ * gets its own `InMemoryKVStore`, created lazily on first access.
+ */
+export function createInMemoryProvider(options) {
+    const stores = new Map();
+    // NOTE: a cached store the CALLER closed directly is handed back closed, so the next op
+    // on it throws `InMemoryKVStore is closed` rather than re-opening — unlike a real backend,
+    // which re-opens the name with its bytes intact. No StoreModule path does that today
+    // (`StoreTableBase.releaseIndexStore` is the only close, and its caller always deletes the
+    // store right after, which drops the entry). If a spec or benchmark ever closes a handle
+    // and keeps using the name, treat a closed cached store as absent here.
+    const getOrCreate = (key) => {
+        let store = stores.get(key);
+        if (!store) {
+            store = new InMemoryKVStore();
+            stores.set(key, store);
+        }
+        return store;
+    };
+    /**
+     * Erase the store named `key`: a caller re-opening this name afterwards must find it
+     * empty, and a caller still holding a LIVE handle to it must see the erase too (the
+     * reclaim battery's "handle the caller already closed" case is the other order — see
+     * below). Two cases, both ending in the map entry being dropped so the name re-opens
+     * fresh:
+     *
+     *   - Live store: `clear()` it first, so an existing handle observes the erase, THEN
+     *     drop the map entry.
+     *   - Already-closed store (the caller closed its handle before asking for the delete —
+     *     exactly what `StoreModuleIndex.tearDownIndexStore` does): `close()` already
+     *     cleared its entries and marked it closed, so `clear()` would just throw
+     *     (`checkOpen()`) for no benefit. Skip straight to dropping the map entry.
+     *
+     * A store that was never created (key absent from the map) is a no-op, matching the
+     * interface's speculative-delete contract.
+     *
+     * NOTE: the live handle is cleared, not closed, so a caller still holding it can go on
+     * PUTting into a store the provider has forgotten — those writes land nowhere anyone can
+     * read, silently. A real backend's handle is dead after its store is dropped. Closing here
+     * instead would trade the silence for a throw, but would also break the contract line
+     * above (a live handle must read back EMPTY, not throw); revisit if a spec is ever found
+     * writing through a post-delete handle.
+     */
+    const erase = async (key) => {
+        const store = stores.get(key);
+        if (!store)
+            return;
+        if (!store.isClosed) {
+            store.clear();
+        }
+        stores.delete(key);
+    };
+    return {
+        ...(options?.costProfile ? { costProfile: options.costProfile } : {}),
+        async getStore(schemaName, tableName) {
+            return getOrCreate(buildDataStoreName(schemaName, tableName));
+        },
+        async getIndexStore(schemaName, tableName, indexName) {
+            return getOrCreate(buildIndexStoreName(schemaName, tableName, indexName));
+        },
+        async getStatsStore() {
+            return getOrCreate(STATS_STORE_NAME);
+        },
+        async getCatalogStore() {
+            return getOrCreate(CATALOG_STORE_NAME);
+        },
+        async closeStore() { },
+        async closeIndexStore() { },
+        async closeAll() {
+            for (const store of stores.values())
+                await store.close();
+            stores.clear();
+        },
+        async deleteIndexStore(schemaName, tableName, indexName) {
+            await erase(buildIndexStoreName(schemaName, tableName, indexName));
+        },
+        async deleteTableStores(schemaName, tableName, indexNames) {
+            await erase(buildDataStoreName(schemaName, tableName));
+            for (const indexName of indexNames) {
+                await erase(buildIndexStoreName(schemaName, tableName, indexName));
+            }
+            // The unified __stats__ store is deliberately untouched — a table's row count is
+            // one ENTRY there, and removing it is the caller's business, not a store deletion.
+        },
+    };
+}
+//# sourceMappingURL=memory-provider.js.map

package/dist/src/testing/memory-provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-provider.js","sourceRoot":"","sources":["../../../src/testing/memory-provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAIH,OAAO,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AACzH,OAAO,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC;AAY5D;;;GAGG;AACH,MAAM,UAAU,sBAAsB,CAAC,OAAiC;IACvE,MAAM,MAAM,GAAG,IAAI,GAAG,EAA2B,CAAC;IAElD,wFAAwF;IACxF,2FAA2F;IAC3F,qFAAqF;IACrF,2FAA2F;IAC3F,yFAAyF;IACzF,wEAAwE;IACxE,MAAM,WAAW,GAAG,CAAC,GAAW,EAAmB,EAAE;QACpD,IAAI,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAC5B,IAAI,CAAC,KAAK,EAAE,CAAC;YACZ,KAAK,GAAG,IAAI,eAAe,EAAE,CAAC;YAC9B,MAAM,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;QACxB,CAAC;QACD,OAAO,KAAK,CAAC;IACd,CAAC,CAAC;IAEF;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,MAAM,KAAK,GAAG,KAAK,EAAE,GAAW,EAAiB,EAAE;QAClD,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAC9B,IAAI,CAAC,KAAK;YAAE,OAAO;QACnB,IAAI,CAAC,KAAK,CAAC,QAAQ,EAAE,CAAC;YACrB,KAAK,CAAC,KAAK,EAAE,CAAC;QACf,CAAC;QACD,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IACpB,CAAC,CAAC;IAEF,OAAO;QACN,GAAG,CAAC,OAAO,EAAE,WAAW,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,OAAO,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAErE,KAAK,CAAC,QAAQ,CAAC,UAAU,EAAE,SAAS;YACnC,OAAO,WAAW,CAAC,kBAAkB,CAAC,UAAU,EAAE,SAAS,CAAC,CAAC,CAAC;QAC/D,CAAC;QACD,KAAK,CAAC,aAAa,CAAC,UAAU,EAAE,SAAS,EAAE,SAAS;YACnD,OAAO,WAAW,CAAC,mBAAmB,CAAC,UAAU,EAAE,SAAS,EAAE,SAAS,CAAC,CAAC,CAAC;QAC3E,CAAC;QACD,KAAK,CAAC,aAAa;YAClB,OAAO,WAAW,CAAC,gBAAgB,CAAC,CAAC;QACtC,CAAC;QACD,KAAK,CAAC,eAAe;YACpB,OAAO,WAAW,CAAC,kBAAkB,CAAC,CAAC;QACxC,CAAC;QACD,KAAK,CAAC,UAAU,KAAI,CAAC;QACrB,KAAK,CAAC,eAAe,KAAI,CAAC;QAC1B,KAAK,CAAC,QAAQ;YACb,KAAK,MAAM,KAAK,IAAI,MAAM,CAAC,MAAM,EAAE;gBAAE,MAAM,KAAK,CAAC,KAAK,EAAE,CAAC;YACzD,MAAM,CAAC,KAAK,EAAE,CAAC;QAChB,CAAC;QAED,KAAK,CAAC,gBAAgB,CAAC,UAAU,EAAE,SAAS,EAAE,SAAS;YACtD,MAAM,KAAK,CAAC,mBAAmB,CAAC,UAAU,EAAE,SAAS,EAAE,SAAS,CAAC,CAAC,CAAC;QACpE,CAAC;QACD,KAAK,CAAC,iBAAiB,CAAC,UAAU,EAAE,SAAS,EAAE,UAAU;YACxD,MAAM,KAAK,CAAC,kBAAkB,CAAC,UAAU,EAAE,SAAS,CAAC,CAAC,CAAC;YACvD,KAAK,MAAM,SAAS,IAAI,UAAU,EAAE,CAAC;gBACpC,MAAM,KAAK,CAAC,mBAAmB,CAAC,UAAU,EAAE,SAAS,EAAE,SAAS,CAAC,CAAC,CAAC;YACpE,CAAC;YACD,iFAAiF;YACjF,mFAAmF;QACpF,CAAC;KACD,CAAC;AACH,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quereus/store",
-  "version": "4.14.0",
+  "version": "4.16.0",
   "type": "module",
   "description": "Abstract key-value storage module for Quereus",
   "keywords": [
@@ -52,12 +52,12 @@
     "test:single": "cd ../.. && node --import ./packages/quereus-store/register.mjs node_modules/mocha/bin/mocha.js --bail"
   },
   "peerDependencies": {
-    "@quereus/isolation": "^4.14.0",
-    "@quereus/quereus": "^4.14.0"
+    "@quereus/isolation": "^4.16.0",
+    "@quereus/quereus": "^4.16.0"
   },
   "dependencies": {
-    "@quereus/isolation": "^4.14.0",
-    "@quereus/quereus": "^4.14.0"
+    "@quereus/isolation": "^4.16.0",
+    "@quereus/quereus": "^4.16.0"
   },
   "devDependencies": {
     "@types/mocha": "^10.0.10",