shelving 1.279.0 → 1.280.0

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/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.279.0",
+	"version": "1.280.0",
 	"author": "Dave Houlbrooke <dave@shax.com>",
 	"repository": {
 		"type": "git",