shelving 1.236.0 → 1.236.2

package/extract/TypescriptExtractor.js

@@ -14,8 +14,29 @@ import { extractMarkdownProps } from "./MarkupExtractor.js";
  * - Members declared with the `override` or `declare` modifier are skipped — the base class already documents overrides, and `declare` members are ambient type-only re-declarations rather than new API.
  * - Keys are the raw declared `name` (case-preserving) so case-distinct exports like `Collection` and `COLLECTION` stay separate.
  * - The file element itself has no `title` — a TS source file has no confident title source; renderers fall back to `name`.
+ *
+ * @example
+ * ```ts
+ * const element = new TypescriptExtractor().extractProps("string.ts", sourceText);
+ * ```
+ *
+ * @see https://dhoulb.github.io/shelving/extract/TypescriptExtractor
  */
 export class TypescriptExtractor extends FileExtractor {
+    /**
+     * Parse a TypeScript source file into the props of a `tree-element`.
+     *
+     * @param name Filename of the source (used as the source file name and the element `name`).
+     * @param text Full TypeScript source text to parse.
+     * @returns Partial `tree-element` props with `name`, `description`, `content`, and `children`.
+     *
+     * @example
+     * ```ts
+     * const props = new TypescriptExtractor().extractProps("string.ts", sourceText);
+     * ```
+     *
+     * @see https://dhoulb.github.io/shelving/extract/TypescriptExtractor/extractProps
+     */
     extractProps(name, text) {
         const source = ts.createSourceFile(name, text, ts.ScriptTarget.Latest, true);
         const content = _getFileDocComment(source);
@@ -158,7 +179,7 @@ function _getHeritage(statement, source) {
 }
 /**
  * Combine the JSDoc leading-description text and any unhandled `@rule` blocks into a single markup content string.
- * - Unhandled rules (anything not `@param`/`@returns`/`@throws`/`@example`) are appended after the description, separated by blank lines, with their `@name` preserved.
+ * - Unhandled rules (anything not `@param`/`@returns`/`@throws`/`@example`/`@see`) are appended after the description, separated by blank lines, with their `@name` preserved.
  * - Returns `undefined` if both are empty.
  */
 function _buildJSDocContent(description, unhandled) {
@@ -419,8 +440,12 @@ function _getClassMembers(statement, source, className) {
     }
     return members.length ? members : undefined;
 }
-/** `@rule` names handled by dedicated parsers — everything else is appended to `unhandled` as raw markup. */
-const _HANDLED_RULES = new Set(["param", "params", "return", "returns", "throw", "throws", "example", "examples"]);
+/**
+ * `@rule` names handled (parsed or deliberately discarded) — everything else is appended to `unhandled` as raw markup.
+ * - `@see` is recognised here purely to strip it: it's a VS Code hover affordance (a link back to the docs site) and must
+ *   never leak into the rendered page content. It has no dedicated parser; it's simply discarded from the `unhandled` bucket.
+ */
+const _HANDLED_RULES = new Set(["param", "params", "return", "returns", "throw", "throws", "example", "examples", "see"]);
 /** Extract JSDoc from a node. */
 function _getJSDoc(node, source) {
     const ranges = ts.getLeadingCommentRanges(source.text, node.pos);

package/firestore/client/FirestoreClientProvider.d.ts

@@ -6,13 +6,26 @@ import type { Item, Items, ItemsSequence, OptionalItem, OptionalItemSequence } f
 import { type Query } from "../../util/query.js";
 import type { Updates } from "../../util/update.js";
 /**
- * Firestore client database provider.
- * - Works with the Firebase JS SDK.
- * - Supports offline mode.
- * - Supports realtime subscriptions.
+ * Cloud Firestore database provider backed by the full Firebase JS SDK, implementing the `DBProvider` abstraction.
+ *
+ * - Works with the Firebase JS SDK via `firebase/firestore`.
+ * - Supports offline mode (local cache and write queueing).
+ * - Supports realtime subscriptions through Firestore `onSnapshot` listeners.
+ *
+ * @example
+ * import { getFirestore } from "firebase/firestore";
+ * const provider = new FirestoreClientProvider(getFirestore());
+ *
+ * @see https://dhoulb.github.io/shelving/firestore/client/FirestoreClientProvider/FirestoreClientProvider
  */
 export declare class FirestoreClientProvider<I extends string = string, T extends Data = Data> extends DBProvider<I, T> {
     private readonly _firestore;
+    /**
+     * Create a provider wrapping a Firebase `Firestore` instance.
+     *
+     * @param firestore The `Firestore` instance to read and write through.
+     * @see https://dhoulb.github.io/shelving/firestore/client/FirestoreClientProvider/FirestoreClientProvider
+     */
     constructor(firestore: Firestore);
     /** Get a Firestore CollectionReference for a given collection. */
     private _collection;
@@ -20,16 +33,128 @@ export declare class FirestoreClientProvider<I extends string = string, T extend
     private _doc;
     /** Get a Firestore QueryReference for a given query. */
     private _query;
+    /**
+     * Read a single item by ID from its Firestore document.
+     *
+     * @param c The collection the item belongs to.
+     * @param id The ID of the item to read.
+     * @returns Promise resolving to the item, or `undefined` if the document does not exist.
+     * @example await provider.getItem(users, "abc123")
+     * @see https://dhoulb.github.io/shelving/firestore/client/FirestoreClientProvider/FirestoreClientProvider/getItem
+     */
     getItem<II extends I, TT extends T>(c: Collection<string, II, TT>, id: II): Promise<OptionalItem<II, TT>>;
+    /**
+     * Subscribe to realtime changes to a single item via a Firestore `onSnapshot` listener.
+     *
+     * @param c The collection the item belongs to.
+     * @param id The ID of the item to subscribe to.
+     * @returns An async sequence yielding the item (or `undefined` when absent) on every change.
+     * @example for await (const item of provider.getItemSequence(users, "abc123")) console.log(item)
+     * @see https://dhoulb.github.io/shelving/firestore/client/FirestoreClientProvider/FirestoreClientProvider/getItemSequence
+     */
     getItemSequence<II extends I, TT extends T>(c: Collection<string, II, TT>, id: II): OptionalItemSequence<II, TT>;
+    /**
+     * Add an item to a collection, letting Firestore generate its document ID.
+     *
+     * @param c The collection to add the item to.
+     * @param data The data for the new item.
+     * @returns Promise resolving to the generated ID of the new item.
+     * @example const id = await provider.addItem(users, { name: "Dave" })
+     * @see https://dhoulb.github.io/shelving/firestore/client/FirestoreClientProvider/FirestoreClientProvider/addItem
+     */
     addItem<II extends I, TT extends T>(c: Collection<string, II, TT>, data: TT): Promise<II>;
+    /**
+     * Write an item by ID, overwriting any existing document.
+     *
+     * @param c The collection the item belongs to.
+     * @param id The ID of the item to write.
+     * @param data The data to store for the item.
+     * @returns Promise resolving once the write completes.
+     * @example await provider.setItem(users, "abc123", { name: "Dave" })
+     * @see https://dhoulb.github.io/shelving/firestore/client/FirestoreClientProvider/FirestoreClientProvider/setItem
+     */
     setItem<II extends I, TT extends T>(c: Collection<string, II, TT>, id: II, data: TT): Promise<void>;
+    /**
+     * Apply partial updates to a single item, translating them into Firestore `FieldValue` operations.
+     *
+     * @param c The collection the item belongs to.
+     * @param id The ID of the item to update.
+     * @param updates The updates to apply to the item.
+     * @returns Promise resolving once the update completes.
+     * @example await provider.updateItem(users, "abc123", { name: "Dave" })
+     * @see https://dhoulb.github.io/shelving/firestore/client/FirestoreClientProvider/FirestoreClientProvider/updateItem
+     */
     updateItem<II extends I, TT extends T>(c: Collection<string, II, TT>, id: II, updates: Updates<Item<II, TT>>): Promise<void>;
+    /**
+     * Delete a single item by ID from its collection.
+     *
+     * @param c The collection the item belongs to.
+     * @param id The ID of the item to delete.
+     * @returns Promise resolving once the deletion completes.
+     * @example await provider.deleteItem(users, "abc123")
+     * @see https://dhoulb.github.io/shelving/firestore/client/FirestoreClientProvider/FirestoreClientProvider/deleteItem
+     */
     deleteItem<II extends I, TT extends T>(c: Collection<string, II, TT>, id: II): Promise<void>;
+    /**
+     * Count the items matching a query using Firestore's server-side aggregation.
+     *
+     * @param c The collection to query.
+     * @param q The query selecting which items to count; counts the whole collection when omitted.
+     * @returns Promise resolving to the number of matching items.
+     * @example const total = await provider.countQuery(users)
+     * @see https://dhoulb.github.io/shelving/firestore/client/FirestoreClientProvider/FirestoreClientProvider/countQuery
+     */
     countQuery<II extends I, TT extends T>(c: Collection<string, II, TT>, q?: Query<Item<II, TT>>): Promise<number>;
+    /**
+     * Read all items matching a query.
+     *
+     * @param c The collection to query.
+     * @param q The query selecting which items to read; reads the whole collection when omitted.
+     * @returns Promise resolving to the array of matching items.
+     * @example const items = await provider.getQuery(users, { "name": "Dave" })
+     * @see https://dhoulb.github.io/shelving/firestore/client/FirestoreClientProvider/FirestoreClientProvider/getQuery
+     */
     getQuery<II extends I, TT extends T>(c: Collection<string, II, TT>, q?: Query<Item<II, TT>>): Promise<Items<II, TT>>;
+    /**
+     * Subscribe to realtime changes to a query via a Firestore `onSnapshot` listener.
+     *
+     * @param c The collection to query.
+     * @param q The query selecting which items to subscribe to; subscribes to the whole collection when omitted.
+     * @returns An async sequence yielding the matching items on every change.
+     * @example for await (const items of provider.getQuerySequence(users)) console.log(items)
+     * @see https://dhoulb.github.io/shelving/firestore/client/FirestoreClientProvider/FirestoreClientProvider/getQuerySequence
+     */
     getQuerySequence<II extends I, TT extends T>(c: Collection<string, II, TT>, q?: Query<Item<II, TT>>): ItemsSequence<II, TT>;
+    /**
+     * Write the same data to every item matching a query, one `setDoc` per matching document.
+     *
+     * @param c The collection to query.
+     * @param q The query selecting which items to write.
+     * @param data The data to write to each matching item.
+     * @returns Promise resolving once all writes complete.
+     * @example await provider.setQuery(users, { "name": "Dave" }, { active: false })
+     * @see https://dhoulb.github.io/shelving/firestore/client/FirestoreClientProvider/FirestoreClientProvider/setQuery
+     */
     setQuery<II extends I, TT extends T>(c: Collection<string, II, TT>, q: Query<Item<II, TT>>, data: TT): Promise<void>;
+    /**
+     * Apply the same partial updates to every item matching a query, one `updateDoc` per matching document.
+     *
+     * @param c The collection to query.
+     * @param q The query selecting which items to update.
+     * @param updates The updates to apply to each matching item.
+     * @returns Promise resolving once all updates complete.
+     * @example await provider.updateQuery(users, { "active": true }, { name: "Dave" })
+     * @see https://dhoulb.github.io/shelving/firestore/client/FirestoreClientProvider/FirestoreClientProvider/updateQuery
+     */
     updateQuery<II extends I, TT extends T>(c: Collection<string, II, TT>, q: Query<Item<II, TT>>, updates: Updates<TT>): Promise<void>;
+    /**
+     * Delete every item matching a query, one `deleteDoc` per matching document.
+     *
+     * @param c The collection to query.
+     * @param q The query selecting which items to delete.
+     * @returns Promise resolving once all deletions complete.
+     * @example await provider.deleteQuery(users, { "active": false })
+     * @see https://dhoulb.github.io/shelving/firestore/client/FirestoreClientProvider/FirestoreClientProvider/deleteQuery
+     */
     deleteQuery<II extends I, TT extends T>(c: Collection<string, II, TT>, q: Query<Item<II, TT>>): Promise<void>;
 }

package/firestore/client/FirestoreClientProvider.js

@@ -63,13 +63,26 @@ function _getFieldValue({ key, action, value }) {
     return action; // Never happens.
 }
 /**
- * Firestore client database provider.
- * - Works with the Firebase JS SDK.
- * - Supports offline mode.
- * - Supports realtime subscriptions.
+ * Cloud Firestore database provider backed by the full Firebase JS SDK, implementing the `DBProvider` abstraction.
+ *
+ * - Works with the Firebase JS SDK via `firebase/firestore`.
+ * - Supports offline mode (local cache and write queueing).
+ * - Supports realtime subscriptions through Firestore `onSnapshot` listeners.
+ *
+ * @example
+ * import { getFirestore } from "firebase/firestore";
+ * const provider = new FirestoreClientProvider(getFirestore());
+ *
+ * @see https://dhoulb.github.io/shelving/firestore/client/FirestoreClientProvider/FirestoreClientProvider
  */
 export class FirestoreClientProvider extends DBProvider {
     _firestore;
+    /**
+     * Create a provider wrapping a Firebase `Firestore` instance.
+     *
+     * @param firestore The `Firestore` instance to read and write through.
+     * @see https://dhoulb.github.io/shelving/firestore/client/FirestoreClientProvider/FirestoreClientProvider
+     */
     constructor(firestore) {
         super();
         this._firestore = firestore;
@@ -86,47 +99,159 @@ export class FirestoreClientProvider extends DBProvider {
     _query(c, q) {
         return q ? query(this._collection(c), ..._getConstraints(q)) : this._collection(c);
     }
+    /**
+     * Read a single item by ID from its Firestore document.
+     *
+     * @param c The collection the item belongs to.
+     * @param id The ID of the item to read.
+     * @returns Promise resolving to the item, or `undefined` if the document does not exist.
+     * @example await provider.getItem(users, "abc123")
+     * @see https://dhoulb.github.io/shelving/firestore/client/FirestoreClientProvider/FirestoreClientProvider/getItem
+     */
     async getItem(c, id) {
         const snapshot = await getDoc(this._doc(c, id));
         return _getOptionalItem(snapshot);
     }
+    /**
+     * Subscribe to realtime changes to a single item via a Firestore `onSnapshot` listener.
+     *
+     * @param c The collection the item belongs to.
+     * @param id The ID of the item to subscribe to.
+     * @returns An async sequence yielding the item (or `undefined` when absent) on every change.
+     * @example for await (const item of provider.getItemSequence(users, "abc123")) console.log(item)
+     * @see https://dhoulb.github.io/shelving/firestore/client/FirestoreClientProvider/FirestoreClientProvider/getItemSequence
+     */
     getItemSequence(c, id) {
         const sequence = new DeferredSequence();
         return new LazySequence(sequence, () => onSnapshot(this._doc(c, id), snapshot => sequence.resolve(_getOptionalItem(snapshot)), reason => sequence.reject(reason)));
     }
+    /**
+     * Add an item to a collection, letting Firestore generate its document ID.
+     *
+     * @param c The collection to add the item to.
+     * @param data The data for the new item.
+     * @returns Promise resolving to the generated ID of the new item.
+     * @example const id = await provider.addItem(users, { name: "Dave" })
+     * @see https://dhoulb.github.io/shelving/firestore/client/FirestoreClientProvider/FirestoreClientProvider/addItem
+     */
     async addItem(c, data) {
         const reference = await addDoc(this._collection(c), data);
         return reference.id; // `as II` needed: Firestore returns string, not II.
     }
+    /**
+     * Write an item by ID, overwriting any existing document.
+     *
+     * @param c The collection the item belongs to.
+     * @param id The ID of the item to write.
+     * @param data The data to store for the item.
+     * @returns Promise resolving once the write completes.
+     * @example await provider.setItem(users, "abc123", { name: "Dave" })
+     * @see https://dhoulb.github.io/shelving/firestore/client/FirestoreClientProvider/FirestoreClientProvider/setItem
+     */
     async setItem(c, id, data) {
         await setDoc(this._doc(c, id), data);
     }
+    /**
+     * Apply partial updates to a single item, translating them into Firestore `FieldValue` operations.
+     *
+     * @param c The collection the item belongs to.
+     * @param id The ID of the item to update.
+     * @param updates The updates to apply to the item.
+     * @returns Promise resolving once the update completes.
+     * @example await provider.updateItem(users, "abc123", { name: "Dave" })
+     * @see https://dhoulb.github.io/shelving/firestore/client/FirestoreClientProvider/FirestoreClientProvider/updateItem
+     */
     async updateItem(c, id, updates) {
         await updateDoc(this._doc(c, id), _getFieldValues(updates));
     }
+    /**
+     * Delete a single item by ID from its collection.
+     *
+     * @param c The collection the item belongs to.
+     * @param id The ID of the item to delete.
+     * @returns Promise resolving once the deletion completes.
+     * @example await provider.deleteItem(users, "abc123")
+     * @see https://dhoulb.github.io/shelving/firestore/client/FirestoreClientProvider/FirestoreClientProvider/deleteItem
+     */
     async deleteItem(c, id) {
         await deleteDoc(this._doc(c, id));
     }
+    /**
+     * Count the items matching a query using Firestore's server-side aggregation.
+     *
+     * @param c The collection to query.
+     * @param q The query selecting which items to count; counts the whole collection when omitted.
+     * @returns Promise resolving to the number of matching items.
+     * @example const total = await provider.countQuery(users)
+     * @see https://dhoulb.github.io/shelving/firestore/client/FirestoreClientProvider/FirestoreClientProvider/countQuery
+     */
     async countQuery(c, q) {
         const snapshot = await getCountFromServer(this._query(c, q));
         return snapshot.data().count;
     }
+    /**
+     * Read all items matching a query.
+     *
+     * @param c The collection to query.
+     * @param q The query selecting which items to read; reads the whole collection when omitted.
+     * @returns Promise resolving to the array of matching items.
+     * @example const items = await provider.getQuery(users, { "name": "Dave" })
+     * @see https://dhoulb.github.io/shelving/firestore/client/FirestoreClientProvider/FirestoreClientProvider/getQuery
+     */
     async getQuery(c, q) {
         return _getItems(await getDocs(this._query(c, q)));
     }
+    /**
+     * Subscribe to realtime changes to a query via a Firestore `onSnapshot` listener.
+     *
+     * @param c The collection to query.
+     * @param q The query selecting which items to subscribe to; subscribes to the whole collection when omitted.
+     * @returns An async sequence yielding the matching items on every change.
+     * @example for await (const items of provider.getQuerySequence(users)) console.log(items)
+     * @see https://dhoulb.github.io/shelving/firestore/client/FirestoreClientProvider/FirestoreClientProvider/getQuerySequence
+     */
     getQuerySequence(c, q) {
         const sequence = new DeferredSequence();
         return new LazySequence(sequence, () => onSnapshot(this._query(c, q), snapshot => sequence.resolve(_getItems(snapshot)), reason => sequence.reject(reason)));
     }
+    /**
+     * Write the same data to every item matching a query, one `setDoc` per matching document.
+     *
+     * @param c The collection to query.
+     * @param q The query selecting which items to write.
+     * @param data The data to write to each matching item.
+     * @returns Promise resolving once all writes complete.
+     * @example await provider.setQuery(users, { "name": "Dave" }, { active: false })
+     * @see https://dhoulb.github.io/shelving/firestore/client/FirestoreClientProvider/FirestoreClientProvider/setQuery
+     */
     async setQuery(c, q, data) {
         const snapshot = await getDocs(this._query(c, q));
         await Promise.all(snapshot.docs.map(s => setDoc(s.ref, data)));
     }
+    /**
+     * Apply the same partial updates to every item matching a query, one `updateDoc` per matching document.
+     *
+     * @param c The collection to query.
+     * @param q The query selecting which items to update.
+     * @param updates The updates to apply to each matching item.
+     * @returns Promise resolving once all updates complete.
+     * @example await provider.updateQuery(users, { "active": true }, { name: "Dave" })
+     * @see https://dhoulb.github.io/shelving/firestore/client/FirestoreClientProvider/FirestoreClientProvider/updateQuery
+     */
     async updateQuery(c, q, updates) {
         const snapshot = await getDocs(this._query(c, q));
         const fieldValues = _getFieldValues(updates);
         await Promise.all(snapshot.docs.map(s => updateDoc(s.ref, fieldValues)));
     }
+    /**
+     * Delete every item matching a query, one `deleteDoc` per matching document.
+     *
+     * @param c The collection to query.
+     * @param q The query selecting which items to delete.
+     * @returns Promise resolving once all deletions complete.
+     * @example await provider.deleteQuery(users, { "active": false })
+     * @see https://dhoulb.github.io/shelving/firestore/client/FirestoreClientProvider/FirestoreClientProvider/deleteQuery
+     */
     async deleteQuery(c, q) {
         const snapshot = await getDocs(this._query(c, q));
         await Promise.all(snapshot.docs.map(s => deleteDoc(s.ref)));

package/firestore/lite/FirestoreLiteProvider.d.ts

@@ -6,13 +6,26 @@ import type { Item, Items, ItemsSequence, OptionalItem, OptionalItemSequence } f
 import { type Query } from "../../util/query.js";
 import type { Updates } from "../../util/update.js";
 /**
- * Firestore Lite client database provider.
- * - Works with the Firebase JS SDK.
+ * Cloud Firestore database provider backed by the Firebase Lite SDK, implementing the `DBProvider` abstraction.
+ *
+ * - Works with the Firebase JS SDK via `firebase/firestore/lite`, which keeps bundle size small.
  * - Does not support offline mode.
- * - Does not support realtime subscriptions.
+ * - Does not support realtime subscriptions: `getItemSequence()` and `getQuerySequence()` throw `UnimplementedError`.
+ *
+ * @example
+ * import { getFirestore } from "firebase/firestore/lite";
+ * const provider = new FirestoreLiteProvider(getFirestore());
+ *
+ * @see https://dhoulb.github.io/shelving/firestore/lite/FirestoreLiteProvider/FirestoreLiteProvider
  */
 export declare class FirestoreLiteProvider<I extends string = string, T extends Data = Data> extends DBProvider<I, T> {
     private readonly _firestore;
+    /**
+     * Create a provider wrapping a Firebase Lite `Firestore` instance.
+     *
+     * @param firestore The `Firestore` instance to read and write through.
+     * @see https://dhoulb.github.io/shelving/firestore/lite/FirestoreLiteProvider/FirestoreLiteProvider
+     */
     constructor(firestore: Firestore);
     /** Get a Firestore CollectionReference for a given collection. */
     private _collection;
@@ -20,16 +33,128 @@ export declare class FirestoreLiteProvider<I extends string = string, T extends
     private _doc;
     /** Get a Firestore QueryReference for a given query. */
     private _query;
+    /**
+     * Read a single item by ID from its Firestore document.
+     *
+     * @param c The collection the item belongs to.
+     * @param id The ID of the item to read.
+     * @returns Promise resolving to the item, or `undefined` if the document does not exist.
+     * @example await provider.getItem(users, "abc123")
+     * @see https://dhoulb.github.io/shelving/firestore/lite/FirestoreLiteProvider/FirestoreLiteProvider/getItem
+     */
     getItem<II extends I, TT extends T>(c: Collection<string, II, TT>, id: II): Promise<OptionalItem<II, TT>>;
+    /**
+     * Not supported — the Firebase Lite SDK has no realtime listeners.
+     *
+     * @param _c The collection the item belongs to.
+     * @param _id The ID of the item to subscribe to.
+     * @returns Never returns normally.
+     * @throws {UnimplementedError} Always, because Firestore Lite does not support realtime subscriptions.
+     * @see https://dhoulb.github.io/shelving/firestore/lite/FirestoreLiteProvider/FirestoreLiteProvider/getItemSequence
+     */
     getItemSequence<II extends I, TT extends T>(_c: Collection<string, II, TT>, _id: II): OptionalItemSequence<II, TT>;
+    /**
+     * Add an item to a collection, letting Firestore generate its document ID.
+     *
+     * @param c The collection to add the item to.
+     * @param data The data for the new item.
+     * @returns Promise resolving to the generated ID of the new item.
+     * @example const id = await provider.addItem(users, { name: "Dave" })
+     * @see https://dhoulb.github.io/shelving/firestore/lite/FirestoreLiteProvider/FirestoreLiteProvider/addItem
+     */
     addItem<II extends I, TT extends T>(c: Collection<string, II, TT>, data: TT): Promise<II>;
+    /**
+     * Write an item by ID, overwriting any existing document.
+     *
+     * @param c The collection the item belongs to.
+     * @param id The ID of the item to write.
+     * @param data The data to store for the item.
+     * @returns Promise resolving once the write completes.
+     * @example await provider.setItem(users, "abc123", { name: "Dave" })
+     * @see https://dhoulb.github.io/shelving/firestore/lite/FirestoreLiteProvider/FirestoreLiteProvider/setItem
+     */
     setItem<II extends I, TT extends T>(c: Collection<string, II, TT>, id: II, data: TT): Promise<void>;
+    /**
+     * Apply partial updates to a single item, translating them into Firestore `FieldValue` operations.
+     *
+     * @param c The collection the item belongs to.
+     * @param id The ID of the item to update.
+     * @param updates The updates to apply to the item.
+     * @returns Promise resolving once the update completes.
+     * @example await provider.updateItem(users, "abc123", { name: "Dave" })
+     * @see https://dhoulb.github.io/shelving/firestore/lite/FirestoreLiteProvider/FirestoreLiteProvider/updateItem
+     */
     updateItem<II extends I, TT extends T>(c: Collection<string, II, TT>, id: II, updates: Updates<Item<II, TT>>): Promise<void>;
+    /**
+     * Delete a single item by ID from its collection.
+     *
+     * @param c The collection the item belongs to.
+     * @param id The ID of the item to delete.
+     * @returns Promise resolving once the deletion completes.
+     * @example await provider.deleteItem(users, "abc123")
+     * @see https://dhoulb.github.io/shelving/firestore/lite/FirestoreLiteProvider/FirestoreLiteProvider/deleteItem
+     */
     deleteItem<II extends I, TT extends T>(c: Collection<string, II, TT>, id: II): Promise<void>;
+    /**
+     * Count the items matching a query using Firestore's server-side aggregation.
+     *
+     * @param c The collection to query.
+     * @param q The query selecting which items to count; counts the whole collection when omitted.
+     * @returns Promise resolving to the number of matching items.
+     * @example const total = await provider.countQuery(users)
+     * @see https://dhoulb.github.io/shelving/firestore/lite/FirestoreLiteProvider/FirestoreLiteProvider/countQuery
+     */
     countQuery<II extends I, TT extends T>(c: Collection<string, II, TT>, q?: Query<Item<II, TT>>): Promise<number>;
+    /**
+     * Read all items matching a query.
+     *
+     * @param c The collection to query.
+     * @param q The query selecting which items to read; reads the whole collection when omitted.
+     * @returns Promise resolving to the array of matching items.
+     * @example const items = await provider.getQuery(users, { "name": "Dave" })
+     * @see https://dhoulb.github.io/shelving/firestore/lite/FirestoreLiteProvider/FirestoreLiteProvider/getQuery
+     */
     getQuery<II extends I, TT extends T>(c: Collection<string, II, TT>, q?: Query<Item<II, TT>>): Promise<Items<II, TT>>;
+    /**
+     * Not supported — the Firebase Lite SDK has no realtime listeners.
+     *
+     * @param _c The collection to query.
+     * @param _q The query to subscribe to.
+     * @returns Never returns normally.
+     * @throws {UnimplementedError} Always, because Firestore Lite does not support realtime subscriptions.
+     * @see https://dhoulb.github.io/shelving/firestore/lite/FirestoreLiteProvider/FirestoreLiteProvider/getQuerySequence
+     */
     getQuerySequence<II extends I, TT extends T>(_c: Collection<string, II, TT>, _q?: Query<Item<II, TT>>): ItemsSequence<II, TT>;
+    /**
+     * Write the same data to every item matching a query, one `setDoc` per matching document.
+     *
+     * @param c The collection to query.
+     * @param q The query selecting which items to write.
+     * @param data The data to write to each matching item.
+     * @returns Promise resolving once all writes complete.
+     * @example await provider.setQuery(users, { "name": "Dave" }, { active: false })
+     * @see https://dhoulb.github.io/shelving/firestore/lite/FirestoreLiteProvider/FirestoreLiteProvider/setQuery
+     */
     setQuery<II extends I, TT extends T>(c: Collection<string, II, TT>, q: Query<Item<II, TT>>, data: TT): Promise<void>;
+    /**
+     * Apply the same partial updates to every item matching a query, one `updateDoc` per matching document.
+     *
+     * @param c The collection to query.
+     * @param q The query selecting which items to update.
+     * @param updates The updates to apply to each matching item.
+     * @returns Promise resolving once all updates complete.
+     * @example await provider.updateQuery(users, { "active": true }, { name: "Dave" })
+     * @see https://dhoulb.github.io/shelving/firestore/lite/FirestoreLiteProvider/FirestoreLiteProvider/updateQuery
+     */
     updateQuery<II extends I, TT extends T>(c: Collection<string, II, TT>, q: Query<Item<II, TT>>, updates: Updates<TT>): Promise<void>;
+    /**
+     * Delete every item matching a query, one `deleteDoc` per matching document.
+     *
+     * @param c The collection to query.
+     * @param q The query selecting which items to delete.
+     * @returns Promise resolving once all deletions complete.
+     * @example await provider.deleteQuery(users, { "active": false })
+     * @see https://dhoulb.github.io/shelving/firestore/lite/FirestoreLiteProvider/FirestoreLiteProvider/deleteQuery
+     */
     deleteQuery<II extends I, TT extends T>(c: Collection<string, II, TT>, q: Query<Item<II, TT>>): Promise<void>;
 }