shelving 1.236.0 → 1.236.2

package/db/provider/MemoryDBProvider.js

@@ -9,67 +9,229 @@ import { getRandom, getRandomKey } from "../../util/random.js";
 import { updateData } from "../../util/update.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 class MemoryDBProvider extends DBProvider {
     /** List of tables in `{ name: MemoryTable }` format. */
     _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(collection) {
         return (this._tables[collection.name] ||= new MemoryTable(collection));
     }
+    /**
+     * 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
+     */
     async getItem(collection, id) {
         return this.getTable(collection).getItem(id);
     }
+    /**
+     * Subscribe to live changes for a single item by its id.
+     *
+     * @param collection Collection the item belongs to.
+     * @param id Identifier of the item to subscribe to.
+     * @returns Async sequence yielding the item (or `undefined`) on every change.
+     * @example for await (const item of provider.getItemSequence(users, 123)) console.log(item);
+     * @see https://dhoulb.github.io/shelving/db/provider/MemoryDBProvider/MemoryDBProvider/getItemSequence
+     */
     async *getItemSequence(collection, id) {
         yield* this.getTable(collection).getItemSequence(id);
     }
+    /**
+     * Add a new item to a collection and return its generated id.
+     *
+     * @param collection Collection to add the item to.
+     * @param data Data for the new item.
+     * @returns The generated identifier for the new item.
+     * @example await provider.addItem(users, { name: "Dave" }) // 123
+     * @see https://dhoulb.github.io/shelving/db/provider/MemoryDBProvider/MemoryDBProvider/addItem
+     */
     async addItem(collection, data) {
         return this.getTable(collection).addItem(data);
     }
+    /**
+     * Set (insert or overwrite) the data for an item by its id.
+     *
+     * @param collection Collection the item belongs to.
+     * @param id Identifier of the item to set.
+     * @param data Full data to store for the item.
+     * @example await provider.setItem(users, 123, { name: "Dave" });
+     * @see https://dhoulb.github.io/shelving/db/provider/MemoryDBProvider/MemoryDBProvider/setItem
+     */
     async setItem(collection, id, data) {
         this.getTable(collection).setItem(id, data);
     }
+    /**
+     * Apply partial updates to an existing item by its id.
+     *
+     * @param collection Collection the item belongs to.
+     * @param id Identifier of the item to update.
+     * @param updates Updates to apply to the item.
+     * @example await provider.updateItem(users, 123, { name: "Dave" });
+     * @see https://dhoulb.github.io/shelving/db/provider/MemoryDBProvider/MemoryDBProvider/updateItem
+     */
     async updateItem(collection, id, updates) {
         this.getTable(collection).updateItem(id, updates);
     }
+    /**
+     * Delete an item from a collection by its id.
+     *
+     * @param collection Collection the item belongs to.
+     * @param id Identifier of the item to delete.
+     * @example await provider.deleteItem(users, 123);
+     * @see https://dhoulb.github.io/shelving/db/provider/MemoryDBProvider/MemoryDBProvider/deleteItem
+     */
     async deleteItem(collection, id) {
         this.getTable(collection).deleteItem(id);
     }
+    /**
+     * Count the items in a collection matching an optional query.
+     *
+     * @param collection Collection to count items in.
+     * @param query Query to filter the counted items (counts all items when omitted).
+     * @returns The number of matching items.
+     * @example await provider.countQuery(users, { age: 40 }) // 7
+     * @see https://dhoulb.github.io/shelving/db/provider/MemoryDBProvider/MemoryDBProvider/countQuery
+     */
     async countQuery(collection, query) {
         return this.getTable(collection).countQuery(query);
     }
+    /**
+     * Get the items in a collection matching an optional query.
+     *
+     * @param collection Collection to query.
+     * @param query Query to filter, sort, and limit the items (returns all items when omitted).
+     * @returns An array of matching items.
+     * @example await provider.getQuery(users, { age: 40, $order: "name" }) // Items.
+     * @see https://dhoulb.github.io/shelving/db/provider/MemoryDBProvider/MemoryDBProvider/getQuery
+     */
     async getQuery(collection, query) {
         return this.getTable(collection).getQuery(query);
     }
+    /**
+     * Subscribe to live changes for the result of a query.
+     *
+     * @param collection Collection to query.
+     * @param query Query to filter, sort, and limit the items.
+     * @returns Async sequence yielding the matching items on every change.
+     * @example for await (const items of provider.getQuerySequence(users, { age: 40 })) console.log(items);
+     * @see https://dhoulb.github.io/shelving/db/provider/MemoryDBProvider/MemoryDBProvider/getQuerySequence
+     */
     async *getQuerySequence(collection, query) {
         return yield* this.getTable(collection).getQuerySequence(query);
     }
+    /**
+     * Set (overwrite) the data for every item matching a query.
+     *
+     * @param collection Collection to write to.
+     * @param query Query selecting the items to set.
+     * @param data Full data to store for each matching item.
+     * @example await provider.setQuery(users, { age: 40 }, { active: true });
+     * @see https://dhoulb.github.io/shelving/db/provider/MemoryDBProvider/MemoryDBProvider/setQuery
+     */
     async setQuery(collection, query, data) {
         this.getTable(collection).setQuery(query, data);
     }
+    /**
+     * Apply partial updates to every item matching a query.
+     *
+     * @param collection Collection to write to.
+     * @param query Query selecting the items to update.
+     * @param updates Updates to apply to each matching item.
+     * @example await provider.updateQuery(users, { age: 40 }, { active: true });
+     * @see https://dhoulb.github.io/shelving/db/provider/MemoryDBProvider/MemoryDBProvider/updateQuery
+     */
     async updateQuery(collection, query, updates) {
         this.getTable(collection).updateQuery(query, updates);
     }
+    /**
+     * Delete every item matching a query.
+     *
+     * @param collection Collection to delete from.
+     * @param query Query selecting the items to delete.
+     * @example await provider.deleteQuery(users, { active: false });
+     * @see https://dhoulb.github.io/shelving/db/provider/MemoryDBProvider/MemoryDBProvider/deleteQuery
+     */
     async deleteQuery(collection, query) {
         this.getTable(collection).deleteQuery(query);
     }
+    /**
+     * 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(collection, items) {
         this.getTable(collection).setItems(items);
     }
 }
-/** 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 class MemoryTable {
     /** Actual data in this table. */
     _data = new Map();
-    /** 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
+     */
     next = new DeferredSequence();
+    /**
+     * Collection this table stores the items of.
+     *
+     * @see https://dhoulb.github.io/shelving/db/provider/MemoryDBProvider/MemoryTable/collection
+     */
     collection;
+    /**
+     * Create a new `MemoryTable` for a collection.
+     *
+     * @param collection Collection this table holds the items of.
+     */
     constructor(collection) {
         this.collection = collection;
     }
+    /**
+     * 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) {
         return this._data.get(id);
     }
@@ -77,6 +239,11 @@ export class MemoryTable {
      * 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
      */
     async *getItemSequence(id) {
         let lastValue = this.getItem(id);
@@ -90,7 +257,14 @@ export class MemoryTable {
             }
         }
     }
-    /** 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() {
         const gen = (this.collection.id instanceof StringSchema ? getRandomKey : getRandom);
         let id = gen();
@@ -98,11 +272,28 @@ export class MemoryTable {
             id = gen(); // Regenerate ID until unique.
         return id;
     }
+    /**
+     * 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) {
         const id = this.generateUniqueID();
         this.setItem(id, data);
         return id;
     }
+    /**
+     * 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, data) {
         const item = getItem(id, data);
         if (this._data.get(id) !== item) {
@@ -110,12 +301,31 @@ export class MemoryTable {
             this.next.resolve();
         }
     }
+    /**
+     * 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
+     */
     async *setItemSequence(id, sequence) {
         for await (const item of sequence) {
             item ? this.setItem(id, item) : this.deleteItem(id);
             yield item;
         }
     }
+    /**
+     * 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, updates) {
         const oldItem = this._data.get(id);
         if (!oldItem)
@@ -126,15 +336,39 @@ export class MemoryTable {
             this.next.resolve();
         }
     }
+    /**
+     * 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) {
         if (this._data.has(id)) {
             this._data.delete(id);
             this.next.resolve();
         }
     }
+    /**
+     * 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) {
         return query ? countItems(queryItems(this._data.values(), query)) : this._data.size;
     }
+    /**
+     * 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) {
         return requireArray(query ? queryItems(this._data.values(), query) : this._data.values());
     }
@@ -142,6 +376,11 @@ export class MemoryTable {
      * 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
      */
     async *getQuerySequence(query) {
         let lastItems = this.getQuery(query);
@@ -155,6 +394,14 @@ export class MemoryTable {
             }
         }
     }
+    /**
+     * 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, data) {
         let changed = false;
         for (const { id } of queryWritableItems(this._data.values(), query)) {
@@ -167,6 +414,14 @@ export class MemoryTable {
         if (changed)
             this.next.resolve();
     }
+    /**
+     * 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, updates) {
         let changed = false;
         for (const { id } of queryWritableItems(this._data.values(), query)) {

package/db/provider/MockDBProvider.d.ts

@@ -4,7 +4,13 @@ import type { Query } from "../../util/query.js";
 import type { Updates } from "../../util/update.js";
 import type { Collection } from "../collection/Collection.js";
 import { MemoryDBProvider } from "./MemoryDBProvider.js";
-/** A structured log entry emitted by `MockDBProvider` for one of its provider operations. */
+/**
+ * Structured log entry recording one operation performed through a `MockDBProvider`.
+ *
+ * - `type` is the operation name; `collection` is the collection name; `id`, `query`, `data`, `updates`, and `result` carry whichever fields apply to that operation.
+ *
+ * @see https://dhoulb.github.io/shelving/db/provider/MockDBProvider/MockDBCall
+ */
 export type MockDBCall = {
     readonly type: "getItem" | "addItem" | "setItem" | "updateItem" | "deleteItem" | "countQuery" | "getQuery" | "setQuery" | "updateQuery" | "deleteQuery";
     readonly collection: string;
@@ -14,17 +20,122 @@ export type MockDBCall = {
     readonly updates?: unknown;
     readonly result?: unknown;
 };
-/** Provider that logs database operations for testing purposes. */
+/**
+ * In-memory database provider that records every operation to its `calls` log, for testing.
+ *
+ * - Extends `MemoryDBProvider`, so it stores data normally, then appends a `MockDBCall` entry (including the result) for each call.
+ * - Assert against `calls` in tests to check which operations ran and with what arguments.
+ *
+ * @example
+ *  const provider = new MockDBProvider();
+ *  await provider.addItem(users, { name: "Dave" });
+ *  provider.calls; // [{ type: "addItem", collection: "users", data: { name: "Dave" }, result: 123 }]
+ *
+ * @see https://dhoulb.github.io/shelving/db/provider/MockDBProvider/MockDBProvider
+ */
 export declare class MockDBProvider<I extends Identifier = Identifier, T extends Data = Data> extends MemoryDBProvider<I, T> {
+    /**
+     * The log of operations performed through this provider, in the order they happened.
+     *
+     * @see https://dhoulb.github.io/shelving/db/provider/MockDBProvider/MockDBProvider/calls
+     */
     readonly calls: MockDBCall[];
+    /**
+     * Get an item by its id, then record a `"getItem"` call.
+     *
+     * @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/MockDBProvider/MockDBProvider/getItem
+     */
     getItem<II extends I, TT extends T>(collection: Collection<string, II, TT>, id: II): Promise<OptionalItem<II, TT>>;
+    /**
+     * Add a new item, then record an `"addItem"` call.
+     *
+     * @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/MockDBProvider/MockDBProvider/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, then record a `"setItem"` 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/MockDBProvider/MockDBProvider/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, then record an `"updateItem"` 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/MockDBProvider/MockDBProvider/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, then record a `"deleteItem"` 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/MockDBProvider/MockDBProvider/deleteItem
+     */
     deleteItem<II extends I, TT extends T>(collection: Collection<string, II, TT>, id: II): Promise<void>;
+    /**
+     * Count the items matching an optional query, then record a `"countQuery"` call.
+     *
+     * @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/MockDBProvider/MockDBProvider/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, then record a `"getQuery"` call.
+     *
+     * @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/MockDBProvider/MockDBProvider/getQuery
+     */
     getQuery<II extends I, TT extends T>(collection: Collection<string, II, TT>, query?: Query<Item<II, TT>>): Promise<Items<II, TT>>;
+    /**
+     * Set (overwrite) every item matching a query, then record a `"setQuery"` 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/MockDBProvider/MockDBProvider/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, then record an `"updateQuery"` 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/MockDBProvider/MockDBProvider/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, then record a `"deleteQuery"` 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/MockDBProvider/MockDBProvider/deleteQuery
+     */
     deleteQuery<II extends I, TT extends T>(collection: Collection<string, II, TT>, query: Query<Item<II, TT>>): Promise<void>;
 }