shelving 1.236.0 → 1.236.2

package/db/provider/CacheDBProvider.js

@@ -1,60 +1,194 @@
 import { awaitDispose } from "../../util/dispose.js";
 import { DBProvider } from "./DBProvider.js";
 import { MemoryDBProvider } from "./MemoryDBProvider.js";
-/** Keep a copy of asynchronous remote data in a local synchronous cache. */
+/**
+ * Database provider that keeps a copy of asynchronous remote data in a local synchronous cache.
+ *
+ * - Wraps a `source` provider and mirrors every read and write into an in-memory `MemoryDBProvider`, so subsequent reads can be served synchronously and live subscriptions stay seeded.
+ * - Reads fetch from `source`, then refresh the cache; writes hit `source`, then mirror the change into the cache.
+ * - Discover the cache from a wrapping layer with `getSource(CacheDBProvider, provider)` to seed stores from `.memory`.
+ *
+ * @example
+ *  const provider = new CacheDBProvider(new FirestoreProvider());
+ *  await provider.getItem(users, 123); // Fetches from source, then caches in memory.
+ *
+ * @see https://dhoulb.github.io/shelving/db/provider/CacheDBProvider/CacheDBProvider
+ */
 export class CacheDBProvider extends DBProvider {
+    /**
+     * The wrapped source provider that data is fetched from and written to.
+     *
+     * @see https://dhoulb.github.io/shelving/db/provider/CacheDBProvider/CacheDBProvider/source
+     */
     source;
+    /**
+     * The in-memory provider holding the local synchronous cache of `source` data.
+     *
+     * @see https://dhoulb.github.io/shelving/db/provider/CacheDBProvider/CacheDBProvider/memory
+     */
     memory;
+    /**
+     * Create a new `CacheDBProvider` wrapping a source provider.
+     *
+     * @param source The provider to fetch from and write to.
+     * @param cache In-memory provider to use as the cache (a fresh `MemoryDBProvider` by default).
+     */
     constructor(source, cache = new MemoryDBProvider()) {
         super();
         this.source = source;
         this.memory = cache;
     }
+    /**
+     * Get an item from `source` by its id, refreshing the cache, or `undefined` if it doesn't exist.
+     *
+     * @param collection Collection the item belongs to.
+     * @param id Identifier of the item to get.
+     * @returns The item, or `undefined` if no item exists with that id.
+     * @example await provider.getItem(users, 123) // Item or undefined.
+     * @see https://dhoulb.github.io/shelving/db/provider/CacheDBProvider/CacheDBProvider/getItem
+     */
     async getItem(collection, id) {
         const item = await this.source.getItem(collection, id);
         const table = this.memory.getTable(collection);
         item ? table.setItem(id, item) : table.deleteItem(id);
         return item;
     }
+    /**
+     * Subscribe to live changes for a single item, mirroring each emission into the cache.
+     *
+     * @param collection Collection the item belongs to.
+     * @param id Identifier of the item to subscribe to.
+     * @returns Async sequence yielding the item (or `undefined`) on every change.
+     * @example for await (const item of provider.getItemSequence(users, 123)) console.log(item);
+     * @see https://dhoulb.github.io/shelving/db/provider/CacheDBProvider/CacheDBProvider/getItemSequence
+     */
     getItemSequence(collection, id) {
         return this.memory.getTable(collection).setItemSequence(id, this.source.getItemSequence(collection, id));
     }
+    /**
+     * Add a new item to `source` and mirror it into the cache.
+     *
+     * @param collection Collection to add the item to.
+     * @param data Data for the new item.
+     * @returns The generated identifier for the new item.
+     * @example await provider.addItem(users, { name: "Dave" }) // 123
+     * @see https://dhoulb.github.io/shelving/db/provider/CacheDBProvider/CacheDBProvider/addItem
+     */
     async addItem(collection, data) {
         const id = await this.source.addItem(collection, data);
         this.memory.getTable(collection).setItem(id, data);
         return id;
     }
+    /**
+     * Set (insert or overwrite) an item in `source` and mirror it into the cache.
+     *
+     * @param collection Collection the item belongs to.
+     * @param id Identifier of the item to set.
+     * @param data Full data to store for the item.
+     * @example await provider.setItem(users, 123, { name: "Dave" });
+     * @see https://dhoulb.github.io/shelving/db/provider/CacheDBProvider/CacheDBProvider/setItem
+     */
     async setItem(collection, id, data) {
         await this.source.setItem(collection, id, data);
         this.memory.getTable(collection).setItem(id, data);
     }
+    /**
+     * Apply partial updates to an item in `source` and mirror them into the cache.
+     *
+     * @param collection Collection the item belongs to.
+     * @param id Identifier of the item to update.
+     * @param updates Updates to apply to the item.
+     * @example await provider.updateItem(users, 123, { name: "Dave" });
+     * @see https://dhoulb.github.io/shelving/db/provider/CacheDBProvider/CacheDBProvider/updateItem
+     */
     async updateItem(collection, id, updates) {
         await this.source.updateItem(collection, id, updates);
         this.memory.getTable(collection).updateItem(id, updates);
     }
+    /**
+     * Delete an item from `source` and remove it from the cache.
+     *
+     * @param collection Collection the item belongs to.
+     * @param id Identifier of the item to delete.
+     * @example await provider.deleteItem(users, 123);
+     * @see https://dhoulb.github.io/shelving/db/provider/CacheDBProvider/CacheDBProvider/deleteItem
+     */
     async deleteItem(collection, id) {
         await this.source.deleteItem(collection, id);
         this.memory.getTable(collection).deleteItem(id);
     }
+    /**
+     * Count the items in `source` matching an optional query (not cached).
+     *
+     * @param collection Collection to count items in.
+     * @param query Query to filter the counted items (counts all items when omitted).
+     * @returns The number of matching items.
+     * @example await provider.countQuery(users, { age: 40 }) // 7
+     * @see https://dhoulb.github.io/shelving/db/provider/CacheDBProvider/CacheDBProvider/countQuery
+     */
     countQuery(collection, query) {
         return this.source.countQuery(collection, query);
     }
+    /**
+     * Get the items in `source` matching an optional query, refreshing the cache.
+     *
+     * @param collection Collection to query.
+     * @param query Query to filter, sort, and limit the items (returns all items when omitted).
+     * @returns An array of matching items.
+     * @example await provider.getQuery(users, { age: 40, $order: "name" }) // Items.
+     * @see https://dhoulb.github.io/shelving/db/provider/CacheDBProvider/CacheDBProvider/getQuery
+     */
     async getQuery(collection, query) {
         const items = await this.source.getQuery(collection, query);
         this.memory.getTable(collection).setItems(items);
         return items;
     }
+    /**
+     * Subscribe to live changes for a query, mirroring each emission into the cache.
+     *
+     * @param collection Collection to query.
+     * @param query Query to filter, sort, and limit the items.
+     * @returns Async sequence yielding the matching items on every change.
+     * @example for await (const items of provider.getQuerySequence(users, { age: 40 })) console.log(items);
+     * @see https://dhoulb.github.io/shelving/db/provider/CacheDBProvider/CacheDBProvider/getQuerySequence
+     */
     getQuerySequence(collection, query) {
         return this.memory.getTable(collection).setItemsSequence(this.source.getQuerySequence(collection, query));
     }
+    /**
+     * Set (overwrite) every item in `source` matching a query and mirror the change into the cache.
+     *
+     * @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://dhoulb.github.io/shelving/db/provider/CacheDBProvider/CacheDBProvider/setQuery
+     */
     async setQuery(collection, query, data) {
         await this.source.setQuery(collection, query, data);
         this.memory.getTable(collection).setQuery(query, data);
     }
+    /**
+     * Apply partial updates to every item in `source` matching a query and mirror them into the cache.
+     *
+     * @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://dhoulb.github.io/shelving/db/provider/CacheDBProvider/CacheDBProvider/updateQuery
+     */
     async updateQuery(collection, query, updates) {
         await this.source.updateQuery(collection, query, updates);
         this.memory.getTable(collection).updateQuery(query, updates);
     }
+    /**
+     * Delete every item in `source` matching a query and remove them from the cache.
+     *
+     * @param collection Collection to delete from.
+     * @param query Query selecting the items to delete.
+     * @example await provider.deleteQuery(users, { active: false });
+     * @see https://dhoulb.github.io/shelving/db/provider/CacheDBProvider/CacheDBProvider/deleteQuery
+     */
     async deleteQuery(collection, query) {
         await this.source.deleteQuery(collection, query);
         this.memory.getTable(collection).deleteQuery(query);

package/db/provider/ChangesDBProvider.d.ts

@@ -5,7 +5,13 @@ import type { Query } from "../../util/query.js";
 import type { Updates } from "../../util/update.js";
 import type { Collection } from "../collection/Collection.js";
 import { ThroughDBProvider } from "./ThroughDBProvider.js";
-/** A structured log entry for a database change. */
+/**
+ * Structured log entry recording a single database write performed through a `ChangesDBProvider`.
+ *
+ * - `action` is the kind of write; `collection` is the collection name; `id`, `query`, `data`, and `updates` carry whichever fields apply to that write.
+ *
+ * @see https://dhoulb.github.io/shelving/db/provider/ChangesDBProvider/DBChange
+ */
 export type DBChange<I extends Identifier> = {
     readonly action: "add" | "set" | "update" | "delete";
     readonly collection: string;
@@ -15,17 +21,92 @@ export type DBChange<I extends Identifier> = {
     readonly updates?: unknown;
 };
 /**
- * Database provider that keeps a log of any written changes to its `.changes` property.
- * - This is useful if you want to hook into a database to build out audit logging functionality.
+ * Database provider that records every write it performs to its `changes` log.
+ *
+ * - Wraps a `source` provider, delegates each write, then appends a `DBChange` entry describing what happened.
+ * - Useful for building audit logging, change feeds, or assertions in tests; reads are passed straight through and not logged.
+ *
+ * @example
+ *  const provider = new ChangesDBProvider(new MemoryDBProvider());
+ *  await provider.addItem(users, { name: "Dave" });
+ *  provider.changes; // [{ action: "add", collection: "users", id: 123, data: { name: "Dave" } }]
+ *
+ * @see https://dhoulb.github.io/shelving/db/provider/ChangesDBProvider/ChangesDBProvider
  */
 export declare class ChangesDBProvider<I extends Identifier, T extends Data> extends ThroughDBProvider<I, T> {
+    /**
+     * The log of writes performed through this provider, in the order they happened.
+     *
+     * @see https://dhoulb.github.io/shelving/db/provider/ChangesDBProvider/ChangesDBProvider/changes
+     */
     get changes(): ReadonlyArray<DBChange<I>>;
     readonly _changes: MutableArray<DBChange<I>>;
+    /**
+     * Add a new item, then log an `"add"` change.
+     *
+     * @param collection Collection to add the item to.
+     * @param data Data for the new item.
+     * @returns The generated identifier for the new item.
+     * @example await provider.addItem(users, { name: "Dave" }) // 123
+     * @see https://dhoulb.github.io/shelving/db/provider/ChangesDBProvider/ChangesDBProvider/addItem
+     */
     addItem<II extends I, TT extends T>(collection: Collection<string, II, TT>, data: TT): Promise<II>;
+    /**
+     * Set (insert or overwrite) an item by its id, then log a `"set"` change.
+     *
+     * @param collection Collection the item belongs to.
+     * @param id Identifier of the item to set.
+     * @param data Full data to store for the item.
+     * @example await provider.setItem(users, 123, { name: "Dave" });
+     * @see https://dhoulb.github.io/shelving/db/provider/ChangesDBProvider/ChangesDBProvider/setItem
+     */
     setItem<II extends I, TT extends T>(collection: Collection<string, II, TT>, id: II, data: TT): Promise<void>;
+    /**
+     * Apply partial updates to an item by its id, then log an `"update"` change.
+     *
+     * @param collection Collection the item belongs to.
+     * @param id Identifier of the item to update.
+     * @param updates Updates to apply to the item.
+     * @example await provider.updateItem(users, 123, { name: "Dave" });
+     * @see https://dhoulb.github.io/shelving/db/provider/ChangesDBProvider/ChangesDBProvider/updateItem
+     */
     updateItem<II extends I, TT extends T>(collection: Collection<string, II, TT>, id: II, updates: Updates<Item<II, TT>>): Promise<void>;
+    /**
+     * Delete an item by its id, then log a `"delete"` change.
+     *
+     * @param collection Collection the item belongs to.
+     * @param id Identifier of the item to delete.
+     * @example await provider.deleteItem(users, 123);
+     * @see https://dhoulb.github.io/shelving/db/provider/ChangesDBProvider/ChangesDBProvider/deleteItem
+     */
     deleteItem<II extends I, TT extends T>(collection: Collection<string, II, TT>, id: II): Promise<void>;
+    /**
+     * Set (overwrite) every item matching a query, then log a `"set"` change.
+     *
+     * @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://dhoulb.github.io/shelving/db/provider/ChangesDBProvider/ChangesDBProvider/setQuery
+     */
     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, then log an `"update"` change.
+     *
+     * @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://dhoulb.github.io/shelving/db/provider/ChangesDBProvider/ChangesDBProvider/updateQuery
+     */
     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, then log a `"delete"` change.
+     *
+     * @param collection Collection to delete from.
+     * @param query Query selecting the items to delete.
+     * @example await provider.deleteQuery(users, { active: false });
+     * @see https://dhoulb.github.io/shelving/db/provider/ChangesDBProvider/ChangesDBProvider/deleteQuery
+     */
     deleteQuery<II extends I, TT extends T>(collection: Collection<string, II, TT>, query: Query<Item<II, TT>>): Promise<void>;
 }

package/db/provider/ChangesDBProvider.js

@@ -1,38 +1,113 @@
 import { ThroughDBProvider } from "./ThroughDBProvider.js";
 /**
- * Database provider that keeps a log of any written changes to its `.changes` property.
- * - This is useful if you want to hook into a database to build out audit logging functionality.
+ * Database provider that records every write it performs to its `changes` log.
+ *
+ * - Wraps a `source` provider, delegates each write, then appends a `DBChange` entry describing what happened.
+ * - Useful for building audit logging, change feeds, or assertions in tests; reads are passed straight through and not logged.
+ *
+ * @example
+ *  const provider = new ChangesDBProvider(new MemoryDBProvider());
+ *  await provider.addItem(users, { name: "Dave" });
+ *  provider.changes; // [{ action: "add", collection: "users", id: 123, data: { name: "Dave" } }]
+ *
+ * @see https://dhoulb.github.io/shelving/db/provider/ChangesDBProvider/ChangesDBProvider
  */
 export class ChangesDBProvider extends ThroughDBProvider {
+    /**
+     * The log of writes performed through this provider, in the order they happened.
+     *
+     * @see https://dhoulb.github.io/shelving/db/provider/ChangesDBProvider/ChangesDBProvider/changes
+     */
     get changes() {
         return this._changes;
     }
     _changes = [];
+    /**
+     * Add a new item, then log an `"add"` change.
+     *
+     * @param collection Collection to add the item to.
+     * @param data Data for the new item.
+     * @returns The generated identifier for the new item.
+     * @example await provider.addItem(users, { name: "Dave" }) // 123
+     * @see https://dhoulb.github.io/shelving/db/provider/ChangesDBProvider/ChangesDBProvider/addItem
+     */
     async addItem(collection, data) {
         const id = await super.addItem(collection, data);
         this._changes.push({ action: "add", collection: collection.name, id, data });
         return id;
     }
+    /**
+     * Set (insert or overwrite) an item by its id, then log a `"set"` change.
+     *
+     * @param collection Collection the item belongs to.
+     * @param id Identifier of the item to set.
+     * @param data Full data to store for the item.
+     * @example await provider.setItem(users, 123, { name: "Dave" });
+     * @see https://dhoulb.github.io/shelving/db/provider/ChangesDBProvider/ChangesDBProvider/setItem
+     */
     async setItem(collection, id, data) {
         await super.setItem(collection, id, data);
         this._changes.push({ action: "set", collection: collection.name, id, data });
     }
+    /**
+     * Apply partial updates to an item by its id, then log an `"update"` change.
+     *
+     * @param collection Collection the item belongs to.
+     * @param id Identifier of the item to update.
+     * @param updates Updates to apply to the item.
+     * @example await provider.updateItem(users, 123, { name: "Dave" });
+     * @see https://dhoulb.github.io/shelving/db/provider/ChangesDBProvider/ChangesDBProvider/updateItem
+     */
     async updateItem(collection, id, updates) {
         await super.updateItem(collection, id, updates);
         this._changes.push({ action: "update", collection: collection.name, id, updates });
     }
+    /**
+     * Delete an item by its id, then log a `"delete"` change.
+     *
+     * @param collection Collection the item belongs to.
+     * @param id Identifier of the item to delete.
+     * @example await provider.deleteItem(users, 123);
+     * @see https://dhoulb.github.io/shelving/db/provider/ChangesDBProvider/ChangesDBProvider/deleteItem
+     */
     async deleteItem(collection, id) {
         await super.deleteItem(collection, id);
         this._changes.push({ action: "delete", collection: collection.name, id });
     }
+    /**
+     * Set (overwrite) every item matching a query, then log a `"set"` change.
+     *
+     * @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://dhoulb.github.io/shelving/db/provider/ChangesDBProvider/ChangesDBProvider/setQuery
+     */
     async setQuery(collection, query, data) {
         await super.setQuery(collection, query, data);
         this._changes.push({ action: "set", collection: collection.name, query, data });
     }
+    /**
+     * Apply partial updates to every item matching a query, then log an `"update"` change.
+     *
+     * @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://dhoulb.github.io/shelving/db/provider/ChangesDBProvider/ChangesDBProvider/updateQuery
+     */
     async updateQuery(collection, query, updates) {
         await super.updateQuery(collection, query, updates);
         this._changes.push({ action: "update", collection: collection.name, query, updates });
     }
+    /**
+     * Delete every item matching a query, then log a `"delete"` change.
+     *
+     * @param collection Collection to delete from.
+     * @param query Query selecting the items to delete.
+     * @example await provider.deleteQuery(users, { active: false });
+     * @see https://dhoulb.github.io/shelving/db/provider/ChangesDBProvider/ChangesDBProvider/deleteQuery
+     */
     async deleteQuery(collection, query) {
         await super.deleteQuery(collection, query);
         this._changes.push({ action: "delete", collection: collection.name, query });

package/db/provider/DBProvider.d.ts

@@ -3,22 +3,169 @@ import type { Identifier, Item, Items, ItemsSequence, OptionalItem, OptionalItem
 import type { Query } from "../../util/query.js";
 import type { Updates } from "../../util/update.js";
 import type { Collection } from "../collection/Collection.js";
-/** Provider with a fully asynchronous interface for database access. */
+/**
+ * Provider with a fully asynchronous interface for database access.
+ *
+ * - Abstract base for every database provider; subclasses implement the storage backend (memory, SQL, remote, etc.).
+ * - All operations are keyed by a `Collection`, which carries the name plus identifier and data schemas.
+ * - Layered behaviour (caching, validation, logging) is added by wrapping a provider in a `Through*Provider`.
+ *
+ * @example
+ *  const provider = new MemoryDBProvider();
+ *  const id = await provider.addItem(users, { name: "Dave" });
+ *
+ * @see https://dhoulb.github.io/shelving/db/provider/DBProvider/DBProvider
+ */
 export declare abstract class DBProvider<I extends Identifier = Identifier, T extends Data = Data> implements AsyncDisposable {
+    /**
+     * Get an item from a collection by its id, or `undefined` if it doesn't exist.
+     *
+     * @param collection Collection the item belongs to.
+     * @param id Identifier of the item to get.
+     * @returns The item, or `undefined` if no item exists with that id.
+     * @example await provider.getItem(users, 123) // Item or undefined.
+     * @see https://dhoulb.github.io/shelving/db/provider/DBProvider/DBProvider/getItem
+     */
     abstract getItem<II extends I, TT extends T>(collection: Collection<string, II, TT>, id: II): Promise<OptionalItem<II, TT>>;
+    /**
+     * Get an item from a collection by its id, or throw if it doesn't exist.
+     *
+     * @param collection Collection the item belongs to.
+     * @param id Identifier of the item to get.
+     * @returns The item.
+     * @throws `RequiredError` if no item exists with that id.
+     * @example await provider.requireItem(users, 123) // Item (or throws).
+     * @see https://dhoulb.github.io/shelving/db/provider/DBProvider/DBProvider/requireItem
+     */
     requireItem<II extends I, TT extends T>(collection: Collection<string, II, TT>, id: II): Promise<Item<II, TT>>;
+    /**
+     * Subscribe to live changes for a single item by its id.
+     *
+     * @param collection Collection the item belongs to.
+     * @param id Identifier of the item to subscribe to.
+     * @returns Async sequence yielding the item (or `undefined`) on every change.
+     * @example for await (const item of provider.getItemSequence(users, 123)) console.log(item);
+     * @see https://dhoulb.github.io/shelving/db/provider/DBProvider/DBProvider/getItemSequence
+     */
     abstract getItemSequence<II extends I, TT extends T>(collection: Collection<string, II, TT>, id: II): OptionalItemSequence<II, TT>;
+    /**
+     * Add a new item to a collection and return its generated id.
+     *
+     * @param collection Collection to add the item to.
+     * @param data Data for the new item.
+     * @returns The generated identifier for the new item.
+     * @example await provider.addItem(users, { name: "Dave" }) // 123
+     * @see https://dhoulb.github.io/shelving/db/provider/DBProvider/DBProvider/addItem
+     */
     abstract addItem<II extends I, TT extends T>(collection: Collection<string, II, TT>, data: TT): Promise<II>;
+    /**
+     * Set (insert or overwrite) the data for an item by its id.
+     *
+     * @param collection Collection the item belongs to.
+     * @param id Identifier of the item to set.
+     * @param data Full data to store for the item.
+     * @example await provider.setItem(users, 123, { name: "Dave" });
+     * @see https://dhoulb.github.io/shelving/db/provider/DBProvider/DBProvider/setItem
+     */
     abstract setItem<II extends I, TT extends T>(collection: Collection<string, II, TT>, id: II, data: TT): Promise<void>;
+    /**
+     * Apply partial updates to an existing item by its id.
+     *
+     * @param collection Collection the item belongs to.
+     * @param id Identifier of the item to update.
+     * @param updates Updates to apply to the item.
+     * @example await provider.updateItem(users, 123, { name: "Dave" });
+     * @see https://dhoulb.github.io/shelving/db/provider/DBProvider/DBProvider/updateItem
+     */
     abstract updateItem<II extends I, TT extends T>(collection: Collection<string, II, TT>, id: II, updates: Updates<Item<II, TT>>): Promise<void>;
+    /**
+     * Delete an item from a collection by its id.
+     *
+     * @param collection Collection the item belongs to.
+     * @param id Identifier of the item to delete.
+     * @example await provider.deleteItem(users, 123);
+     * @see https://dhoulb.github.io/shelving/db/provider/DBProvider/DBProvider/deleteItem
+     */
     abstract deleteItem<II extends I, TT extends T>(collection: Collection<string, II, TT>, id: II): Promise<void>;
+    /**
+     * Count the items in a collection matching an optional query.
+     *
+     * @param collection Collection to count items in.
+     * @param query Query to filter the counted items (counts all items when omitted).
+     * @returns The number of matching items.
+     * @example await provider.countQuery(users, { age: 40 }) // 7
+     * @see https://dhoulb.github.io/shelving/db/provider/DBProvider/DBProvider/countQuery
+     */
     countQuery<II extends I, TT extends T>(collection: Collection<string, II, TT>, query?: Query<Item<II, TT>>): Promise<number>;
+    /**
+     * Get the items in a collection matching an optional query.
+     *
+     * @param collection Collection to query.
+     * @param query Query to filter, sort, and limit the items (returns all items when omitted).
+     * @returns An array of matching items.
+     * @example await provider.getQuery(users, { age: 40, $order: "name" }) // Items.
+     * @see https://dhoulb.github.io/shelving/db/provider/DBProvider/DBProvider/getQuery
+     */
     abstract getQuery<II extends I, TT extends T>(collection: Collection<string, II, TT>, query?: Query<Item<II, TT>>): Promise<Items<II, TT>>;
+    /**
+     * Subscribe to live changes for the result of a query.
+     *
+     * @param collection Collection to query.
+     * @param query Query to filter, sort, and limit the items.
+     * @returns Async sequence yielding the matching items on every change.
+     * @example for await (const items of provider.getQuerySequence(users, { age: 40 })) console.log(items);
+     * @see https://dhoulb.github.io/shelving/db/provider/DBProvider/DBProvider/getQuerySequence
+     */
     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.
+     *
+     * @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://dhoulb.github.io/shelving/db/provider/DBProvider/DBProvider/setQuery
+     */
     abstract 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.
+     *
+     * @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://dhoulb.github.io/shelving/db/provider/DBProvider/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>;
+    /**
+     * Delete every item matching a query.
+     *
+     * @param collection Collection to delete from.
+     * @param query Query selecting the items to delete.
+     * @example await provider.deleteQuery(users, { active: false });
+     * @see https://dhoulb.github.io/shelving/db/provider/DBProvider/DBProvider/deleteQuery
+     */
     abstract 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.
+     *
+     * @param collection Collection to query.
+     * @param query Query to filter and sort the items.
+     * @returns The first matching item, or `undefined` if none match.
+     * @example await provider.getFirst(users, { $order: "name" }) // Item or undefined.
+     * @see https://dhoulb.github.io/shelving/db/provider/DBProvider/DBProvider/getFirst
+     */
     getFirst<II extends I, TT extends T>(collection: Collection<string, II, TT>, query: Query<Item<II, TT>>): Promise<OptionalItem<II, TT>>;
+    /**
+     * Get the first item matching a query, or throw if there are none.
+     *
+     * @param collection Collection to query.
+     * @param query Query to filter and sort the items.
+     * @returns The first matching item.
+     * @throws `RequiredError` if no item matches the query.
+     * @example await provider.requireFirst(users, { $order: "name" }) // Item (or throws).
+     * @see https://dhoulb.github.io/shelving/db/provider/DBProvider/DBProvider/requireFirst
+     */
     requireFirst<II extends I, TT extends T>(collection: Collection<string, II, TT>, query: Query<Item<II, TT>>): Promise<Item<II, TT>>;
     [Symbol.asyncDispose](): Promise<void>;
 }

package/db/provider/DBProvider.js

@@ -1,8 +1,30 @@
 import { RequiredError } from "../../error/RequiredError.js";
 import { countArray, getFirst } from "../../util/array.js";
 import { awaitDispose } from "../../util/dispose.js";
-/** Provider with a fully asynchronous interface for database access. */
+/**
+ * Provider with a fully asynchronous interface for database access.
+ *
+ * - Abstract base for every database provider; subclasses implement the storage backend (memory, SQL, remote, etc.).
+ * - All operations are keyed by a `Collection`, which carries the name plus identifier and data schemas.
+ * - Layered behaviour (caching, validation, logging) is added by wrapping a provider in a `Through*Provider`.
+ *
+ * @example
+ *  const provider = new MemoryDBProvider();
+ *  const id = await provider.addItem(users, { name: "Dave" });
+ *
+ * @see https://dhoulb.github.io/shelving/db/provider/DBProvider/DBProvider
+ */
 export class DBProvider {
+    /**
+     * Get an item from a collection by its id, or throw if it doesn't exist.
+     *
+     * @param collection Collection the item belongs to.
+     * @param id Identifier of the item to get.
+     * @returns The item.
+     * @throws `RequiredError` if no item exists with that id.
+     * @example await provider.requireItem(users, 123) // Item (or throws).
+     * @see https://dhoulb.github.io/shelving/db/provider/DBProvider/DBProvider/requireItem
+     */
     async requireItem(collection, id) {
         const item = await this.getItem(collection, id);
         if (!item)
@@ -14,12 +36,40 @@ export class DBProvider {
             });
         return item;
     }
+    /**
+     * Count the items in a collection matching an optional query.
+     *
+     * @param collection Collection to count items in.
+     * @param query Query to filter the counted items (counts all items when omitted).
+     * @returns The number of matching items.
+     * @example await provider.countQuery(users, { age: 40 }) // 7
+     * @see https://dhoulb.github.io/shelving/db/provider/DBProvider/DBProvider/countQuery
+     */
     async countQuery(collection, query) {
         return countArray(await this.getQuery(collection, query));
     }
+    /**
+     * Get the first item matching a query, or `undefined` if there are none.
+     *
+     * @param collection Collection to query.
+     * @param query Query to filter and sort the items.
+     * @returns The first matching item, or `undefined` if none match.
+     * @example await provider.getFirst(users, { $order: "name" }) // Item or undefined.
+     * @see https://dhoulb.github.io/shelving/db/provider/DBProvider/DBProvider/getFirst
+     */
     async getFirst(collection, query) {
         return getFirst(await this.getQuery(collection, { ...query, $limit: 1 }));
     }
+    /**
+     * Get the first item matching a query, or throw if there are none.
+     *
+     * @param collection Collection to query.
+     * @param query Query to filter and sort the items.
+     * @returns The first matching item.
+     * @throws `RequiredError` if no item matches the query.
+     * @example await provider.requireFirst(users, { $order: "name" }) // Item (or throws).
+     * @see https://dhoulb.github.io/shelving/db/provider/DBProvider/DBProvider/requireFirst
+     */
     async requireFirst(collection, query) {
         const first = await this.getFirst(collection, query);
         if (!first)