shelving 1.277.0 → 1.278.0

package/db/provider/ChangesDBProvider.d.ts

@@ -48,7 +48,7 @@ export declare class ChangesDBProvider<I extends Identifier, T extends Data> ext
     /**
      * Replay the `changes` log onto another provider, re-issuing each write in order.
      *
-     * - Useful for audit replay or syncing a secondary store.
+     * - 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.
      *

package/db/provider/ChangesDBProvider.js

@@ -43,7 +43,7 @@ export class ChangesDBProvider extends ThroughDBProvider {
     /**
      * Replay the `changes` log onto another provider, re-issuing each write in order.
      *
-     * - Useful for audit replay or syncing a secondary store.
+     * - 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.
      *

package/db/provider/DBProvider.d.ts

@@ -177,7 +177,7 @@ export declare abstract class DBProvider<I extends Identifier = Identifier, T ex
      * - 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`.
+     * - Portable code must not use realtime sequences or nested `transact()` calls inside a transaction — most backends throw `UnsupportedError`, though some (e.g. `MemoryDBProvider`) support them scoped to the transaction.
      * - 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.

package/db/provider/DBProvider.js

@@ -89,7 +89,7 @@ export class DBProvider {
      * - 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`.
+     * - Portable code must not use realtime sequences or nested `transact()` calls inside a transaction — most backends throw `UnsupportedError`, though some (e.g. `MemoryDBProvider`) support them scoped to the transaction.
      * - 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.

package/db/provider/MemoryDBProvider.d.ts

@@ -11,6 +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.
  *
  * @see https://shelving.cc/db/MemoryDBProvider
  */
@@ -57,13 +58,32 @@ export declare class MemoryDBProvider<I extends Identifier = Identifier, T exten
      * @see https://shelving.cc/db/MemoryDBProvider/setItems
      */
     setItems<II extends I, TT extends T>(collection: Collection<string, II, TT>, items: Items<II, TT>): void;
+    /**
+     * Clone this provider into a new plain `MemoryDBProvider` containing the same items.
+     *
+     * - Shallow: new tables and maps sharing the same (immutable) item instances, so cloning is cheap and unchanged items keep their identity.
+     * - The clone is always a plain `MemoryDBProvider` with plain `MemoryTable`s, even when called on a subclass — writes to the clone only touch its own memory, never a subclass's backing store (e.g. `StorageDBProvider` persistence).
+     *
+     * @example provider.clone() // MemoryDBProvider
+     * @see https://shelving.cc/db/MemoryDBProvider/clone
+     */
+    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.
+     * - 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).
+     * - 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>;
     [Symbol.asyncDispose](): Promise<void>;
 }
 /**
  * In-memory table holding the items of a single collection for a `MemoryDBProvider`.
  *
  * - Keys items by id in a `Map`, preserving the exact object instance passed in.
- * - Exposes a `next` `DeferredSequence` that resolves on every change, powering the live `*Sequence` subscriptions.
+ * - An internal `DeferredSequence` resolves on every change, powering the live `*Sequence` subscriptions.
  *
  * @example
  *  const table = provider.getTable(users);
@@ -74,19 +94,16 @@ export declare class MemoryDBProvider<I extends Identifier = Identifier, T exten
 export declare class MemoryTable<I extends Identifier, T extends Data> implements AsyncDisposable {
     /** Actual data in this table. */
     protected readonly _data: Map<I, Item<I, T>>;
-    /**
-     * Deferred sequence that resolves on every change to this table.
-     *
-     * @see https://shelving.cc/db/MemoryTable/next
-     */
-    readonly next: DeferredSequence<void, void, void>;
+    /** Deferred sequence that resolves on every change to this table — `false` for a change, or `true` once when the table is disposed and its sequences should end. */
+    protected readonly _next: DeferredSequence<boolean, void, void>;
     /**
      * Collection this table stores the items of.
      *
      * @see https://shelving.cc/db/MemoryTable/collection
      */
     readonly collection: Collection<string, I, T>;
-    constructor(collection: Collection<string, I, T>);
+    /** @param items Optional initial `[id, item]` entries to seed the table with. */
+    constructor(collection: Collection<string, I, T>, items?: Iterable<readonly [I, Item<I, T>]>);
     /**
      * Get an item by its id, or `undefined` if it doesn't exist.
      *
@@ -215,5 +232,15 @@ export declare class MemoryTable<I extends Identifier, T extends Data> implement
     deleteQuery(query: Query<Item<I, T>>): void;
     setItems(items: Items<I, T>): void;
     setItemsSequence(sequence: AsyncIterable<Items<I, T>>): AsyncIterable<Items<I, T>>;
+    /**
+     * Clone this table into a new plain `MemoryTable` containing the same items.
+     *
+     * - Shallow: a new map sharing the same (immutable) item instances, so cloning is cheap.
+     * - The clone is always a plain `MemoryTable`, even when called on a subclass — writes to the clone have no side effects (e.g. `StorageTable` persistence).
+     *
+     * @example table.clone() // MemoryTable
+     * @see https://shelving.cc/db/MemoryTable/clone
+     */
+    clone(): MemoryTable<I, T>;
     [Symbol.asyncDispose](): Promise<void>;
 }

package/db/provider/MemoryDBProvider.js

@@ -8,6 +8,7 @@ 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";
 /**
  * Synchronous in-memory database provider, storing each collection in a `MemoryTable`.
@@ -15,6 +16,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.
  *
  * @see https://shelving.cc/db/MemoryDBProvider
  */
@@ -89,6 +91,42 @@ export class MemoryDBProvider extends DBProvider {
     setItems(collection, items) {
         this.getTable(collection).setItems(items);
     }
+    /**
+     * Clone this provider into a new plain `MemoryDBProvider` containing the same items.
+     *
+     * - Shallow: new tables and maps sharing the same (immutable) item instances, so cloning is cheap and unchanged items keep their identity.
+     * - The clone is always a plain `MemoryDBProvider` with plain `MemoryTable`s, even when called on a subclass — writes to the clone only touch its own memory, never a subclass's backing store (e.g. `StorageDBProvider` persistence).
+     *
+     * @example provider.clone() // MemoryDBProvider
+     * @see https://shelving.cc/db/MemoryDBProvider/clone
+     */
+    clone() {
+        const clone = new MemoryDBProvider();
+        for (const [name, table] of Object.entries(this._tables))
+            if (table)
+                clone._tables[name] = table.clone();
+        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.
+     * - 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).
+     * - 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 result = await callback(transaction);
+            await transaction.replay(this); // Commit the captured changes.
+            return result;
+        }
+        finally {
+            await clone[Symbol.asyncDispose](); // End any sequences opened inside the callback.
+        }
+    }
     // Implement `AsyncDisposable`
     async [Symbol.asyncDispose]() {
         await awaitDispose(...Object.values(this._tables), // Dispose all tables.
@@ -99,7 +137,7 @@ export class MemoryDBProvider extends DBProvider {
  * In-memory table holding the items of a single collection for a `MemoryDBProvider`.
  *
  * - Keys items by id in a `Map`, preserving the exact object instance passed in.
- * - Exposes a `next` `DeferredSequence` that resolves on every change, powering the live `*Sequence` subscriptions.
+ * - An internal `DeferredSequence` resolves on every change, powering the live `*Sequence` subscriptions.
  *
  * @example
  *  const table = provider.getTable(users);
@@ -109,21 +147,19 @@ export class MemoryDBProvider extends DBProvider {
  */
 export class MemoryTable {
     /** Actual data in this table. */
-    _data = new Map();
-    /**
-     * Deferred sequence that resolves on every change to this table.
-     *
-     * @see https://shelving.cc/db/MemoryTable/next
-     */
-    next = new DeferredSequence();
+    _data;
+    /** Deferred sequence that resolves on every change to this table — `false` for a change, or `true` once when the table is disposed and its sequences should end. */
+    _next = new DeferredSequence();
     /**
      * Collection this table stores the items of.
      *
      * @see https://shelving.cc/db/MemoryTable/collection
      */
     collection;
-    constructor(collection) {
+    /** @param items Optional initial `[id, item]` entries to seed the table with. */
+    constructor(collection, items) {
         this.collection = collection;
+        this._data = new Map(items);
     }
     /**
      * Get an item by its id, or `undefined` if it doesn't exist.
@@ -150,7 +186,9 @@ export class MemoryTable {
         let lastValue = this.getItem(id);
         yield lastValue;
         while (true) {
-            await this.next;
+            const done = await this._next;
+            if (done)
+                return;
             const nextValue = this.getItem(id);
             if (nextValue !== lastValue) {
                 yield nextValue;
@@ -199,7 +237,7 @@ export class MemoryTable {
         const item = getItem(id, data);
         if (this._data.get(id) !== item) {
             this._data.set(id, item);
-            this.next.resolve();
+            this._next.resolve(false);
         }
     }
     /**
@@ -244,7 +282,7 @@ export class MemoryTable {
     deleteItem(id) {
         if (this._data.has(id)) {
             this._data.delete(id);
-            this.next.resolve();
+            this._next.resolve(false);
         }
     }
     /**
@@ -283,7 +321,9 @@ export class MemoryTable {
         let lastItems = this.getQuery(query);
         yield lastItems;
         while (true) {
-            await this.next;
+            const done = await this._next;
+            if (done)
+                return;
             const nextItems = this.getQuery(query);
             if (!isArrayEqual(lastItems, nextItems)) {
                 yield nextItems;
@@ -329,10 +369,20 @@ export class MemoryTable {
             yield items;
         }
     }
+    /**
+     * Clone this table into a new plain `MemoryTable` containing the same items.
+     *
+     * - Shallow: a new map sharing the same (immutable) item instances, so cloning is cheap.
+     * - The clone is always a plain `MemoryTable`, even when called on a subclass — writes to the clone have no side effects (e.g. `StorageTable` persistence).
+     *
+     * @example table.clone() // MemoryTable
+     * @see https://shelving.cc/db/MemoryTable/clone
+     */
+    clone() {
+        return new MemoryTable(this.collection, this._data);
+    }
     // Implement `AsyncDisposable`
     async [Symbol.asyncDispose]() {
-        await awaitDispose(
-        // Empty by default.
-        );
+        await awaitDispose(() => this._next.resolve(true));
     }
 }

package/package.json

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

package/test/testDBProvider.d.ts

@@ -2,10 +2,12 @@ import type { DBProvider } from "../db/provider/DBProvider.js";
 import type { Data } from "../util/data.js";
 /** Options for `testDBProvider()`, declaring the capabilities of the provider under test. */
 export interface TestDBProviderOptions {
-    /** Whether the provider supports realtime sequences — when `false`, sequences are asserted to throw `UnsupportedError`. @default true */
+    /** Whether the provider supports realtime sequences — when `false`, sequences are asserted to throw `UnsupportedError` (including inside `transact()`); when `true` combined with `transactions`, sequences inside a transaction are asserted to observe the transaction and end with it. @default true */
     readonly realtime?: boolean;
     /** Whether the provider supports `transact()` — when `false`, it is asserted to throw `UnsupportedError`. @default false */
     readonly transactions?: boolean;
+    /** Whether `transact()` can be nested, committing the inner transaction into the outer — when `false`, nested calls are asserted to throw `UnsupportedError`. @default false */
+    readonly nestedTransactions?: boolean;
 }
 /**
  * Register the universal `DBProvider` contract test suite against a provider, so every backend proves the same behaviour.
@@ -19,4 +21,4 @@ export interface TestDBProviderOptions {
  * @example testDBProvider("MemoryDBProvider", () => new MemoryDBProvider<string>());
  * @see https://shelving.cc/test/testDBProvider
  */
-export declare function testDBProvider(name: string, createProvider: () => DBProvider<string, Data> | PromiseLike<DBProvider<string, Data>>, { realtime, transactions }?: TestDBProviderOptions): void;
+export declare function testDBProvider(name: string, createProvider: () => DBProvider<string, Data> | PromiseLike<DBProvider<string, Data>>, { realtime, transactions, nestedTransactions }?: TestDBProviderOptions): void;

package/test/testDBProvider.js

@@ -18,7 +18,7 @@ import { expectOrderedItems, expectUnorderedItems } from "./util.js";
  * @example testDBProvider("MemoryDBProvider", () => new MemoryDBProvider<string>());
  * @see https://shelving.cc/test/testDBProvider
  */
-export function testDBProvider(name, createProvider, { realtime = true, transactions = false } = {}) {
+export function testDBProvider(name, createProvider, { realtime = true, transactions = false, nestedTransactions = false } = {}) {
     // Create the provider and wipe both fixture collections so each test starts clean.
     async function init() {
         const provider = await createProvider();
@@ -204,6 +204,7 @@ export function testDBProvider(name, createProvider, { realtime = true, transact
         if (transactions) {
             test("transact(): commits reads and writes atomically", async () => {
                 const db = await init();
+                expect(await db.transact(async () => 123)).toBe(123); // The callback's value is returned.
                 await db.setItem(BASICS_COLLECTION, "basic1", basic1);
                 await db.setItem(BASICS_COLLECTION, "basic2", basic2);
                 const id = await db.transact(async (tx) => {
@@ -252,15 +253,58 @@ export function testDBProvider(name, createProvider, { realtime = true, transact
                 expectUnorderedItems(await db.getQuery(BASICS_COLLECTION, { str: "TX" }), ["basic1", "basic2", "basic3"]);
                 expect(await db.countQuery(BASICS_COLLECTION, {})).toBe(6);
             });
-            test("transact(): sequences and nested transactions are unsupported inside a transaction", async () => {
-                const db = await init();
-                expect(await db.transact(async () => 123)).toBe(123);
-                await db.transact(async (tx) => {
-                    expect(() => tx.getItemSequence(BASICS_COLLECTION, "basic1")).toThrow(UnsupportedError);
-                    expect(() => tx.getQuerySequence(BASICS_COLLECTION, {})).toThrow(UnsupportedError);
-                    expect(() => tx.transact(async () => undefined)).toThrow(UnsupportedError);
+            // Sequence support inside a transaction follows the `realtime` flag — a provider that supports both capabilities supports them together.
+            if (realtime) {
+                test("transact(): sequences inside a transaction observe the transaction and end with it", async () => {
+                    const db = await init();
+                    await db.setItem(BASICS_COLLECTION, "basic1", basic1);
+                    const emissions = [];
+                    let sequence;
+                    await db.transact(async (tx) => {
+                        sequence = (async () => {
+                            for await (const item of tx.getItemSequence(BASICS_COLLECTION, "basic1"))
+                                emissions.push(item);
+                        })();
+                        await runMicrotasks();
+                        await tx.updateItem(BASICS_COLLECTION, "basic1", { str: "TX" });
+                        await runMicrotasks();
+                    });
+                    await sequence; // The sequence ends when the transaction completes (this would hang otherwise).
+                    expect(emissions[0]).toMatchObject(basic1);
+                    expect(emissions[1]).toMatchObject({ ...basic1, str: "TX" });
+                    expect(await db.getItem(BASICS_COLLECTION, "basic1")).toMatchObject({ ...basic1, str: "TX" });
                 });
-            });
+            }
+            else {
+                test("transact(): sequences are unsupported inside a transaction", async () => {
+                    const db = await init();
+                    await db.transact(async (tx) => {
+                        expect(() => tx.getItemSequence(BASICS_COLLECTION, "basic1")).toThrow(UnsupportedError);
+                        expect(() => tx.getQuerySequence(BASICS_COLLECTION, {})).toThrow(UnsupportedError);
+                    });
+                });
+            }
+            if (nestedTransactions) {
+                test("transact(): nested transactions commit into the outer transaction", async () => {
+                    const db = await init();
+                    await db.transact(async (tx) => {
+                        await tx.transact(async (nested) => {
+                            await nested.setItem(BASICS_COLLECTION, "basic1", basic1);
+                        });
+                        expect(await tx.getItem(BASICS_COLLECTION, "basic1")).toMatchObject(basic1); // The inner commit is visible to the outer transaction…
+                        expect(await db.getItem(BASICS_COLLECTION, "basic1")).toBe(undefined); // …but not yet committed to the provider.
+                    });
+                    expect(await db.getItem(BASICS_COLLECTION, "basic1")).toMatchObject(basic1);
+                });
+            }
+            else {
+                test("transact(): nested transactions are unsupported", async () => {
+                    const db = await init();
+                    await db.transact(async (tx) => {
+                        expect(() => tx.transact(async () => undefined)).toThrow(UnsupportedError);
+                    });
+                });
+            }
         }
         else {
             test("transactions are not supported", async () => {