shelving 1.276.0 → 1.277.0

package/api/cache/APICache.d.ts

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

package/api/cache/APICache.js

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

package/api/provider/CachedAPIProvider.d.ts

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

package/api/provider/CachedAPIProvider.js

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

package/db/provider/ChangesDBProvider.d.ts

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

package/db/provider/ChangesDBProvider.js

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

package/db/provider/DBProvider.d.ts

@@ -119,6 +119,7 @@ export declare abstract class DBProvider<I extends Identifier = Identifier, T ex
     abstract getQuerySequence<II extends I, TT extends T>(collection: Collection<string, II, TT>, query?: Query<Item<II, TT>>): ItemsSequence<II, TT>;
     /**
      * Set (overwrite) the data for every item matching a query.
+     * - Not guaranteed atomic: an implementation may resolve the matching items first and then write per item (two-step — see `ThroughDBProvider`), so wrap the call in `transact()` when atomicity matters.
      *
      * @param collection Collection to write to.
      * @param query Query selecting the items to set.
@@ -129,6 +130,7 @@ export declare abstract class DBProvider<I extends Identifier = Identifier, T ex
     abstract setQuery<II extends I, TT extends T>(collection: Collection<string, II, TT>, query: Query<Item<II, TT>>, data: TT): Promise<void>;
     /**
      * Apply partial updates to every item matching a query.
+     * - Not guaranteed atomic: an implementation may resolve the matching items first and then write per item (two-step — see `ThroughDBProvider`), so wrap the call in `transact()` when atomicity matters.
      *
      * @param collection Collection to write to.
      * @param query Query selecting the items to update.
@@ -139,6 +141,7 @@ export declare abstract class DBProvider<I extends Identifier = Identifier, T ex
     abstract updateQuery<II extends I, TT extends T>(collection: Collection<string, II, TT>, query: Query<Item<II, TT>>, updates: Updates<TT>): Promise<void>;
     /**
      * Delete every item matching a query.
+     * - Not guaranteed atomic: an implementation may resolve the matching items first and then delete per item (two-step — see `ThroughDBProvider`), so wrap the call in `transact()` when atomicity matters.
      *
      * @param collection Collection to delete from.
      * @param query Query selecting the items to delete.

package/db/provider/DebugDBProvider.d.ts

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

package/db/provider/DebugDBProvider.js

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

package/db/provider/ThroughDBProvider.d.ts

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

package/db/provider/ThroughDBProvider.js

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

package/db/provider/ValidationDBProvider.d.ts

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

package/db/provider/ValidationDBProvider.js

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

package/firebase/FirestoreProvider.d.ts

@@ -108,7 +108,7 @@ export declare class FirestoreProvider<I extends string = string, T extends Data
     deleteQuery<II extends I, TT extends T>(collection: Collection<string, II, TT>, query: Query<Item<II, TT>>): Promise<void>;
     /**
      * Runs the callback in a Firestore transaction: begin → reads with the transaction id → buffered writes committed atomically.
-     * - Retries the whole callback (up to 5 attempts) when the commit is aborted by contention, so the callback must have no side effects other than through its provider.
+     * - Retries the whole callback (up to 5 attempts, with jittered exponential backoff) when the commit is aborted by contention, so the callback must have no side effects other than through its provider.
      * - Rolls back and rethrows if the callback throws.
      * - Reads see a consistent snapshot and never the transaction's own buffered writes.
      */

package/firebase/FirestoreProvider.js

@@ -1,12 +1,13 @@
 import { DBProvider } from "../db/provider/DBProvider.js";
 import { ResponseError } from "../error/ResponseError.js";
 import { UnsupportedError } from "../error/UnsupportedError.js";
+import { getDelay } from "../util/async.js";
 import { joinDataPath } from "../util/data.js";
 import { BLACKHOLE } from "../util/function.js";
 import { getItem } from "../util/item.js";
 import { isPlainObject } from "../util/object.js";
 import { getQueryFilters, getQueryLimit, getQueryOrders } from "../util/query.js";
-import { getRandomKey } from "../util/random.js";
+import { getRandom, getRandomKey } from "../util/random.js";
 import { getUpdates } from "../util/update.js";
 import { toData, toFirestoreFields, toFirestoreValue } from "./value.js";
 // Constants.
@@ -260,7 +261,7 @@ export class FirestoreProvider extends DBProvider {
     }
     /**
      * Runs the callback in a Firestore transaction: begin → reads with the transaction id → buffered writes committed atomically.
-     * - Retries the whole callback (up to 5 attempts) when the commit is aborted by contention, so the callback must have no side effects other than through its provider.
+     * - Retries the whole callback (up to 5 attempts, with jittered exponential backoff) when the commit is aborted by contention, so the callback must have no side effects other than through its provider.
      * - Rolls back and rethrows if the callback throws.
      * - Reads see a consistent snapshot and never the transaction's own buffered writes.
      */
@@ -268,6 +269,9 @@ export class FirestoreProvider extends DBProvider {
         let retryTransaction;
         let aborted;
         for (let attempt = 0; attempt < TRANSACTION_ATTEMPTS; attempt++) {
+            // Back off with jitter before each retry so contending transactions de-synchronise instead of re-aborting each other in lockstep.
+            if (attempt)
+                await getDelay(getRandom(0, 100 * 2 ** attempt));
             const { transaction } = (await this._request("beginTransaction", {
                 options: { readWrite: retryTransaction ? { retryTransaction } : {} },
             }));

package/package.json

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