shelving 1.236.0 → 1.236.2

package/db/provider/SQLProvider.js

@@ -3,8 +3,28 @@ import { UnimplementedError } from "../../error/UnimplementedError.js";
 import { getQueryFilters, getQueryLimit, getQueryOrders } from "../../util/query.js";
 import { getUpdates } from "../../util/update.js";
 import { DBProvider } from "./DBProvider.js";
-/** Shared SQL execution and CRUD/query behavior. */
+/**
+ * Abstract database provider that implements CRUD and query operations by generating and executing SQL.
+ *
+ * - Subclasses implement `exec()` to run a query against a concrete database (e.g. SQLite, PostgreSQL).
+ * - The `sql*` helpers build composable `SQLFragment` objects so dialect differences can be overridden.
+ * - Realtime subscriptions are unsupported and throw `UnimplementedError`.
+ *
+ * @example
+ *  class MyProvider extends SQLProvider { async exec(strings, ...values) { ... } }
+ *  const item = await new MyProvider().getItem(collection, "abc");
+ * @see https://dhoulb.github.io/shelving/db/provider/SQLProvider/SQLProvider
+ */
 export class SQLProvider extends DBProvider {
+    /**
+     * Get a single item by ID, or `undefined` if it doesn't exist.
+     *
+     * @param collection The collection to read from.
+     * @param id The ID of the item to get.
+     * @returns Promise resolving to the item, or `undefined` if it doesn't exist.
+     * @example await provider.getItem(collection, "abc")
+     * @see https://dhoulb.github.io/shelving/db/provider/SQLProvider/SQLProvider/getItem
+     */
     async getItem(collection, id) {
         const rows = await this.exec `
 			SELECT * FROM ${this.sqlIdentifier(collection.name)}
@@ -13,9 +33,29 @@ export class SQLProvider extends DBProvider {
 		`;
         return rows[0];
     }
+    /**
+     * Subscribe to realtime updates for a single item — unsupported by SQL providers.
+     *
+     * @param collection The collection to read from.
+     * @param id The ID of the item to subscribe to.
+     * @returns Never returns; always throws.
+     * @throws {UnimplementedError} Always, because SQL providers don't support realtime subscriptions.
+     * @example provider.getItemSequence(collection, "abc") // throws
+     * @see https://dhoulb.github.io/shelving/db/provider/SQLProvider/SQLProvider/getItemSequence
+     */
     getItemSequence(_collection, _id) {
         throw new UnimplementedError(`SQLProvider does not support realtime subscriptions`);
     }
+    /**
+     * Insert a new item and return its generated ID.
+     *
+     * @param collection The collection to insert into.
+     * @param data The data of the item to insert.
+     * @returns Promise resolving to the ID of the inserted item.
+     * @throws {RequiredError} If the `INSERT` didn't return an ID.
+     * @example await provider.addItem(collection, { name: "Dave" })
+     * @see https://dhoulb.github.io/shelving/db/provider/SQLProvider/SQLProvider/addItem
+     */
     async addItem(collection, data) {
         const rows = await this.exec `
 			INSERT INTO ${this.sqlIdentifier(collection.name)} ${this.sqlValues(data)}
@@ -26,12 +66,32 @@ export class SQLProvider extends DBProvider {
             throw new RequiredError(`No id returned from INSERT into "${collection.name}"`, { provider: this });
         return id;
     }
+    /**
+     * Set (insert or overwrite) an item at a specific ID.
+     *
+     * @param collection The collection to write to.
+     * @param id The ID of the item to set.
+     * @param data The full data to store for the item.
+     * @returns Promise that resolves once the item has been set.
+     * @example await provider.setItem(collection, "abc", { name: "Dave" })
+     * @see https://dhoulb.github.io/shelving/db/provider/SQLProvider/SQLProvider/setItem
+     */
     async setItem(collection, id, data) {
         await this.exec `
 			INSERT INTO ${this.sqlIdentifier(collection.name)} ${this.sqlValues({ id, ...data })}
 			ON CONFLICT (${this.sqlIdentifier("id")}) DO UPDATE SET ${this.sqlSetters(data)}
 		`;
     }
+    /**
+     * Apply a set of updates to a single item by ID.
+     *
+     * @param collection The collection to write to.
+     * @param id The ID of the item to update.
+     * @param updates The updates to apply.
+     * @returns Promise that resolves once the item has been updated.
+     * @example await provider.updateItem(collection, "abc", { name: "Dave" })
+     * @see https://dhoulb.github.io/shelving/db/provider/SQLProvider/SQLProvider/updateItem
+     */
     async updateItem(collection, id, updates) {
         await this.exec `
 			UPDATE ${this.sqlIdentifier(collection.name)}
@@ -39,9 +99,27 @@ export class SQLProvider extends DBProvider {
 			WHERE ${this.sqlIdentifier("id")} = ${id}
 		`;
     }
+    /**
+     * Delete a single item by ID.
+     *
+     * @param collection The collection to delete from.
+     * @param id The ID of the item to delete.
+     * @returns Promise that resolves once the item has been deleted.
+     * @example await provider.deleteItem(collection, "abc")
+     * @see https://dhoulb.github.io/shelving/db/provider/SQLProvider/SQLProvider/deleteItem
+     */
     async deleteItem(collection, id) {
         await this.exec `DELETE FROM ${this.sqlIdentifier(collection.name)} WHERE ${this.sqlIdentifier("id")} = ${id}`;
     }
+    /**
+     * Count the items in a collection that match an optional query.
+     *
+     * @param collection The collection to count.
+     * @param query Optional query to filter the items to count.
+     * @returns Promise resolving to the number of matching items.
+     * @example await provider.countQuery(collection, query)
+     * @see https://dhoulb.github.io/shelving/db/provider/SQLProvider/SQLProvider/countQuery
+     */
     async countQuery(collection, query) {
         const rows = await this.exec `
 			SELECT COUNT(*) AS "count" FROM ${this.sqlIdentifier(collection.name)}
@@ -49,52 +127,145 @@ export class SQLProvider extends DBProvider {
 		`;
         return rows[0]?.count ?? 0;
     }
+    /**
+     * Get the items in a collection that match an optional query.
+     *
+     * @param collection The collection to read from.
+     * @param query Optional query to filter, sort, and limit the items.
+     * @returns Promise resolving to the array of matching items.
+     * @example await provider.getQuery(collection, query)
+     * @see https://dhoulb.github.io/shelving/db/provider/SQLProvider/SQLProvider/getQuery
+     */
     async getQuery(collection, query) {
         return this.exec `
 			SELECT * FROM ${this.sqlIdentifier(collection.name)}
 			${query ? this.sqlClauses(query) : this.sql ``}
 		`;
     }
+    /**
+     * Subscribe to realtime updates for a query — unsupported by SQL providers.
+     *
+     * @param collection The collection to read from.
+     * @param query Optional query to subscribe to.
+     * @returns Never returns; always throws.
+     * @throws {UnimplementedError} Always, because SQL providers don't support realtime subscriptions.
+     * @example provider.getQuerySequence(collection, query) // throws
+     * @see https://dhoulb.github.io/shelving/db/provider/SQLProvider/SQLProvider/getQuerySequence
+     */
     getQuerySequence(_collection, _query) {
         throw new UnimplementedError(`SQLProvider does not support realtime subscriptions`);
     }
+    /**
+     * Set (overwrite) the data of every item matching a query.
+     *
+     * @param collection The collection to write to.
+     * @param query The query selecting the items to set.
+     * @param data The full data to store for each matching item.
+     * @returns Promise that resolves once the matching items have been set.
+     * @example await provider.setQuery(collection, query, { active: true })
+     * @see https://dhoulb.github.io/shelving/db/provider/SQLProvider/SQLProvider/setQuery
+     */
     async setQuery(collection, query, data) {
         await this.exec `UPDATE ${this.sqlIdentifier(collection.name)} SET ${this.sqlSetters(data)}${this.sqlClauses(query)}`;
     }
+    /**
+     * Apply a set of updates to every item matching a query.
+     *
+     * @param collection The collection to write to.
+     * @param query The query selecting the items to update.
+     * @param updates The updates to apply to each matching item.
+     * @returns Promise that resolves once the matching items have been updated.
+     * @example await provider.updateQuery(collection, query, { active: true })
+     * @see https://dhoulb.github.io/shelving/db/provider/SQLProvider/SQLProvider/updateQuery
+     */
     async updateQuery(collection, query, updates) {
         await this.exec `UPDATE ${this.sqlIdentifier(collection.name)} SET ${this.sqlUpdates(updates)}${this.sqlClauses(query)}`;
     }
+    /**
+     * Delete every item matching a query.
+     *
+     * @param collection The collection to delete from.
+     * @param query The query selecting the items to delete.
+     * @returns Promise that resolves once the matching items have been deleted.
+     * @example await provider.deleteQuery(collection, query)
+     * @see https://dhoulb.github.io/shelving/db/provider/SQLProvider/SQLProvider/deleteQuery
+     */
     async deleteQuery(collection, query) {
         await this.exec `DELETE FROM ${this.sqlIdentifier(collection.name)}${this.sqlClauses(query)}`;
     }
     /**
      * Define an SQL fragment using Javascript template literal format.
+     *
+     * @param strings The template string parts of the fragment.
+     * @param values The interpolated values to embed into the fragment.
+     * @returns The composed `SQLFragment`.
      * @example this.sql`SELECT * FROM ${table}`; // SQLFragment
+     * @see https://dhoulb.github.io/shelving/db/provider/SQLProvider/SQLProvider/sql
      */
     sql(strings, ...values) {
         return { strings, values };
     }
-    /** Define an SQL fragment for an identifier, e.g. `"myTable"` */
+    /**
+     * Define an SQL fragment for an escaped identifier, e.g. `"myTable"`.
+     *
+     * @param name The identifier (table or column name) to escape.
+     * @returns An `SQLFragment` containing the quoted identifier.
+     * @example this.sqlIdentifier("myTable"); // "myTable"
+     * @see https://dhoulb.github.io/shelving/db/provider/SQLProvider/SQLProvider/sqlIdentifier
+     */
     sqlIdentifier(name) {
         return { strings: [_escapeIdentifier(name)], values: [] };
     }
-    /** Define an SQL fragment that extracts a deeply nested value for comparison, e.g. `"a" #>> {"b","c"}` in Postgres */
+    /**
+     * Define an SQL fragment that extracts a value at a key for comparison, e.g. `"a" #>> {"b","c"}` in Postgres.
+     * - Base implementation only supports flat (single-segment) keys; subclasses override for nested JSON paths.
+     *
+     * @param key The key segments identifying the column (and any nested path).
+     * @returns An `SQLFragment` extracting the value.
+     * @throws {UnimplementedError} If the key is nested (multi-segment).
+     * @example this.sqlExtract(["name"]); // "name"
+     * @see https://dhoulb.github.io/shelving/db/provider/SQLProvider/SQLProvider/sqlExtract
+     */
     sqlExtract(key) {
         if (key.length > 1)
             throw new UnimplementedError("SQLProvider does not support nested filter keys");
         return this.sqlIdentifier(key[0]);
     }
-    /** Define an SQL fragment to generate a series of values with a separator, e.g. `"a" = 1 AND "b" = 2` */
+    /**
+     * Define an SQL fragment that joins a series of fragments with a separator, e.g. `"a" = 1 AND "b" = 2`.
+     *
+     * @param values The fragments to join.
+     * @param separator The separator placed between fragments.
+     * @param before Text placed before the first fragment.
+     * @param after Text placed after the last fragment.
+     * @returns The joined `SQLFragment`.
+     * @example this.sqlConcat([a, b], " AND "); // a AND b
+     * @see https://dhoulb.github.io/shelving/db/provider/SQLProvider/SQLProvider/sqlConcat
+     */
     sqlConcat(values, separator = ", ", before = "", after = "") {
         const strings = [before, ...new Array(Math.max(0, values.length - 1)).fill(separator), after];
         return { strings, values };
     }
-    /** Define an SQL fragment for setting a list of values, e.g. `"a" = 1, "b" = 2` */
+    /**
+     * Define an SQL fragment for setting a list of values, e.g. `"a" = 1, "b" = 2`.
+     *
+     * @param data The data whose entries become `column = value` assignments.
+     * @returns The composed `SQLFragment`.
+     * @example this.sqlSetters({ a: 1, b: 2 }); // "a" = 1, "b" = 2
+     * @see https://dhoulb.github.io/shelving/db/provider/SQLProvider/SQLProvider/sqlSetters
+     */
     sqlSetters(data) {
         const entries = Object.entries(data);
         return this.sqlConcat(entries.map(([key, value]) => this.sql `${this.sqlIdentifier(key)} = ${value}`), ", ");
     }
-    /** Define an SQL fragment for updates, e.g. `"a" = 1, "b" = "b" + 5` */
+    /**
+     * Define an SQL fragment for a set of updates, e.g. `"a" = 1, "b" = "b" + 5`.
+     *
+     * @param updates The updates to convert into SQL assignments.
+     * @returns The composed `SQLFragment`.
+     * @example this.sqlUpdates({ a: 1 }); // "a" = 1
+     * @see https://dhoulb.github.io/shelving/db/provider/SQLProvider/SQLProvider/sqlUpdates
+     */
     sqlUpdates(updates) {
         return this.sqlConcat(getUpdates(updates).map(update => this.sqlUpdate(update)), ", ");
     }
@@ -103,6 +274,12 @@ export class SQLProvider extends DBProvider {
      * - Handles flat `set` and `sum` only (single-segment key).
      * - Nested keys (multi-segment) and `with`/`omit` actions throw `UnimplementedError`.
      * - Subclasses should override to support nested keys and array mutation actions.
+     *
+     * @param update The update action (`action`, `key`, `value`) to convert.
+     * @returns The composed `SQLFragment`.
+     * @throws {UnimplementedError} If the key is nested or the action is unsupported.
+     * @example this.sqlUpdate({ action: "set", key: ["a"], value: 1 }); // "a" = 1
+     * @see https://dhoulb.github.io/shelving/db/provider/SQLProvider/SQLProvider/sqlUpdate
      */
     sqlUpdate({ action, key, value }) {
         if (key.length > 1)
@@ -114,18 +291,39 @@ export class SQLProvider extends DBProvider {
             return this.sql `${column} = ${column} + ${value}`;
         throw new UnimplementedError(`SQLProvider does not support "${action}" updates`);
     }
-    /** Define an SQL fragment for `VALUES` syntax, e.g. `("a", "b") VALUES (1, 2)` */
+    /**
+     * Define an SQL fragment for `VALUES` syntax, e.g. `("a", "b") VALUES (1, 2)`.
+     *
+     * @param data The data whose keys and values become the column list and values.
+     * @returns The composed `SQLFragment`.
+     * @example this.sqlValues({ a: 1, b: 2 }); // ("a", "b") VALUES (1, 2)
+     * @see https://dhoulb.github.io/shelving/db/provider/SQLProvider/SQLProvider/sqlValues
+     */
     sqlValues(data) {
         const entries = Object.entries(data);
         const keys = this.sqlConcat(entries.map(([key]) => this.sqlIdentifier(key)), ", ");
         const values = this.sqlConcat(entries.map(([, value]) => this.sql `${value}`), ", ");
         return this.sql `(${keys}) VALUES (${values})`;
     }
-    /** Define an SQL for the `WHERE`, `ORDER BY` and `LIMIT` clauses of an SQL query, e.g. e.g. ` WHERE x = 1 ORDER BY "name" LIMIT 0, 50` */
+    /**
+     * Define an SQL fragment for the `WHERE`, `ORDER BY` and `LIMIT` clauses of a query, e.g. ` WHERE x = 1 ORDER BY "name" LIMIT 0, 50`.
+     *
+     * @param query The query to translate into clauses.
+     * @returns The composed `SQLFragment`.
+     * @example this.sqlClauses(query); // WHERE ... ORDER BY ... LIMIT ...
+     * @see https://dhoulb.github.io/shelving/db/provider/SQLProvider/SQLProvider/sqlClauses
+     */
     sqlClauses(query) {
         return this.sql `${this.sqlWhere(query)}${this.sqlOrder(query)}${this.sqlLimit(query)}`;
     }
-    /** Define an SQL fragment for a `WHERE` clause, e.g. ` WHERE x = 1 AND y <= 100` */
+    /**
+     * Define an SQL fragment for a `WHERE` clause, e.g. ` WHERE x = 1 AND y <= 100`.
+     *
+     * @param query The query whose filters become the `WHERE` clause.
+     * @returns The composed `SQLFragment` (empty if there are no filters).
+     * @example this.sqlWhere(query); // WHERE x = 1
+     * @see https://dhoulb.github.io/shelving/db/provider/SQLProvider/SQLProvider/sqlWhere
+     */
     sqlWhere(query) {
         const filters = getQueryFilters(query);
         if (filters.length)
@@ -133,7 +331,13 @@ export class SQLProvider extends DBProvider {
         return this.sql ` WHERE ${this.sqlConcat(filters.map(filter => this.sqlFilter(filter)), " AND ")}`;
     }
     /**
-     * Define an SQL fragment for a filter clause on a column.
+     * Define an SQL fragment for a single filter clause on a column, e.g. `x = 1` or `x IN (1, 2)`.
+     *
+     * @param filter The filter (`key`, `operator`, `value`) to translate.
+     * @returns The composed `SQLFragment`.
+     * @throws {UnimplementedError} If the operator is unsupported.
+     * @example this.sqlFilter({ key: ["x"], operator: "is", value: 1 }); // "x" = 1
+     * @see https://dhoulb.github.io/shelving/db/provider/SQLProvider/SQLProvider/sqlFilter
      */
     sqlFilter({ key, operator, value }) {
         const path = this.sqlExtract(key);
@@ -162,8 +366,14 @@ export class SQLProvider extends DBProvider {
         throw new UnimplementedError(`SQLProvider does not support "${operator}" filters`);
     }
     /**
-     * Define an SQL fragment for an `ORDER BY` clause, e.g. ` ORDER BY "a" ASC, "b" DESC`
+     * Define an SQL fragment for an `ORDER BY` clause, e.g. ` ORDER BY "a" ASC, "b" DESC`.
      * - Nested keys (multi-segment) throw `UnimplementedError`.
+     *
+     * @param query The query whose orders become the `ORDER BY` clause.
+     * @returns The composed `SQLFragment` (empty if there are no orders).
+     * @throws {UnimplementedError} If an order key is nested (multi-segment).
+     * @example this.sqlOrder(query); // ORDER BY "a" ASC
+     * @see https://dhoulb.github.io/shelving/db/provider/SQLProvider/SQLProvider/sqlOrder
      */
     sqlOrder(query) {
         const orders = getQueryOrders(query);
@@ -171,7 +381,14 @@ export class SQLProvider extends DBProvider {
             return this.sql ``;
         return this.sql ` ORDER BY ${this.sqlConcat(orders.map(order => this.sqlSort(order)), ", ")}`;
     }
-    /** Define an SQL fragment for an individual column in an `ORDER BY`, e.g. `"a" ASC` */
+    /**
+     * Define an SQL fragment for an individual column in an `ORDER BY`, e.g. `"a" ASC`.
+     *
+     * @param order The order (`key`, `direction`) to translate.
+     * @returns The composed `SQLFragment`.
+     * @example this.sqlSort({ key: ["a"], direction: "asc" }); // "a" ASC
+     * @see https://dhoulb.github.io/shelving/db/provider/SQLProvider/SQLProvider/sqlSort
+     */
     sqlSort({ key, direction }) {
         const path = this.sqlExtract(key);
         if (direction === "asc")
@@ -180,7 +397,14 @@ export class SQLProvider extends DBProvider {
             return this.sql `${path} DESC`;
         return direction; // Never happens.
     }
-    /** Define an SQL fragment for an `LIMIT` clause, e.g. ` LIMIT 50, 100` */
+    /**
+     * Define an SQL fragment for a `LIMIT` clause, e.g. ` LIMIT 50`.
+     *
+     * @param query The query whose limit becomes the `LIMIT` clause.
+     * @returns The composed `SQLFragment` (empty if the query has no limit).
+     * @example this.sqlLimit(query); // LIMIT 50
+     * @see https://dhoulb.github.io/shelving/db/provider/SQLProvider/SQLProvider/sqlLimit
+     */
     sqlLimit(query) {
         const limit = getQueryLimit(query);
         return typeof limit === "number" ? this.sql ` LIMIT ${limit}` : this.sql ``;

package/db/provider/SQLiteProvider.d.ts

@@ -11,13 +11,53 @@ import { type SQLFragment, SQLProvider } from "./SQLProvider.js";
  * Note the following compatibility caveats:
  * - For `with` and `omit` updates this does not preserve ordering of the original array.
  * - For `with` and `omit` updates this does not guarantee equality for de-duplication when working with nested objects or arrays.
+ *
+ * @example
+ *  class MyProvider extends SQLiteProvider { async exec(strings, ...values) { ... } }
+ *  const item = await new MyProvider().getItem(collection, "abc");
+ * @see https://dhoulb.github.io/shelving/db/provider/SQLiteProvider/SQLiteProvider
  */
 export declare abstract class SQLiteProvider<I extends Identifier = Identifier, T extends Data = Data> extends SQLProvider<I, T> {
+    /**
+     * Insert a new item and return its ID, generating a UUID client-side for string-keyed collections.
+     * - SQLite has no native UUID generation, so for `StringSchema` IDs the UUID is generated here and delegated to `setItem`.
+     *
+     * @param collection The collection to insert into.
+     * @param data The data of the item to insert.
+     * @returns Promise resolving to the ID of the inserted item.
+     * @example await provider.addItem(collection, { name: "Dave" })
+     * @see https://dhoulb.github.io/shelving/db/provider/SQLiteProvider/SQLiteProvider/addItem
+     */
     addItem<II extends I, TT extends T>(collection: Collection<string, II, TT>, data: TT): Promise<II>;
     /** Get the SQLite JSON path for the nested segments of a key (everything after the column name), e.g. `$.b.c` */
     private sqlPath;
-    /** Get the SQLite JSON extract syntax, e.g. `json_extract("a", $.b.c)` */
+    /**
+     * Get the SQLite JSON extract syntax for a key, e.g. `json_extract("a", $.b.c)`.
+     *
+     * @param key The key segments identifying the column and any nested JSON path.
+     * @returns An `SQLFragment` extracting the value.
+     * @example this.sqlExtract(["a", "b"]); // json_extract("a", $.b)
+     * @see https://dhoulb.github.io/shelving/db/provider/SQLiteProvider/SQLiteProvider/sqlExtract
+     */
     sqlExtract(key: Segments): SQLFragment;
+    /**
+     * Define an SQL fragment for a single update action, with SQLite JSON1 support for nested keys and `with`/`omit` array mutations.
+     *
+     * @param update The update action (`action`, `key`, `value`) to convert.
+     * @returns The composed `SQLFragment`.
+     * @throws {UnimplementedError} If the action is unsupported.
+     * @example this.sqlUpdate({ action: "set", key: ["a", "b"], value: 1 })
+     * @see https://dhoulb.github.io/shelving/db/provider/SQLiteProvider/SQLiteProvider/sqlUpdate
+     */
     sqlUpdate(update: Update): SQLFragment;
+    /**
+     * Define an SQL fragment for a filter clause, with SQLite JSON1 support for `contains` and deeply-nested JSON queries.
+     *
+     * @param filter The filter (`key`, `operator`, `value`) to translate.
+     * @returns The composed `SQLFragment`.
+     * @throws {UnimplementedError} If the operator is unsupported.
+     * @example this.sqlFilter({ key: ["tags"], operator: "contains", value: "x" })
+     * @see https://dhoulb.github.io/shelving/db/provider/SQLiteProvider/SQLiteProvider/sqlFilter
+     */
     sqlFilter(filter: QueryFilter): SQLFragment;
 }

package/db/provider/SQLiteProvider.js

@@ -6,9 +6,23 @@ import { SQLProvider } from "./SQLProvider.js";
  * Note the following compatibility caveats:
  * - For `with` and `omit` updates this does not preserve ordering of the original array.
  * - For `with` and `omit` updates this does not guarantee equality for de-duplication when working with nested objects or arrays.
+ *
+ * @example
+ *  class MyProvider extends SQLiteProvider { async exec(strings, ...values) { ... } }
+ *  const item = await new MyProvider().getItem(collection, "abc");
+ * @see https://dhoulb.github.io/shelving/db/provider/SQLiteProvider/SQLiteProvider
  */
 export class SQLiteProvider extends SQLProvider {
-    // Override `addItem` to support string (UUID) IDs in SQLite.
+    /**
+     * Insert a new item and return its ID, generating a UUID client-side for string-keyed collections.
+     * - SQLite has no native UUID generation, so for `StringSchema` IDs the UUID is generated here and delegated to `setItem`.
+     *
+     * @param collection The collection to insert into.
+     * @param data The data of the item to insert.
+     * @returns Promise resolving to the ID of the inserted item.
+     * @example await provider.addItem(collection, { name: "Dave" })
+     * @see https://dhoulb.github.io/shelving/db/provider/SQLiteProvider/SQLiteProvider/addItem
+     */
     // SQLite has no native UUID generation, so when the collection uses a `StringSchema` ID
     // we generate the UUID client-side and delegate to `setItem`.
     // Note: `as II` is required here because TypeScript cannot narrow the generic `II` from `instanceof StringSchema`.
@@ -24,7 +38,14 @@ export class SQLiteProvider extends SQLProvider {
     sqlPath(key) {
         return this.sqlConcat(key.slice(1).map(k => this.sqlIdentifier(k)), ".", "$.");
     }
-    /** Get the SQLite JSON extract syntax, e.g. `json_extract("a", $.b.c)` */
+    /**
+     * Get the SQLite JSON extract syntax for a key, e.g. `json_extract("a", $.b.c)`.
+     *
+     * @param key The key segments identifying the column and any nested JSON path.
+     * @returns An `SQLFragment` extracting the value.
+     * @example this.sqlExtract(["a", "b"]); // json_extract("a", $.b)
+     * @see https://dhoulb.github.io/shelving/db/provider/SQLiteProvider/SQLiteProvider/sqlExtract
+     */
     sqlExtract(key) {
         const column = this.sqlIdentifier(key[0]);
         if (key.length > 1) {
@@ -33,7 +54,15 @@ export class SQLiteProvider extends SQLProvider {
         }
         return column;
     }
-    // Override to implement `with` and `omit` updates and deeply nested JSONB values.
+    /**
+     * Define an SQL fragment for a single update action, with SQLite JSON1 support for nested keys and `with`/`omit` array mutations.
+     *
+     * @param update The update action (`action`, `key`, `value`) to convert.
+     * @returns The composed `SQLFragment`.
+     * @throws {UnimplementedError} If the action is unsupported.
+     * @example this.sqlUpdate({ action: "set", key: ["a", "b"], value: 1 })
+     * @see https://dhoulb.github.io/shelving/db/provider/SQLiteProvider/SQLiteProvider/sqlUpdate
+     */
     sqlUpdate(update) {
         const { action, key, value } = update;
         const column = this.sqlIdentifier(key[0]);
@@ -94,7 +123,15 @@ export class SQLiteProvider extends SQLProvider {
         }
         return super.sqlUpdate(update);
     }
-    // Override to implement `contains` queries and deeply-nested JSONB queries.
+    /**
+     * Define an SQL fragment for a filter clause, with SQLite JSON1 support for `contains` and deeply-nested JSON queries.
+     *
+     * @param filter The filter (`key`, `operator`, `value`) to translate.
+     * @returns The composed `SQLFragment`.
+     * @throws {UnimplementedError} If the operator is unsupported.
+     * @example this.sqlFilter({ key: ["tags"], operator: "contains", value: "x" })
+     * @see https://dhoulb.github.io/shelving/db/provider/SQLiteProvider/SQLiteProvider/sqlFilter
+     */
     sqlFilter(filter) {
         const { key, operator, value } = filter;
         // Implement `contains` filters.