shelving 1.279.0 → 1.281.0

package/db/index.d.ts

@@ -6,16 +6,17 @@ export * from "./migrate/PostgresMigrator.js";
 export * from "./migrate/SQLiteMigrator.js";
 export * from "./migrate/SQLMigrator.js";
 export * from "./provider/CacheDBProvider.js";
-export * from "./provider/ChangesDBProvider.js";
 export * from "./provider/DBProvider.js";
 export * from "./provider/DebugDBProvider.js";
 export * from "./provider/MemoryDBProvider.js";
 export * from "./provider/MockDBProvider.js";
 export * from "./provider/PostgresProvider.js";
+export * from "./provider/RecordingDBProvider.js";
 export * from "./provider/SQLiteProvider.js";
 export * from "./provider/SQLProvider.js";
 export * from "./provider/StorageDBProvider.js";
 export * from "./provider/ThroughDBProvider.js";
+export * from "./provider/UndoDBProvider.js";
 export * from "./provider/ValidationDBProvider.js";
 export * from "./store/ItemStore.js";
 export * from "./store/QueryStore.js";

package/db/index.js

@@ -6,16 +6,17 @@ export * from "./migrate/PostgresMigrator.js";
 export * from "./migrate/SQLiteMigrator.js";
 export * from "./migrate/SQLMigrator.js";
 export * from "./provider/CacheDBProvider.js";
-export * from "./provider/ChangesDBProvider.js";
 export * from "./provider/DBProvider.js";
 export * from "./provider/DebugDBProvider.js";
 export * from "./provider/MemoryDBProvider.js";
 export * from "./provider/MockDBProvider.js";
 export * from "./provider/PostgresProvider.js";
+export * from "./provider/RecordingDBProvider.js";
 export * from "./provider/SQLiteProvider.js";
 export * from "./provider/SQLProvider.js";
 export * from "./provider/StorageDBProvider.js";
 export * from "./provider/ThroughDBProvider.js";
+export * from "./provider/UndoDBProvider.js";
 export * from "./provider/ValidationDBProvider.js";
 export * from "./store/ItemStore.js";
 export * from "./store/QueryStore.js";

package/db/provider/DBProvider.d.ts

@@ -119,7 +119,8 @@ 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.
+     * - Two-step by default: resolves the query to its matching items with `getQuery()`, then sets each one concurrently with `setItem()`. Engine providers override this with a native query write where one exists (e.g. SQL `UPDATE … WHERE`).
+     * - Not guaranteed atomic: the resolve and the writes are separate steps, so wrap the call in `transact()` when atomicity matters.
      *
      * @param collection Collection to write to.
      * @param query Query selecting the items to set.
@@ -127,10 +128,11 @@ export declare abstract class DBProvider<I extends Identifier = Identifier, T ex
      * @example await provider.setQuery(users, { age: 40 }, { active: true });
      * @see https://shelving.cc/db/DBProvider/setQuery
      */
-    abstract setQuery<II extends I, TT extends T>(collection: Collection<string, II, TT>, query: Query<Item<II, TT>>, data: TT): Promise<void>;
+    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.
+     * - Two-step by default: resolves the query to its matching items with `getQuery()`, then updates each one concurrently with `updateItem()`. Engine providers override this with a native query write where one exists (e.g. SQL `UPDATE … WHERE`).
+     * - Not guaranteed atomic: the resolve and the writes are separate steps, so wrap the call in `transact()` when atomicity matters.
      *
      * @param collection Collection to write to.
      * @param query Query selecting the items to update.
@@ -138,17 +140,18 @@ export declare abstract class DBProvider<I extends Identifier = Identifier, T ex
      * @example await provider.updateQuery(users, { age: 40 }, { active: true });
      * @see https://shelving.cc/db/DBProvider/updateQuery
      */
-    abstract updateQuery<II extends I, TT extends T>(collection: Collection<string, II, TT>, query: Query<Item<II, TT>>, updates: Updates<TT>): Promise<void>;
+    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.
+     * - Two-step by default: resolves the query to its matching items with `getQuery()`, then deletes each one concurrently with `deleteItem()`. Engine providers override this with a native query write where one exists (e.g. SQL `DELETE … WHERE`).
+     * - Not guaranteed atomic: the resolve and the writes are separate steps, so wrap the call in `transact()` when atomicity matters.
      *
      * @param collection Collection to delete from.
      * @param query Query selecting the items to delete.
      * @example await provider.deleteQuery(users, { active: false });
      * @see https://shelving.cc/db/DBProvider/deleteQuery
      */
-    abstract deleteQuery<II extends I, TT extends T>(collection: Collection<string, II, TT>, query: Query<Item<II, TT>>): Promise<void>;
+    deleteQuery<II extends I, TT extends T>(collection: Collection<string, II, TT>, query: Query<Item<II, TT>>): Promise<void>;
     /**
      * Get the first item matching a query, or `undefined` if there are none.
      *

package/db/provider/DBProvider.js

@@ -1,6 +1,7 @@
 import { RequiredError } from "../../error/RequiredError.js";
 import { UnsupportedError } from "../../error/UnsupportedError.js";
 import { countArray, getFirst } from "../../util/array.js";
+import { awaitValues } from "../../util/async.js";
 import { awaitDispose } from "../../util/dispose.js";
 /**
  * Provider with a fully asynchronous interface for database access.
@@ -49,6 +50,50 @@ export class DBProvider {
     async countQuery(collection, query) {
         return countArray(await this.getQuery(collection, query));
     }
+    /**
+     * Set (overwrite) the data for every item matching a query.
+     * - Two-step by default: resolves the query to its matching items with `getQuery()`, then sets each one concurrently with `setItem()`. Engine providers override this with a native query write where one exists (e.g. SQL `UPDATE … WHERE`).
+     * - Not guaranteed atomic: the resolve and the writes are separate steps, so wrap the call in `transact()` when atomicity matters.
+     *
+     * @param collection Collection to write to.
+     * @param query Query selecting the items to set.
+     * @param data Full data to store for each matching item.
+     * @example await provider.setQuery(users, { age: 40 }, { active: true });
+     * @see https://shelving.cc/db/DBProvider/setQuery
+     */
+    async setQuery(collection, query, data) {
+        const items = await this.getQuery(collection, query);
+        await awaitValues(...items.map(({ id }) => this.setItem(collection, id, data)));
+    }
+    /**
+     * Apply partial updates to every item matching a query.
+     * - Two-step by default: resolves the query to its matching items with `getQuery()`, then updates each one concurrently with `updateItem()`. Engine providers override this with a native query write where one exists (e.g. SQL `UPDATE … WHERE`).
+     * - Not guaranteed atomic: the resolve and the writes are separate steps, so wrap the call in `transact()` when atomicity matters.
+     *
+     * @param collection Collection to write to.
+     * @param query Query selecting the items to update.
+     * @param updates Updates to apply to each matching item.
+     * @example await provider.updateQuery(users, { age: 40 }, { active: true });
+     * @see https://shelving.cc/db/DBProvider/updateQuery
+     */
+    async updateQuery(collection, query, updates) {
+        const items = await this.getQuery(collection, query);
+        await awaitValues(...items.map(({ id }) => this.updateItem(collection, id, updates)));
+    }
+    /**
+     * Delete every item matching a query.
+     * - Two-step by default: resolves the query to its matching items with `getQuery()`, then deletes each one concurrently with `deleteItem()`. Engine providers override this with a native query write where one exists (e.g. SQL `DELETE … WHERE`).
+     * - Not guaranteed atomic: the resolve and the writes are separate steps, so wrap the call in `transact()` when atomicity matters.
+     *
+     * @param collection Collection to delete from.
+     * @param query Query selecting the items to delete.
+     * @example await provider.deleteQuery(users, { active: false });
+     * @see https://shelving.cc/db/DBProvider/deleteQuery
+     */
+    async deleteQuery(collection, query) {
+        const items = await this.getQuery(collection, query);
+        await awaitValues(...items.map(({ id }) => this.deleteItem(collection, id)));
+    }
     /**
      * Get the first item matching a query, or `undefined` if there are none.
      *

package/db/provider/MemoryDBProvider.d.ts

@@ -11,7 +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.
+ * - Supports transactions: `transact()` runs the callback against a snapshot clone, records its operations with `RecordingDBProvider`, and replays the recorded writes onto this provider on success — sequences and nested transactions work inside the callback, scoped to the transaction.
  *
  * @see https://shelving.cc/db/MemoryDBProvider
  */
@@ -69,11 +69,11 @@ export declare class MemoryDBProvider<I extends Identifier = Identifier, T exten
      */
     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.
+     * Runs the callback against a shallow clone of this provider, recording its operations with `RecordingDBProvider`, then replays the recorded writes onto this provider when the callback resolves.
+     * - If the callback throws, the clone and its recorded operations 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).
+     * - Writes made to this provider while the callback is running are kept — the recorded writes 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>;

package/db/provider/MemoryDBProvider.js

@@ -8,15 +8,15 @@ 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";
+import { RecordingDBProvider } from "./RecordingDBProvider.js";
 /**
  * Synchronous in-memory database provider, storing each collection in a `MemoryTable`.
  *
  * - 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.
+ * - Supports transactions: `transact()` runs the callback against a snapshot clone, records its operations with `RecordingDBProvider`, and replays the recorded writes onto this provider on success — sequences and nested transactions work inside the callback, scoped to the transaction.
  *
  * @see https://shelving.cc/db/MemoryDBProvider
  */
@@ -108,19 +108,19 @@ export class MemoryDBProvider extends DBProvider {
         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.
+     * Runs the callback against a shallow clone of this provider, recording its operations with `RecordingDBProvider`, then replays the recorded writes onto this provider when the callback resolves.
+     * - If the callback throws, the clone and its recorded operations 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).
+     * - Writes made to this provider while the callback is running are kept — the recorded writes 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 transaction = new RecordingDBProvider(clone);
             const result = await callback(transaction);
-            await transaction.replay(this); // Commit the captured changes.
+            await transaction.replayWrites(this); // Commit the recorded writes.
             return result;
         }
         finally {

package/db/provider/RecordingDBProvider.d.ts

@@ -0,0 +1,115 @@
+import type { ImmutableArray, MutableArray } from "../../util/array.js";
+import type { Data } from "../../util/data.js";
+import type { Identifier, Item, Items, OptionalItem } 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";
+import { ThroughDBProvider } from "./ThroughDBProvider.js";
+/**
+ * Structured log entry recording a single database operation performed through a `RecordingDBProvider`.
+ *
+ * - `action` is the kind of operation; `collection` is the `Collection` it applies to; `id` is the item involved; `data` and `updates` carry whichever fields apply to that operation.
+ * - A `"get"` operation records a read — `data` is the item that was observed, or `undefined` if the read confirmed the item absent.
+ *
+ * @see https://shelving.cc/db/DBOperation
+ */
+export type DBOperation<I extends Identifier = Identifier, T extends Data = Data> = {
+    readonly action: "get" | "add" | "set" | "update" | "delete";
+    readonly collection: Collection<string, I, T>;
+    readonly id: I;
+    readonly data?: unknown;
+    readonly updates?: unknown;
+};
+/**
+ * Readonly array of `DBOperation` entries, e.g. the log recorded by a `RecordingDBProvider`.
+ *
+ * @see https://shelving.cc/db/DBOperations
+ */
+export type DBOperations<I extends Identifier = Identifier, T extends Data = Data> = ImmutableArray<DBOperation<I, T>>;
+/**
+ * Replay a list of database operations onto a provider, re-issuing each one in order.
+ *
+ * - Writes re-issue as the corresponding item write — `"add"` replays as `DBProvider.setItem()` with the logged id, so the target keeps the same generated ids.
+ * - `"get"` reads apply what they observed — the item is set, or deleted when the read confirmed it absent. That's right for refreshing a mirror or cache, and wrong for an authoritative target, where an observed snapshot would overwrite newer data — replay only the writes there (see `RecordingDBProvider.replayWrites()`).
+ * - Operations re-issue as a sequence of awaited writes — the replay itself is not atomic.
+ *
+ * @param provider Provider to replay the operations onto.
+ * @param operations Operations to replay, in order.
+ * @example await replayOperations(mirror, recording.operations);
+ * @see https://shelving.cc/db/replayOperations
+ */
+export declare function replayOperations<I extends Identifier, T extends Data>(provider: DBProvider<I, T>, operations: DBOperations<I, T>): Promise<void>;
+/**
+ * Database provider that records every operation it performs to its `operations` log.
+ *
+ * - Wraps a `source` provider, delegates each operation, then appends a `DBOperation` entry describing what happened.
+ * - Records reads as well as writes: `getItem()` logs a `"get"` with the item it observed (or its confirmed absence), and `getQuery()` logs a `"get"` per item returned. Derived reads and two-step query writes are inherited, so everything they do is recorded per item too. Realtime sequences are not recorded.
+ * - Replay the log onto another provider with `replay()`, `replayWrites()`, or `replayReads()`.
+ * - Useful for building audit logging, change feeds, optimistic updates (see `UndoDBProvider`), or assertions in tests.
+ *
+ * @see https://shelving.cc/db/RecordingDBProvider
+ */
+export declare class RecordingDBProvider<I extends Identifier, T extends Data> extends ThroughDBProvider<I, T> {
+    /**
+     * The log of operations performed through this provider, in the order they happened.
+     *
+     * @see https://shelving.cc/db/RecordingDBProvider/operations
+     */
+    get operations(): DBOperations<I, T>;
+    readonly _operations: MutableArray<DBOperation<I, T>>;
+    /**
+     * The write operations from the `operations` log, in the order they happened.
+     *
+     * @see https://shelving.cc/db/RecordingDBProvider/writes
+     */
+    get writes(): DBOperations<I, T>;
+    /**
+     * The `"get"` read operations from the `operations` log, in the order they happened.
+     *
+     * @see https://shelving.cc/db/RecordingDBProvider/reads
+     */
+    get reads(): DBOperations<I, T>;
+    /** Log a `"get"` operation recording the item that was observed (or its confirmed absence). */
+    getItem<II extends I, TT extends T>(collection: Collection<string, II, TT>, id: II): Promise<OptionalItem<II, TT>>;
+    /** Log a `"get"` operation for each item the query observed. */
+    getQuery<II extends I, TT extends T>(collection: Collection<string, II, TT>, query?: Query<Item<II, TT>>): Promise<Items<II, TT>>;
+    /** Log an `"add"` operation after writing. */
+    addItem<II extends I, TT extends T>(collection: Collection<string, II, TT>, data: TT): Promise<II>;
+    /** Log a `"set"` operation after writing. */
+    setItem<II extends I, TT extends T>(collection: Collection<string, II, TT>, id: II, data: TT): Promise<void>;
+    /** Log an `"update"` operation after writing. */
+    updateItem<II extends I, TT extends T>(collection: Collection<string, II, TT>, id: II, updates: Updates<Item<II, TT>>): Promise<void>;
+    /** Log a `"delete"` operation after writing. */
+    deleteItem<II extends I, TT extends T>(collection: Collection<string, II, TT>, id: II): Promise<void>;
+    /**
+     * Replay every recorded operation onto another provider, in order.
+     * - Reads apply what they observed and writes re-issue, so this refreshes a mirror or cache exactly — see `replayOperations()`.
+     * - Use `replayWrites()` for an authoritative target, where applying observed reads would overwrite newer data.
+     *
+     * @param provider Provider to replay the operations onto.
+     * @example await recording.replay(mirror);
+     * @see https://shelving.cc/db/RecordingDBProvider/replay
+     */
+    replay(provider: DBProvider<I, T>): Promise<void>;
+    /**
+     * Replay only the recorded write operations onto another provider, in order.
+     * - The right call for authoritative targets — applying a log to a real database, audit replay, syncing a second source of truth — where updates should compose onto current state and observed reads must never overwrite newer data.
+     *
+     * @param provider Provider to replay the writes onto.
+     * @example await recording.replayWrites(db);
+     * @see https://shelving.cc/db/RecordingDBProvider/replayWrites
+     */
+    replayWrites(provider: DBProvider<I, T>): Promise<void>;
+    /**
+     * Replay only the recorded `"get"` read operations onto another provider, in order.
+     * - Applies what each read observed (setting the item, or deleting it when the read confirmed absence) — e.g. warming a cache from a recorded session.
+     *
+     * @param provider Provider to replay the reads onto.
+     * @example await recording.replayReads(cache.memory);
+     * @see https://shelving.cc/db/RecordingDBProvider/replayReads
+     */
+    replayReads(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/RecordingDBProvider.js

@@ -0,0 +1,146 @@
+import { ThroughDBProvider } from "./ThroughDBProvider.js";
+/**
+ * Replay a list of database operations onto a provider, re-issuing each one in order.
+ *
+ * - Writes re-issue as the corresponding item write — `"add"` replays as `DBProvider.setItem()` with the logged id, so the target keeps the same generated ids.
+ * - `"get"` reads apply what they observed — the item is set, or deleted when the read confirmed it absent. That's right for refreshing a mirror or cache, and wrong for an authoritative target, where an observed snapshot would overwrite newer data — replay only the writes there (see `RecordingDBProvider.replayWrites()`).
+ * - Operations re-issue as a sequence of awaited writes — the replay itself is not atomic.
+ *
+ * @param provider Provider to replay the operations onto.
+ * @param operations Operations to replay, in order.
+ * @example await replayOperations(mirror, recording.operations);
+ * @see https://shelving.cc/db/replayOperations
+ */
+export async function replayOperations(provider, operations) {
+    // `as` casts needed: the log stores `data` and `updates` loosely as `unknown`.
+    for (const { action, collection, id, data, updates } of operations) {
+        if (action === "update")
+            await provider.updateItem(collection, id, updates);
+        else if (action === "delete")
+            await provider.deleteItem(collection, id);
+        else if (action === "get" && !data)
+            await provider.deleteItem(collection, id);
+        else
+            await provider.setItem(collection, id, data); // Observed items, adds, and sets all replay as the item's full data.
+    }
+}
+/**
+ * Database provider that records every operation it performs to its `operations` log.
+ *
+ * - Wraps a `source` provider, delegates each operation, then appends a `DBOperation` entry describing what happened.
+ * - Records reads as well as writes: `getItem()` logs a `"get"` with the item it observed (or its confirmed absence), and `getQuery()` logs a `"get"` per item returned. Derived reads and two-step query writes are inherited, so everything they do is recorded per item too. Realtime sequences are not recorded.
+ * - Replay the log onto another provider with `replay()`, `replayWrites()`, or `replayReads()`.
+ * - Useful for building audit logging, change feeds, optimistic updates (see `UndoDBProvider`), or assertions in tests.
+ *
+ * @see https://shelving.cc/db/RecordingDBProvider
+ */
+export class RecordingDBProvider extends ThroughDBProvider {
+    /**
+     * The log of operations performed through this provider, in the order they happened.
+     *
+     * @see https://shelving.cc/db/RecordingDBProvider/operations
+     */
+    get operations() {
+        return this._operations;
+    }
+    _operations = [];
+    /**
+     * The write operations from the `operations` log, in the order they happened.
+     *
+     * @see https://shelving.cc/db/RecordingDBProvider/writes
+     */
+    get writes() {
+        return this._operations.filter(({ action }) => action !== "get");
+    }
+    /**
+     * The `"get"` read operations from the `operations` log, in the order they happened.
+     *
+     * @see https://shelving.cc/db/RecordingDBProvider/reads
+     */
+    get reads() {
+        return this._operations.filter(({ action }) => action === "get");
+    }
+    /** Log a `"get"` operation recording the item that was observed (or its confirmed absence). */
+    async getItem(collection, id) {
+        const item = await super.getItem(collection, id);
+        this._operations.push({ action: "get", collection, id, data: item });
+        return item;
+    }
+    /** Log a `"get"` operation for each item the query observed. */
+    async getQuery(collection, query) {
+        const items = await super.getQuery(collection, query);
+        for (const item of items)
+            this._operations.push({ action: "get", collection, id: item.id, data: item });
+        return items;
+    }
+    /** Log an `"add"` operation after writing. */
+    async addItem(collection, data) {
+        const id = await super.addItem(collection, data);
+        this._operations.push({ action: "add", collection, id, data });
+        return id;
+    }
+    /** Log a `"set"` operation after writing. */
+    async setItem(collection, id, data) {
+        await super.setItem(collection, id, data);
+        this._operations.push({ action: "set", collection, id, data });
+    }
+    /** Log an `"update"` operation after writing. */
+    async updateItem(collection, id, updates) {
+        await super.updateItem(collection, id, updates);
+        this._operations.push({ action: "update", collection, id, updates });
+    }
+    /** Log a `"delete"` operation after writing. */
+    async deleteItem(collection, id) {
+        await super.deleteItem(collection, id);
+        this._operations.push({ action: "delete", collection, id });
+    }
+    /**
+     * Replay every recorded operation onto another provider, in order.
+     * - Reads apply what they observed and writes re-issue, so this refreshes a mirror or cache exactly — see `replayOperations()`.
+     * - Use `replayWrites()` for an authoritative target, where applying observed reads would overwrite newer data.
+     *
+     * @param provider Provider to replay the operations onto.
+     * @example await recording.replay(mirror);
+     * @see https://shelving.cc/db/RecordingDBProvider/replay
+     */
+    replay(provider) {
+        return replayOperations(provider, this._operations);
+    }
+    /**
+     * Replay only the recorded write operations onto another provider, in order.
+     * - The right call for authoritative targets — applying a log to a real database, audit replay, syncing a second source of truth — where updates should compose onto current state and observed reads must never overwrite newer data.
+     *
+     * @param provider Provider to replay the writes onto.
+     * @example await recording.replayWrites(db);
+     * @see https://shelving.cc/db/RecordingDBProvider/replayWrites
+     */
+    replayWrites(provider) {
+        return replayOperations(provider, this.writes);
+    }
+    /**
+     * Replay only the recorded `"get"` read operations onto another provider, in order.
+     * - Applies what each read observed (setting the item, or deleting it when the read confirmed absence) — e.g. warming a cache from a recorded session.
+     *
+     * @param provider Provider to replay the reads onto.
+     * @example await recording.replayReads(cache.memory);
+     * @see https://shelving.cc/db/RecordingDBProvider/replayReads
+     */
+    replayReads(provider) {
+        return replayOperations(provider, this.reads);
+    }
+    // Override so that transaction copies get their own log.
+    cloneWith(source) {
+        const clone = super.cloneWith(source);
+        Object.defineProperty(clone, "_operations", { value: [], enumerable: false });
+        return clone;
+    }
+    // Override to log the transaction's operations after it commits — a failed transaction logs nothing.
+    // The merge must happen after `source.transact()` resolves: backends may retry the callback or fail the commit itself, and only the committed attempt's operations belong in the log.
+    async transact(callback) {
+        let transaction;
+        const result = await this.source.transact(provider => callback((transaction = this.cloneWith(provider))));
+        if (transaction)
+            this._operations.push(...transaction.operations);
+        return result;
+    }
+}

package/db/provider/ThroughDBProvider.d.ts

@@ -4,17 +4,17 @@ import type { Query } from "../../util/query.js";
 import type { Sourceable } from "../../util/source.js";
 import type { Updates } from "../../util/update.js";
 import type { Collection } from "../collection/Collection.js";
-import type { DBProvider } from "./DBProvider.js";
+import { DBProvider } from "./DBProvider.js";
 /**
- * Database provider that passes every operation straight through to a wrapped `source` provider.
+ * Database provider that passes every core 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.
+ * - Only the core operations delegate to `source` — derived reads (`DBProvider.requireItem()`, `DBProvider.getFirst()`, `DBProvider.requireFirst()`) and two-step query writes are inherited from `DBProvider`, so they route through this provider's own overridden methods and wrapper behaviour applies to everything they do. Wrappers that don't need per-item behaviour override the query writes 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
  */
-export declare class ThroughDBProvider<I extends Identifier, T extends Data> implements DBProvider<I, T>, Sourceable<DBProvider<I, T>> {
+export declare class ThroughDBProvider<I extends Identifier, T extends Data> extends DBProvider<I, T> implements Sourceable<DBProvider<I, T>> {
     /**
      * The wrapped source provider that every operation is delegated to.
      *
@@ -23,28 +23,15 @@ export declare class ThroughDBProvider<I extends Identifier, T extends Data> imp
     readonly source: DBProvider<I, T>;
     constructor(source: DBProvider<I, T>);
     getItem<II extends I, TT extends T>(collection: Collection<string, II, TT>, id: II): Promise<OptionalItem<II, TT>>;
-    requireItem<II extends I, TT extends T>(collection: Collection<string, II, TT>, id: II): Promise<Item<II, TT>>;
     getItemSequence<II extends I, TT extends T>(collection: Collection<string, II, TT>, id: II): OptionalItemSequence<II, TT>;
     addItem<II extends I, TT extends T>(collection: Collection<string, II, TT>, data: TT): Promise<II>;
     setItem<II extends I, TT extends T>(collection: Collection<string, II, TT>, id: II, data: TT): Promise<void>;
     updateItem<II extends I, TT extends T>(collection: Collection<string, II, TT>, id: II, updates: Updates<Item<II, TT>>): Promise<void>;
     deleteItem<II extends I, TT extends T>(collection: Collection<string, II, TT>, id: II): Promise<void>;
+    /** Delegates to `source` so its native counting is kept (the base implementation would fetch the items and count them). */
     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>>;
     transact<X>(callback: (provider: DBProvider<I, T>) => Promise<X>): Promise<X>;
     /** Clone this provider with different `source`. */
     cloneWith(source: DBProvider<I, T>): this;

package/db/provider/ThroughDBProvider.js

@@ -1,15 +1,15 @@
-import { awaitValues } from "../../util/async.js";
 import { awaitDispose } from "../../util/dispose.js";
+import { DBProvider } from "./DBProvider.js";
 /**
- * Database provider that passes every operation straight through to a wrapped `source` provider.
+ * Database provider that passes every core 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.
+ * - Only the core operations delegate to `source` — derived reads (`DBProvider.requireItem()`, `DBProvider.getFirst()`, `DBProvider.requireFirst()`) and two-step query writes are inherited from `DBProvider`, so they route through this provider's own overridden methods and wrapper behaviour applies to everything they do. Wrappers that don't need per-item behaviour override the query writes 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
  */
-export class ThroughDBProvider {
+export class ThroughDBProvider extends DBProvider {
     /**
      * The wrapped source provider that every operation is delegated to.
      *
@@ -17,14 +17,12 @@ export class ThroughDBProvider {
      */
     source;
     constructor(source) {
+        super();
         this.source = source;
     }
     getItem(collection, id) {
         return this.source.getItem(collection, id);
     }
-    requireItem(collection, id) {
-        return this.source.requireItem(collection, id);
-    }
     getItemSequence(collection, id) {
         return this.source.getItemSequence(collection, id);
     }
@@ -40,6 +38,7 @@ export class ThroughDBProvider {
     deleteItem(collection, id) {
         return this.source.deleteItem(collection, id);
     }
+    /** Delegates to `source` so its native counting is kept (the base implementation would fetch the items and count them). */
     countQuery(collection, query) {
         return this.source.countQuery(collection, query);
     }
@@ -49,32 +48,6 @@ export class ThroughDBProvider {
     getQuerySequence(collection, query) {
         return this.source.getQuerySequence(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);
-    }
-    requireFirst(collection, query) {
-        return this.source.requireFirst(collection, query);
-    }
     // Run the transaction against the wrapped `source` provider, keeping this provider's behaviour inside the transaction.
     transact(callback) {
         return this.source.transact(transaction => callback(this.cloneWith(transaction)));
@@ -85,6 +58,7 @@ export class ThroughDBProvider {
     }
     // Implement `AsyncDisposable`
     async [Symbol.asyncDispose]() {
-        await awaitDispose(this.source);
+        await awaitDispose(this.source, // Dispose the source API provider.
+        super[Symbol.asyncDispose]());
     }
 }

package/db/provider/UndoDBProvider.d.ts

@@ -0,0 +1,44 @@
+import type { Data } from "../../util/data.js";
+import type { Identifier, Item } from "../../util/item.js";
+import type { Updates } from "../../util/update.js";
+import type { Collection } from "../collection/Collection.js";
+import { RecordingDBProvider } from "./RecordingDBProvider.js";
+/**
+ * Database provider that records every operation and can undo its own writes.
+ *
+ * - Extends `RecordingDBProvider`, additionally reading each item before the first write that touches it — so the log always contains every touched item's original state.
+ * - Call `undo()` to restore the wrapped provider to the state the log first observed, e.g. rolling back optimistic local updates after a failed server call.
+ * - The extra read is skipped when the log already establishes the item's state (an earlier read observed it, or an earlier add created it) — over a local `MemoryDBProvider` the reads are effectively free anyway.
+ *
+ * @example
+ *  const local = new UndoDBProvider(memory);
+ *  await runServiceLogic(local); // Applies locally right away.
+ *  try {
+ *  	await api.push(local.writes); // Send the writes to the server.
+ *  } catch {
+ *  	await local.undo(); // Server failed — restore the local copy.
+ *  }
+ *
+ * @see https://shelving.cc/db/UndoDBProvider
+ */
+export declare class UndoDBProvider<I extends Identifier, T extends Data> extends RecordingDBProvider<I, T> {
+    /** Whether the log already establishes the original state of an item (an earlier read observed it, or an earlier add created it). */
+    protected _isEstablished(collection: Collection<string, I, T>, id: I): boolean;
+    /** Read the item first (recording its original state) if the log doesn't already establish it. */
+    setItem<II extends I, TT extends T>(collection: Collection<string, II, TT>, id: II, data: TT): Promise<void>;
+    /** Read the item first (recording its original state) if the log doesn't already establish it. */
+    updateItem<II extends I, TT extends T>(collection: Collection<string, II, TT>, id: II, updates: Updates<Item<II, TT>>): Promise<void>;
+    /** Read the item first (recording its original state) if the log doesn't already establish it. */
+    deleteItem<II extends I, TT extends T>(collection: Collection<string, II, TT>, id: II): Promise<void>;
+    /**
+     * Restore the wrapped provider to the state the log first observed, undoing this provider's writes.
+     *
+     * - Applies the state-establishing operations in reverse order, so the earliest observed state of each item wins: reads restore the item that was observed (or delete it when the read confirmed it absent), and adds delete (the item did not exist before).
+     * - Restores touched items unconditionally, so concurrent writes made to those items since the recording are overwritten.
+     * - Writes directly to `source` without recording, so the log still describes the original operations afterwards.
+     *
+     * @example await provider.undo();
+     * @see https://shelving.cc/db/UndoDBProvider/undo
+     */
+    undo(): Promise<void>;
+}

package/db/provider/UndoDBProvider.js

@@ -0,0 +1,62 @@
+import { RecordingDBProvider } from "./RecordingDBProvider.js";
+/**
+ * Database provider that records every operation and can undo its own writes.
+ *
+ * - Extends `RecordingDBProvider`, additionally reading each item before the first write that touches it — so the log always contains every touched item's original state.
+ * - Call `undo()` to restore the wrapped provider to the state the log first observed, e.g. rolling back optimistic local updates after a failed server call.
+ * - The extra read is skipped when the log already establishes the item's state (an earlier read observed it, or an earlier add created it) — over a local `MemoryDBProvider` the reads are effectively free anyway.
+ *
+ * @example
+ *  const local = new UndoDBProvider(memory);
+ *  await runServiceLogic(local); // Applies locally right away.
+ *  try {
+ *  	await api.push(local.writes); // Send the writes to the server.
+ *  } catch {
+ *  	await local.undo(); // Server failed — restore the local copy.
+ *  }
+ *
+ * @see https://shelving.cc/db/UndoDBProvider
+ */
+export class UndoDBProvider extends RecordingDBProvider {
+    /** Whether the log already establishes the original state of an item (an earlier read observed it, or an earlier add created it). */
+    _isEstablished(collection, id) {
+        return this._operations.some(operation => operation.collection === collection && operation.id === id && (operation.action === "get" || operation.action === "add"));
+    }
+    /** Read the item first (recording its original state) if the log doesn't already establish it. */
+    async setItem(collection, id, data) {
+        if (!this._isEstablished(collection, id))
+            await this.getItem(collection, id);
+        await super.setItem(collection, id, data);
+    }
+    /** Read the item first (recording its original state) if the log doesn't already establish it. */
+    async updateItem(collection, id, updates) {
+        if (!this._isEstablished(collection, id))
+            await this.getItem(collection, id);
+        await super.updateItem(collection, id, updates);
+    }
+    /** Read the item first (recording its original state) if the log doesn't already establish it. */
+    async deleteItem(collection, id) {
+        if (!this._isEstablished(collection, id))
+            await this.getItem(collection, id);
+        await super.deleteItem(collection, id);
+    }
+    /**
+     * Restore the wrapped provider to the state the log first observed, undoing this provider's writes.
+     *
+     * - Applies the state-establishing operations in reverse order, so the earliest observed state of each item wins: reads restore the item that was observed (or delete it when the read confirmed it absent), and adds delete (the item did not exist before).
+     * - Restores touched items unconditionally, so concurrent writes made to those items since the recording are overwritten.
+     * - Writes directly to `source` without recording, so the log still describes the original operations afterwards.
+     *
+     * @example await provider.undo();
+     * @see https://shelving.cc/db/UndoDBProvider/undo
+     */
+    async undo() {
+        // `as` cast needed: the log stores `data` loosely as `unknown`.
+        for (const { action, collection, id, data } of this._operations.toReversed()) {
+            if (action === "get" && data)
+                await this.source.setItem(collection, id, data);
+            else if (action === "get" || action === "add")
+                await this.source.deleteItem(collection, id);
+        }
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "shelving",
-	"version": "1.279.0",
+	"version": "1.281.0",
 	"author": "Dave Houlbrooke <dave@shax.com>",
 	"repository": {
 		"type": "git",

package/db/provider/ChangesDBProvider.d.ts

@@ -1,62 +0,0 @@
-import type { MutableArray } from "../../util/array.js";
-import type { Data } from "../../util/data.js";
-import type { Identifier, Item } from "../../util/item.js";
-import type { Updates } from "../../util/update.js";
-import type { Collection } from "../collection/Collection.js";
-import type { DBProvider } from "./DBProvider.js";
-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` 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, T extends Data = Data> = {
-    readonly action: "add" | "set" | "update" | "delete";
-    readonly collection: Collection<string, I, T>;
-    readonly id: I;
-    readonly data?: unknown;
-    readonly updates?: unknown;
-};
-/**
- * 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
- */
-export declare class ChangesDBProvider<I extends Identifier, T extends Data> extends ThroughDBProvider<I, T> {
-    /**
-     * The log of writes performed through this provider, in the order they happened.
-     *
-     * @see https://shelving.cc/db/ChangesDBProvider/changes
-     */
-    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. */
-    setItem<II extends I, TT extends T>(collection: Collection<string, II, TT>, id: II, data: TT): Promise<void>;
-    /** Log an `"update"` change after writing. */
-    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>;
-    /**
-     * 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

@@ -1,80 +0,0 @@
-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
- */
-export class ChangesDBProvider extends ThroughDBProvider {
-    /**
-     * The log of writes performed through this provider, in the order they happened.
-     *
-     * @see https://shelving.cc/db/ChangesDBProvider/changes
-     */
-    get changes() {
-        return this._changes;
-    }
-    _changes = [];
-    /** Log an `"add"` change after writing. */
-    async addItem(collection, data) {
-        const id = await super.addItem(collection, 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, 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, id, updates });
-    }
-    /** Log a `"delete"` change after writing. */
-    async deleteItem(collection, id) {
-        await super.deleteItem(collection, id);
-        this._changes.push({ action: "delete", collection, id });
-    }
-    /**
-     * 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) {
-        const clone = super.cloneWith(source);
-        Object.defineProperty(clone, "_changes", { value: [], enumerable: false });
-        return clone;
-    }
-    // Override to log the transaction's writes after it commits — a failed transaction logs nothing.
-    // The merge must happen after `source.transact()` resolves: backends may retry the callback or fail the commit itself, and only the committed attempt's writes belong in the log.
-    async transact(callback) {
-        let transaction;
-        const result = await this.source.transact(provider => callback((transaction = this.cloneWith(provider))));
-        if (transaction)
-            this._changes.push(...transaction.changes);
-        return result;
-    }
-}