shelving 1.236.0 → 1.236.2

package/firestore/lite/FirestoreLiteProvider.js

@@ -62,13 +62,26 @@ function _getFieldValue({ key, action, value }) {
     return action; // Never happens.
 }
 /**
- * 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 class FirestoreLiteProvider extends DBProvider {
     _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) {
         super();
         this._firestore = firestore;
@@ -85,45 +98,157 @@ export class FirestoreLiteProvider 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/lite/FirestoreLiteProvider/FirestoreLiteProvider/getItem
+     */
     async getItem(c, id) {
         const snapshot = await getDoc(this._doc(c, id));
         return _getOptionalItem(snapshot);
     }
+    /**
+     * 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(_c, _id) {
         throw new UnimplementedError("FirestoreLiteProvider does not support realtime subscriptions");
     }
+    /**
+     * 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
+     */
     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/lite/FirestoreLiteProvider/FirestoreLiteProvider/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/lite/FirestoreLiteProvider/FirestoreLiteProvider/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/lite/FirestoreLiteProvider/FirestoreLiteProvider/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/lite/FirestoreLiteProvider/FirestoreLiteProvider/countQuery
+     */
     async countQuery(c, q) {
         const snapshot = await getCount(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/lite/FirestoreLiteProvider/FirestoreLiteProvider/getQuery
+     */
     async getQuery(c, q) {
         return _getItems(await getDocs(this._query(c, q)));
     }
+    /**
+     * 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(_c, _q) {
         throw new UnimplementedError("FirestoreLiteProvider does not support realtime subscriptions");
     }
+    /**
+     * 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
+     */
     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/lite/FirestoreLiteProvider/FirestoreLiteProvider/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/lite/FirestoreLiteProvider/FirestoreLiteProvider/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/server/FirestoreServerProvider.d.ts

@@ -6,11 +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 server database provider.
- * - Works with the Firebase Admin SDK for Node.JS
+ * Cloud Firestore database provider backed by the Firebase Admin SDK, implementing the `DBProvider` abstraction.
+ *
+ * - Runs server-side via `@google-cloud/firestore` (the Firebase Admin SDK for Node.JS).
+ * - Supports realtime subscriptions through Firestore `onSnapshot` listeners.
+ * - Collection writes (`setQuery`, `updateQuery`, `deleteQuery`) are batched through a Firestore `BulkWriter`.
+ *
+ * @example
+ * import { Firestore } from "@google-cloud/firestore";
+ * const provider = new FirestoreServerProvider(new Firestore());
+ *
+ * @see https://dhoulb.github.io/shelving/firestore/server/FirestoreServerProvider/FirestoreServerProvider
  */
 export declare class FirestoreServerProvider<I extends string = string, T extends Data = Data> extends DBProvider<I, T> {
     private readonly _firestore;
+    /**
+     * Create a provider wrapping a Firestore Admin SDK instance.
+     *
+     * @param firestore The `Firestore` instance to read and write through; defaults to a new `Firestore()`.
+     * @see https://dhoulb.github.io/shelving/firestore/server/FirestoreServerProvider/FirestoreServerProvider
+     */
     constructor(firestore?: Firestore);
     /** Create a corresponding `FirestoreCollection` reference from a collection. */
     private _getCollection;
@@ -18,16 +33,128 @@ export declare class FirestoreServerProvider<I extends string = string, T extend
     private _getQuery;
     /** Perform a bulk update on a set of documents using a `BulkWriter` */
     private _bulkWrite;
+    /**
+     * Read a single item by ID from its Firestore document.
+     *
+     * @param collection 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/server/FirestoreServerProvider/FirestoreServerProvider/getItem
+     */
     getItem<II extends I, TT extends T>(collection: 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/server/FirestoreServerProvider/FirestoreServerProvider/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/server/FirestoreServerProvider/FirestoreServerProvider/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/server/FirestoreServerProvider/FirestoreServerProvider/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/server/FirestoreServerProvider/FirestoreServerProvider/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/server/FirestoreServerProvider/FirestoreServerProvider/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/server/FirestoreServerProvider/FirestoreServerProvider/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/server/FirestoreServerProvider/FirestoreServerProvider/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/server/FirestoreServerProvider/FirestoreServerProvider/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, batched through a Firestore `BulkWriter`.
+     *
+     * @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/server/FirestoreServerProvider/FirestoreServerProvider/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, batched through a Firestore `BulkWriter`.
+     *
+     * @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/server/FirestoreServerProvider/FirestoreServerProvider/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, batched through a Firestore `BulkWriter`.
+     *
+     * @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/server/FirestoreServerProvider/FirestoreServerProvider/deleteQuery
+     */
     deleteQuery<II extends I, TT extends T>(c: Collection<string, II, TT>, q: Query<Item<II, TT>>): Promise<void>;
 }

package/firestore/server/FirestoreServerProvider.js

@@ -51,11 +51,26 @@ function _getFieldValue({ key, action, value }) {
     return action; // Never happens.
 }
 /**
- * Firestore server database provider.
- * - Works with the Firebase Admin SDK for Node.JS
+ * Cloud Firestore database provider backed by the Firebase Admin SDK, implementing the `DBProvider` abstraction.
+ *
+ * - Runs server-side via `@google-cloud/firestore` (the Firebase Admin SDK for Node.JS).
+ * - Supports realtime subscriptions through Firestore `onSnapshot` listeners.
+ * - Collection writes (`setQuery`, `updateQuery`, `deleteQuery`) are batched through a Firestore `BulkWriter`.
+ *
+ * @example
+ * import { Firestore } from "@google-cloud/firestore";
+ * const provider = new FirestoreServerProvider(new Firestore());
+ *
+ * @see https://dhoulb.github.io/shelving/firestore/server/FirestoreServerProvider/FirestoreServerProvider
  */
 export class FirestoreServerProvider extends DBProvider {
     _firestore;
+    /**
+     * Create a provider wrapping a Firestore Admin SDK instance.
+     *
+     * @param firestore The `Firestore` instance to read and write through; defaults to a new `Firestore()`.
+     * @see https://dhoulb.github.io/shelving/firestore/server/FirestoreServerProvider/FirestoreServerProvider
+     */
     constructor(firestore = new Firestore()) {
         super();
         this._firestore = firestore;
@@ -96,45 +111,157 @@ export class FirestoreServerProvider extends DBProvider {
         }
         await writer.close();
     }
+    /**
+     * Read a single item by ID from its Firestore document.
+     *
+     * @param collection 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/server/FirestoreServerProvider/FirestoreServerProvider/getItem
+     */
     async getItem(collection, id) {
         return _getOptionalItem(await this._getCollection(collection).doc(id).get());
     }
+    /**
+     * 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/server/FirestoreServerProvider/FirestoreServerProvider/getItemSequence
+     */
     getItemSequence(c, id) {
         const ref = this._getCollection(c).doc(id);
         const sequence = new DeferredSequence();
         return new LazySequence(sequence, () => ref.onSnapshot(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/server/FirestoreServerProvider/FirestoreServerProvider/addItem
+     */
     async addItem(c, data) {
         return (await this._getCollection(c).add(data)).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/server/FirestoreServerProvider/FirestoreServerProvider/setItem
+     */
     async setItem(c, id, data) {
         await this._getCollection(c).doc(id).set(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/server/FirestoreServerProvider/FirestoreServerProvider/updateItem
+     */
     async updateItem(c, id, updates) {
         await this._getCollection(c).doc(id).update(_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/server/FirestoreServerProvider/FirestoreServerProvider/deleteItem
+     */
     async deleteItem(c, id) {
         await this._getCollection(c).doc(id).delete();
     }
+    /**
+     * 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/server/FirestoreServerProvider/FirestoreServerProvider/countQuery
+     */
     async countQuery(c, q) {
         const snapshot = await this._getQuery(c, q).count().get();
         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/server/FirestoreServerProvider/FirestoreServerProvider/getQuery
+     */
     async getQuery(c, q) {
         return _getItems(await this._getQuery(c, q).get());
     }
+    /**
+     * 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/server/FirestoreServerProvider/FirestoreServerProvider/getQuerySequence
+     */
     getQuerySequence(c, q) {
         const ref = this._getQuery(c, q);
         const sequence = new DeferredSequence();
         return new LazySequence(sequence, () => ref.onSnapshot(snapshot => sequence.resolve(_getItems(snapshot)), reason => sequence.reject(reason)));
     }
+    /**
+     * Write the same data to every item matching a query, batched through a Firestore `BulkWriter`.
+     *
+     * @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/server/FirestoreServerProvider/FirestoreServerProvider/setQuery
+     */
     async setQuery(c, q, data) {
         return await this._bulkWrite(c, q, (w, s) => void w.set(s.ref, data));
     }
+    /**
+     * Apply the same partial updates to every item matching a query, batched through a Firestore `BulkWriter`.
+     *
+     * @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/server/FirestoreServerProvider/FirestoreServerProvider/updateQuery
+     */
     async updateQuery(c, q, updates) {
         const fieldValues = _getFieldValues(updates);
         return await this._bulkWrite(c, q, (w, s) => void w.update(s.ref, fieldValues));
     }
+    /**
+     * Delete every item matching a query, batched through a Firestore `BulkWriter`.
+     *
+     * @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/server/FirestoreServerProvider/FirestoreServerProvider/deleteQuery
+     */
     async deleteQuery(c, q) {
         return await this._bulkWrite(c, q, (w, s) => void w.delete(s.ref));
     }

package/markup/MarkupParser.d.ts

@@ -6,7 +6,13 @@ import { type ImmutableURI, type URISchemes } from "../util/uri.js";
 import type { ImmutableURL } from "../util/url.js";
 import type { MarkupRule, MarkupRules } from "./MarkupRule.js";
 import type { Parser } from "./Parser.js";
-/** The current parsing options (represents the current state of the parsing). */
+/**
+ * Options configuring a `MarkupParser` (represents the current state of the parsing).
+ * - Every field is optional — an empty object yields a parser with the default rules and behaviour.
+ * - Link resolution honours `url`, `root`, and `schemes`; link safety hinges on `schemes`.
+ *
+ * @see https://dhoulb.github.io/shelving/markup/MarkupParser/MarkupOptions
+ */
 export type MarkupOptions = {
     /**
      * The active list of parsing rules.
@@ -37,61 +43,102 @@ export type MarkupOptions = {
      */
     readonly context?: string;
 };
+/**
+ * Parses a Markdownish markup string and renders it as a React node using a tiered, masking rule engine.
+ * - The syntax isn't hardcoded — it's defined entirely by the `rules` supplied (defaults to `MARKUP_RULES`).
+ * - Rules are grouped into priority tiers and resolved highest tier first; a claimed region is masked so lower-priority rules can't match into or across it.
+ * - Rules own the recursion into their own children by calling `parse()` again, optionally with a different context.
+ *
+ * @example
+ * const node = new MarkupParser().parse("This is a *bold* string.");
+ * @see https://dhoulb.github.io/shelving/markup/MarkupParser/MarkupParser
+ */
 export declare class MarkupParser implements Parser<string, ReactNode> {
     /**
      * The list of parsing rules this parser applies.
+     * @see https://dhoulb.github.io/shelving/markup/MarkupParser/MarkupParser/rules
      */
     readonly rules: MarkupRules;
     /**
      * Calculated list of priorities to iterate over (extracted from the rules), e.g. [10, 0, -10]
+     * @see https://dhoulb.github.io/shelving/markup/MarkupParser/MarkupParser/priorities
      */
     readonly priorities: ImmutableArray<number>;
     /**
      * Set the `rel=""` property used for any links (e.g. `rel="nofollow ugc"`).
      * @example "nofollow ugc"
+     * @see https://dhoulb.github.io/shelving/markup/MarkupParser/MarkupParser/rel
      */
     readonly rel: string | undefined;
     /**
      * Current page URL — used as the base for resolving relative refs (`./foo`, `#x`, bare segments) in link hrefs.
      * @default Falls back to `root` if not set.
+     * @see https://dhoulb.github.io/shelving/markup/MarkupParser/MarkupParser/url
      */
     readonly url: ImmutableURL | undefined;
     /**
      * Site root URL — used as the base for resolving site-absolute path hrefs (`/foo`), honoring its subfolder.
      * @default Falls back to `url` if not set.
+     * @see https://dhoulb.github.io/shelving/markup/MarkupParser/MarkupParser/root
      */
     readonly root: ImmutableURL | undefined;
     /**
      * Valid URI schemes/protocols for URLs and URIs.
      * @example ["http:", "https:"]
      * @default ["http:", "https:"]
+     * @see https://dhoulb.github.io/shelving/markup/MarkupParser/MarkupParser/schemes
      */
     readonly schemes: URISchemes;
     /**
      * Default context to use if one isn't set. Defaults to `"block"`
+     * @see https://dhoulb.github.io/shelving/markup/MarkupParser/MarkupParser/context
      */
     readonly context: string;
+    /**
+     * Create a new `MarkupParser` from a set of options.
+     *
+     * @param options Options configuring the rules, link resolution, and default context (all optional).
+     * @returns A `MarkupParser` instance.
+     * @example new MarkupParser({ rel: "nofollow ugc" })
+     * @see https://dhoulb.github.io/shelving/markup/MarkupParser/MarkupParser
+     */
     constructor({ rules, rel, url, root, schemes, context }?: MarkupOptions);
     /**
-     * Parse a text string as Markdownish markup syntax and render it as elements.
+     * Parse a text string as Markdownish markup syntax and render it as a React node.
      * - Syntax is not defined by this code, but by the rules supplied to it.
      *
-     * @param input The string content possibly containing markup syntax, e.g. "This is a *bold* string.
-     * @param parser A markup parser instance.
+     * @param input The string content possibly containing markup syntax, e.g. `"This is a *bold* string."`.
      * @param context The context to render in (defaults to `"block"`).
-     *
      * @returns A React node — an element, a string, `null`, or an array of zero or more of those.
+     * @example new MarkupParser().parse("This is a *bold* string.")
+     * @see https://dhoulb.github.io/shelving/markup/MarkupParser/MarkupParser/parse
      */
     parse(input: string, context?: string): ReactNode;
-    /** Yield the rules active in `context` that sit in the given priority tier. */
+    /**
+     * Yield the rules active in `context` that sit in the given priority tier.
+     *
+     * @param context The render context to filter rules by (e.g. `"block"`, `"inline"`).
+     * @param priority The priority tier to filter rules by.
+     * @returns An iterable of the matching `MarkupRule` instances.
+     * @example for (const rule of parser.getRules("block", 0)) { ... }
+     * @see https://dhoulb.github.io/shelving/markup/MarkupParser/MarkupParser/getRules
+     */
     getRules(context: string, priority: number): Iterable<MarkupRule>;
     /**
-     * Get a HREF link with the correct context of our `options.url` and `options.root`
+     * Resolve a link href against this parser's `url` and `root`, returning it only if its scheme is allowed.
      *
-     * @returns `ImmutableURI` a (URL) object if the link matches and is parseable and has an allowed scheme.
-     * @returns `undefined` if the link does not amtch the allowed `options.schemes`
+     * @param href The raw link reference to resolve (relative or absolute), or a nullish value.
+     * @returns An `ImmutableURI` if the link parses and its scheme is in `schemes`, otherwise `undefined`.
+     * @example parser.getLink("/about") // ImmutableURI | undefined
+     * @see https://dhoulb.github.io/shelving/markup/MarkupParser/MarkupParser/getLink
      */
     getLink(href: Nullish<PossibleLink>): ImmutableURI | undefined;
 }
-/** MarkupParser sentinel with the default markup rules */
+/**
+ * Shared `MarkupParser` instance configured with the default markup rules and behaviour.
+ * - Use this singleton when no custom rules, link resolution, or default context are needed.
+ *
+ * @example MARKUP_PARSER.parse("This is a *bold* string.")
+ * @see https://dhoulb.github.io/shelving/markup/MarkupParser/MARKUP_PARSER
+ */
 export declare const MARKUP_PARSER: MarkupParser;