shelving 1.277.0 → 1.279.0

package/bun/BunPostgresProvider.d.ts

@@ -0,0 +1,33 @@
+import { SQL } from "bun";
+import type { Collection } from "../db/collection/Collection.js";
+import { PostgresProvider, SQLFragment } from "../db/index.js";
+import type { DBProvider } from "../db/provider/DBProvider.js";
+import type { ImmutableArray } 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";
+/**
+ * PostgreSQL database provider backed by Bun's built-in `Bun.SQL` driver.
+ *
+ * Implements the `PostgresProvider` SQL abstraction by executing tagged-template queries against a `Bun.SQL` connection.
+ * - Identifiers are escaped through `Bun.SQL`'s own `sql()` helper rather than naive string quoting, which is more secure.
+ * - Supports transactions via `transact()` — the callback runs in a `SERIALIZABLE` Postgres transaction, and contention aborts are retried automatically.
+ * - Requires the `bun` peer dependency and a running Bun environment.
+ *
+ * @see https://shelving.cc/bun/BunPostgresProvider
+ */
+export declare class BunPostgresProvider<I extends Identifier = Identifier, T extends Data = Data> extends PostgresProvider<I, T> {
+    private _sql;
+    constructor(sql: SQL);
+    /** Composes via `SQLFragment` (which flattens embedded fragments at construction), since `Bun.SQL` would otherwise bind them as `$n` parameters. */
+    exec<X extends Data>(strings: TemplateStringsArray, ...values: ImmutableArray<unknown>): Promise<ImmutableArray<X>>;
+    /** Escapes the identifier via `Bun.SQL`'s first-class `sql()` wrapping rather than manual quoting, which is more secure. */
+    sqlIdentifier(name: string): SQLFragment;
+    /** Coerces the count to a number, since `Bun.SQL` returns Postgres's 64-bit `COUNT(*)` as a string. */
+    countQuery<II extends I, TT extends T>(collection: Collection<string, II, TT>, query?: Query<Item<II, TT>>): Promise<number>;
+    /**
+     * Runs the callback in a `SERIALIZABLE` Postgres transaction via `Bun.SQL`'s `begin()` — resolving commits, throwing rolls back and rethrows.
+     * - Retries the whole callback (up to 5 attempts, with jittered exponential backoff) when Postgres aborts it for contention (serialization failure or deadlock), so the callback must have no side effects other than through its provider.
+     */
+    transact<X>(callback: (provider: DBProvider<I, T>) => Promise<X>): Promise<X>;
+}

package/bun/BunPostgresProvider.js

@@ -0,0 +1,79 @@
+import { SQL } from "bun";
+import { PostgresProvider, SQLFragment } from "../db/index.js";
+import { UnsupportedError } from "../error/UnsupportedError.js";
+import { getDelay } from "../util/async.js";
+import { getRandom } from "../util/random.js";
+// Constants.
+const TRANSACTION_ATTEMPTS = 5;
+const RETRYABLE_SQLSTATES = ["40001", "40P01"]; // Serialization failure and deadlock.
+/**
+ * PostgreSQL database provider backed by Bun's built-in `Bun.SQL` driver.
+ *
+ * Implements the `PostgresProvider` SQL abstraction by executing tagged-template queries against a `Bun.SQL` connection.
+ * - Identifiers are escaped through `Bun.SQL`'s own `sql()` helper rather than naive string quoting, which is more secure.
+ * - Supports transactions via `transact()` — the callback runs in a `SERIALIZABLE` Postgres transaction, and contention aborts are retried automatically.
+ * - Requires the `bun` peer dependency and a running Bun environment.
+ *
+ * @see https://shelving.cc/bun/BunPostgresProvider
+ */
+export class BunPostgresProvider extends PostgresProvider {
+    _sql;
+    constructor(sql) {
+        super();
+        this._sql = sql;
+    }
+    /** Composes via `SQLFragment` (which flattens embedded fragments at construction), since `Bun.SQL` would otherwise bind them as `$n` parameters. */
+    exec(strings, ...values) {
+        const flat = new SQLFragment(strings, values);
+        return this._sql(_getTemplateStrings(flat.strings), ...flat.values);
+    }
+    /** Escapes the identifier via `Bun.SQL`'s first-class `sql()` wrapping rather than manual quoting, which is more secure. */
+    sqlIdentifier(name) {
+        return this.sql `${this._sql(name)}`;
+    }
+    /** Coerces the count to a number, since `Bun.SQL` returns Postgres's 64-bit `COUNT(*)` as a string. */
+    async countQuery(collection, query) {
+        return Number.parseInt((await super.countQuery(collection, query)).toString(), 10);
+    }
+    /**
+     * Runs the callback in a `SERIALIZABLE` Postgres transaction via `Bun.SQL`'s `begin()` — resolving commits, throwing rolls back and rethrows.
+     * - Retries the whole callback (up to 5 attempts, with jittered exponential backoff) when Postgres aborts it for contention (serialization failure or deadlock), so the callback must have no side effects other than through its provider.
+     */
+    async transact(callback) {
+        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));
+            try {
+                return await this._sql.begin("isolation level serializable", tx => callback(new _BunPostgresTransaction(tx)));
+            }
+            catch (thrown) {
+                if (!_isRetryableError(thrown))
+                    throw thrown;
+                aborted = thrown; // Retry the transaction after contention.
+            }
+        }
+        throw aborted;
+    }
+}
+/** Transaction-scoped provider for `BunPostgresProvider.transact()` — every query runs on the transaction's reserved connection. */
+class _BunPostgresTransaction extends BunPostgresProvider {
+    /** Not supported inside a transaction — always throws `UnsupportedError`. */
+    transact(callback) {
+        throw new UnsupportedError("BunPostgresProvider does not support nested transactions", {
+            provider: this,
+            received: callback,
+            caller: this.transact,
+        });
+    }
+}
+/** Is a thrown value a Postgres contention abort that a fresh transaction attempt may resolve? */
+function _isRetryableError(thrown) {
+    return thrown instanceof SQL.PostgresError && RETRYABLE_SQLSTATES.includes(thrown.errno ?? thrown.code);
+}
+/** Convert a strings array into the `TemplateStringsArray` shape `Bun.SQL` expects. */
+function _getTemplateStrings(strings) {
+    const raw = [...strings];
+    return Object.assign(raw, { raw });
+}

package/bun/index.d.ts

@@ -1 +1 @@
-export * from "./BunPostgreSQLProvider.js";
+export * from "./BunPostgresProvider.js";

package/bun/index.js

@@ -1 +1 @@
-export * from "./BunPostgreSQLProvider.js";
+export * from "./BunPostgresProvider.js";

package/db/index.d.ts

@@ -2,7 +2,7 @@ export * from "./cache/CollectionCache.js";
 export * from "./cache/DBCache.js";
 export * from "./collection/Collection.js";
 export * from "./migrate/DBMigrator.js";
-export * from "./migrate/PostgreSQLMigrator.js";
+export * from "./migrate/PostgresMigrator.js";
 export * from "./migrate/SQLiteMigrator.js";
 export * from "./migrate/SQLMigrator.js";
 export * from "./provider/CacheDBProvider.js";
@@ -11,7 +11,7 @@ export * from "./provider/DBProvider.js";
 export * from "./provider/DebugDBProvider.js";
 export * from "./provider/MemoryDBProvider.js";
 export * from "./provider/MockDBProvider.js";
-export * from "./provider/PostgreSQLProvider.js";
+export * from "./provider/PostgresProvider.js";
 export * from "./provider/SQLiteProvider.js";
 export * from "./provider/SQLProvider.js";
 export * from "./provider/StorageDBProvider.js";

package/db/index.js

@@ -2,7 +2,7 @@ export * from "./cache/CollectionCache.js";
 export * from "./cache/DBCache.js";
 export * from "./collection/Collection.js";
 export * from "./migrate/DBMigrator.js";
-export * from "./migrate/PostgreSQLMigrator.js";
+export * from "./migrate/PostgresMigrator.js";
 export * from "./migrate/SQLiteMigrator.js";
 export * from "./migrate/SQLMigrator.js";
 export * from "./provider/CacheDBProvider.js";
@@ -11,7 +11,7 @@ export * from "./provider/DBProvider.js";
 export * from "./provider/DebugDBProvider.js";
 export * from "./provider/MemoryDBProvider.js";
 export * from "./provider/MockDBProvider.js";
-export * from "./provider/PostgreSQLProvider.js";
+export * from "./provider/PostgresProvider.js";
 export * from "./provider/SQLiteProvider.js";
 export * from "./provider/SQLProvider.js";
 export * from "./provider/StorageDBProvider.js";

package/db/migrate/{PostgreSQLMigrator.d.ts → PostgresMigrator.d.ts}

@@ -16,9 +16,9 @@ type PostgreSQLColumnRow = {
 /**
  * PostgreSQL migrator that inspects the live schema via `pg_catalog` tables to diff and migrate columns.
  *
- * @see https://shelving.cc/db/PostgreSQLMigrator
+ * @see https://shelving.cc/db/PostgresMigrator
  */
-export declare class PostgreSQLMigrator<T extends SQLProvider = SQLProvider> extends SQLMigrator<T> {
+export declare class PostgresMigrator<T extends SQLProvider = SQLProvider> extends SQLMigrator<T> {
     protected getTables(): Promise<readonly string[]>;
     protected getTable(name: string): Promise<SQLTable | undefined>;
     protected getCreateTableSuffix<TData extends Data>(_collection: Collection<string, Identifier, TData>): string;

package/db/migrate/{PostgreSQLMigrator.js → PostgresMigrator.js}

@@ -18,9 +18,9 @@ const COMPATIBLE_STRING_TYPES = ["character varying", "varchar", "text", "char",
 /**
  * PostgreSQL migrator that inspects the live schema via `pg_catalog` tables to diff and migrate columns.
  *
- * @see https://shelving.cc/db/PostgreSQLMigrator
+ * @see https://shelving.cc/db/PostgresMigrator
  */
-export class PostgreSQLMigrator extends SQLMigrator {
+export class PostgresMigrator extends SQLMigrator {
     async getTables() {
         const rows = await this.provider.exec `
 			SELECT c.relname AS ${this.provider.sqlIdentifier("name")}

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/db/provider/{PostgreSQLProvider.d.ts → PostgresProvider.d.ts}

@@ -7,15 +7,15 @@ import { type SQLFragment, SQLProvider } from "./SQLProvider.js";
 /**
  * Abstract PostgreSQL provider with JSONB function support for nested keys, array containment, and array mutations.
  *
- * @see https://shelving.cc/db/PostgreSQLProvider
+ * @see https://shelving.cc/db/PostgresProvider
  */
-export declare abstract class PostgreSQLProvider<I extends Identifier = Identifier, T extends Data = Data> extends SQLProvider<I, T> {
+export declare abstract class PostgresProvider<I extends Identifier = Identifier, T extends Data = Data> extends SQLProvider<I, T> {
     /** Get the Postgres JSONB path for the nested segments of a key, e.g. `{"b","c"}`. */
     private sqlPath;
     /** Extract via the Postgres `#>>` JSONB operator for nested keys, e.g. `"a" #>> {"b"}`. */
     sqlExtract(key: Segments): SQLFragment;
     /** Add Postgres JSONB support for nested keys and `with` / `omit` array mutations. */
     sqlUpdate(update: Update): SQLFragment;
-    /** Add Postgres JSONB support for `contains` filters and deeply-nested queries. */
+    /** Add Postgres JSONB support for `contains` filters, and boolean literals for empty `in` / `out` filters. */
     sqlFilter(filter: QueryFilter): SQLFragment;
 }

package/db/provider/{PostgreSQLProvider.js → PostgresProvider.js}

@@ -2,9 +2,9 @@ import { SQLProvider } from "./SQLProvider.js";
 /**
  * Abstract PostgreSQL provider with JSONB function support for nested keys, array containment, and array mutations.
  *
- * @see https://shelving.cc/db/PostgreSQLProvider
+ * @see https://shelving.cc/db/PostgresProvider
  */
-export class PostgreSQLProvider extends SQLProvider {
+export class PostgresProvider extends SQLProvider {
     /** Get the Postgres JSONB path for the nested segments of a key, e.g. `{"b","c"}`. */
     sqlPath(key) {
         return this.sqlConcat(key.slice(1).map(k => this.sqlIdentifier(k)), ",", "{", "}");
@@ -65,12 +65,17 @@ export class PostgreSQLProvider extends SQLProvider {
         }
         return super.sqlUpdate(update);
     }
-    /** Add Postgres JSONB support for `contains` filters and deeply-nested queries. */
+    /** Add Postgres JSONB support for `contains` filters, and boolean literals for empty `in` / `out` filters. */
     sqlFilter(filter) {
         const { key, operator, value } = filter;
         // Implement `contains` filters.
         if (operator === "contains")
             return this.sql `${this.sqlExtract(key)} @> ${[value]}`;
+        // Postgres `WHERE` requires a boolean, so empty `in` / `out` filters can't use the base class's `0` / `1` integer literals.
+        if (operator === "in" && !value.length)
+            return this.sql `FALSE`;
+        if (operator === "out" && !value.length)
+            return this.sql `TRUE`;
         return super.sqlFilter(filter);
     }
 }

package/db/provider/SQLProvider.d.ts

@@ -8,11 +8,16 @@ import type { Collection } from "../collection/Collection.js";
 import { DBProvider } from "./DBProvider.js";
 /**
  * SQL fragment made from template strings plus embedded expressions, ready to be composed into a query.
+ *
+ * - Flattens eagerly: `SQLFragment` values are spliced inline at construction, so `values` only ever contains bindable parameters (or driver-specific identifier tokens) — never other fragments.
+ * - Concrete providers can therefore pass `strings` / `values` straight to their driver, and detect fragments with a plain `instanceof` check.
+ *
  * @see https://shelving.cc/db/SQLFragment
  */
-export interface SQLFragment {
+export declare class SQLFragment {
     readonly strings: ImmutableArray<string>;
     readonly values: ImmutableArray<unknown>;
+    constructor(strings: ImmutableArray<string>, values: ImmutableArray<unknown>);
 }
 /**
  * Abstract database provider that implements CRUD and query operations by generating and executing SQL.
@@ -41,6 +46,7 @@ export declare abstract class SQLProvider<I extends Identifier = Identifier, T e
     setItem<II extends I, TT extends T>(collection: Collection<string, II, TT>, id: II, data: TT): Promise<void>;
     updateItem<II extends I, TT extends T>(collection: Collection<string, II, TT>, id: II, updates: Updates<Item<II, TT>>): Promise<void>;
     deleteItem<II extends I, TT extends T>(collection: Collection<string, II, TT>, id: II): Promise<void>;
+    /** Counts via a subquery so a `$limit` in the query caps the counted rows rather than the (single) result row. */
     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>>;
     /** Unsupported by SQL providers — always throws `UnsupportedError`. */

package/db/provider/SQLProvider.js

@@ -3,6 +3,39 @@ import { UnsupportedError } from "../../error/UnsupportedError.js";
 import { getQueryFilters, getQueryLimit, getQueryOrders } from "../../util/query.js";
 import { getUpdates } from "../../util/update.js";
 import { DBProvider } from "./DBProvider.js";
+/**
+ * SQL fragment made from template strings plus embedded expressions, ready to be composed into a query.
+ *
+ * - Flattens eagerly: `SQLFragment` values are spliced inline at construction, so `values` only ever contains bindable parameters (or driver-specific identifier tokens) — never other fragments.
+ * - Concrete providers can therefore pass `strings` / `values` straight to their driver, and detect fragments with a plain `instanceof` check.
+ *
+ * @see https://shelving.cc/db/SQLFragment
+ */
+export class SQLFragment {
+    strings;
+    values;
+    constructor(strings, values) {
+        const outStrings = [strings[0] ?? ""];
+        const outValues = [];
+        for (const [i, value] of values.entries()) {
+            if (value instanceof SQLFragment) {
+                // Splice the (already flat) fragment inline.
+                outStrings[outStrings.length - 1] += value.strings[0] ?? "";
+                for (let n = 0; n < value.values.length; n++) {
+                    outValues.push(value.values[n]);
+                    outStrings.push(value.strings[n + 1] ?? "");
+                }
+            }
+            else {
+                outValues.push(value);
+                outStrings.push("");
+            }
+            outStrings[outStrings.length - 1] += strings[i + 1] ?? "";
+        }
+        this.strings = outStrings;
+        this.values = outValues;
+    }
+}
 /**
  * Abstract database provider that implements CRUD and query operations by generating and executing SQL.
  *
@@ -52,10 +85,13 @@ export class SQLProvider extends DBProvider {
     async deleteItem(collection, id) {
         await this.exec `DELETE FROM ${this.sqlIdentifier(collection.name)} WHERE ${this.sqlIdentifier("id")} = ${id}`;
     }
+    /** Counts via a subquery so a `$limit` in the query caps the counted rows rather than the (single) result row. */
     async countQuery(collection, query) {
         const rows = await this.exec `
-			SELECT COUNT(*) AS "count" FROM ${this.sqlIdentifier(collection.name)}
-			${query ? this.sqlClauses(query) : this.sql ``}
+			SELECT COUNT(*) AS "count" FROM (
+				SELECT 1 FROM ${this.sqlIdentifier(collection.name)}
+				${query ? this.sqlClauses(query) : this.sql ``}
+			) AS ${this.sqlIdentifier("items")}
 		`;
         return rows[0]?.count ?? 0;
     }
@@ -87,7 +123,7 @@ export class SQLProvider extends DBProvider {
      * @see https://shelving.cc/db/SQLProvider/sql
      */
     sql(strings, ...values) {
-        return { strings, values };
+        return new SQLFragment(strings, values);
     }
     /**
      * Define an SQL fragment for an escaped identifier, e.g. `"myTable"`.
@@ -97,7 +133,7 @@ export class SQLProvider extends DBProvider {
      * @see https://shelving.cc/db/SQLProvider/sqlIdentifier
      */
     sqlIdentifier(name) {
-        return { strings: [_escapeIdentifier(name)], values: [] };
+        return new SQLFragment([_escapeIdentifier(name)], []);
     }
     /**
      * Define an SQL fragment that extracts a value at a key for comparison, e.g. `"a" #>> {"b","c"}` in Postgres.
@@ -125,7 +161,7 @@ export class SQLProvider extends DBProvider {
      */
     sqlConcat(values, separator = ", ", before = "", after = "") {
         const strings = [before, ...new Array(Math.max(0, values.length - 1)).fill(separator), after];
-        return { strings, values };
+        return new SQLFragment(strings, values);
     }
     /**
      * Define an SQL fragment for setting a list of values, e.g. `"a" = 1, "b" = 2`.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "shelving",
-	"version": "1.277.0",
+	"version": "1.279.0",
 	"author": "Dave Houlbrooke <dave@shax.com>",
 	"repository": {
 		"type": "git",
@@ -68,7 +68,8 @@
 		"fix": "bun run --sequential fix:*",
 		"fix:0:lint": "biome check --write .",
 		"fix:1:style": "stylelint \"modules/**/*.css\" --fix",
-		"test:firebase": "bunx firebase-tools emulators:exec --only firestore --project shelving-test \"bun test ./modules/firebase\"",
+		"firebase": "bunx firebase-tools emulators:exec --only firestore --project shelving-test \"bun test ./modules/firebase\"",
+		"postgres": "bun ./scripts/postgres.ts",
 		"docs:build": "bun ./docs/build.tsx",
 		"docs:start": "bun ./docs/start.tsx",
 		"build": "bun run --sequential build:*",

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 () => {

package/bun/BunPostgreSQLProvider.d.ts

@@ -1,21 +0,0 @@
-import type { SQL } from "bun";
-import { PostgreSQLProvider, type SQLFragment } from "../db/index.js";
-import type { ImmutableArray } from "../util/array.js";
-import type { Data } from "../util/data.js";
-import type { Identifier } from "../util/item.js";
-/**
- * PostgreSQL database provider backed by Bun's built-in `Bun.SQL` driver.
- *
- * Implements the `PostgreSQLProvider` SQL abstraction by executing tagged-template queries against a `Bun.SQL` connection.
- * - Identifiers are escaped through `Bun.SQL`'s own `sql()` helper rather than naive string quoting, which is more secure.
- * - Requires the `bun` peer dependency and a running Bun environment.
- *
- * @see https://shelving.cc/bun/BunPostgreSQLProvider
- */
-export declare class BunPostgreSQLProvider<I extends Identifier = Identifier, T extends Data = Data> extends PostgreSQLProvider<I, T> {
-    private _sql;
-    constructor(sql: SQL);
-    exec<X extends Data>(strings: TemplateStringsArray, ...values: ImmutableArray<unknown>): Promise<ImmutableArray<X>>;
-    /** Escapes the identifier via `Bun.SQL`'s first-class `sql()` wrapping rather than manual quoting, which is more secure. */
-    sqlIdentifier(name: string): SQLFragment;
-}

package/bun/BunPostgreSQLProvider.js

@@ -1,24 +0,0 @@
-import { PostgreSQLProvider } from "../db/index.js";
-/**
- * PostgreSQL database provider backed by Bun's built-in `Bun.SQL` driver.
- *
- * Implements the `PostgreSQLProvider` SQL abstraction by executing tagged-template queries against a `Bun.SQL` connection.
- * - Identifiers are escaped through `Bun.SQL`'s own `sql()` helper rather than naive string quoting, which is more secure.
- * - Requires the `bun` peer dependency and a running Bun environment.
- *
- * @see https://shelving.cc/bun/BunPostgreSQLProvider
- */
-export class BunPostgreSQLProvider extends PostgreSQLProvider {
-    _sql;
-    constructor(sql) {
-        super();
-        this._sql = sql;
-    }
-    exec(strings, ...values) {
-        return this._sql(strings, ...values);
-    }
-    /** Escapes the identifier via `Bun.SQL`'s first-class `sql()` wrapping rather than manual quoting, which is more secure. */
-    sqlIdentifier(name) {
-        return this.sql `${this._sql(name)}`;
-    }
-}