shelving 1.278.0 → 1.280.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/DBProvider.d.ts

@@ -119,7 +119,8 @@ 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.
+     * - Two-step by default: resolves the query to its matching items with `getQuery()`, then sets each one concurrently with `setItem()`. Engine providers override this with a native query write where one exists (e.g. SQL `UPDATE … WHERE`).
+     * - Not guaranteed atomic: the resolve and the writes are separate steps, so wrap the call in `transact()` when atomicity matters.
      *
      * @param collection Collection to write to.
      * @param query Query selecting the items to set.
@@ -127,10 +128,11 @@ export declare abstract class DBProvider<I extends Identifier = Identifier, T ex
      * @example await provider.setQuery(users, { age: 40 }, { active: true });
      * @see https://shelving.cc/db/DBProvider/setQuery
      */
-    abstract setQuery<II extends I, TT extends T>(collection: Collection<string, II, TT>, query: Query<Item<II, TT>>, data: TT): Promise<void>;
+    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.
+     * - Two-step by default: resolves the query to its matching items with `getQuery()`, then updates each one concurrently with `updateItem()`. Engine providers override this with a native query write where one exists (e.g. SQL `UPDATE … WHERE`).
+     * - Not guaranteed atomic: the resolve and the writes are separate steps, so wrap the call in `transact()` when atomicity matters.
      *
      * @param collection Collection to write to.
      * @param query Query selecting the items to update.
@@ -138,17 +140,18 @@ export declare abstract class DBProvider<I extends Identifier = Identifier, T ex
      * @example await provider.updateQuery(users, { age: 40 }, { active: true });
      * @see https://shelving.cc/db/DBProvider/updateQuery
      */
-    abstract updateQuery<II extends I, TT extends T>(collection: Collection<string, II, TT>, query: Query<Item<II, TT>>, updates: Updates<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>;
     /**
      * 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.
+     * - Two-step by default: resolves the query to its matching items with `getQuery()`, then deletes each one concurrently with `deleteItem()`. Engine providers override this with a native query write where one exists (e.g. SQL `DELETE … WHERE`).
+     * - Not guaranteed atomic: the resolve and the writes are separate steps, so wrap the call in `transact()` when atomicity matters.
      *
      * @param collection Collection to delete from.
      * @param query Query selecting the items to delete.
      * @example await provider.deleteQuery(users, { active: false });
      * @see https://shelving.cc/db/DBProvider/deleteQuery
      */
-    abstract deleteQuery<II extends I, TT extends T>(collection: Collection<string, II, TT>, query: Query<Item<II, TT>>): Promise<void>;
+    deleteQuery<II extends I, TT extends T>(collection: Collection<string, II, TT>, query: Query<Item<II, TT>>): Promise<void>;
     /**
      * Get the first item matching a query, or `undefined` if there are none.
      *

package/db/provider/DBProvider.js

@@ -1,6 +1,7 @@
 import { RequiredError } from "../../error/RequiredError.js";
 import { UnsupportedError } from "../../error/UnsupportedError.js";
 import { countArray, getFirst } from "../../util/array.js";
+import { awaitValues } from "../../util/async.js";
 import { awaitDispose } from "../../util/dispose.js";
 /**
  * Provider with a fully asynchronous interface for database access.
@@ -49,6 +50,50 @@ export class DBProvider {
     async countQuery(collection, query) {
         return countArray(await this.getQuery(collection, query));
     }
+    /**
+     * Set (overwrite) the data for every item matching a query.
+     * - Two-step by default: resolves the query to its matching items with `getQuery()`, then sets each one concurrently with `setItem()`. Engine providers override this with a native query write where one exists (e.g. SQL `UPDATE … WHERE`).
+     * - Not guaranteed atomic: the resolve and the writes are separate steps, so wrap the call in `transact()` when atomicity matters.
+     *
+     * @param collection Collection to write to.
+     * @param query Query selecting the items to set.
+     * @param data Full data to store for each matching item.
+     * @example await provider.setQuery(users, { age: 40 }, { active: true });
+     * @see https://shelving.cc/db/DBProvider/setQuery
+     */
+    async setQuery(collection, query, data) {
+        const items = await this.getQuery(collection, query);
+        await awaitValues(...items.map(({ id }) => this.setItem(collection, id, data)));
+    }
+    /**
+     * Apply partial updates to every item matching a query.
+     * - Two-step by default: resolves the query to its matching items with `getQuery()`, then updates each one concurrently with `updateItem()`. Engine providers override this with a native query write where one exists (e.g. SQL `UPDATE … WHERE`).
+     * - Not guaranteed atomic: the resolve and the writes are separate steps, so wrap the call in `transact()` when atomicity matters.
+     *
+     * @param collection Collection to write to.
+     * @param query Query selecting the items to update.
+     * @param updates Updates to apply to each matching item.
+     * @example await provider.updateQuery(users, { age: 40 }, { active: true });
+     * @see https://shelving.cc/db/DBProvider/updateQuery
+     */
+    async updateQuery(collection, query, updates) {
+        const items = await this.getQuery(collection, query);
+        await awaitValues(...items.map(({ id }) => this.updateItem(collection, id, updates)));
+    }
+    /**
+     * Delete every item matching a query.
+     * - Two-step by default: resolves the query to its matching items with `getQuery()`, then deletes each one concurrently with `deleteItem()`. Engine providers override this with a native query write where one exists (e.g. SQL `DELETE … WHERE`).
+     * - Not guaranteed atomic: the resolve and the writes are separate steps, so wrap the call in `transact()` when atomicity matters.
+     *
+     * @param collection Collection to delete from.
+     * @param query Query selecting the items to delete.
+     * @example await provider.deleteQuery(users, { active: false });
+     * @see https://shelving.cc/db/DBProvider/deleteQuery
+     */
+    async deleteQuery(collection, query) {
+        const items = await this.getQuery(collection, query);
+        await awaitValues(...items.map(({ id }) => this.deleteItem(collection, id)));
+    }
     /**
      * Get the first item matching a query, or `undefined` if there are none.
      *

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/db/provider/ThroughDBProvider.d.ts

@@ -4,17 +4,17 @@ import type { Query } from "../../util/query.js";
 import type { Sourceable } from "../../util/source.js";
 import type { Updates } from "../../util/update.js";
 import type { Collection } from "../collection/Collection.js";
-import type { DBProvider } from "./DBProvider.js";
+import { DBProvider } from "./DBProvider.js";
 /**
- * Database provider that passes every operation straight through to a wrapped `source` provider.
+ * Database provider that passes every core 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.
+ * - Only the core operations delegate to `source` — derived reads (`DBProvider.requireItem()`, `DBProvider.getFirst()`, `DBProvider.requireFirst()`) and two-step query writes are inherited from `DBProvider`, so they route through this provider's own overridden methods and wrapper behaviour applies to everything they do. Wrappers that don't need per-item behaviour override the query writes 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
  */
-export declare class ThroughDBProvider<I extends Identifier, T extends Data> implements DBProvider<I, T>, Sourceable<DBProvider<I, T>> {
+export declare class ThroughDBProvider<I extends Identifier, T extends Data> extends DBProvider<I, T> implements Sourceable<DBProvider<I, T>> {
     /**
      * The wrapped source provider that every operation is delegated to.
      *
@@ -23,28 +23,15 @@ export declare class ThroughDBProvider<I extends Identifier, T extends Data> imp
     readonly source: DBProvider<I, T>;
     constructor(source: DBProvider<I, T>);
     getItem<II extends I, TT extends T>(collection: Collection<string, II, TT>, id: II): Promise<OptionalItem<II, TT>>;
-    requireItem<II extends I, TT extends T>(collection: Collection<string, II, TT>, id: II): Promise<Item<II, TT>>;
     getItemSequence<II extends I, TT extends T>(collection: Collection<string, II, TT>, id: II): OptionalItemSequence<II, TT>;
     addItem<II extends I, TT extends T>(collection: Collection<string, II, TT>, data: TT): Promise<II>;
     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>;
+    /** Delegates to `source` so its native counting is kept (the base implementation would fetch the items and count them). */
     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>>;
     transact<X>(callback: (provider: DBProvider<I, T>) => Promise<X>): Promise<X>;
     /** Clone this provider with different `source`. */
     cloneWith(source: DBProvider<I, T>): this;

package/db/provider/ThroughDBProvider.js

@@ -1,15 +1,15 @@
-import { awaitValues } from "../../util/async.js";
 import { awaitDispose } from "../../util/dispose.js";
+import { DBProvider } from "./DBProvider.js";
 /**
- * Database provider that passes every operation straight through to a wrapped `source` provider.
+ * Database provider that passes every core 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.
+ * - Only the core operations delegate to `source` — derived reads (`DBProvider.requireItem()`, `DBProvider.getFirst()`, `DBProvider.requireFirst()`) and two-step query writes are inherited from `DBProvider`, so they route through this provider's own overridden methods and wrapper behaviour applies to everything they do. Wrappers that don't need per-item behaviour override the query writes 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
  */
-export class ThroughDBProvider {
+export class ThroughDBProvider extends DBProvider {
     /**
      * The wrapped source provider that every operation is delegated to.
      *
@@ -17,14 +17,12 @@ export class ThroughDBProvider {
      */
     source;
     constructor(source) {
+        super();
         this.source = source;
     }
     getItem(collection, id) {
         return this.source.getItem(collection, id);
     }
-    requireItem(collection, id) {
-        return this.source.requireItem(collection, id);
-    }
     getItemSequence(collection, id) {
         return this.source.getItemSequence(collection, id);
     }
@@ -40,6 +38,7 @@ export class ThroughDBProvider {
     deleteItem(collection, id) {
         return this.source.deleteItem(collection, id);
     }
+    /** Delegates to `source` so its native counting is kept (the base implementation would fetch the items and count them). */
     countQuery(collection, query) {
         return this.source.countQuery(collection, query);
     }
@@ -49,32 +48,6 @@ export class ThroughDBProvider {
     getQuerySequence(collection, query) {
         return this.source.getQuerySequence(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);
-    }
-    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)));
@@ -85,6 +58,7 @@ export class ThroughDBProvider {
     }
     // Implement `AsyncDisposable`
     async [Symbol.asyncDispose]() {
-        await awaitDispose(this.source);
+        await awaitDispose(this.source, // Dispose the source API provider.
+        super[Symbol.asyncDispose]());
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "shelving",
-	"version": "1.278.0",
+	"version": "1.280.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/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)}`;
-    }
-}