shelving 1.236.0 → 1.236.2

package/db/collection/Collection.js

@@ -1,6 +1,10 @@
 import { DataSchema, ITEM } from "../../schema/DataSchema.js";
 import { NumberSchema } from "../../schema/NumberSchema.js";
-/** Default identifier schema (integer). */
+/**
+ * Default identifier schema (integer) used when a collection doesn't supply its own.
+ *
+ * @see https://dhoulb.github.io/shelving/db/collection/Collection/ID
+ */
 export const ID = new NumberSchema({
     step: 1,
     min: Number.MIN_SAFE_INTEGER,
@@ -9,14 +13,44 @@ export const ID = new NumberSchema({
     one: "ID",
     title: "ID",
 });
-/** Declarative definition of a database collection/table. */
+/**
+ * Declarative definition of a database collection/table.
+ *
+ * - Pairs a collection name with an identifier schema and a data schema, so providers can validate and address items.
+ * - Extends `DataSchema<T>`, so the collection itself validates an item's data, while `.item` validates the complete `id + data` item.
+ *
+ * @example
+ *  const users = new Collection("users", ID, { name: STRING, age: NUMBER });
+ *  users.validate({ name: "Dave", age: 40 }); // Validates item data.
+ *
+ * @see https://dhoulb.github.io/shelving/db/collection/Collection/Collection
+ */
 export class Collection extends DataSchema {
-    /** Collection name (used as the table/collection key). */
+    /**
+     * Collection name (used as the table/collection key).
+     *
+     * @see https://dhoulb.github.io/shelving/db/collection/Collection/Collection/name
+     */
     name;
-    /** Schema for the identifier type. */
+    /**
+     * Schema for the identifier type.
+     *
+     * @see https://dhoulb.github.io/shelving/db/collection/Collection/Collection/id
+     */
     id;
-    /** Schema for a complete item (id + data). */
+    /**
+     * Schema for a complete item (id + data).
+     *
+     * @see https://dhoulb.github.io/shelving/db/collection/Collection/Collection/item
+     */
     item;
+    /**
+     * Create a new `Collection`.
+     *
+     * @param name Collection name used as the table/collection key.
+     * @param id Schema for the identifier type.
+     * @param data Data schema, or the `Schemas` props used to construct one.
+     */
     constructor(name, id, data) {
         const dataSchema = data instanceof DataSchema ? data : new DataSchema({ props: data });
         super({ ...dataSchema, props: dataSchema.props });
@@ -24,11 +58,29 @@ export class Collection extends DataSchema {
         this.id = id;
         this.item = ITEM(id, dataSchema);
     }
+    /**
+     * Convert this collection to its string name.
+     *
+     * @returns The collection name.
+     * @example `${users}` // "users"
+     * @see https://dhoulb.github.io/shelving/db/collection/Collection/Collection/toString
+     */
     toString() {
         return this.name;
     }
 }
-/** Shortcut factory for creating a Collection. */
+/**
+ * Create a `Collection` from a name, an identifier schema, and a data schema.
+ *
+ * *Factory for `Collection`.*
+ *
+ * @param name Collection name used as the table/collection key.
+ * @param id Schema for the identifier type.
+ * @param data Data schema, or the `Schemas` props used to construct one.
+ * @returns A new `Collection` instance.
+ * @example COLLECTION("users", ID, { name: STRING, age: NUMBER }) // Collection<"users", number, { name: string; age: number }>
+ * @see https://dhoulb.github.io/shelving/db/collection/Collection/COLLECTION
+ */
 export function COLLECTION(name, id, data) {
     return new Collection(name, id, data);
 }

package/db/migrate/DBMigrator.d.ts

@@ -1,8 +1,36 @@
 import type { Collections } from "../collection/Collection.js";
 import type { DBProvider } from "../provider/DBProvider.js";
-/** Base class for database schema migrators. */
+/**
+ * Base class for database schema migrators that bring a provider's storage into line with a set of collection schemas.
+ *
+ * - Subclasses implement `migrate()` for a specific backend (e.g. SQL via `SQLMigrator`).
+ *
+ * @example
+ *  class MyMigrator extends DBMigrator { async migrate(...collections) { ... } }
+ *  await new MyMigrator(provider).migrate(users, posts);
+ * @see https://dhoulb.github.io/shelving/db/migrate/DBMigrator/DBMigrator
+ */
 export declare abstract class DBMigrator<T extends DBProvider = DBProvider> {
+    /**
+     * The database provider whose storage this migrator updates.
+     * @see https://dhoulb.github.io/shelving/db/migrate/DBMigrator/DBMigrator/provider
+     */
     readonly provider: T;
+    /**
+     * Create a migrator bound to a database provider.
+     *
+     * @param provider The database provider whose storage this migrator updates.
+     * @example new DBMigrator(provider)
+     */
     constructor(provider: T);
+    /**
+     * Bring the provider's storage into line with the given collection schemas.
+     *
+     * @param collections The collections whose schemas the storage should match.
+     * @returns Promise that resolves once migration has completed.
+     * @throws {UnimplementedError} If a schema feature can't be represented by the backend.
+     * @example await migrator.migrate(users, posts)
+     * @see https://dhoulb.github.io/shelving/db/migrate/DBMigrator/DBMigrator/migrate
+     */
     abstract migrate(...collections: Collections): Promise<void>;
 }

package/db/migrate/DBMigrator.js

@@ -1,6 +1,25 @@
-/** Base class for database schema migrators. */
+/**
+ * Base class for database schema migrators that bring a provider's storage into line with a set of collection schemas.
+ *
+ * - Subclasses implement `migrate()` for a specific backend (e.g. SQL via `SQLMigrator`).
+ *
+ * @example
+ *  class MyMigrator extends DBMigrator { async migrate(...collections) { ... } }
+ *  await new MyMigrator(provider).migrate(users, posts);
+ * @see https://dhoulb.github.io/shelving/db/migrate/DBMigrator/DBMigrator
+ */
 export class DBMigrator {
+    /**
+     * The database provider whose storage this migrator updates.
+     * @see https://dhoulb.github.io/shelving/db/migrate/DBMigrator/DBMigrator/provider
+     */
     provider;
+    /**
+     * Create a migrator bound to a database provider.
+     *
+     * @param provider The database provider whose storage this migrator updates.
+     * @example new DBMigrator(provider)
+     */
     constructor(provider) {
         this.provider = provider;
     }

package/db/migrate/PostgreSQLMigrator.d.ts

@@ -13,7 +13,14 @@ type PostgreSQLColumnRow = {
     readonly type: string;
     readonly value: string | null;
 };
-/** PostgreSQL migrator using pg_catalog-style schema inspection. */
+/**
+ * PostgreSQL migrator that inspects the live schema via `pg_catalog` tables to diff and migrate columns.
+ *
+ * @example
+ *  const migrator = new PostgreSQLMigrator(provider);
+ *  await migrator.migrate(users, posts);
+ * @see https://dhoulb.github.io/shelving/db/migrate/PostgreSQLMigrator/PostgreSQLMigrator
+ */
 export declare class PostgreSQLMigrator<T extends SQLProvider = SQLProvider> extends SQLMigrator<T> {
     protected getTables(): Promise<readonly string[]>;
     protected getTable(name: string): Promise<SQLTable | undefined>;

package/db/migrate/PostgreSQLMigrator.js

@@ -15,7 +15,14 @@ const INT4_MAX = 2147483647;
 const INT4_MIN = -2147483648;
 const COMPATIBLE_NUMBER_TYPES = ["integer", "bigint", "numeric", "int", "int4", "int8"];
 const COMPATIBLE_STRING_TYPES = ["character varying", "varchar", "text", "char", "character"];
-/** PostgreSQL migrator using pg_catalog-style schema inspection. */
+/**
+ * PostgreSQL migrator that inspects the live schema via `pg_catalog` tables to diff and migrate columns.
+ *
+ * @example
+ *  const migrator = new PostgreSQLMigrator(provider);
+ *  await migrator.migrate(users, posts);
+ * @see https://dhoulb.github.io/shelving/db/migrate/PostgreSQLMigrator/PostgreSQLMigrator
+ */
 export class PostgreSQLMigrator extends SQLMigrator {
     async getTables() {
         const rows = await this.provider.exec `

package/db/migrate/SQLMigrator.d.ts

@@ -3,29 +3,88 @@ import type { Data } from "../../util/data.js";
 import type { Collection, Collections } from "../collection/Collection.js";
 import type { SQLProvider } from "../provider/SQLProvider.js";
 import { DBMigrator } from "./DBMigrator.js";
-/** Column definition in a live SQL table. */
+/**
+ * Column definition in a live SQL table, pairing a column name with its raw definition statement.
+ * @see https://dhoulb.github.io/shelving/db/migrate/SQLMigrator/SQLTableColumn
+ */
 export type SQLTableColumn = {
     readonly name: string;
     readonly statement: string;
 };
-/** Existing SQL table schema keyed by column name. */
+/**
+ * Existing SQL table schema keyed by column name, as read back from the database.
+ * @see https://dhoulb.github.io/shelving/db/migrate/SQLMigrator/SQLTable
+ */
 export type SQLTable = {
     readonly columns: Readonly<Record<string, SQLTableColumn>>;
     readonly name: string;
     readonly sql?: string | undefined;
 };
-/** Generated SQL column mapped from a collection path. */
+/**
+ * Generated SQL column mapped from a collection schema path, holding its column name, key, and JSON path.
+ * @see https://dhoulb.github.io/shelving/db/migrate/SQLMigrator/SQLColumn
+ */
 export type SQLColumn = {
     readonly column: string;
     readonly key: string;
     readonly path: string;
 };
-/** Shared SQL migration logic based on schema diffing. */
+/**
+ * Shared SQL migration logic that diffs collection schemas against live tables to produce migration statements.
+ *
+ * - Subclasses implement backend-specific schema inspection and column definitions (e.g. SQLite, PostgreSQL).
+ *
+ * @example
+ *  const migrator = new SQLiteMigrator(provider);
+ *  await migrator.migrate(users, posts);
+ * @see https://dhoulb.github.io/shelving/db/migrate/SQLMigrator/SQLMigrator
+ */
 export declare abstract class SQLMigrator<T extends SQLProvider = SQLProvider> extends DBMigrator<T> {
+    /**
+     * Bring the provider's tables into line with the given collection schemas by running the generated migrations.
+     *
+     * @param collections The collections whose schemas the tables should match.
+     * @returns Promise that resolves once every migration has been executed.
+     * @throws {UnimplementedError} If a schema feature can't be represented as a SQL column.
+     * @example await migrator.migrate(users, posts)
+     * @see https://dhoulb.github.io/shelving/db/migrate/SQLMigrator/SQLMigrator/migrate
+     */
     migrate(...collections: Collections<number>): Promise<void>;
+    /**
+     * Compute the SQL statements needed to bring the tables into line with the given collection schemas, without executing them.
+     *
+     * @param collections The collections whose schemas the tables should match.
+     * @returns Promise resolving to the ordered list of SQL migration statements.
+     * @example const sql = await migrator.getMigrations(users)
+     * @see https://dhoulb.github.io/shelving/db/migrate/SQLMigrator/SQLMigrator/getMigrations
+     */
     getMigrations(...collections: Collections<number>): Promise<readonly string[]>;
+    /**
+     * Build the `CREATE TABLE` statement for a collection, including its ID, data, and generated columns.
+     *
+     * @param collection The collection to create a table for.
+     * @returns The `CREATE TABLE` SQL statement.
+     * @example migrator.getCreateTableQuery(users) // CREATE TABLE "users" (...)
+     * @see https://dhoulb.github.io/shelving/db/migrate/SQLMigrator/SQLMigrator/getCreateTableQuery
+     */
     getCreateTableQuery<T extends Data>(collection: Collection<string, number, T>): string;
+    /**
+     * Get the full set of columns for a collection's table: the ID column, data column, and generated columns.
+     *
+     * @param collection The collection to get columns for.
+     * @returns The ordered list of table columns.
+     * @example migrator.getCreateTableColumns(users)
+     * @see https://dhoulb.github.io/shelving/db/migrate/SQLMigrator/SQLMigrator/getCreateTableColumns
+     */
     getCreateTableColumns<T extends Data>(collection: Collection<string, number, T>): readonly SQLTableColumn[];
+    /**
+     * Get the generated (computed) columns for a collection's table, derived from its schema's scalar properties.
+     *
+     * @param collection The collection to get generated columns for.
+     * @returns The list of generated table columns.
+     * @example migrator.getGeneratedTableColumns(users)
+     * @see https://dhoulb.github.io/shelving/db/migrate/SQLMigrator/SQLMigrator/getGeneratedTableColumns
+     */
     getGeneratedTableColumns<T extends Data>(collection: Collection<string, number, T>): readonly SQLTableColumn[];
     protected getColumnMigrations(tableName: string, from: SQLTableColumn | undefined, to: SQLTableColumn | undefined): readonly string[];
     protected getAlterColumnQueries(tableName: string, from: SQLTableColumn, to: SQLTableColumn): readonly string[];

package/db/migrate/SQLMigrator.js

@@ -9,12 +9,38 @@ import { NumberSchema } from "../../schema/NumberSchema.js";
 import { StringSchema } from "../../schema/StringSchema.js";
 import { ThroughSchema } from "../../schema/ThroughSchema.js";
 import { DBMigrator } from "./DBMigrator.js";
-/** Shared SQL migration logic based on schema diffing. */
+/**
+ * Shared SQL migration logic that diffs collection schemas against live tables to produce migration statements.
+ *
+ * - Subclasses implement backend-specific schema inspection and column definitions (e.g. SQLite, PostgreSQL).
+ *
+ * @example
+ *  const migrator = new SQLiteMigrator(provider);
+ *  await migrator.migrate(users, posts);
+ * @see https://dhoulb.github.io/shelving/db/migrate/SQLMigrator/SQLMigrator
+ */
 export class SQLMigrator extends DBMigrator {
+    /**
+     * Bring the provider's tables into line with the given collection schemas by running the generated migrations.
+     *
+     * @param collections The collections whose schemas the tables should match.
+     * @returns Promise that resolves once every migration has been executed.
+     * @throws {UnimplementedError} If a schema feature can't be represented as a SQL column.
+     * @example await migrator.migrate(users, posts)
+     * @see https://dhoulb.github.io/shelving/db/migrate/SQLMigrator/SQLMigrator/migrate
+     */
     async migrate(...collections) {
         for (const migration of await this.getMigrations(...collections))
             await this.provider.exec(_getTemplateStrings(migration));
     }
+    /**
+     * Compute the SQL statements needed to bring the tables into line with the given collection schemas, without executing them.
+     *
+     * @param collections The collections whose schemas the tables should match.
+     * @returns Promise resolving to the ordered list of SQL migration statements.
+     * @example const sql = await migrator.getMigrations(users)
+     * @see https://dhoulb.github.io/shelving/db/migrate/SQLMigrator/SQLMigrator/getMigrations
+     */
     async getMigrations(...collections) {
         const tables = await this.getTables();
         const existing = new Set(tables);
@@ -26,15 +52,39 @@ export class SQLMigrator extends DBMigrator {
         }
         return migrations;
     }
+    /**
+     * Build the `CREATE TABLE` statement for a collection, including its ID, data, and generated columns.
+     *
+     * @param collection The collection to create a table for.
+     * @returns The `CREATE TABLE` SQL statement.
+     * @example migrator.getCreateTableQuery(users) // CREATE TABLE "users" (...)
+     * @see https://dhoulb.github.io/shelving/db/migrate/SQLMigrator/SQLMigrator/getCreateTableQuery
+     */
     getCreateTableQuery(collection) {
         const suffix = this.getCreateTableSuffix(collection);
         return `CREATE TABLE ${this.quoteIdentifier(collection.name)} (\n${this.getCreateTableColumns(collection)
             .map(column => `  ${this.getTableColumnDefinition(column)}`)
             .join(",\n")}\n)${suffix};`;
     }
+    /**
+     * Get the full set of columns for a collection's table: the ID column, data column, and generated columns.
+     *
+     * @param collection The collection to get columns for.
+     * @returns The ordered list of table columns.
+     * @example migrator.getCreateTableColumns(users)
+     * @see https://dhoulb.github.io/shelving/db/migrate/SQLMigrator/SQLMigrator/getCreateTableColumns
+     */
     getCreateTableColumns(collection) {
         return [this.getIDColumn(collection), this.getDataColumn(), ...this.getGeneratedTableColumns(collection)];
     }
+    /**
+     * Get the generated (computed) columns for a collection's table, derived from its schema's scalar properties.
+     *
+     * @param collection The collection to get generated columns for.
+     * @returns The list of generated table columns.
+     * @example migrator.getGeneratedTableColumns(users)
+     * @see https://dhoulb.github.io/shelving/db/migrate/SQLMigrator/SQLMigrator/getGeneratedTableColumns
+     */
     getGeneratedTableColumns(collection) {
         return this.getGeneratedColumns(collection).map(column => this.getGeneratedColumn(column, collection));
     }

package/db/migrate/SQLiteMigrator.d.ts

@@ -3,7 +3,14 @@ import type { Identifier } from "../../util/item.js";
 import type { Collection } from "../collection/Collection.js";
 import type { SQLProvider } from "../provider/SQLProvider.js";
 import { SQLMigrator, type SQLTable, type SQLTableColumn } from "./SQLMigrator.js";
-/** SQLite and D1 migrator using sqlite_master as the schema source of truth. */
+/**
+ * SQLite (and Cloudflare D1) migrator that uses `sqlite_master` as the schema source of truth.
+ *
+ * @example
+ *  const migrator = new SQLiteMigrator(provider);
+ *  await migrator.migrate(users, posts);
+ * @see https://dhoulb.github.io/shelving/db/migrate/SQLiteMigrator/SQLiteMigrator
+ */
 export declare class SQLiteMigrator<T extends SQLProvider = SQLProvider> extends SQLMigrator<T> {
     protected getTables(): Promise<readonly string[]>;
     protected getTable(name: string): Promise<SQLTable | undefined>;

package/db/migrate/SQLiteMigrator.js

@@ -3,7 +3,14 @@ import { ChoiceSchema } from "../../schema/ChoiceSchema.js";
 import { DateSchema } from "../../schema/DateSchema.js";
 import { NumberSchema } from "../../schema/NumberSchema.js";
 import { SQLMigrator } from "./SQLMigrator.js";
-/** SQLite and D1 migrator using sqlite_master as the schema source of truth. */
+/**
+ * SQLite (and Cloudflare D1) migrator that uses `sqlite_master` as the schema source of truth.
+ *
+ * @example
+ *  const migrator = new SQLiteMigrator(provider);
+ *  await migrator.migrate(users, posts);
+ * @see https://dhoulb.github.io/shelving/db/migrate/SQLiteMigrator/SQLiteMigrator
+ */
 export class SQLiteMigrator extends SQLMigrator {
     async getTables() {
         const rows = await this.provider.exec `

package/db/provider/CacheDBProvider.d.ts

@@ -6,22 +6,156 @@ import type { Updates } from "../../util/update.js";
 import type { Collection } from "../collection/Collection.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 declare class CacheDBProvider<I extends Identifier, T extends Data> extends DBProvider<I, T> implements Sourceable<DBProvider<I, T>> {
+    /**
+     * The wrapped source provider that data is fetched from and written to.
+     *
+     * @see https://dhoulb.github.io/shelving/db/provider/CacheDBProvider/CacheDBProvider/source
+     */
     readonly source: DBProvider<I, T>;
+    /**
+     * The in-memory provider holding the local synchronous cache of `source` data.
+     *
+     * @see https://dhoulb.github.io/shelving/db/provider/CacheDBProvider/CacheDBProvider/memory
+     */
     readonly memory: MemoryDBProvider<I, T>;
+    /**
+     * 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: DBProvider<I, T>, cache?: MemoryDBProvider<I, T>);
+    /**
+     * 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
+     */
     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, 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<II extends I, TT extends T>(collection: Collection<string, II, TT>, id: II): OptionalItemSequence<II, TT>;
+    /**
+     * 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
+     */
     addItem<II extends I, TT extends T>(collection: Collection<string, II, TT>, data: TT): Promise<II>;
+    /**
+     * 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
+     */
     setItem<II extends I, TT extends T>(collection: Collection<string, II, TT>, id: II, data: TT): Promise<void>;
+    /**
+     * 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
+     */
     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 `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
+     */
     deleteItem<II extends I, TT extends T>(collection: Collection<string, II, TT>, id: II): Promise<void>;
+    /**
+     * 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<II extends I, TT extends T>(collection: Collection<string, II, TT>, query?: Query<Item<II, TT>>): Promise<number>;
+    /**
+     * 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
+     */
     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, 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<II extends I, TT extends T>(collection: Collection<string, II, TT>, query?: Query<Item<II, TT>>): ItemsSequence<II, TT>;
+    /**
+     * 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
+     */
     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 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
+     */
     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 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
+     */
     deleteQuery<II extends I, TT extends T>(collection: Collection<string, II, TT>, query: Query<Item<II, TT>>): Promise<void>;
     [Symbol.asyncDispose](): Promise<void>;
 }