shelving 1.236.0 → 1.236.2

package/db/provider/DebugDBProvider.d.ts

@@ -4,18 +4,135 @@ import type { Query } from "../../util/query.js";
 import type { Updates } from "../../util/update.js";
 import type { Collection } from "../collection/Collection.js";
 import { ThroughDBProvider } from "./ThroughDBProvider.js";
-/** Provider that logs operations to the console. */
+/**
+ * Database provider that logs every operation it performs to the console for debugging.
+ *
+ * - Wraps a `source` provider and writes `console.debug` lines (with ANSI direction markers) before and after each call, and `console.error` on failure.
+ * - Drop it into a provider chain while developing to trace database reads and writes; it changes no data.
+ *
+ * @example
+ *  const provider = new DebugDBProvider(new MemoryDBProvider());
+ *  await provider.getItem(users, 123); // Logs the call and its result.
+ *
+ * @see https://dhoulb.github.io/shelving/db/provider/DebugDBProvider/DebugDBProvider
+ */
 export declare class DebugDBProvider<I extends Identifier, T extends Data> extends ThroughDBProvider<I, T> {
+    /**
+     * Get an item by its id, logging the call and result.
+     *
+     * @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/DebugDBProvider/DebugDBProvider/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, logging each emission.
+     *
+     * @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/DebugDBProvider/DebugDBProvider/getItemSequence
+     */
     getItemSequence<II extends I, TT extends T>(collection: Collection<string, II, TT>, id: II): OptionalItemSequence<II, TT>;
+    /**
+     * Add a new item, logging the call and generated id.
+     *
+     * @param collection Collection to add the item to.
+     * @param data Data for the new item.
+     * @returns The generated identifier for the new item.
+     * @example await provider.addItem(users, { name: "Dave" }) // 123
+     * @see https://dhoulb.github.io/shelving/db/provider/DebugDBProvider/DebugDBProvider/addItem
+     */
     addItem<II extends I, TT extends T>(collection: Collection<string, II, TT>, data: TT): Promise<II>;
+    /**
+     * Set (insert or overwrite) an item by its id, logging the call.
+     *
+     * @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/DebugDBProvider/DebugDBProvider/setItem
+     */
     setItem<II extends I, TT extends T>(collection: Collection<string, II, TT>, id: II, data: TT): Promise<void>;
+    /**
+     * Apply partial updates to an item by its id, logging the call.
+     *
+     * @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/DebugDBProvider/DebugDBProvider/updateItem
+     */
     updateItem<II extends I, TT extends T>(collection: Collection<string, II, TT>, id: II, updates: Updates<Item<II, TT>>): Promise<void>;
+    /**
+     * Delete an item by its id, logging the call.
+     *
+     * @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/DebugDBProvider/DebugDBProvider/deleteItem
+     */
     deleteItem<II extends I, TT extends T>(collection: Collection<string, II, TT>, id: II): Promise<void>;
+    /**
+     * Count the items matching an optional query, logging the call and result.
+     *
+     * @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/DebugDBProvider/DebugDBProvider/countQuery
+     */
     countQuery<II extends I, TT extends T>(collection: Collection<string, II, TT>, query?: Query<Item<II, TT>>): Promise<number>;
+    /**
+     * Get the items matching an optional query, logging the call and result.
+     *
+     * @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/DebugDBProvider/DebugDBProvider/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, logging each emission.
+     *
+     * @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/DebugDBProvider/DebugDBProvider/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 matching a query, logging the call.
+     *
+     * @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/DebugDBProvider/DebugDBProvider/setQuery
+     */
     setQuery<II extends I, TT extends T>(collection: Collection<string, II, TT>, query: Query<Item<II, TT>>, data: TT): Promise<void>;
+    /**
+     * Apply partial updates to every item matching a query, logging the call.
+     *
+     * @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/DebugDBProvider/DebugDBProvider/updateQuery
+     */
     updateQuery<II extends I, TT extends T>(collection: Collection<string, II, TT>, query: Query<Item<II, TT>>, updates: Updates<TT>): Promise<void>;
+    /**
+     * Delete every item matching a query, logging the call.
+     *
+     * @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/DebugDBProvider/DebugDBProvider/deleteQuery
+     */
     deleteQuery<II extends I, TT extends T>(collection: Collection<string, II, TT>, query: Query<Item<II, TT>>): Promise<void>;
 }

package/db/provider/DebugDBProvider.js

@@ -1,7 +1,27 @@
 import { ANSI_FAILURE, ANSI_LEFT, ANSI_RIGHT, ANSI_SUCCESS } from "../../util/ansi.js";
 import { ThroughDBProvider } from "./ThroughDBProvider.js";
-/** Provider that logs operations to the console. */
+/**
+ * Database provider that logs every operation it performs to the console for debugging.
+ *
+ * - Wraps a `source` provider and writes `console.debug` lines (with ANSI direction markers) before and after each call, and `console.error` on failure.
+ * - Drop it into a provider chain while developing to trace database reads and writes; it changes no data.
+ *
+ * @example
+ *  const provider = new DebugDBProvider(new MemoryDBProvider());
+ *  await provider.getItem(users, 123); // Logs the call and its result.
+ *
+ * @see https://dhoulb.github.io/shelving/db/provider/DebugDBProvider/DebugDBProvider
+ */
 export class DebugDBProvider extends ThroughDBProvider {
+    /**
+     * Get an item by its id, logging the call and result.
+     *
+     * @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/DebugDBProvider/DebugDBProvider/getItem
+     */
     async getItem(collection, id) {
         try {
             console.debug(`${ANSI_RIGHT} GET ITEM`, collection.name, id);
@@ -14,6 +34,15 @@ export class DebugDBProvider extends ThroughDBProvider {
             throw reason;
         }
     }
+    /**
+     * Subscribe to live changes for a single item, logging each emission.
+     *
+     * @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/DebugDBProvider/DebugDBProvider/getItemSequence
+     */
     async *getItemSequence(collection, id) {
         try {
             console.debug(`${ANSI_RIGHT} SEQUENCE ITEM`, collection.name, id);
@@ -27,6 +56,15 @@ export class DebugDBProvider extends ThroughDBProvider {
             console.error(`${ANSI_FAILURE} SEQUENCE ITEM`, collection.name, id, thrown);
         }
     }
+    /**
+     * Add a new item, logging the call and generated id.
+     *
+     * @param collection Collection to add the item to.
+     * @param data Data for the new item.
+     * @returns The generated identifier for the new item.
+     * @example await provider.addItem(users, { name: "Dave" }) // 123
+     * @see https://dhoulb.github.io/shelving/db/provider/DebugDBProvider/DebugDBProvider/addItem
+     */
     async addItem(collection, data) {
         try {
             console.debug(`${ANSI_RIGHT} ADD ITEM`, collection.name, data);
@@ -39,6 +77,15 @@ export class DebugDBProvider extends ThroughDBProvider {
             throw reason;
         }
     }
+    /**
+     * Set (insert or overwrite) an item by its id, logging the call.
+     *
+     * @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/DebugDBProvider/DebugDBProvider/setItem
+     */
     async setItem(collection, id, data) {
         try {
             console.debug(`${ANSI_RIGHT} SET ITEM`, collection.name, id, data);
@@ -50,6 +97,15 @@ export class DebugDBProvider extends ThroughDBProvider {
             throw reason;
         }
     }
+    /**
+     * Apply partial updates to an item by its id, logging the call.
+     *
+     * @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/DebugDBProvider/DebugDBProvider/updateItem
+     */
     async updateItem(collection, id, updates) {
         try {
             console.debug(`${ANSI_RIGHT} UPDATE ITEM`, collection.name, id, updates);
@@ -61,6 +117,14 @@ export class DebugDBProvider extends ThroughDBProvider {
             throw reason;
         }
     }
+    /**
+     * Delete an item by its id, logging the call.
+     *
+     * @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/DebugDBProvider/DebugDBProvider/deleteItem
+     */
     async deleteItem(collection, id) {
         try {
             console.debug(`${ANSI_RIGHT} DELETE`, collection.name, id);
@@ -72,6 +136,15 @@ export class DebugDBProvider extends ThroughDBProvider {
             throw reason;
         }
     }
+    /**
+     * Count the items matching an optional query, logging the call and result.
+     *
+     * @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/DebugDBProvider/DebugDBProvider/countQuery
+     */
     async countQuery(collection, query) {
         try {
             console.debug(`${ANSI_RIGHT} COUNT QUERY`, collection.name, query);
@@ -84,6 +157,15 @@ export class DebugDBProvider extends ThroughDBProvider {
             throw reason;
         }
     }
+    /**
+     * Get the items matching an optional query, logging the call and result.
+     *
+     * @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/DebugDBProvider/DebugDBProvider/getQuery
+     */
     async getQuery(collection, query) {
         try {
             console.debug(`${ANSI_RIGHT} GET`, collection.name, query);
@@ -96,6 +178,15 @@ export class DebugDBProvider extends ThroughDBProvider {
             throw reason;
         }
     }
+    /**
+     * Subscribe to live changes for a query, logging each emission.
+     *
+     * @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/DebugDBProvider/DebugDBProvider/getQuerySequence
+     */
     async *getQuerySequence(collection, query) {
         try {
             console.debug(`${ANSI_RIGHT} SEQUENCE QUERY`, collection.name, query);
@@ -109,6 +200,15 @@ export class DebugDBProvider extends ThroughDBProvider {
             console.error(`${ANSI_FAILURE} SEQUENCE QUERY`, collection.name, query, thrown);
         }
     }
+    /**
+     * Set (overwrite) every item matching a query, logging the call.
+     *
+     * @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/DebugDBProvider/DebugDBProvider/setQuery
+     */
     async setQuery(collection, query, data) {
         try {
             console.debug(`${ANSI_RIGHT} SET QUERY`, collection.name, query, data);
@@ -120,6 +220,15 @@ export class DebugDBProvider extends ThroughDBProvider {
             throw reason;
         }
     }
+    /**
+     * Apply partial updates to every item matching a query, logging the call.
+     *
+     * @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/DebugDBProvider/DebugDBProvider/updateQuery
+     */
     async updateQuery(collection, query, updates) {
         try {
             console.debug(`${ANSI_RIGHT} UPDATE QUERY`, collection.name, query, updates);
@@ -131,6 +240,14 @@ export class DebugDBProvider extends ThroughDBProvider {
             throw reason;
         }
     }
+    /**
+     * Delete every item matching a query, logging the call.
+     *
+     * @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/DebugDBProvider/DebugDBProvider/deleteQuery
+     */
     async deleteQuery(collection, query) {
         try {
             console.debug(`${ANSI_RIGHT} DELETE QUERY`, collection.name, query);

package/db/provider/MemoryDBProvider.d.ts

@@ -6,60 +6,315 @@ import type { Updates } from "../../util/update.js";
 import type { Collection } from "../collection/Collection.js";
 import { DBProvider } from "./DBProvider.js";
 /**
- * Fast in-memory store for data.
- * - Extremely fast (ideal for caching!), but does not persist data after the browser window is closed.
- * - `getItem()` etc return the exact same instance of an object that's passed into `setItem()`
+ * Synchronous in-memory database provider, storing each collection in a `MemoryTable`.
+ *
+ * - Extremely fast (ideal as the cache behind `CacheDBProvider`!), but does not persist data after the process or browser window closes.
+ * - Identity-preserving: `getItem()` etc. return the exact same object instance that was passed into `setItem()`.
+ * - Supports live subscriptions, so it can back `ItemStore` / `QueryStore` reads.
+ *
+ * @example
+ *  const provider = new MemoryDBProvider();
+ *  const id = await provider.addItem(users, { name: "Dave" });
+ *
+ * @see https://dhoulb.github.io/shelving/db/provider/MemoryDBProvider/MemoryDBProvider
  */
 export declare class MemoryDBProvider<I extends Identifier = Identifier, T extends Data = Data> extends DBProvider<I, T> {
     /** List of tables in `{ name: MemoryTable }` format. */
     private _tables;
-    /** Get a table for a collection. */
+    /**
+     * Get (or lazily create) the `MemoryTable` backing a collection.
+     *
+     * @param collection Collection to get the table for.
+     * @returns The `MemoryTable` holding that collection's items.
+     * @example provider.getTable(users) // MemoryTable
+     * @see https://dhoulb.github.io/shelving/db/provider/MemoryDBProvider/MemoryDBProvider/getTable
+     */
     getTable<II extends I, TT extends T>(collection: Collection<string, II, TT>): MemoryTable<II, TT>;
+    /**
+     * Get an item from its collection's table by id, or `undefined` if it doesn't exist.
+     *
+     * @param collection Collection the item belongs to.
+     * @param id Identifier of the item to get.
+     * @returns The item, or `undefined` if no item exists with that id.
+     * @example await provider.getItem(users, 123) // Item or undefined.
+     * @see https://dhoulb.github.io/shelving/db/provider/MemoryDBProvider/MemoryDBProvider/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 by its id.
+     *
+     * @param collection Collection the item belongs to.
+     * @param id Identifier of the item to subscribe to.
+     * @returns Async sequence yielding the item (or `undefined`) on every change.
+     * @example for await (const item of provider.getItemSequence(users, 123)) console.log(item);
+     * @see https://dhoulb.github.io/shelving/db/provider/MemoryDBProvider/MemoryDBProvider/getItemSequence
+     */
     getItemSequence<II extends I, TT extends T>(collection: Collection<string, II, TT>, id: II): OptionalItemSequence<II, TT>;
+    /**
+     * Add a new item to a collection and return its generated id.
+     *
+     * @param collection Collection to add the item to.
+     * @param data Data for the new item.
+     * @returns The generated identifier for the new item.
+     * @example await provider.addItem(users, { name: "Dave" }) // 123
+     * @see https://dhoulb.github.io/shelving/db/provider/MemoryDBProvider/MemoryDBProvider/addItem
+     */
     addItem<II extends I, TT extends T>(collection: Collection<string, II, TT>, data: TT): Promise<II>;
+    /**
+     * Set (insert or overwrite) the data for an item by its id.
+     *
+     * @param collection Collection the item belongs to.
+     * @param id Identifier of the item to set.
+     * @param data Full data to store for the item.
+     * @example await provider.setItem(users, 123, { name: "Dave" });
+     * @see https://dhoulb.github.io/shelving/db/provider/MemoryDBProvider/MemoryDBProvider/setItem
+     */
     setItem<II extends I, TT extends T>(collection: Collection<string, II, TT>, id: II, data: TT): Promise<void>;
+    /**
+     * Apply partial updates to an existing item by its id.
+     *
+     * @param collection Collection the item belongs to.
+     * @param id Identifier of the item to update.
+     * @param updates Updates to apply to the item.
+     * @example await provider.updateItem(users, 123, { name: "Dave" });
+     * @see https://dhoulb.github.io/shelving/db/provider/MemoryDBProvider/MemoryDBProvider/updateItem
+     */
     updateItem<II extends I, TT extends T>(collection: Collection<string, II, TT>, id: II, updates: Updates<Item<II, TT>>): Promise<void>;
+    /**
+     * Delete an item from a collection by its id.
+     *
+     * @param collection Collection the item belongs to.
+     * @param id Identifier of the item to delete.
+     * @example await provider.deleteItem(users, 123);
+     * @see https://dhoulb.github.io/shelving/db/provider/MemoryDBProvider/MemoryDBProvider/deleteItem
+     */
     deleteItem<II extends I, TT extends T>(collection: Collection<string, II, TT>, id: II): Promise<void>;
+    /**
+     * Count the items in a collection matching an optional query.
+     *
+     * @param collection Collection to count items in.
+     * @param query Query to filter the counted items (counts all items when omitted).
+     * @returns The number of matching items.
+     * @example await provider.countQuery(users, { age: 40 }) // 7
+     * @see https://dhoulb.github.io/shelving/db/provider/MemoryDBProvider/MemoryDBProvider/countQuery
+     */
     countQuery<II extends I, TT extends T>(collection: Collection<string, II, TT>, query?: Query<Item<II, TT>>): Promise<number>;
+    /**
+     * Get the items in a collection matching an optional query.
+     *
+     * @param collection Collection to query.
+     * @param query Query to filter, sort, and limit the items (returns all items when omitted).
+     * @returns An array of matching items.
+     * @example await provider.getQuery(users, { age: 40, $order: "name" }) // Items.
+     * @see https://dhoulb.github.io/shelving/db/provider/MemoryDBProvider/MemoryDBProvider/getQuery
+     */
     getQuery<II extends I, TT extends T>(collection: Collection<string, II, TT>, query?: Query<Item<II, TT>>): Promise<Items<II, TT>>;
+    /**
+     * Subscribe to live changes for the result of a query.
+     *
+     * @param collection Collection to query.
+     * @param query Query to filter, sort, and limit the items.
+     * @returns Async sequence yielding the matching items on every change.
+     * @example for await (const items of provider.getQuerySequence(users, { age: 40 })) console.log(items);
+     * @see https://dhoulb.github.io/shelving/db/provider/MemoryDBProvider/MemoryDBProvider/getQuerySequence
+     */
     getQuerySequence<II extends I, TT extends T>(collection: Collection<string, II, TT>, query?: Query<Item<II, TT>>): ItemsSequence<II, TT>;
+    /**
+     * Set (overwrite) the data for every item matching a query.
+     *
+     * @param collection Collection to write to.
+     * @param query Query selecting the items to set.
+     * @param data Full data to store for each matching item.
+     * @example await provider.setQuery(users, { age: 40 }, { active: true });
+     * @see https://dhoulb.github.io/shelving/db/provider/MemoryDBProvider/MemoryDBProvider/setQuery
+     */
     setQuery<II extends I, TT extends T>(collection: Collection<string, II, TT>, query: Query<Item<II, TT>>, data: TT): Promise<void>;
+    /**
+     * Apply partial updates to every item matching a query.
+     *
+     * @param collection Collection to write to.
+     * @param query Query selecting the items to update.
+     * @param updates Updates to apply to each matching item.
+     * @example await provider.updateQuery(users, { age: 40 }, { active: true });
+     * @see https://dhoulb.github.io/shelving/db/provider/MemoryDBProvider/MemoryDBProvider/updateQuery
+     */
     updateQuery<II extends I, TT extends T>(collection: Collection<string, II, TT>, query: Query<Item<II, TT>>, updates: Updates<TT>): Promise<void>;
+    /**
+     * Delete every item matching a query.
+     *
+     * @param collection Collection to delete from.
+     * @param query Query selecting the items to delete.
+     * @example await provider.deleteQuery(users, { active: false });
+     * @see https://dhoulb.github.io/shelving/db/provider/MemoryDBProvider/MemoryDBProvider/deleteQuery
+     */
     deleteQuery<II extends I, TT extends T>(collection: Collection<string, II, TT>, query: Query<Item<II, TT>>): Promise<void>;
+    /**
+     * Set (insert or overwrite) several whole items in a collection at once.
+     *
+     * @param collection Collection to write to.
+     * @param items Items (each with its own id) to store.
+     * @example provider.setItems(users, [{ id: 123, name: "Dave" }]);
+     * @see https://dhoulb.github.io/shelving/db/provider/MemoryDBProvider/MemoryDBProvider/setItems
+     */
     setItems<II extends I, TT extends T>(collection: Collection<string, II, TT>, items: Items<II, TT>): void;
 }
-/** An individual table of data. */
+/**
+ * In-memory table holding the items of a single collection for a `MemoryDBProvider`.
+ *
+ * - Keys items by id in a `Map`, preserving the exact object instance passed in.
+ * - Exposes a `next` `DeferredSequence` that resolves on every change, powering the live `*Sequence` subscriptions.
+ *
+ * @example
+ *  const table = provider.getTable(users);
+ *  table.setItem(123, { name: "Dave" });
+ *
+ * @see https://dhoulb.github.io/shelving/db/provider/MemoryDBProvider/MemoryTable
+ */
 export declare class MemoryTable<I extends Identifier, T extends Data> {
     /** Actual data in this table. */
     protected readonly _data: Map<I, Item<I, T>>;
-    /** Deferred sequence of next values. */
+    /**
+     * Deferred sequence that resolves on every change to this table.
+     *
+     * @see https://dhoulb.github.io/shelving/db/provider/MemoryDBProvider/MemoryTable/next
+     */
     readonly next: DeferredSequence<void, void, void>;
+    /**
+     * Collection this table stores the items of.
+     *
+     * @see https://dhoulb.github.io/shelving/db/provider/MemoryDBProvider/MemoryTable/collection
+     */
     readonly collection: Collection<string, I, T>;
+    /**
+     * Create a new `MemoryTable` for a collection.
+     *
+     * @param collection Collection this table holds the items of.
+     */
     constructor(collection: Collection<string, I, T>);
+    /**
+     * Get an item by its id, or `undefined` if it doesn't exist.
+     *
+     * @param id Identifier of the item to get.
+     * @returns The item, or `undefined` if no item exists with that id.
+     * @example table.getItem(123) // Item or undefined.
+     * @see https://dhoulb.github.io/shelving/db/provider/MemoryDBProvider/MemoryTable/getItem
+     */
     getItem(id: I): OptionalItem<I, T>;
     /**
      * Subscribe to all changes for this item key.
      * - Emits the current item immediately, including `undefined` when absent.
      * - Wakes on every table change, but only yields when this item's value actually changed.
+     *
+     * @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 table.getItemSequence(123)) console.log(item);
+     * @see https://dhoulb.github.io/shelving/db/provider/MemoryDBProvider/MemoryTable/getItemSequence
      */
     getItemSequence(id: I): AsyncIterable<OptionalItem<I, T>>;
-    /** Generate a unique ID for a new item in this table. */
+    /**
+     * Generate a unique id for a new item in this table.
+     * - Uses a random string for `StringSchema` ids, otherwise a random number, regenerating until it doesn't collide.
+     *
+     * @returns An id that no existing item in this table uses.
+     * @example table.generateUniqueID() // 4827193 (or a random string)
+     * @see https://dhoulb.github.io/shelving/db/provider/MemoryDBProvider/MemoryTable/generateUniqueID
+     */
     generateUniqueID(): I;
+    /**
+     * Add a new item with a freshly generated unique id.
+     *
+     * @param data Data for the new item.
+     * @returns The generated identifier for the new item.
+     * @example table.addItem({ name: "Dave" }) // 123
+     * @see https://dhoulb.github.io/shelving/db/provider/MemoryDBProvider/MemoryTable/addItem
+     */
     addItem(data: T): I;
+    /**
+     * Set (insert or overwrite) an item by its id.
+     * - Only resolves `next` when the stored instance actually changes.
+     *
+     * @param id Identifier of the item to set.
+     * @param data Full item, or data to combine with `id` into an item.
+     * @example table.setItem(123, { name: "Dave" });
+     * @see https://dhoulb.github.io/shelving/db/provider/MemoryDBProvider/MemoryTable/setItem
+     */
     setItem(id: I, data: Item<I, T> | T): void;
+    /**
+     * Mirror an async sequence of item values into this table, passing each value through.
+     * - Sets the item when a value arrives, or deletes it when the value is `undefined`.
+     *
+     * @param id Identifier of the item the sequence applies to.
+     * @param sequence Source sequence of item values (or `undefined`) to mirror.
+     * @returns Async sequence yielding each value after it has been mirrored.
+     * @example for await (const item of table.setItemSequence(123, source)) console.log(item);
+     * @see https://dhoulb.github.io/shelving/db/provider/MemoryDBProvider/MemoryTable/setItemSequence
+     */
     setItemSequence(id: I, sequence: AsyncIterable<OptionalItem<I, T>>): AsyncIterable<OptionalItem<I, T>>;
+    /**
+     * Apply partial updates to an existing item by its id.
+     * - Does nothing if no item exists with that id.
+     *
+     * @param id Identifier of the item to update.
+     * @param updates Updates to apply to the item.
+     * @example table.updateItem(123, { name: "Dave" });
+     * @see https://dhoulb.github.io/shelving/db/provider/MemoryDBProvider/MemoryTable/updateItem
+     */
     updateItem(id: I, updates: Updates<Item<I, T>>): void;
+    /**
+     * Delete an item by its id.
+     * - Only resolves `next` when an item was actually removed.
+     *
+     * @param id Identifier of the item to delete.
+     * @example table.deleteItem(123);
+     * @see https://dhoulb.github.io/shelving/db/provider/MemoryDBProvider/MemoryTable/deleteItem
+     */
     deleteItem(id: I): void;
+    /**
+     * Count the items in this table matching an optional query.
+     *
+     * @param query Query to filter the counted items (counts all items when omitted).
+     * @returns The number of matching items.
+     * @example table.countQuery({ age: 40 }) // 7
+     * @see https://dhoulb.github.io/shelving/db/provider/MemoryDBProvider/MemoryTable/countQuery
+     */
     countQuery(query?: Query<Item<I, T>>): number;
+    /**
+     * Get the items in this table matching an optional query.
+     *
+     * @param query Query to filter, sort, and limit the items (returns all items when omitted).
+     * @returns An array of matching items.
+     * @example table.getQuery({ age: 40, $order: "name" }) // Items.
+     * @see https://dhoulb.github.io/shelving/db/provider/MemoryDBProvider/MemoryTable/getQuery
+     */
     getQuery(query?: Query<Item<I, T>>): Items<I, T>;
     /**
      * Subscribe to the live result of a query.
      * - Emits the current query result immediately, even if empty.
      * - Wakes on every table change, but only yields when the computed query result changed.
+     *
+     * @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 table.getQuerySequence({ age: 40 })) console.log(items);
+     * @see https://dhoulb.github.io/shelving/db/provider/MemoryDBProvider/MemoryTable/getQuerySequence
      */
     getQuerySequence(query?: Query<Item<I, T>>): AsyncIterable<Items<I, T>>;
+    /**
+     * Set (overwrite) the data for every item matching a query.
+     *
+     * @param query Query selecting the items to set.
+     * @param data Full data to store for each matching item.
+     * @example table.setQuery({ age: 40 }, { active: true });
+     * @see https://dhoulb.github.io/shelving/db/provider/MemoryDBProvider/MemoryTable/setQuery
+     */
     setQuery(query: Query<Item<I, T>>, data: T): void;
+    /**
+     * Apply partial updates to every item matching a query.
+     *
+     * @param query Query selecting the items to update.
+     * @param updates Updates to apply to each matching item.
+     * @example table.updateQuery({ age: 40 }, { active: true });
+     * @see https://dhoulb.github.io/shelving/db/provider/MemoryDBProvider/MemoryTable/updateQuery
+     */
     updateQuery(query: Query<Item<I, T>>, updates: Updates<T>): void;
     deleteQuery(query: Query<Item<I, T>>): void;
     setItems(items: Items<I, T>): void;