shelving 1.236.0 → 1.236.2

package/db/provider/ThroughDBProvider.d.ts

@@ -5,24 +5,179 @@ 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";
-/** A provider that passes through to an asynchronous source. */
+/**
+ * Database provider that passes every 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.
+ * - Exposes `source` and implements `Sourceable`, so wrapped providers can be discovered with `getSource()` / `requireSource()`.
+ *
+ * @example
+ *  const provider = new ValidationDBProvider(new MemoryDBProvider());
+ *
+ * @see https://dhoulb.github.io/shelving/db/provider/ThroughDBProvider/ThroughDBProvider
+ */
 export declare class ThroughDBProvider<I extends Identifier, T extends Data> implements DBProvider<I, T>, Sourceable<DBProvider<I, T>> {
+    /**
+     * The wrapped source provider that every operation is delegated to.
+     *
+     * @see https://dhoulb.github.io/shelving/db/provider/ThroughDBProvider/ThroughDBProvider/source
+     */
     readonly source: DBProvider<I, T>;
+    /**
+     * Create a new `ThroughDBProvider` wrapping a source provider.
+     *
+     * @param source The provider to delegate all operations to.
+     */
     constructor(source: DBProvider<I, T>);
+    /**
+     * 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/ThroughDBProvider/ThroughDBProvider/getItem
+     */
     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/ThroughDBProvider/ThroughDBProvider/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/ThroughDBProvider/ThroughDBProvider/getItemSequence
+     */
     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/ThroughDBProvider/ThroughDBProvider/addItem
+     */
     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/ThroughDBProvider/ThroughDBProvider/setItem
+     */
     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/ThroughDBProvider/ThroughDBProvider/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 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/ThroughDBProvider/ThroughDBProvider/deleteItem
+     */
     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/ThroughDBProvider/ThroughDBProvider/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/ThroughDBProvider/ThroughDBProvider/getQuery
+     */
     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/ThroughDBProvider/ThroughDBProvider/getQuerySequence
+     */
     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/ThroughDBProvider/ThroughDBProvider/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.
+     *
+     * @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/ThroughDBProvider/ThroughDBProvider/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.
+     *
+     * @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/ThroughDBProvider/ThroughDBProvider/deleteQuery
+     */
     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/ThroughDBProvider/ThroughDBProvider/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/ThroughDBProvider/ThroughDBProvider/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/ThroughDBProvider.js

@@ -1,52 +1,207 @@
 import { awaitDispose } from "../../util/dispose.js";
-/** A provider that passes through to an asynchronous source. */
+/**
+ * Database provider that passes every 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.
+ * - Exposes `source` and implements `Sourceable`, so wrapped providers can be discovered with `getSource()` / `requireSource()`.
+ *
+ * @example
+ *  const provider = new ValidationDBProvider(new MemoryDBProvider());
+ *
+ * @see https://dhoulb.github.io/shelving/db/provider/ThroughDBProvider/ThroughDBProvider
+ */
 export class ThroughDBProvider {
+    /**
+     * The wrapped source provider that every operation is delegated to.
+     *
+     * @see https://dhoulb.github.io/shelving/db/provider/ThroughDBProvider/ThroughDBProvider/source
+     */
     source;
+    /**
+     * Create a new `ThroughDBProvider` wrapping a source provider.
+     *
+     * @param source The provider to delegate all operations to.
+     */
     constructor(source) {
         this.source = source;
     }
+    /**
+     * 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/ThroughDBProvider/ThroughDBProvider/getItem
+     */
     getItem(collection, id) {
         return this.source.getItem(collection, id);
     }
+    /**
+     * 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/ThroughDBProvider/ThroughDBProvider/requireItem
+     */
     requireItem(collection, id) {
         return this.source.requireItem(collection, id);
     }
+    /**
+     * 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/ThroughDBProvider/ThroughDBProvider/getItemSequence
+     */
     getItemSequence(collection, id) {
         return this.source.getItemSequence(collection, id);
     }
+    /**
+     * 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/ThroughDBProvider/ThroughDBProvider/addItem
+     */
     addItem(collection, data) {
         return this.source.addItem(collection, data);
     }
+    /**
+     * 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/ThroughDBProvider/ThroughDBProvider/setItem
+     */
     setItem(collection, id, data) {
         return this.source.setItem(collection, id, data);
     }
+    /**
+     * 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/ThroughDBProvider/ThroughDBProvider/updateItem
+     */
     updateItem(collection, id, updates) {
         return this.source.updateItem(collection, id, updates);
     }
+    /**
+     * 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/ThroughDBProvider/ThroughDBProvider/deleteItem
+     */
     deleteItem(collection, id) {
         return this.source.deleteItem(collection, id);
     }
+    /**
+     * 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/ThroughDBProvider/ThroughDBProvider/countQuery
+     */
     countQuery(collection, query) {
         return this.source.countQuery(collection, query);
     }
+    /**
+     * 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/ThroughDBProvider/ThroughDBProvider/getQuery
+     */
     getQuery(collection, query) {
         return this.source.getQuery(collection, query);
     }
+    /**
+     * 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/ThroughDBProvider/ThroughDBProvider/getQuerySequence
+     */
     getQuerySequence(collection, query) {
         return this.source.getQuerySequence(collection, query);
     }
+    /**
+     * 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/ThroughDBProvider/ThroughDBProvider/setQuery
+     */
     setQuery(collection, query, data) {
         return this.source.setQuery(collection, query, data);
     }
+    /**
+     * 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/ThroughDBProvider/ThroughDBProvider/updateQuery
+     */
     updateQuery(collection, query, updates) {
         return this.source.updateQuery(collection, query, updates);
     }
+    /**
+     * 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/ThroughDBProvider/ThroughDBProvider/deleteQuery
+     */
     deleteQuery(collection, query) {
         return this.source.deleteQuery(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/ThroughDBProvider/ThroughDBProvider/getFirst
+     */
     getFirst(collection, query) {
         return this.source.getFirst(collection, query);
     }
+    /**
+     * 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/ThroughDBProvider/ThroughDBProvider/requireFirst
+     */
     requireFirst(collection, query) {
         return this.source.requireFirst(collection, query);
     }

package/db/provider/ValidationDBProvider.d.ts

@@ -4,17 +4,136 @@ 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";
-/** Validate an asynchronous source provider (source can have any type because validation guarantees the type). */
+/**
+ * Database provider that validates data flowing to and from an asynchronous source provider.
+ *
+ * - Wraps a `source` provider (which may have any type, because validation guarantees the type) and runs every value through the relevant `Collection` schema before writing and after reading.
+ * - Written data is validated against the collection's data schema; read data is validated against the item schema, so trusted, correctly-typed values reach the rest of the app.
+ * - Validation failures here are program-state errors, so they throw a typed `ValueError` rather than a raw validation `string`.
+ *
+ * @example
+ *  const provider = new ValidationDBProvider(new FirestoreProvider());
+ *  await provider.setItem(users, 123, { name: "Dave", age: 40 }); // Validates before writing.
+ *
+ * @see https://dhoulb.github.io/shelving/db/provider/ValidationDBProvider/ValidationDBProvider
+ */
 export declare class ValidationDBProvider<I extends Identifier, T extends Data> extends ThroughDBProvider<I, T> {
+    /**
+     * Get an item by its id and validate it, or `undefined` if it doesn't exist.
+     *
+     * @param collection Collection the item belongs to.
+     * @param id Identifier of the item to get.
+     * @returns The validated item, or `undefined` if no item exists with that id.
+     * @throws `ValueError` if the stored item does not validate against the collection schema.
+     * @example await provider.getItem(users, 123) // Validated item or undefined.
+     * @see https://dhoulb.github.io/shelving/db/provider/ValidationDBProvider/ValidationDBProvider/getItem
+     */
     getItem<II extends I, TT extends T>(collection: Collection<string, II, TT>, id: II): Promise<OptionalItem<II, TT>>;
+    /**
+     * Subscribe to live changes for a single item, validating each emission.
+     *
+     * @param collection Collection the item belongs to.
+     * @param id Identifier of the item to subscribe to.
+     * @returns Async sequence yielding the validated item (or `undefined`) on every change.
+     * @throws `ValueError` if an emitted item does not validate against the collection schema.
+     * @example for await (const item of provider.getItemSequence(users, 123)) console.log(item);
+     * @see https://dhoulb.github.io/shelving/db/provider/ValidationDBProvider/ValidationDBProvider/getItemSequence
+     */
     getItemSequence<II extends I, TT extends T>(collection: Collection<string, II, TT>, id: II): OptionalItemSequence<II, TT>;
+    /**
+     * Validate and add a new item, returning its validated generated id.
+     *
+     * @param collection Collection to add the item to.
+     * @param data Data for the new item (validated before writing).
+     * @returns The validated generated identifier for the new item.
+     * @throws `ValueError` if the data or returned id does not validate against the collection schema.
+     * @example await provider.addItem(users, { name: "Dave", age: 40 }) // 123
+     * @see https://dhoulb.github.io/shelving/db/provider/ValidationDBProvider/ValidationDBProvider/addItem
+     */
     addItem<II extends I, TT extends T>(collection: Collection<string, II, TT>, data: TT): Promise<II>;
+    /**
+     * Validate and 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 (validated before writing).
+     * @throws `ValueError` if the data does not validate against the collection schema.
+     * @example await provider.setItem(users, 123, { name: "Dave", age: 40 });
+     * @see https://dhoulb.github.io/shelving/db/provider/ValidationDBProvider/ValidationDBProvider/setItem
+     */
     setItem<II extends I, TT extends T>(collection: Collection<string, II, TT>, id: II, data: TT): Promise<void>;
+    /**
+     * Validate and 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 (validated before writing).
+     * @throws `ValueError` if the updates do not validate against the collection schema.
+     * @example await provider.updateItem(users, 123, { age: 41 });
+     * @see https://dhoulb.github.io/shelving/db/provider/ValidationDBProvider/ValidationDBProvider/updateItem
+     */
     updateItem<II extends I, TT extends T>(collection: Collection<string, II, TT>, id: II, updates: Updates<Item<II, TT>>): Promise<void>;
+    /**
+     * Count the items in a collection matching an optional query (passed straight through).
+     *
+     * @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/ValidationDBProvider/ValidationDBProvider/countQuery
+     */
     countQuery<II extends I, TT extends T>(collection: Collection<string, II, TT>, query?: Query<Item<II, TT>>): Promise<number>;
+    /**
+     * Get the items matching an optional query and validate them.
+     *
+     * @param collection Collection to query.
+     * @param query Query to filter, sort, and limit the items (returns all items when omitted).
+     * @returns An array of validated matching items.
+     * @throws `ValueError` if one or more stored items do not validate against the collection schema.
+     * @example await provider.getQuery(users, { age: 40, $order: "name" }) // Validated items.
+     * @see https://dhoulb.github.io/shelving/db/provider/ValidationDBProvider/ValidationDBProvider/getQuery
+     */
     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 a query, validating each emitted result.
+     *
+     * @param collection Collection to query.
+     * @param query Query to filter, sort, and limit the items.
+     * @returns Async sequence yielding the validated matching items on every change.
+     * @throws `ValueError` if one or more emitted items do not validate against the collection schema.
+     * @example for await (const items of provider.getQuerySequence(users, { age: 40 })) console.log(items);
+     * @see https://dhoulb.github.io/shelving/db/provider/ValidationDBProvider/ValidationDBProvider/getQuerySequence
+     */
     getQuerySequence<II extends I, TT extends T>(collection: Collection<string, II, TT>, query?: Query<Item<II, TT>>): ItemsSequence<II, TT>;
+    /**
+     * Validate and 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 (validated before writing).
+     * @throws `ValueError` if the data does not validate against the collection schema.
+     * @example await provider.setQuery(users, { age: 40 }, { name: "Dave", age: 41 });
+     * @see https://dhoulb.github.io/shelving/db/provider/ValidationDBProvider/ValidationDBProvider/setQuery
+     */
     setQuery<II extends I, TT extends T>(collection: Collection<string, II, TT>, query: Query<Item<II, TT>>, data: TT): Promise<void>;
+    /**
+     * Validate and 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 (validated before writing).
+     * @throws `ValueError` if the updates do not validate against the collection schema.
+     * @example await provider.updateQuery(users, { age: 40 }, { active: true });
+     * @see https://dhoulb.github.io/shelving/db/provider/ValidationDBProvider/ValidationDBProvider/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 (passed straight through).
+     *
+     * @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/ValidationDBProvider/ValidationDBProvider/deleteQuery
+     */
     deleteQuery<II extends I, TT extends T>(collection: Collection<string, II, TT>, query: Query<Item<II, TT>>): Promise<void>;
 }