shelving 1.276.1 → 1.278.0

package/api/cache/APICache.d.ts

@@ -74,7 +74,7 @@ export declare class APICache<P, R> implements AsyncDisposable {
      * @example cache.refresh(getUser, { id: "abc" })
      * @see https://shelving.cc/api/APICache/refresh
      */
-    refresh<PP extends P, RR extends R>(endpoint: Endpoint<PP, RR>, payload: PP, maxAge?: number): void;
+    refresh<PP extends P, RR extends R>(endpoint: Endpoint<PP, RR>, payload: PP, maxAge?: number): Promise<void>;
     /**
      * Trigger a refetch on all stores for an endpoint.
      *
@@ -83,6 +83,6 @@ export declare class APICache<P, R> implements AsyncDisposable {
      * @example cache.refreshAll(getUser)
      * @see https://shelving.cc/api/APICache/refreshAll
      */
-    refreshAll<PP extends P, RR extends R>(endpoint: Endpoint<PP, RR>, maxAge?: number): void;
+    refreshAll<PP extends P, RR extends R>(endpoint: Endpoint<PP, RR>, maxAge?: number): Promise<void>;
     [Symbol.asyncDispose](): Promise<void>;
 }

package/api/cache/APICache.js

@@ -78,8 +78,8 @@ export class APICache {
      * @example cache.refresh(getUser, { id: "abc" })
      * @see https://shelving.cc/api/APICache/refresh
      */
-    refresh(endpoint, payload, maxAge) {
-        this._get(endpoint)?.refresh(payload, maxAge);
+    async refresh(endpoint, payload, maxAge) {
+        await this._get(endpoint)?.refresh(payload, maxAge);
     }
     /**
      * Trigger a refetch on all stores for an endpoint.
@@ -89,8 +89,8 @@ export class APICache {
      * @example cache.refreshAll(getUser)
      * @see https://shelving.cc/api/APICache/refreshAll
      */
-    refreshAll(endpoint, maxAge) {
-        this._get(endpoint)?.refreshAll(maxAge);
+    async refreshAll(endpoint, maxAge) {
+        await this._get(endpoint)?.refreshAll(maxAge);
     }
     // Implement `AsyncDisposable`
     [Symbol.asyncDispose]() {

package/api/provider/CachedAPIProvider.d.ts

@@ -43,13 +43,13 @@ export declare class CachedAPIProvider<P, R> extends ThroughAPIProvider<P, R> im
      * @param payload The payload identifying the cached result.
      * @see https://shelving.cc/api/CachedAPIProvider/refresh
      */
-    refresh<PP extends P, RR extends R>(endpoint: Endpoint<PP, RR>, payload: PP): void;
+    refresh<PP extends P, RR extends R>(endpoint: Endpoint<PP, RR>, payload: PP): Promise<void>;
     /**
      * Refresh every cached result for an endpoint, across all payloads.
      *
      * @param endpoint The endpoint whose cached results should be refreshed.
      * @see https://shelving.cc/api/CachedAPIProvider/refreshAll
      */
-    refreshAll<PP extends P, RR extends R>(endpoint: Endpoint<PP, RR>): void;
+    refreshAll<PP extends P, RR extends R>(endpoint: Endpoint<PP, RR>): Promise<void>;
     [Symbol.asyncDispose](): Promise<void>;
 }

package/api/provider/CachedAPIProvider.js

@@ -52,8 +52,8 @@ export class CachedAPIProvider extends ThroughAPIProvider {
      * @param payload The payload identifying the cached result.
      * @see https://shelving.cc/api/CachedAPIProvider/refresh
      */
-    refresh(endpoint, payload) {
-        this._cache.refresh(endpoint, payload, this.maxAge);
+    async refresh(endpoint, payload) {
+        await this._cache.refresh(endpoint, payload, this.maxAge);
     }
     /**
      * Refresh every cached result for an endpoint, across all payloads.
@@ -61,8 +61,8 @@ export class CachedAPIProvider extends ThroughAPIProvider {
      * @param endpoint The endpoint whose cached results should be refreshed.
      * @see https://shelving.cc/api/CachedAPIProvider/refreshAll
      */
-    refreshAll(endpoint) {
-        this._cache.refreshAll(endpoint, this.maxAge);
+    async refreshAll(endpoint) {
+        await this._cache.refreshAll(endpoint, this.maxAge);
     }
     // Implement `AsyncDisposable`
     async [Symbol.asyncDispose]() {

package/db/provider/ChangesDBProvider.d.ts

@@ -1,7 +1,6 @@
 import type { MutableArray } from "../../util/array.js";
 import type { Data } from "../../util/data.js";
 import type { Identifier, Item } from "../../util/item.js";
-import type { Query } from "../../util/query.js";
 import type { Updates } from "../../util/update.js";
 import type { Collection } from "../collection/Collection.js";
 import type { DBProvider } from "./DBProvider.js";
@@ -9,15 +8,14 @@ import { ThroughDBProvider } from "./ThroughDBProvider.js";
 /**
  * Structured log entry recording a single database write performed through a `ChangesDBProvider`.
  *
- * - `action` is the kind of write; `collection` is the collection name; `id`, `query`, `data`, and `updates` carry whichever fields apply to that write.
+ * - `action` is the kind of write; `collection` is the `Collection` the write applies to; `id` is the item that was written; `data` and `updates` carry whichever fields apply to that write.
  *
  * @see https://shelving.cc/db/DBChange
  */
-export type DBChange<I extends Identifier> = {
+export type DBChange<I extends Identifier, T extends Data = Data> = {
     readonly action: "add" | "set" | "update" | "delete";
-    readonly collection: string;
-    readonly id?: I | undefined;
-    readonly query?: unknown;
+    readonly collection: Collection<string, I, T>;
+    readonly id: I;
     readonly data?: unknown;
     readonly updates?: unknown;
 };
@@ -25,6 +23,8 @@ export type DBChange<I extends Identifier> = {
  * Database provider that records every write it performs to its `changes` log.
  *
  * - Wraps a `source` provider, delegates each write, then appends a `DBChange` entry describing what happened.
+ * - Every change is an explicit per-item write with an `id` — query writes are inherited two-step from `ThroughDBProvider`, so they arrive here as the individual item writes they resolved to.
+ * - Replay the log onto another provider with `ChangesDBProvider.replay()`.
  * - Useful for building audit logging, change feeds, or assertions in tests; reads are passed straight through and not logged.
  *
  * @see https://shelving.cc/db/ChangesDBProvider
@@ -35,8 +35,8 @@ export declare class ChangesDBProvider<I extends Identifier, T extends Data> ext
      *
      * @see https://shelving.cc/db/ChangesDBProvider/changes
      */
-    get changes(): ReadonlyArray<DBChange<I>>;
-    readonly _changes: MutableArray<DBChange<I>>;
+    get changes(): ReadonlyArray<DBChange<I, T>>;
+    readonly _changes: MutableArray<DBChange<I, T>>;
     /** Log an `"add"` change after writing. */
     addItem<II extends I, TT extends T>(collection: Collection<string, II, TT>, data: TT): Promise<II>;
     /** Log a `"set"` change after writing. */
@@ -45,12 +45,18 @@ export declare class ChangesDBProvider<I extends Identifier, T extends Data> ext
     updateItem<II extends I, TT extends T>(collection: Collection<string, II, TT>, id: II, updates: Updates<Item<II, TT>>): Promise<void>;
     /** Log a `"delete"` change after writing. */
     deleteItem<II extends I, TT extends T>(collection: Collection<string, II, TT>, id: II): Promise<void>;
-    /** Log a `"set"` change after writing. */
-    setQuery<II extends I, TT extends T>(collection: Collection<string, II, TT>, query: Query<Item<II, TT>>, data: TT): Promise<void>;
-    /** Log an `"update"` change after writing. */
-    updateQuery<II extends I, TT extends T>(collection: Collection<string, II, TT>, query: Query<Item<II, TT>>, updates: Updates<TT>): Promise<void>;
-    /** Log a `"delete"` change after writing. */
-    deleteQuery<II extends I, TT extends T>(collection: Collection<string, II, TT>, query: Query<Item<II, TT>>): Promise<void>;
+    /**
+     * Replay the `changes` log onto another provider, re-issuing each write in order.
+     *
+     * - Useful for audit replay or syncing a secondary store — and the commit mechanism for `MemoryDBProvider.transact()`.
+     * - `"add"` changes replay as `DBProvider.setItem()` with the logged id, so the target keeps the same generated ids.
+     * - The changes replay as a sequence of awaited writes — the replay itself is not atomic.
+     *
+     * @param provider Provider to replay the changes onto.
+     * @example await changes.replay(mirror);
+     * @see https://shelving.cc/db/ChangesDBProvider/replay
+     */
+    replay(provider: DBProvider<I, T>): Promise<void>;
     cloneWith(source: DBProvider<I, T>): this;
     transact<X>(callback: (provider: DBProvider<I, T>) => Promise<X>): Promise<X>;
 }

package/db/provider/ChangesDBProvider.js

@@ -3,6 +3,8 @@ import { ThroughDBProvider } from "./ThroughDBProvider.js";
  * Database provider that records every write it performs to its `changes` log.
  *
  * - Wraps a `source` provider, delegates each write, then appends a `DBChange` entry describing what happened.
+ * - Every change is an explicit per-item write with an `id` — query writes are inherited two-step from `ThroughDBProvider`, so they arrive here as the individual item writes they resolved to.
+ * - Replay the log onto another provider with `ChangesDBProvider.replay()`.
  * - Useful for building audit logging, change feeds, or assertions in tests; reads are passed straight through and not logged.
  *
  * @see https://shelving.cc/db/ChangesDBProvider
@@ -20,38 +22,45 @@ export class ChangesDBProvider extends ThroughDBProvider {
     /** Log an `"add"` change after writing. */
     async addItem(collection, data) {
         const id = await super.addItem(collection, data);
-        this._changes.push({ action: "add", collection: collection.name, id, data });
+        this._changes.push({ action: "add", collection, id, data });
         return id;
     }
     /** Log a `"set"` change after writing. */
     async setItem(collection, id, data) {
         await super.setItem(collection, id, data);
-        this._changes.push({ action: "set", collection: collection.name, id, data });
+        this._changes.push({ action: "set", collection, id, data });
     }
     /** Log an `"update"` change after writing. */
     async updateItem(collection, id, updates) {
         await super.updateItem(collection, id, updates);
-        this._changes.push({ action: "update", collection: collection.name, id, updates });
+        this._changes.push({ action: "update", collection, id, updates });
     }
     /** Log a `"delete"` change after writing. */
     async deleteItem(collection, id) {
         await super.deleteItem(collection, id);
-        this._changes.push({ action: "delete", collection: collection.name, id });
+        this._changes.push({ action: "delete", collection, id });
     }
-    /** Log a `"set"` change after writing. */
-    async setQuery(collection, query, data) {
-        await super.setQuery(collection, query, data);
-        this._changes.push({ action: "set", collection: collection.name, query, data });
-    }
-    /** Log an `"update"` change after writing. */
-    async updateQuery(collection, query, updates) {
-        await super.updateQuery(collection, query, updates);
-        this._changes.push({ action: "update", collection: collection.name, query, updates });
-    }
-    /** Log a `"delete"` change after writing. */
-    async deleteQuery(collection, query) {
-        await super.deleteQuery(collection, query);
-        this._changes.push({ action: "delete", collection: collection.name, query });
+    /**
+     * Replay the `changes` log onto another provider, re-issuing each write in order.
+     *
+     * - Useful for audit replay or syncing a secondary store — and the commit mechanism for `MemoryDBProvider.transact()`.
+     * - `"add"` changes replay as `DBProvider.setItem()` with the logged id, so the target keeps the same generated ids.
+     * - The changes replay as a sequence of awaited writes — the replay itself is not atomic.
+     *
+     * @param provider Provider to replay the changes onto.
+     * @example await changes.replay(mirror);
+     * @see https://shelving.cc/db/ChangesDBProvider/replay
+     */
+    async replay(provider) {
+        // `as` casts needed: the log stores `data` and `updates` loosely as `unknown`.
+        for (const { action, collection, id, data, updates } of this._changes) {
+            if (action === "delete")
+                await provider.deleteItem(collection, id);
+            else if (action === "update")
+                await provider.updateItem(collection, id, updates);
+            else
+                await provider.setItem(collection, id, data);
+        }
     }
     // Override so that transaction copies get their own log.
     cloneWith(source) {

package/db/provider/DBProvider.d.ts

@@ -119,6 +119,7 @@ export declare abstract class DBProvider<I extends Identifier = Identifier, T ex
     abstract getQuerySequence<II extends I, TT extends T>(collection: Collection<string, II, TT>, query?: Query<Item<II, TT>>): ItemsSequence<II, TT>;
     /**
      * Set (overwrite) the data for every item matching a query.
+     * - Not guaranteed atomic: an implementation may resolve the matching items first and then write per item (two-step — see `ThroughDBProvider`), so wrap the call in `transact()` when atomicity matters.
      *
      * @param collection Collection to write to.
      * @param query Query selecting the items to set.
@@ -129,6 +130,7 @@ export declare abstract class DBProvider<I extends Identifier = Identifier, T ex
     abstract setQuery<II extends I, TT extends T>(collection: Collection<string, II, TT>, query: Query<Item<II, TT>>, data: TT): Promise<void>;
     /**
      * Apply partial updates to every item matching a query.
+     * - Not guaranteed atomic: an implementation may resolve the matching items first and then write per item (two-step — see `ThroughDBProvider`), so wrap the call in `transact()` when atomicity matters.
      *
      * @param collection Collection to write to.
      * @param query Query selecting the items to update.
@@ -139,6 +141,7 @@ export declare abstract class DBProvider<I extends Identifier = Identifier, T ex
     abstract updateQuery<II extends I, TT extends T>(collection: Collection<string, II, TT>, query: Query<Item<II, TT>>, updates: Updates<TT>): Promise<void>;
     /**
      * Delete every item matching a query.
+     * - Not guaranteed atomic: an implementation may resolve the matching items first and then delete per item (two-step — see `ThroughDBProvider`), so wrap the call in `transact()` when atomicity matters.
      *
      * @param collection Collection to delete from.
      * @param query Query selecting the items to delete.
@@ -174,7 +177,7 @@ export declare abstract class DBProvider<I extends Identifier = Identifier, T ex
      * - Reads see a consistent snapshot of the data from before the transaction, and do not see the transaction's own uncommitted writes.
      * - If the callback throws, nothing is committed and the error is rethrown.
      * - The callback may run more than once if the backend retries on contention, so it must have no side effects other than through its provider.
-     * - Inside a transaction, realtime sequences and nested `transact()` calls throw `UnsupportedError`.
+     * - Portable code must not use realtime sequences or nested `transact()` calls inside a transaction — most backends throw `UnsupportedError`, though some (e.g. `MemoryDBProvider`) support them scoped to the transaction.
      * - Not every provider supports transactions — the base implementation throws `UnsupportedError`.
      *
      * @param callback Function that performs the transaction's reads and writes through the provider it receives.

package/db/provider/DBProvider.js

@@ -89,7 +89,7 @@ export class DBProvider {
      * - Reads see a consistent snapshot of the data from before the transaction, and do not see the transaction's own uncommitted writes.
      * - If the callback throws, nothing is committed and the error is rethrown.
      * - The callback may run more than once if the backend retries on contention, so it must have no side effects other than through its provider.
-     * - Inside a transaction, realtime sequences and nested `transact()` calls throw `UnsupportedError`.
+     * - Portable code must not use realtime sequences or nested `transact()` calls inside a transaction — most backends throw `UnsupportedError`, though some (e.g. `MemoryDBProvider`) support them scoped to the transaction.
      * - Not every provider supports transactions — the base implementation throws `UnsupportedError`.
      *
      * @param callback Function that performs the transaction's reads and writes through the provider it receives.

package/db/provider/DebugDBProvider.d.ts

@@ -27,8 +27,11 @@ export declare class DebugDBProvider<I extends Identifier, T extends Data> exten
     countQuery<II extends I, TT extends T>(collection: Collection<string, II, TT>, query?: Query<Item<II, TT>>): Promise<number>;
     getQuery<II extends I, TT extends T>(collection: Collection<string, II, TT>, query?: Query<Item<II, TT>>): Promise<Items<II, TT>>;
     getQuerySequence<II extends I, TT extends T>(collection: Collection<string, II, TT>, query?: Query<Item<II, TT>>): ItemsSequence<II, TT>;
+    /** Passthrough, not two-step: log the query write the caller made, not the per-item writes it implies. */
     setQuery<II extends I, TT extends T>(collection: Collection<string, II, TT>, query: Query<Item<II, TT>>, data: TT): Promise<void>;
+    /** Passthrough, not two-step: log the query write the caller made, not the per-item writes it implies. */
     updateQuery<II extends I, TT extends T>(collection: Collection<string, II, TT>, query: Query<Item<II, TT>>, updates: Updates<TT>): Promise<void>;
+    /** Passthrough, not two-step: log the query write the caller made, not the per-item writes it implies. */
     deleteQuery<II extends I, TT extends T>(collection: Collection<string, II, TT>, query: Query<Item<II, TT>>): Promise<void>;
     /** Adds TRANSACT logging around the base behaviour, which re-wraps so operations inside the transaction are logged too. */
     transact<X>(callback: (provider: DBProvider<I, T>) => Promise<X>): Promise<X>;

package/db/provider/DebugDBProvider.js

@@ -120,10 +120,11 @@ export class DebugDBProvider extends ThroughDBProvider {
             console.error(`${ANSI_FAILURE} SEQUENCE QUERY`, collection.name, query, thrown);
         }
     }
+    /** Passthrough, not two-step: log the query write the caller made, not the per-item writes it implies. */
     async setQuery(collection, query, data) {
         try {
             console.debug(`${ANSI_RIGHT} SET QUERY`, collection.name, query, data);
-            await super.setQuery(collection, query, data);
+            await this.source.setQuery(collection, query, data);
             console.debug(`${ANSI_SUCCESS} SET QUERY`, collection.name, query, data);
         }
         catch (reason) {
@@ -131,10 +132,11 @@ export class DebugDBProvider extends ThroughDBProvider {
             throw reason;
         }
     }
+    /** Passthrough, not two-step: log the query write the caller made, not the per-item writes it implies. */
     async updateQuery(collection, query, updates) {
         try {
             console.debug(`${ANSI_RIGHT} UPDATE QUERY`, collection.name, query, updates);
-            await super.updateQuery(collection, query, updates);
+            await this.source.updateQuery(collection, query, updates);
             console.debug(`${ANSI_SUCCESS} UPDATE QUERY`, collection.name, query, updates);
         }
         catch (reason) {
@@ -142,10 +144,11 @@ export class DebugDBProvider extends ThroughDBProvider {
             throw reason;
         }
     }
+    /** Passthrough, not two-step: log the query write the caller made, not the per-item writes it implies. */
     async deleteQuery(collection, query) {
         try {
             console.debug(`${ANSI_RIGHT} DELETE QUERY`, collection.name, query);
-            await super.deleteQuery(collection, query);
+            await this.source.deleteQuery(collection, query);
             console.debug(`${ANSI_SUCCESS} DELETE QUERY`, collection.name, query);
         }
         catch (reason) {

package/db/provider/MemoryDBProvider.d.ts

@@ -11,6 +11,7 @@ import { DBProvider } from "./DBProvider.js";
  * - Extremely fast (ideal as the cache behind `CacheDBProvider`!), but does not persist data after the process or browser window closes.
  * - Identity-preserving: `getItem()` etc. return the exact same object instance that was passed into `setItem()`.
  * - Supports live subscriptions, so it can back `ItemStore` / `QueryStore` reads.
+ * - Supports transactions: `transact()` runs the callback against a snapshot clone, captures its writes with `ChangesDBProvider`, and replays them onto this provider on success — sequences and nested transactions work inside the callback, scoped to the transaction.
  *
  * @see https://shelving.cc/db/MemoryDBProvider
  */
@@ -57,13 +58,32 @@ export declare class MemoryDBProvider<I extends Identifier = Identifier, T exten
      * @see https://shelving.cc/db/MemoryDBProvider/setItems
      */
     setItems<II extends I, TT extends T>(collection: Collection<string, II, TT>, items: Items<II, TT>): void;
+    /**
+     * Clone this provider into a new plain `MemoryDBProvider` containing the same items.
+     *
+     * - Shallow: new tables and maps sharing the same (immutable) item instances, so cloning is cheap and unchanged items keep their identity.
+     * - The clone is always a plain `MemoryDBProvider` with plain `MemoryTable`s, even when called on a subclass — writes to the clone only touch its own memory, never a subclass's backing store (e.g. `StorageDBProvider` persistence).
+     *
+     * @example provider.clone() // MemoryDBProvider
+     * @see https://shelving.cc/db/MemoryDBProvider/clone
+     */
+    clone(): MemoryDBProvider<I, T>;
+    /**
+     * Runs the callback against a shallow clone of this provider, capturing its writes with `ChangesDBProvider`, then replays them onto this provider when the callback resolves.
+     * - If the callback throws, the clone and its captured changes are discarded and nothing is committed.
+     * - Reads inside the callback see a snapshot from when the transaction began, plus the transaction's own writes. Realtime sequences and nested `transact()` also work inside the callback, scoped to the transaction — portable code must not rely on any of this (see `DBProvider.transact()`).
+     * - The clone is disposed when the transaction completes or fails, ending any sequences opened inside the callback.
+     * - Writes made to this provider while the callback is running are kept — the captured changes replay on top in order (updates apply as deltas, sets and deletes overwrite), with no conflict detection; overlapping transactions replay in completion order (last write wins per item).
+     * - Query writes resolve two-step against the clone, so they commit to exactly the items they matched inside the transaction, even if concurrent writes changed which items match.
+     */
+    transact<X>(callback: (provider: DBProvider<I, T>) => Promise<X>): Promise<X>;
     [Symbol.asyncDispose](): Promise<void>;
 }
 /**
  * In-memory table holding the items of a single collection for a `MemoryDBProvider`.
  *
  * - Keys items by id in a `Map`, preserving the exact object instance passed in.
- * - Exposes a `next` `DeferredSequence` that resolves on every change, powering the live `*Sequence` subscriptions.
+ * - An internal `DeferredSequence` resolves on every change, powering the live `*Sequence` subscriptions.
  *
  * @example
  *  const table = provider.getTable(users);
@@ -74,19 +94,16 @@ export declare class MemoryDBProvider<I extends Identifier = Identifier, T exten
 export declare class MemoryTable<I extends Identifier, T extends Data> implements AsyncDisposable {
     /** Actual data in this table. */
     protected readonly _data: Map<I, Item<I, T>>;
-    /**
-     * Deferred sequence that resolves on every change to this table.
-     *
-     * @see https://shelving.cc/db/MemoryTable/next
-     */
-    readonly next: DeferredSequence<void, void, void>;
+    /** Deferred sequence that resolves on every change to this table — `false` for a change, or `true` once when the table is disposed and its sequences should end. */
+    protected readonly _next: DeferredSequence<boolean, void, void>;
     /**
      * Collection this table stores the items of.
      *
      * @see https://shelving.cc/db/MemoryTable/collection
      */
     readonly collection: Collection<string, I, T>;
-    constructor(collection: Collection<string, I, T>);
+    /** @param items Optional initial `[id, item]` entries to seed the table with. */
+    constructor(collection: Collection<string, I, T>, items?: Iterable<readonly [I, Item<I, T>]>);
     /**
      * Get an item by its id, or `undefined` if it doesn't exist.
      *
@@ -215,5 +232,15 @@ export declare class MemoryTable<I extends Identifier, T extends Data> implement
     deleteQuery(query: Query<Item<I, T>>): void;
     setItems(items: Items<I, T>): void;
     setItemsSequence(sequence: AsyncIterable<Items<I, T>>): AsyncIterable<Items<I, T>>;
+    /**
+     * Clone this table into a new plain `MemoryTable` containing the same items.
+     *
+     * - Shallow: a new map sharing the same (immutable) item instances, so cloning is cheap.
+     * - The clone is always a plain `MemoryTable`, even when called on a subclass — writes to the clone have no side effects (e.g. `StorageTable` persistence).
+     *
+     * @example table.clone() // MemoryTable
+     * @see https://shelving.cc/db/MemoryTable/clone
+     */
+    clone(): MemoryTable<I, T>;
     [Symbol.asyncDispose](): Promise<void>;
 }

package/db/provider/MemoryDBProvider.js

@@ -8,6 +8,7 @@ import { countItems } from "../../util/iterate.js";
 import { queryItems, queryWritableItems } from "../../util/query.js";
 import { getRandom, getRandomKey } from "../../util/random.js";
 import { updateData } from "../../util/update.js";
+import { ChangesDBProvider } from "./ChangesDBProvider.js";
 import { DBProvider } from "./DBProvider.js";
 /**
  * Synchronous in-memory database provider, storing each collection in a `MemoryTable`.
@@ -15,6 +16,7 @@ import { DBProvider } from "./DBProvider.js";
  * - Extremely fast (ideal as the cache behind `CacheDBProvider`!), but does not persist data after the process or browser window closes.
  * - Identity-preserving: `getItem()` etc. return the exact same object instance that was passed into `setItem()`.
  * - Supports live subscriptions, so it can back `ItemStore` / `QueryStore` reads.
+ * - Supports transactions: `transact()` runs the callback against a snapshot clone, captures its writes with `ChangesDBProvider`, and replays them onto this provider on success — sequences and nested transactions work inside the callback, scoped to the transaction.
  *
  * @see https://shelving.cc/db/MemoryDBProvider
  */
@@ -89,6 +91,42 @@ export class MemoryDBProvider extends DBProvider {
     setItems(collection, items) {
         this.getTable(collection).setItems(items);
     }
+    /**
+     * Clone this provider into a new plain `MemoryDBProvider` containing the same items.
+     *
+     * - Shallow: new tables and maps sharing the same (immutable) item instances, so cloning is cheap and unchanged items keep their identity.
+     * - The clone is always a plain `MemoryDBProvider` with plain `MemoryTable`s, even when called on a subclass — writes to the clone only touch its own memory, never a subclass's backing store (e.g. `StorageDBProvider` persistence).
+     *
+     * @example provider.clone() // MemoryDBProvider
+     * @see https://shelving.cc/db/MemoryDBProvider/clone
+     */
+    clone() {
+        const clone = new MemoryDBProvider();
+        for (const [name, table] of Object.entries(this._tables))
+            if (table)
+                clone._tables[name] = table.clone();
+        return clone;
+    }
+    /**
+     * Runs the callback against a shallow clone of this provider, capturing its writes with `ChangesDBProvider`, then replays them onto this provider when the callback resolves.
+     * - If the callback throws, the clone and its captured changes are discarded and nothing is committed.
+     * - Reads inside the callback see a snapshot from when the transaction began, plus the transaction's own writes. Realtime sequences and nested `transact()` also work inside the callback, scoped to the transaction — portable code must not rely on any of this (see `DBProvider.transact()`).
+     * - The clone is disposed when the transaction completes or fails, ending any sequences opened inside the callback.
+     * - Writes made to this provider while the callback is running are kept — the captured changes replay on top in order (updates apply as deltas, sets and deletes overwrite), with no conflict detection; overlapping transactions replay in completion order (last write wins per item).
+     * - Query writes resolve two-step against the clone, so they commit to exactly the items they matched inside the transaction, even if concurrent writes changed which items match.
+     */
+    async transact(callback) {
+        const clone = this.clone();
+        try {
+            const transaction = new ChangesDBProvider(clone);
+            const result = await callback(transaction);
+            await transaction.replay(this); // Commit the captured changes.
+            return result;
+        }
+        finally {
+            await clone[Symbol.asyncDispose](); // End any sequences opened inside the callback.
+        }
+    }
     // Implement `AsyncDisposable`
     async [Symbol.asyncDispose]() {
         await awaitDispose(...Object.values(this._tables), // Dispose all tables.
@@ -99,7 +137,7 @@ export class MemoryDBProvider extends DBProvider {
  * In-memory table holding the items of a single collection for a `MemoryDBProvider`.
  *
  * - Keys items by id in a `Map`, preserving the exact object instance passed in.
- * - Exposes a `next` `DeferredSequence` that resolves on every change, powering the live `*Sequence` subscriptions.
+ * - An internal `DeferredSequence` resolves on every change, powering the live `*Sequence` subscriptions.
  *
  * @example
  *  const table = provider.getTable(users);
@@ -109,21 +147,19 @@ export class MemoryDBProvider extends DBProvider {
  */
 export class MemoryTable {
     /** Actual data in this table. */
-    _data = new Map();
-    /**
-     * Deferred sequence that resolves on every change to this table.
-     *
-     * @see https://shelving.cc/db/MemoryTable/next
-     */
-    next = new DeferredSequence();
+    _data;
+    /** Deferred sequence that resolves on every change to this table — `false` for a change, or `true` once when the table is disposed and its sequences should end. */
+    _next = new DeferredSequence();
     /**
      * Collection this table stores the items of.
      *
      * @see https://shelving.cc/db/MemoryTable/collection
      */
     collection;
-    constructor(collection) {
+    /** @param items Optional initial `[id, item]` entries to seed the table with. */
+    constructor(collection, items) {
         this.collection = collection;
+        this._data = new Map(items);
     }
     /**
      * Get an item by its id, or `undefined` if it doesn't exist.
@@ -150,7 +186,9 @@ export class MemoryTable {
         let lastValue = this.getItem(id);
         yield lastValue;
         while (true) {
-            await this.next;
+            const done = await this._next;
+            if (done)
+                return;
             const nextValue = this.getItem(id);
             if (nextValue !== lastValue) {
                 yield nextValue;
@@ -199,7 +237,7 @@ export class MemoryTable {
         const item = getItem(id, data);
         if (this._data.get(id) !== item) {
             this._data.set(id, item);
-            this.next.resolve();
+            this._next.resolve(false);
         }
     }
     /**
@@ -244,7 +282,7 @@ export class MemoryTable {
     deleteItem(id) {
         if (this._data.has(id)) {
             this._data.delete(id);
-            this.next.resolve();
+            this._next.resolve(false);
         }
     }
     /**
@@ -283,7 +321,9 @@ export class MemoryTable {
         let lastItems = this.getQuery(query);
         yield lastItems;
         while (true) {
-            await this.next;
+            const done = await this._next;
+            if (done)
+                return;
             const nextItems = this.getQuery(query);
             if (!isArrayEqual(lastItems, nextItems)) {
                 yield nextItems;
@@ -329,10 +369,20 @@ export class MemoryTable {
             yield items;
         }
     }
+    /**
+     * Clone this table into a new plain `MemoryTable` containing the same items.
+     *
+     * - Shallow: a new map sharing the same (immutable) item instances, so cloning is cheap.
+     * - The clone is always a plain `MemoryTable`, even when called on a subclass — writes to the clone have no side effects (e.g. `StorageTable` persistence).
+     *
+     * @example table.clone() // MemoryTable
+     * @see https://shelving.cc/db/MemoryTable/clone
+     */
+    clone() {
+        return new MemoryTable(this.collection, this._data);
+    }
     // Implement `AsyncDisposable`
     async [Symbol.asyncDispose]() {
-        await awaitDispose(
-        // Empty by default.
-        );
+        await awaitDispose(() => this._next.resolve(true));
     }
 }

package/db/provider/ThroughDBProvider.d.ts

@@ -9,6 +9,7 @@ import type { DBProvider } from "./DBProvider.js";
  * Database provider that passes every operation straight through to a wrapped `source` provider.
  *
  * - Base for the layered `Through*Provider` family (validation, caching, logging, change tracking); subclasses override individual methods to add behaviour and call `super` to delegate.
+ * - Query writes (`setQuery()`, `updateQuery()`, `deleteQuery()`) are two-step by default — resolved to their matching items with `getQuery()`, then written per item through this provider's own item methods — so wrapper behaviour applies to every implied write. Subclasses that don't need per-item behaviour override them to pass through to `source` directly.
  * - Exposes `source` and implements `Sourceable`, so wrapped providers can be discovered with `getSource()` / `requireSource()`.
  *
  * @see https://shelving.cc/db/ThroughDBProvider
@@ -31,8 +32,16 @@ export declare class ThroughDBProvider<I extends Identifier, T extends Data> imp
     countQuery<II extends I, TT extends T>(collection: Collection<string, II, TT>, query?: Query<Item<II, TT>>): Promise<number>;
     getQuery<II extends I, TT extends T>(collection: Collection<string, II, TT>, query?: Query<Item<II, TT>>): Promise<Items<II, TT>>;
     getQuerySequence<II extends I, TT extends T>(collection: Collection<string, II, TT>, query?: Query<Item<II, TT>>): ItemsSequence<II, TT>;
+    /**
+     * Two-step: resolve the query to its matching items with `getQuery()`, then set each one with `setItem()`.
+     * - Routes every implied write through this provider's own item methods, so wrapper behaviour applies to each item — the same theory as `transact()` re-wrapping the transaction provider.
+     * - The per-item writes run concurrently (`awaitValues()`), so a batch over a remote source costs one round-trip of latency, not one per item.
+     * - The resolve and the writes are separate steps, so this is only atomic inside `transact()`.
+     */
     setQuery<II extends I, TT extends T>(collection: Collection<string, II, TT>, query: Query<Item<II, TT>>, data: TT): Promise<void>;
+    /** Two-step: resolve the query to its matching items with `getQuery()`, then update each one concurrently with `updateItem()` — see `ThroughDBProvider.setQuery()`. */
     updateQuery<II extends I, TT extends T>(collection: Collection<string, II, TT>, query: Query<Item<II, TT>>, updates: Updates<TT>): Promise<void>;
+    /** Two-step: resolve the query to its matching items with `getQuery()`, then delete each one concurrently with `deleteItem()` — see `ThroughDBProvider.setQuery()`. */
     deleteQuery<II extends I, TT extends T>(collection: Collection<string, II, TT>, query: Query<Item<II, TT>>): Promise<void>;
     getFirst<II extends I, TT extends T>(collection: Collection<string, II, TT>, query: Query<Item<II, TT>>): Promise<OptionalItem<II, TT>>;
     requireFirst<II extends I, TT extends T>(collection: Collection<string, II, TT>, query: Query<Item<II, TT>>): Promise<Item<II, TT>>;

package/db/provider/ThroughDBProvider.js

@@ -1,8 +1,10 @@
+import { awaitValues } from "../../util/async.js";
 import { awaitDispose } from "../../util/dispose.js";
 /**
  * Database provider that passes every operation straight through to a wrapped `source` provider.
  *
  * - Base for the layered `Through*Provider` family (validation, caching, logging, change tracking); subclasses override individual methods to add behaviour and call `super` to delegate.
+ * - Query writes (`setQuery()`, `updateQuery()`, `deleteQuery()`) are two-step by default — resolved to their matching items with `getQuery()`, then written per item through this provider's own item methods — so wrapper behaviour applies to every implied write. Subclasses that don't need per-item behaviour override them to pass through to `source` directly.
  * - Exposes `source` and implements `Sourceable`, so wrapped providers can be discovered with `getSource()` / `requireSource()`.
  *
  * @see https://shelving.cc/db/ThroughDBProvider
@@ -47,14 +49,25 @@ export class ThroughDBProvider {
     getQuerySequence(collection, query) {
         return this.source.getQuerySequence(collection, query);
     }
-    setQuery(collection, query, data) {
-        return this.source.setQuery(collection, query, data);
-    }
-    updateQuery(collection, query, updates) {
-        return this.source.updateQuery(collection, query, updates);
-    }
-    deleteQuery(collection, query) {
-        return this.source.deleteQuery(collection, query);
+    /**
+     * Two-step: resolve the query to its matching items with `getQuery()`, then set each one with `setItem()`.
+     * - Routes every implied write through this provider's own item methods, so wrapper behaviour applies to each item — the same theory as `transact()` re-wrapping the transaction provider.
+     * - The per-item writes run concurrently (`awaitValues()`), so a batch over a remote source costs one round-trip of latency, not one per item.
+     * - The resolve and the writes are separate steps, so this is only atomic inside `transact()`.
+     */
+    async setQuery(collection, query, data) {
+        const items = await this.getQuery(collection, query);
+        await awaitValues(...items.map(({ id }) => this.setItem(collection, id, data)));
+    }
+    /** Two-step: resolve the query to its matching items with `getQuery()`, then update each one concurrently with `updateItem()` — see `ThroughDBProvider.setQuery()`. */
+    async updateQuery(collection, query, updates) {
+        const items = await this.getQuery(collection, query);
+        await awaitValues(...items.map(({ id }) => this.updateItem(collection, id, updates)));
+    }
+    /** Two-step: resolve the query to its matching items with `getQuery()`, then delete each one concurrently with `deleteItem()` — see `ThroughDBProvider.setQuery()`. */
+    async deleteQuery(collection, query) {
+        const items = await this.getQuery(collection, query);
+        await awaitValues(...items.map(({ id }) => this.deleteItem(collection, id)));
     }
     getFirst(collection, query) {
         return this.source.getFirst(collection, query);

package/db/provider/ValidationDBProvider.d.ts

@@ -30,9 +30,16 @@ export declare class ValidationDBProvider<I extends Identifier, T extends Data>
     getQuery<II extends I, TT extends T>(collection: Collection<string, II, TT>, query?: Query<Item<II, TT>>): Promise<Items<II, TT>>;
     /** Validate each emitted result; throws `ValueError` if any items fail the collection schema. */
     getQuerySequence<II extends I, TT extends T>(collection: Collection<string, II, TT>, query?: Query<Item<II, TT>>): ItemsSequence<II, TT>;
-    /** Validate the data before writing; throws `ValueError` if it fails the collection schema. */
+    /**
+     * Validate the data before writing; throws `ValueError` if it fails the collection schema.
+     * - Passthrough, not two-step: validation applies to the query write's own inputs up front, so per-item routing adds nothing — pass through to keep the source's native query write.
+     */
     setQuery<II extends I, TT extends T>(collection: Collection<string, II, TT>, query: Query<Item<II, TT>>, data: TT): Promise<void>;
-    /** Validate the updates before writing; throws `ValueError` if they fail the collection schema. */
+    /**
+     * Validate the updates before writing; throws `ValueError` if they fail the collection schema.
+     * - Passthrough, not two-step: validation applies to the query write's own inputs up front, so per-item routing adds nothing — pass through to keep the source's native query write.
+     */
     updateQuery<II extends I, TT extends T>(collection: Collection<string, II, TT>, query: Query<Item<II, TT>>, updates: Updates<TT>): Promise<void>;
+    /** Passthrough, not two-step: there are no inputs to validate per item, so keep the source's native query write. */
     deleteQuery<II extends I, TT extends T>(collection: Collection<string, II, TT>, query: Query<Item<II, TT>>): Promise<void>;
 }

package/db/provider/ValidationDBProvider.js

@@ -46,16 +46,23 @@ export class ValidationDBProvider extends ThroughDBProvider {
         for await (const items of super.getQuerySequence(collection, query))
             yield _validateItems(collection, items, this.getQuerySequence);
     }
-    /** Validate the data before writing; throws `ValueError` if it fails the collection schema. */
+    /**
+     * Validate the data before writing; throws `ValueError` if it fails the collection schema.
+     * - Passthrough, not two-step: validation applies to the query write's own inputs up front, so per-item routing adds nothing — pass through to keep the source's native query write.
+     */
     setQuery(collection, query, data) {
-        return super.setQuery(collection, query, collection.validate(data));
+        return this.source.setQuery(collection, query, collection.validate(data));
     }
-    /** Validate the updates before writing; throws `ValueError` if they fail the collection schema. */
+    /**
+     * Validate the updates before writing; throws `ValueError` if they fail the collection schema.
+     * - Passthrough, not two-step: validation applies to the query write's own inputs up front, so per-item routing adds nothing — pass through to keep the source's native query write.
+     */
     updateQuery(collection, query, updates) {
-        return super.updateQuery(collection, query, _validateUpdates(collection, updates, this.updateQuery));
+        return this.source.updateQuery(collection, query, _validateUpdates(collection, updates, this.updateQuery));
     }
+    /** Passthrough, not two-step: there are no inputs to validate per item, so keep the source's native query write. */
     deleteQuery(collection, query) {
-        return super.deleteQuery(collection, query);
+        return this.source.deleteQuery(collection, query);
     }
 }
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "shelving",
-	"version": "1.276.1",
+	"version": "1.278.0",
 	"author": "Dave Houlbrooke <dave@shax.com>",
 	"repository": {
 		"type": "git",
@@ -9,14 +9,14 @@
 	"main": "./index.js",
 	"module": "./index.js",
 	"devDependencies": {
-		"@biomejs/biome": "^2.5.4",
+		"@biomejs/biome": "^2.5.7",
 		"@heroicons/react": "^2.2.0",
 		"@types/bun": "^1.3.14",
-		"@types/react": "^19.2.17",
-		"@types/react-dom": "^19.2.3",
+		"@types/react": "^19.2.18",
+		"@types/react-dom": "^19.2.4",
 		"react": "^19.3.0-canary-fef12a01-20260413",
 		"react-dom": "^19.3.0-canary-fef12a01-20260413",
-		"stylelint": "^17.14.0",
+		"stylelint": "^17.14.1",
 		"stylelint-config-standard": "^40.0.0",
 		"typescript": "^7.0.2"
 	},

package/test/testDBProvider.d.ts

@@ -2,10 +2,12 @@ import type { DBProvider } from "../db/provider/DBProvider.js";
 import type { Data } from "../util/data.js";
 /** Options for `testDBProvider()`, declaring the capabilities of the provider under test. */
 export interface TestDBProviderOptions {
-    /** Whether the provider supports realtime sequences — when `false`, sequences are asserted to throw `UnsupportedError`. @default true */
+    /** Whether the provider supports realtime sequences — when `false`, sequences are asserted to throw `UnsupportedError` (including inside `transact()`); when `true` combined with `transactions`, sequences inside a transaction are asserted to observe the transaction and end with it. @default true */
     readonly realtime?: boolean;
     /** Whether the provider supports `transact()` — when `false`, it is asserted to throw `UnsupportedError`. @default false */
     readonly transactions?: boolean;
+    /** Whether `transact()` can be nested, committing the inner transaction into the outer — when `false`, nested calls are asserted to throw `UnsupportedError`. @default false */
+    readonly nestedTransactions?: boolean;
 }
 /**
  * Register the universal `DBProvider` contract test suite against a provider, so every backend proves the same behaviour.
@@ -19,4 +21,4 @@ export interface TestDBProviderOptions {
  * @example testDBProvider("MemoryDBProvider", () => new MemoryDBProvider<string>());
  * @see https://shelving.cc/test/testDBProvider
  */
-export declare function testDBProvider(name: string, createProvider: () => DBProvider<string, Data> | PromiseLike<DBProvider<string, Data>>, { realtime, transactions }?: TestDBProviderOptions): void;
+export declare function testDBProvider(name: string, createProvider: () => DBProvider<string, Data> | PromiseLike<DBProvider<string, Data>>, { realtime, transactions, nestedTransactions }?: TestDBProviderOptions): void;

package/test/testDBProvider.js

@@ -18,7 +18,7 @@ import { expectOrderedItems, expectUnorderedItems } from "./util.js";
  * @example testDBProvider("MemoryDBProvider", () => new MemoryDBProvider<string>());
  * @see https://shelving.cc/test/testDBProvider
  */
-export function testDBProvider(name, createProvider, { realtime = true, transactions = false } = {}) {
+export function testDBProvider(name, createProvider, { realtime = true, transactions = false, nestedTransactions = false } = {}) {
     // Create the provider and wipe both fixture collections so each test starts clean.
     async function init() {
         const provider = await createProvider();
@@ -204,6 +204,7 @@ export function testDBProvider(name, createProvider, { realtime = true, transact
         if (transactions) {
             test("transact(): commits reads and writes atomically", async () => {
                 const db = await init();
+                expect(await db.transact(async () => 123)).toBe(123); // The callback's value is returned.
                 await db.setItem(BASICS_COLLECTION, "basic1", basic1);
                 await db.setItem(BASICS_COLLECTION, "basic2", basic2);
                 const id = await db.transact(async (tx) => {
@@ -252,15 +253,58 @@ export function testDBProvider(name, createProvider, { realtime = true, transact
                 expectUnorderedItems(await db.getQuery(BASICS_COLLECTION, { str: "TX" }), ["basic1", "basic2", "basic3"]);
                 expect(await db.countQuery(BASICS_COLLECTION, {})).toBe(6);
             });
-            test("transact(): sequences and nested transactions are unsupported inside a transaction", async () => {
-                const db = await init();
-                expect(await db.transact(async () => 123)).toBe(123);
-                await db.transact(async (tx) => {
-                    expect(() => tx.getItemSequence(BASICS_COLLECTION, "basic1")).toThrow(UnsupportedError);
-                    expect(() => tx.getQuerySequence(BASICS_COLLECTION, {})).toThrow(UnsupportedError);
-                    expect(() => tx.transact(async () => undefined)).toThrow(UnsupportedError);
+            // Sequence support inside a transaction follows the `realtime` flag — a provider that supports both capabilities supports them together.
+            if (realtime) {
+                test("transact(): sequences inside a transaction observe the transaction and end with it", async () => {
+                    const db = await init();
+                    await db.setItem(BASICS_COLLECTION, "basic1", basic1);
+                    const emissions = [];
+                    let sequence;
+                    await db.transact(async (tx) => {
+                        sequence = (async () => {
+                            for await (const item of tx.getItemSequence(BASICS_COLLECTION, "basic1"))
+                                emissions.push(item);
+                        })();
+                        await runMicrotasks();
+                        await tx.updateItem(BASICS_COLLECTION, "basic1", { str: "TX" });
+                        await runMicrotasks();
+                    });
+                    await sequence; // The sequence ends when the transaction completes (this would hang otherwise).
+                    expect(emissions[0]).toMatchObject(basic1);
+                    expect(emissions[1]).toMatchObject({ ...basic1, str: "TX" });
+                    expect(await db.getItem(BASICS_COLLECTION, "basic1")).toMatchObject({ ...basic1, str: "TX" });
                 });
-            });
+            }
+            else {
+                test("transact(): sequences are unsupported inside a transaction", async () => {
+                    const db = await init();
+                    await db.transact(async (tx) => {
+                        expect(() => tx.getItemSequence(BASICS_COLLECTION, "basic1")).toThrow(UnsupportedError);
+                        expect(() => tx.getQuerySequence(BASICS_COLLECTION, {})).toThrow(UnsupportedError);
+                    });
+                });
+            }
+            if (nestedTransactions) {
+                test("transact(): nested transactions commit into the outer transaction", async () => {
+                    const db = await init();
+                    await db.transact(async (tx) => {
+                        await tx.transact(async (nested) => {
+                            await nested.setItem(BASICS_COLLECTION, "basic1", basic1);
+                        });
+                        expect(await tx.getItem(BASICS_COLLECTION, "basic1")).toMatchObject(basic1); // The inner commit is visible to the outer transaction…
+                        expect(await db.getItem(BASICS_COLLECTION, "basic1")).toBe(undefined); // …but not yet committed to the provider.
+                    });
+                    expect(await db.getItem(BASICS_COLLECTION, "basic1")).toMatchObject(basic1);
+                });
+            }
+            else {
+                test("transact(): nested transactions are unsupported", async () => {
+                    const db = await init();
+                    await db.transact(async (tx) => {
+                        expect(() => tx.transact(async () => undefined)).toThrow(UnsupportedError);
+                    });
+                });
+            }
         }
         else {
             test("transactions are not supported", async () => {