shelving 1.281.0 → 1.282.0

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/package.json

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