shelving 1.273.1 → 1.274.0

package/db/provider/ChangesDBProvider.d.ts

@@ -4,6 +4,7 @@ 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";
 import { ThroughDBProvider } from "./ThroughDBProvider.js";
 /**
  * Structured log entry recording a single database write performed through a `ChangesDBProvider`.
@@ -50,4 +51,6 @@ export declare class ChangesDBProvider<I extends Identifier, T extends Data> ext
     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>;
+    cloneWith(source: DBProvider<I, T>): this;
+    transact<X>(callback: (provider: DBProvider<I, T>) => Promise<X>): Promise<X>;
 }

package/db/provider/ChangesDBProvider.js

@@ -53,4 +53,19 @@ export class ChangesDBProvider extends ThroughDBProvider {
         await super.deleteQuery(collection, query);
         this._changes.push({ action: "delete", collection: collection.name, query });
     }
+    // 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;
+    }
 }

package/db/provider/DBProvider.d.ts

@@ -167,5 +167,22 @@ export declare abstract class DBProvider<I extends Identifier = Identifier, T ex
      * @see https://shelving.cc/db/DBProvider/requireFirst
      */
     requireFirst<II extends I, TT extends T>(collection: Collection<string, II, TT>, query: Query<Item<II, TT>>): Promise<Item<II, TT>>;
+    /**
+     * Run a callback as a single atomic transaction — every write made through the callback's provider is committed together, or not at all.
+     *
+     * - The callback receives a transaction-scoped `DBProvider`; reads and writes made through it belong to the transaction.
+     * - Reads see a consistent snapshot of the data from before the transaction, and do not see the transaction's own uncommitted writes.
+     * - If the callback throws, nothing is committed and the error is rethrown.
+     * - The callback may run more than once if the backend retries on contention, so it must have no side effects other than through its provider.
+     * - Inside a transaction, realtime sequences and nested `transact()` calls throw `UnsupportedError`.
+     * - Not every provider supports transactions — the base implementation throws `UnsupportedError`.
+     *
+     * @param callback Function that performs the transaction's reads and writes through the provider it receives.
+     * @returns The value returned by the callback.
+     * @throws `UnsupportedError` if this provider does not support transactions.
+     * @example await provider.transact(async db => void (await db.updateItem(users, 123, { logins: { sum: 1 } })));
+     * @see https://shelving.cc/db/DBProvider/transact
+     */
+    transact<X>(callback: (provider: DBProvider<I, T>) => Promise<X>): Promise<X>;
     [Symbol.asyncDispose](): Promise<void>;
 }

package/db/provider/DBProvider.js

@@ -1,4 +1,5 @@
 import { RequiredError } from "../../error/RequiredError.js";
+import { UnsupportedError } from "../../error/UnsupportedError.js";
 import { countArray, getFirst } from "../../util/array.js";
 import { awaitDispose } from "../../util/dispose.js";
 /**
@@ -81,6 +82,29 @@ export class DBProvider {
             });
         return first;
     }
+    /**
+     * Run a callback as a single atomic transaction — every write made through the callback's provider is committed together, or not at all.
+     *
+     * - The callback receives a transaction-scoped `DBProvider`; reads and writes made through it belong to the transaction.
+     * - Reads see a consistent snapshot of the data from before the transaction, and do not see the transaction's own uncommitted writes.
+     * - If the callback throws, nothing is committed and the error is rethrown.
+     * - The callback may run more than once if the backend retries on contention, so it must have no side effects other than through its provider.
+     * - Inside a transaction, realtime sequences and nested `transact()` calls throw `UnsupportedError`.
+     * - Not every provider supports transactions — the base implementation throws `UnsupportedError`.
+     *
+     * @param callback Function that performs the transaction's reads and writes through the provider it receives.
+     * @returns The value returned by the callback.
+     * @throws `UnsupportedError` if this provider does not support transactions.
+     * @example await provider.transact(async db => void (await db.updateItem(users, 123, { logins: { sum: 1 } })));
+     * @see https://shelving.cc/db/DBProvider/transact
+     */
+    transact(callback) {
+        throw new UnsupportedError(`${this.constructor.name} does not support transactions`, {
+            provider: this,
+            received: callback,
+            caller: this.transact,
+        });
+    }
     // Implement `AsyncDisposable`
     async [Symbol.asyncDispose]() {
         await awaitDispose(

package/db/provider/DebugDBProvider.d.ts

@@ -3,6 +3,7 @@ import type { Identifier, Item, Items, ItemsSequence, OptionalItem, OptionalItem
 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";
 /**
  * Database provider that logs every operation it performs to the console for debugging.
@@ -29,4 +30,6 @@ export declare class DebugDBProvider<I extends Identifier, T extends Data> exten
     setQuery<II extends I, TT extends T>(collection: Collection<string, II, TT>, query: Query<Item<II, TT>>, data: TT): Promise<void>;
     updateQuery<II extends I, TT extends T>(collection: Collection<string, II, TT>, query: Query<Item<II, TT>>, updates: Updates<TT>): Promise<void>;
     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

@@ -153,4 +153,17 @@ export class DebugDBProvider extends ThroughDBProvider {
             throw reason;
         }
     }
+    /** Adds TRANSACT logging around the base behaviour, which re-wraps so operations inside the transaction are logged too. */
+    async transact(callback) {
+        try {
+            console.debug(`${ANSI_RIGHT} TRANSACT`);
+            const result = await super.transact(callback);
+            console.debug(`${ANSI_SUCCESS} TRANSACT`);
+            return result;
+        }
+        catch (reason) {
+            console.error(`${ANSI_FAILURE} TRANSACT`, reason);
+            throw reason;
+        }
+    }
 }

package/db/provider/ThroughDBProvider.d.ts

@@ -36,5 +36,8 @@ export declare class ThroughDBProvider<I extends Identifier, T extends Data> imp
     deleteQuery<II extends I, TT extends T>(collection: Collection<string, II, TT>, query: Query<Item<II, TT>>): Promise<void>;
     getFirst<II extends I, TT extends T>(collection: Collection<string, II, TT>, query: Query<Item<II, TT>>): Promise<OptionalItem<II, TT>>;
     requireFirst<II extends I, TT extends T>(collection: Collection<string, II, TT>, query: Query<Item<II, TT>>): Promise<Item<II, TT>>;
+    transact<X>(callback: (provider: DBProvider<I, T>) => Promise<X>): Promise<X>;
+    /** Clone this provider with different `source`. */
+    cloneWith(source: DBProvider<I, T>): this;
     [Symbol.asyncDispose](): Promise<void>;
 }

package/db/provider/ThroughDBProvider.js

@@ -62,6 +62,14 @@ export class ThroughDBProvider {
     requireFirst(collection, query) {
         return this.source.requireFirst(collection, query);
     }
+    // Run the transaction against the wrapped `source` provider, keeping this provider's behaviour inside the transaction.
+    transact(callback) {
+        return this.source.transact(transaction => callback(this.cloneWith(transaction)));
+    }
+    /** Clone this provider with different `source`. */
+    cloneWith(source) {
+        return Object.create(this, { source: { value: source, enumerable: true } });
+    }
     // Implement `AsyncDisposable`
     async [Symbol.asyncDispose]() {
         await awaitDispose(this.source);

package/db/provider/ValidationDBProvider.d.ts

@@ -10,6 +10,7 @@ import { ThroughDBProvider } from "./ThroughDBProvider.js";
  * - Wraps a `source` provider (which may have any type, because validation guarantees the type) and runs every value through the relevant `Collection` schema before writing and after reading.
  * - Written data is validated against the collection's data schema; read data is validated against the item schema, so trusted, correctly-typed values reach the rest of the app.
  * - Validation failures here are program-state errors, so they throw a typed `ValueError` rather than a raw validation `string`.
+ * - Applies inside `transact()` too — the transaction provider the callback receives validates its reads and writes the same way.
  *
  * @see https://shelving.cc/db/ValidationDBProvider
  */

package/db/provider/ValidationDBProvider.js

@@ -8,6 +8,7 @@ import { ThroughDBProvider } from "./ThroughDBProvider.js";
  * - Wraps a `source` provider (which may have any type, because validation guarantees the type) and runs every value through the relevant `Collection` schema before writing and after reading.
  * - Written data is validated against the collection's data schema; read data is validated against the item schema, so trusted, correctly-typed values reach the rest of the app.
  * - Validation failures here are program-state errors, so they throw a typed `ValueError` rather than a raw validation `string`.
+ * - Applies inside `transact()` too — the transaction provider the callback receives validates its reads and writes the same way.
  *
  * @see https://shelving.cc/db/ValidationDBProvider
  */

package/package.json

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

package/test/TransactionTestDBProvider.d.ts

@@ -0,0 +1,15 @@
+import type { DBProvider } from "../db/provider/DBProvider.js";
+import { MemoryDBProvider } from "../db/provider/MemoryDBProvider.js";
+import type { Data } from "../util/data.js";
+import type { Identifier } from "../util/item.js";
+/**
+ * In-memory provider for testing wrapping providers' `transact()` — runs the callback directly against itself.
+ *
+ * - No atomicity or rollback: writes apply immediately and are kept even if the callback throws.
+ * - Use it as the `source` of a wrapping provider to test how the wrapper behaves inside transactions, not to test transaction semantics themselves.
+ *
+ * @see https://shelving.cc/test/TransactionTestDBProvider
+ */
+export declare class TransactionTestDBProvider<I extends Identifier = Identifier, T extends Data = Data> extends MemoryDBProvider<I, T> {
+    transact<X>(callback: (provider: DBProvider<I, T>) => Promise<X>): Promise<X>;
+}

package/test/TransactionTestDBProvider.js

@@ -0,0 +1,14 @@
+import { MemoryDBProvider } from "../db/provider/MemoryDBProvider.js";
+/**
+ * In-memory provider for testing wrapping providers' `transact()` — runs the callback directly against itself.
+ *
+ * - No atomicity or rollback: writes apply immediately and are kept even if the callback throws.
+ * - Use it as the `source` of a wrapping provider to test how the wrapper behaves inside transactions, not to test transaction semantics themselves.
+ *
+ * @see https://shelving.cc/test/TransactionTestDBProvider
+ */
+export class TransactionTestDBProvider extends MemoryDBProvider {
+    async transact(callback) {
+        return await callback(this);
+    }
+}

package/test/index.d.ts

@@ -1,6 +1,7 @@
 import { Collection } from "../db/collection/Collection.js";
 export * from "./basics.js";
 export * from "./people.js";
+export * from "./TransactionTestDBProvider.js";
 export * from "./util.js";
 export declare const BASICS_COLLECTION: Collection<"basics", string, {
     str: string;

package/test/index.js

@@ -4,6 +4,7 @@ import { BASIC_SCHEMA } from "./basics.js";
 import { PERSON_SCHEMA } from "./people.js";
 export * from "./basics.js";
 export * from "./people.js";
+export * from "./TransactionTestDBProvider.js";
 export * from "./util.js";
 export const BASICS_COLLECTION = new Collection("basics", STRING, BASIC_SCHEMA);
 export const PEOPLE_COLLECTION = new Collection("people", STRING, PERSON_SCHEMA);