shelving 1.280.0 → 1.282.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/CacheDBProvider.d.ts

@@ -1,27 +1,23 @@
 import type { Data } from "../../util/data.js";
 import type { Identifier, Item, Items, ItemsSequence, OptionalItem, OptionalItemSequence } from "../../util/item.js";
 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 { DBProvider } from "./DBProvider.js";
+import type { DBProvider } from "./DBProvider.js";
 import { MemoryDBProvider } from "./MemoryDBProvider.js";
+import { ThroughDBProvider } from "./ThroughDBProvider.js";
 /**
  * Database provider that keeps a copy of asynchronous remote data in a local synchronous cache.
  *
  * - Wraps a `source` provider and mirrors every read and write into an in-memory `MemoryDBProvider`, so subsequent reads can be served synchronously and live subscriptions stay seeded.
  * - Reads fetch from `source`, then refresh the cache; writes hit `source`, then mirror the change into the cache.
+ * - Fetch-first item writes: `updateItem()` and `deleteItem()` fetch the item first (caching it) and skip the source write when it doesn't exist. Query writes are inherited two-step, resolving through this provider's own `getQuery()` — so the matched items are cached, and each per-item write mirrors exactly. The fetch and the writes are separate steps, so wrap them in `transact()` when they must be atomic.
+ * - Transactions run on `source` via `transact()` with a transaction-scoped mirror — only a committed transaction's writes reach the cache.
  * - Discover the cache from a wrapping layer with `getSource(CacheDBProvider, provider)` to seed stores from `.memory`.
  *
  * @see https://shelving.cc/db/CacheDBProvider
  */
-export declare class CacheDBProvider<I extends Identifier, T extends Data> extends DBProvider<I, T> implements Sourceable<DBProvider<I, T>> {
-    /**
-     * The wrapped source provider that data is fetched from and written to.
-     *
-     * @see https://shelving.cc/db/CacheDBProvider/source
-     */
-    readonly source: DBProvider<I, T>;
+export declare class CacheDBProvider<I extends Identifier, T extends Data> extends ThroughDBProvider<I, T> {
     /**
      * The in-memory provider holding the local synchronous cache of `source` data.
      *
@@ -40,20 +36,21 @@ export declare class CacheDBProvider<I extends Identifier, T extends Data> exten
     addItem<II extends I, TT extends T>(collection: Collection<string, II, TT>, data: TT): Promise<II>;
     /** Mirror the set item into the cache. */
     setItem<II extends I, TT extends T>(collection: Collection<string, II, TT>, id: II, data: TT): Promise<void>;
-    /** Mirror the updates into the cache. */
+    /** Fetch the item first (caching it), then update it only if it exists. */
     updateItem<II extends I, TT extends T>(collection: Collection<string, II, TT>, id: II, updates: Updates<Item<II, TT>>): Promise<void>;
-    /** Remove the deleted item from the cache. */
+    /** Fetch the item first, then delete it only if it exists. */
     deleteItem<II extends I, TT extends T>(collection: Collection<string, II, TT>, id: II): Promise<void>;
-    countQuery<II extends I, TT extends T>(collection: Collection<string, II, TT>, query?: Query<Item<II, TT>>): Promise<number>;
     /** Read from `source`, then refresh the cache. */
     getQuery<II extends I, TT extends T>(collection: Collection<string, II, TT>, query?: Query<Item<II, TT>>): Promise<Items<II, TT>>;
     /** Mirror each emission into the cache. */
     getQuerySequence<II extends I, TT extends T>(collection: Collection<string, II, TT>, query?: Query<Item<II, TT>>): ItemsSequence<II, TT>;
-    /** Mirror the change into the cache. */
-    setQuery<II extends I, TT extends T>(collection: Collection<string, II, TT>, query: Query<Item<II, TT>>, data: TT): Promise<void>;
-    /** Mirror the updates into the cache. */
-    updateQuery<II extends I, TT extends T>(collection: Collection<string, II, TT>, query: Query<Item<II, TT>>, updates: Updates<TT>): Promise<void>;
-    /** Remove the deleted items from the cache. */
-    deleteQuery<II extends I, TT extends T>(collection: Collection<string, II, TT>, query: Query<Item<II, TT>>): Promise<void>;
+    cloneWith(source: DBProvider<I, T>): this;
+    /**
+     * Runs the transaction on `source`, recording the callback's operations, then commits the recorded writes into the cache once the source commits.
+     * - The callback's provider is this cache over the source's transaction (with its own transaction-scoped mirror), so fetch-first writes and query resolution behave exactly as they do outside a transaction — and the fetch-then-write steps are atomic because both run in the source transaction.
+     * - Uncommitted data never touches the cache: a thrown callback commits nothing, and if the backend retries the callback only the committed attempt's writes are mirrored.
+     * - Update writes commit to the cache as deltas, so they refresh cached items and skip uncached ones — an item only read inside the transaction stays uncached until its next read.
+     */
+    transact<X>(callback: (provider: DBProvider<I, T>) => Promise<X>): Promise<X>;
     [Symbol.asyncDispose](): Promise<void>;
 }

package/db/provider/CacheDBProvider.js

@@ -1,22 +1,19 @@
 import { awaitDispose } from "../../util/dispose.js";
-import { DBProvider } from "./DBProvider.js";
 import { MemoryDBProvider } from "./MemoryDBProvider.js";
+import { RecordingDBProvider } from "./RecordingDBProvider.js";
+import { ThroughDBProvider } from "./ThroughDBProvider.js";
 /**
  * Database provider that keeps a copy of asynchronous remote data in a local synchronous cache.
  *
  * - Wraps a `source` provider and mirrors every read and write into an in-memory `MemoryDBProvider`, so subsequent reads can be served synchronously and live subscriptions stay seeded.
  * - Reads fetch from `source`, then refresh the cache; writes hit `source`, then mirror the change into the cache.
+ * - Fetch-first item writes: `updateItem()` and `deleteItem()` fetch the item first (caching it) and skip the source write when it doesn't exist. Query writes are inherited two-step, resolving through this provider's own `getQuery()` — so the matched items are cached, and each per-item write mirrors exactly. The fetch and the writes are separate steps, so wrap them in `transact()` when they must be atomic.
+ * - Transactions run on `source` via `transact()` with a transaction-scoped mirror — only a committed transaction's writes reach the cache.
  * - Discover the cache from a wrapping layer with `getSource(CacheDBProvider, provider)` to seed stores from `.memory`.
  *
  * @see https://shelving.cc/db/CacheDBProvider
  */
-export class CacheDBProvider extends DBProvider {
-    /**
-     * The wrapped source provider that data is fetched from and written to.
-     *
-     * @see https://shelving.cc/db/CacheDBProvider/source
-     */
-    source;
+export class CacheDBProvider extends ThroughDBProvider {
     /**
      * The in-memory provider holding the local synchronous cache of `source` data.
      *
@@ -27,74 +24,79 @@ export class CacheDBProvider extends DBProvider {
      * @param cache In-memory provider to use as the cache (a fresh `MemoryDBProvider` by default).
      */
     constructor(source, cache = new MemoryDBProvider()) {
-        super();
-        this.source = source;
+        super(source);
         this.memory = cache;
     }
     /** Read from `source`, then refresh the cache. */
     async getItem(collection, id) {
-        const item = await this.source.getItem(collection, id);
+        const item = await super.getItem(collection, id);
         const table = this.memory.getTable(collection);
         item ? table.setItem(id, item) : table.deleteItem(id);
         return item;
     }
     /** Mirror each emission into the cache. */
     getItemSequence(collection, id) {
-        return this.memory.getTable(collection).setItemSequence(id, this.source.getItemSequence(collection, id));
+        return this.memory.getTable(collection).setItemSequence(id, super.getItemSequence(collection, id));
     }
     /** Mirror the added item into the cache. */
     async addItem(collection, data) {
-        const id = await this.source.addItem(collection, data);
+        const id = await super.addItem(collection, data);
         this.memory.getTable(collection).setItem(id, data);
         return id;
     }
     /** Mirror the set item into the cache. */
     async setItem(collection, id, data) {
-        await this.source.setItem(collection, id, data);
+        await super.setItem(collection, id, data);
         this.memory.getTable(collection).setItem(id, data);
     }
-    /** Mirror the updates into the cache. */
+    /** Fetch the item first (caching it), then update it only if it exists. */
     async updateItem(collection, id, updates) {
-        await this.source.updateItem(collection, id, updates);
+        const item = await this.getItem(collection, id);
+        if (!item)
+            return;
+        await super.updateItem(collection, id, updates);
         this.memory.getTable(collection).updateItem(id, updates);
     }
-    /** Remove the deleted item from the cache. */
+    /** Fetch the item first, then delete it only if it exists. */
     async deleteItem(collection, id) {
-        await this.source.deleteItem(collection, id);
+        const item = await this.getItem(collection, id);
+        if (!item)
+            return;
+        await super.deleteItem(collection, id);
         this.memory.getTable(collection).deleteItem(id);
     }
-    countQuery(collection, query) {
-        return this.source.countQuery(collection, query);
-    }
     /** Read from `source`, then refresh the cache. */
     async getQuery(collection, query) {
-        const items = await this.source.getQuery(collection, query);
+        const items = await super.getQuery(collection, query);
         this.memory.getTable(collection).setItems(items);
         return items;
     }
     /** Mirror each emission into the cache. */
     getQuerySequence(collection, query) {
-        return this.memory.getTable(collection).setItemsSequence(this.source.getQuerySequence(collection, query));
+        return this.memory.getTable(collection).setItemsSequence(super.getQuerySequence(collection, query));
     }
-    /** Mirror the change into the cache. */
-    async setQuery(collection, query, data) {
-        await this.source.setQuery(collection, query, data);
-        this.memory.getTable(collection).setQuery(query, data);
+    // Override so transaction copies get their own transaction-scoped mirror — uncommitted writes must never touch the real cache.
+    cloneWith(source) {
+        const clone = super.cloneWith(source);
+        Object.defineProperty(clone, "memory", { value: new MemoryDBProvider(), enumerable: true });
+        return clone;
     }
-    /** Mirror the updates into the cache. */
-    async updateQuery(collection, query, updates) {
-        await this.source.updateQuery(collection, query, updates);
-        this.memory.getTable(collection).updateQuery(query, updates);
-    }
-    /** Remove the deleted items from the cache. */
-    async deleteQuery(collection, query) {
-        await this.source.deleteQuery(collection, query);
-        this.memory.getTable(collection).deleteQuery(query);
+    /**
+     * Runs the transaction on `source`, recording the callback's operations, then commits the recorded writes into the cache once the source commits.
+     * - The callback's provider is this cache over the source's transaction (with its own transaction-scoped mirror), so fetch-first writes and query resolution behave exactly as they do outside a transaction — and the fetch-then-write steps are atomic because both run in the source transaction.
+     * - Uncommitted data never touches the cache: a thrown callback commits nothing, and if the backend retries the callback only the committed attempt's writes are mirrored.
+     * - Update writes commit to the cache as deltas, so they refresh cached items and skip uncached ones — an item only read inside the transaction stays uncached until its next read.
+     */
+    async transact(callback) {
+        let transaction;
+        const result = await this.source.transact(provider => callback((transaction = new RecordingDBProvider(this.cloneWith(provider)))));
+        if (transaction)
+            await transaction.replayWrites(this.memory); // Commit the recorded writes into the cache.
+        return result;
     }
     // Implement `AsyncDisposable`
     async [Symbol.asyncDispose]() {
-        await awaitDispose(this.source, // Dispose the source API provider.
-        this.memory, // Dispose the source API provider.
+        await awaitDispose(this.memory, // Dispose the cache memory provider.
         super[Symbol.asyncDispose]());
     }
 }

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/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.280.0",
+	"version": "1.282.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;
-    }
-}