shelving 1.236.0 → 1.236.2

package/bun/BunPostgreSQLProvider.d.ts

@@ -3,9 +3,47 @@ import { PostgreSQLProvider, type SQLFragment } from "../db/index.js";
 import type { ImmutableArray } from "../util/array.js";
 import type { Data } from "../util/data.js";
 import type { Identifier } from "../util/item.js";
+/**
+ * PostgreSQL database provider backed by Bun's built-in `Bun.SQL` driver.
+ *
+ * Implements the `PostgreSQLProvider` SQL abstraction by executing tagged-template queries against a `Bun.SQL` connection.
+ * - Identifiers are escaped through `Bun.SQL`'s own `sql()` helper rather than naive string quoting, which is more secure.
+ * - Requires the `bun` peer dependency and a running Bun environment.
+ *
+ * @example
+ * import { SQL } from "bun";
+ * const provider = new BunPostgreSQLProvider(new SQL(process.env.DATABASE_URL));
+ *
+ * @see https://dhoulb.github.io/shelving/bun/BunPostgreSQLProvider/BunPostgreSQLProvider
+ */
 export declare class BunPostgreSQLProvider<I extends Identifier = Identifier, T extends Data = Data> extends PostgreSQLProvider<I, T> {
     private _sql;
+    /**
+     * Create a provider wrapping an existing `Bun.SQL` connection.
+     *
+     * @param sql The `Bun.SQL` instance to execute queries against.
+     * @see https://dhoulb.github.io/shelving/bun/BunPostgreSQLProvider/BunPostgreSQLProvider
+     */
     constructor(sql: SQL);
+    /**
+     * Execute an SQL query through the underlying `Bun.SQL` connection.
+     *
+     * @param strings The tagged-template string parts of the query.
+     * @param values The interpolated values bound as query parameters.
+     * @returns Promise resolving to the array of result rows.
+     * @example provider.exec`SELECT * FROM ${provider.sqlIdentifier("items")}`
+     * @see https://dhoulb.github.io/shelving/bun/BunPostgreSQLProvider/BunPostgreSQLProvider/exec
+     */
     exec<X extends Data>(strings: TemplateStringsArray, ...values: ImmutableArray<unknown>): Promise<ImmutableArray<X>>;
+    /**
+     * Build an SQL fragment for an identifier, escaped via `Bun.SQL`'s `sql()` helper.
+     *
+     * Overrides the base implementation because the Bun SQL engine supports first-class identifier wrapping, which is more secure than manual quoting.
+     *
+     * @param name The identifier (table or column name) to escape.
+     * @returns An `SQLFragment` wrapping the escaped identifier.
+     * @example provider.sqlIdentifier("items")
+     * @see https://dhoulb.github.io/shelving/bun/BunPostgreSQLProvider/BunPostgreSQLProvider/sqlIdentifier
+     */
     sqlIdentifier(name: string): SQLFragment;
 }

package/bun/BunPostgreSQLProvider.js

@@ -1,15 +1,51 @@
 import { PostgreSQLProvider } from "../db/index.js";
+/**
+ * PostgreSQL database provider backed by Bun's built-in `Bun.SQL` driver.
+ *
+ * Implements the `PostgreSQLProvider` SQL abstraction by executing tagged-template queries against a `Bun.SQL` connection.
+ * - Identifiers are escaped through `Bun.SQL`'s own `sql()` helper rather than naive string quoting, which is more secure.
+ * - Requires the `bun` peer dependency and a running Bun environment.
+ *
+ * @example
+ * import { SQL } from "bun";
+ * const provider = new BunPostgreSQLProvider(new SQL(process.env.DATABASE_URL));
+ *
+ * @see https://dhoulb.github.io/shelving/bun/BunPostgreSQLProvider/BunPostgreSQLProvider
+ */
 export class BunPostgreSQLProvider extends PostgreSQLProvider {
     _sql;
+    /**
+     * Create a provider wrapping an existing `Bun.SQL` connection.
+     *
+     * @param sql The `Bun.SQL` instance to execute queries against.
+     * @see https://dhoulb.github.io/shelving/bun/BunPostgreSQLProvider/BunPostgreSQLProvider
+     */
     constructor(sql) {
         super();
         this._sql = sql;
     }
-    // Implement `SQLProvider` using `Bun.SQL` instance.
+    /**
+     * Execute an SQL query through the underlying `Bun.SQL` connection.
+     *
+     * @param strings The tagged-template string parts of the query.
+     * @param values The interpolated values bound as query parameters.
+     * @returns Promise resolving to the array of result rows.
+     * @example provider.exec`SELECT * FROM ${provider.sqlIdentifier("items")}`
+     * @see https://dhoulb.github.io/shelving/bun/BunPostgreSQLProvider/BunPostgreSQLProvider/exec
+     */
     exec(strings, ...values) {
         return this._sql(strings, ...values);
     }
-    // Override to wrap identifiers using `sql()`, since Bun SQL engine supports this and it's more secure.
+    /**
+     * Build an SQL fragment for an identifier, escaped via `Bun.SQL`'s `sql()` helper.
+     *
+     * Overrides the base implementation because the Bun SQL engine supports first-class identifier wrapping, which is more secure than manual quoting.
+     *
+     * @param name The identifier (table or column name) to escape.
+     * @returns An `SQLFragment` wrapping the escaped identifier.
+     * @example provider.sqlIdentifier("items")
+     * @see https://dhoulb.github.io/shelving/bun/BunPostgreSQLProvider/BunPostgreSQLProvider/sqlIdentifier
+     */
     sqlIdentifier(name) {
         return this.sql `${this._sql(name)}`;
     }

package/cloudflare/CloudflareD1Provider.d.ts

@@ -4,12 +4,39 @@ import type { Data } from "../util/data.js";
 import type { Identifier } from "../util/item.js";
 import type { D1Database } from "./types.js";
 /**
- * Cloudflare D1 database provider.
+ * SQLite database provider backed by Cloudflare D1.
  *
- * Uses the D1 Worker API for execution and standard SQL from `SQLProvider`.
+ * Implements the `SQLiteProvider` SQL abstraction by binding tagged-template queries and running them through the D1 Worker API.
+ * - Tagged-template values are flattened into positional `?` bindings; nested `SQLFragment` values are inlined recursively.
+ * - Array and plain-object values are JSON-encoded before binding; other non-primitive values throw `ValueError`.
+ * - The `D1Database` binding is provided by the Cloudflare Workers runtime environment.
+ *
+ * @example
+ * // `env.DB` is the D1 binding from the Worker environment.
+ * const provider = new CloudflareD1Provider(env.DB);
+ *
+ * @see https://dhoulb.github.io/shelving/cloudflare/CloudflareD1Provider/CloudflareD1Provider
  */
 export declare class CloudflareD1Provider<I extends Identifier = Identifier, T extends Data = Data> extends SQLiteProvider<I, T> {
     private readonly _db;
+    /**
+     * Create a provider wrapping a Cloudflare D1 database binding.
+     *
+     * @param db The `D1Database` binding from the Worker environment.
+     * @see https://dhoulb.github.io/shelving/cloudflare/CloudflareD1Provider/CloudflareD1Provider
+     */
     constructor(db: D1Database);
+    /**
+     * Execute an SQL query through the Cloudflare D1 Worker API.
+     *
+     * Converts the tagged-template query into a parameterised statement, binds its values, and runs it via `prepare().bind().run()`.
+     *
+     * @param strings The tagged-template string parts of the query.
+     * @param values The interpolated values, bound as positional parameters or inlined `SQLFragment` instances.
+     * @returns Promise resolving to the array of result rows (empty if D1 returns no results).
+     * @throws {ValueError} If a value cannot be converted to a D1 binding.
+     * @example provider.exec`SELECT * FROM ${provider.sqlIdentifier("items")}`
+     * @see https://dhoulb.github.io/shelving/cloudflare/CloudflareD1Provider/CloudflareD1Provider/exec
+     */
     exec<X extends Data>(strings: TemplateStringsArray, ...values: ImmutableArray<unknown>): Promise<readonly X[]>;
 }

package/cloudflare/CloudflareD1Provider.js

@@ -3,16 +3,43 @@ import { ValueError } from "../error/ValueError.js";
 import { isArray } from "../util/array.js";
 import { isPlainObject } from "../util/object.js";
 /**
- * Cloudflare D1 database provider.
+ * SQLite database provider backed by Cloudflare D1.
  *
- * Uses the D1 Worker API for execution and standard SQL from `SQLProvider`.
+ * Implements the `SQLiteProvider` SQL abstraction by binding tagged-template queries and running them through the D1 Worker API.
+ * - Tagged-template values are flattened into positional `?` bindings; nested `SQLFragment` values are inlined recursively.
+ * - Array and plain-object values are JSON-encoded before binding; other non-primitive values throw `ValueError`.
+ * - The `D1Database` binding is provided by the Cloudflare Workers runtime environment.
+ *
+ * @example
+ * // `env.DB` is the D1 binding from the Worker environment.
+ * const provider = new CloudflareD1Provider(env.DB);
+ *
+ * @see https://dhoulb.github.io/shelving/cloudflare/CloudflareD1Provider/CloudflareD1Provider
  */
 export class CloudflareD1Provider extends SQLiteProvider {
     _db;
+    /**
+     * Create a provider wrapping a Cloudflare D1 database binding.
+     *
+     * @param db The `D1Database` binding from the Worker environment.
+     * @see https://dhoulb.github.io/shelving/cloudflare/CloudflareD1Provider/CloudflareD1Provider
+     */
     constructor(db) {
         super();
         this._db = db;
     }
+    /**
+     * Execute an SQL query through the Cloudflare D1 Worker API.
+     *
+     * Converts the tagged-template query into a parameterised statement, binds its values, and runs it via `prepare().bind().run()`.
+     *
+     * @param strings The tagged-template string parts of the query.
+     * @param values The interpolated values, bound as positional parameters or inlined `SQLFragment` instances.
+     * @returns Promise resolving to the array of result rows (empty if D1 returns no results).
+     * @throws {ValueError} If a value cannot be converted to a D1 binding.
+     * @example provider.exec`SELECT * FROM ${provider.sqlIdentifier("items")}`
+     * @see https://dhoulb.github.io/shelving/cloudflare/CloudflareD1Provider/CloudflareD1Provider/exec
+     */
     async exec(strings, ...values) {
         const { query, values: bindings } = _getD1Query(strings, values, this.exec);
         const result = await this._db

package/cloudflare/CloudflareKVProvider.d.ts

@@ -26,19 +26,134 @@ import type { KVNamespace } from "./types.js";
  * - **Single-key store only:** This provider is intentionally limited to direct key reads and writes.
  *   If you need collection queries, filtering, sorting, or bulk mutations, use a different backend.
  * - **Eventual consistency:** KV is eventually consistent, so reads may briefly return stale values shortly after writes.
+ *
+ * @example
+ * // `env.KV` is the KV namespace binding from the Worker environment.
+ * const provider = new CloudflareKVProvider(env.KV);
+ *
+ * @see https://dhoulb.github.io/shelving/cloudflare/CloudflareKVProvider/CloudflareKVProvider
  */
 export declare class CloudflareKVProvider<I extends string = string, T extends Data = Data> extends DBProvider<I, T> {
     private readonly _kv;
+    /**
+     * Create a provider wrapping a Cloudflare Workers KV namespace binding.
+     *
+     * @param kv The `KVNamespace` binding from the Worker environment.
+     * @see https://dhoulb.github.io/shelving/cloudflare/CloudflareKVProvider/CloudflareKVProvider
+     */
     constructor(kv: KVNamespace);
+    /**
+     * Read a single item by ID from the KV namespace.
+     *
+     * @param collection The collection the item belongs to (only its `name` is used to form the key).
+     * @param id The ID of the item to read.
+     * @returns Promise resolving to the item, or `undefined` if no value exists for the key.
+     * @example await provider.getItem(users, "abc123")
+     * @see https://dhoulb.github.io/shelving/cloudflare/CloudflareKVProvider/CloudflareKVProvider/getItem
+     */
     getItem<II extends I, TT extends T>({ name }: Collection<string, II, TT>, id: II): Promise<OptionalItem<II, TT>>;
+    /**
+     * Not supported — KV has no change feed or push notification mechanism.
+     *
+     * @param collection The collection the item belongs to.
+     * @param id The ID of the item to subscribe to.
+     * @returns Never returns normally.
+     * @throws {UnimplementedError} Always, because KV does not support realtime subscriptions.
+     * @see https://dhoulb.github.io/shelving/cloudflare/CloudflareKVProvider/CloudflareKVProvider/getItemSequence
+     */
     getItemSequence<II extends I, TT extends T>(_collection: Collection<string, II, TT>, _id: II): OptionalItemSequence<II, TT>;
+    /**
+     * Add an item with an automatically generated UUID v4 identifier.
+     *
+     * @param collection The collection to add the item to (only its `name` is used to form the key).
+     * @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/cloudflare/CloudflareKVProvider/CloudflareKVProvider/addItem
+     */
     addItem<II extends I, TT extends T>({ name }: Collection<string, II, TT>, data: TT): Promise<II>;
+    /**
+     * Write an item by ID, overwriting any existing value.
+     *
+     * @param collection The collection the item belongs to (only its `name` is used to form the key).
+     * @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/cloudflare/CloudflareKVProvider/CloudflareKVProvider/setItem
+     */
     setItem<II extends I, TT extends T>({ name }: Collection<string, II, TT>, id: II, data: TT): Promise<void>;
+    /**
+     * Not supported — KV cannot apply partial updates atomically.
+     *
+     * @param collection The collection the item belongs to.
+     * @param id The ID of the item to update.
+     * @param updates The updates to apply.
+     * @returns Never returns normally.
+     * @throws {UnimplementedError} Always, because KV does not support item updates.
+     * @see https://dhoulb.github.io/shelving/cloudflare/CloudflareKVProvider/CloudflareKVProvider/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 ID from the KV namespace.
+     *
+     * @param collection The collection the item belongs to (only its `name` is used to form the key).
+     * @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/cloudflare/CloudflareKVProvider/CloudflareKVProvider/deleteItem
+     */
     deleteItem<II extends I, TT extends T>({ name }: Collection<string, II, TT>, id: II): Promise<void>;
+    /**
+     * Not supported — KV cannot efficiently filter, sort, or scan collections.
+     *
+     * @param collection The collection to query.
+     * @param query The query to run.
+     * @returns Never returns normally.
+     * @throws {UnimplementedError} Always, because KV does not support collection queries.
+     * @see https://dhoulb.github.io/shelving/cloudflare/CloudflareKVProvider/CloudflareKVProvider/getQuery
+     */
     getQuery<II extends I, TT extends T>(_collection: Collection<string, II, TT>, _query?: Query<Item<II, TT>>): Promise<Items<II, TT>>;
+    /**
+     * Not supported — KV has no change feed and cannot run collection queries.
+     *
+     * @param collection The collection to query.
+     * @param query The query to subscribe to.
+     * @returns Never returns normally.
+     * @throws {UnimplementedError} Always, because KV does not support realtime subscriptions.
+     * @see https://dhoulb.github.io/shelving/cloudflare/CloudflareKVProvider/CloudflareKVProvider/getQuerySequence
+     */
     getQuerySequence<II extends I, TT extends T>(_collection: Collection<string, II, TT>, _query?: Query<Item<II, TT>>): ItemsSequence<II, TT>;
+    /**
+     * Not supported — KV cannot run the collection query needed to target matching items.
+     *
+     * @param collection The collection to query.
+     * @param query The query selecting items to write.
+     * @param data The data to write to each matching item.
+     * @returns Never returns normally.
+     * @throws {UnimplementedError} Always, because KV does not support collection queries.
+     * @see https://dhoulb.github.io/shelving/cloudflare/CloudflareKVProvider/CloudflareKVProvider/setQuery
+     */
     setQuery<II extends I, TT extends T>(_collection: Collection<string, II, TT>, _query: Query<Item<II, TT>>, _data: TT): Promise<void>;
+    /**
+     * Not supported — KV supports neither updates nor collection queries.
+     *
+     * @param collection The collection to query.
+     * @param query The query selecting items to update.
+     * @param updates The updates to apply to each matching item.
+     * @returns Never returns normally.
+     * @throws {UnimplementedError} Always, because KV does not support item updates.
+     * @see https://dhoulb.github.io/shelving/cloudflare/CloudflareKVProvider/CloudflareKVProvider/updateQuery
+     */
     updateQuery<II extends I, TT extends T>(_collection: Collection<string, II, TT>, _query: Query<Item<II, TT>>, _updates: Updates<TT>): Promise<void>;
+    /**
+     * Not supported — KV cannot run the collection query needed to target matching items.
+     *
+     * @param collection The collection to query.
+     * @param query The query selecting items to delete.
+     * @returns Never returns normally.
+     * @throws {UnimplementedError} Always, because KV does not support collection queries.
+     * @see https://dhoulb.github.io/shelving/cloudflare/CloudflareKVProvider/CloudflareKVProvider/deleteQuery
+     */
     deleteQuery<II extends I, TT extends T>(_collection: Collection<string, II, TT>, _query: Query<Item<II, TT>>): Promise<void>;
 }

package/cloudflare/CloudflareKVProvider.js

@@ -23,47 +23,162 @@ import { randomUUID } from "../util/uuid.js";
  * - **Single-key store only:** This provider is intentionally limited to direct key reads and writes.
  *   If you need collection queries, filtering, sorting, or bulk mutations, use a different backend.
  * - **Eventual consistency:** KV is eventually consistent, so reads may briefly return stale values shortly after writes.
+ *
+ * @example
+ * // `env.KV` is the KV namespace binding from the Worker environment.
+ * const provider = new CloudflareKVProvider(env.KV);
+ *
+ * @see https://dhoulb.github.io/shelving/cloudflare/CloudflareKVProvider/CloudflareKVProvider
  */
 export class CloudflareKVProvider extends DBProvider {
     _kv;
+    /**
+     * Create a provider wrapping a Cloudflare Workers KV namespace binding.
+     *
+     * @param kv The `KVNamespace` binding from the Worker environment.
+     * @see https://dhoulb.github.io/shelving/cloudflare/CloudflareKVProvider/CloudflareKVProvider
+     */
     constructor(kv) {
         super();
         this._kv = kv;
     }
+    /**
+     * Read a single item by ID from the KV namespace.
+     *
+     * @param collection The collection the item belongs to (only its `name` is used to form the key).
+     * @param id The ID of the item to read.
+     * @returns Promise resolving to the item, or `undefined` if no value exists for the key.
+     * @example await provider.getItem(users, "abc123")
+     * @see https://dhoulb.github.io/shelving/cloudflare/CloudflareKVProvider/CloudflareKVProvider/getItem
+     */
     async getItem({ name }, id) {
         const data = (await this._kv.get(_getKey(name, id), { type: "json" })); // `as TT` needed: KV returns unknown from JSON parse.
         if (data)
             return getItem(id, data);
     }
+    /**
+     * Not supported — KV has no change feed or push notification mechanism.
+     *
+     * @param collection The collection the item belongs to.
+     * @param id The ID of the item to subscribe to.
+     * @returns Never returns normally.
+     * @throws {UnimplementedError} Always, because KV does not support realtime subscriptions.
+     * @see https://dhoulb.github.io/shelving/cloudflare/CloudflareKVProvider/CloudflareKVProvider/getItemSequence
+     */
     getItemSequence(_collection, _id) {
         throw new UnimplementedError("CloudflareKVProvider does not support realtime subscriptions");
     }
+    /**
+     * Add an item with an automatically generated UUID v4 identifier.
+     *
+     * @param collection The collection to add the item to (only its `name` is used to form the key).
+     * @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/cloudflare/CloudflareKVProvider/CloudflareKVProvider/addItem
+     */
     async addItem({ name }, data) {
         const id = randomUUID(); // `as II` needed: TypeScript can't narrow II from string return type.
         await this._kv.put(_getKey(name, id), JSON.stringify(data));
         return id;
     }
+    /**
+     * Write an item by ID, overwriting any existing value.
+     *
+     * @param collection The collection the item belongs to (only its `name` is used to form the key).
+     * @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/cloudflare/CloudflareKVProvider/CloudflareKVProvider/setItem
+     */
     async setItem({ name }, id, data) {
         await this._kv.put(_getKey(name, id), JSON.stringify(data));
     }
+    /**
+     * Not supported — KV cannot apply partial updates atomically.
+     *
+     * @param collection The collection the item belongs to.
+     * @param id The ID of the item to update.
+     * @param updates The updates to apply.
+     * @returns Never returns normally.
+     * @throws {UnimplementedError} Always, because KV does not support item updates.
+     * @see https://dhoulb.github.io/shelving/cloudflare/CloudflareKVProvider/CloudflareKVProvider/updateItem
+     */
     async updateItem(_collection, _id, _updates) {
         throw new UnimplementedError("CloudflareKVProvider does not support updates to items");
     }
+    /**
+     * Delete an item by ID from the KV namespace.
+     *
+     * @param collection The collection the item belongs to (only its `name` is used to form the key).
+     * @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/cloudflare/CloudflareKVProvider/CloudflareKVProvider/deleteItem
+     */
     async deleteItem({ name }, id) {
         await this._kv.delete(_getKey(name, id));
     }
+    /**
+     * Not supported — KV cannot efficiently filter, sort, or scan collections.
+     *
+     * @param collection The collection to query.
+     * @param query The query to run.
+     * @returns Never returns normally.
+     * @throws {UnimplementedError} Always, because KV does not support collection queries.
+     * @see https://dhoulb.github.io/shelving/cloudflare/CloudflareKVProvider/CloudflareKVProvider/getQuery
+     */
     async getQuery(_collection, _query) {
         throw new UnimplementedError("CloudflareKVProvider does not support querying items");
     }
+    /**
+     * Not supported — KV has no change feed and cannot run collection queries.
+     *
+     * @param collection The collection to query.
+     * @param query The query to subscribe to.
+     * @returns Never returns normally.
+     * @throws {UnimplementedError} Always, because KV does not support realtime subscriptions.
+     * @see https://dhoulb.github.io/shelving/cloudflare/CloudflareKVProvider/CloudflareKVProvider/getQuerySequence
+     */
     getQuerySequence(_collection, _query) {
         throw new UnimplementedError("CloudflareKVProvider does not support realtime subscriptions");
     }
+    /**
+     * Not supported — KV cannot run the collection query needed to target matching items.
+     *
+     * @param collection The collection to query.
+     * @param query The query selecting items to write.
+     * @param data The data to write to each matching item.
+     * @returns Never returns normally.
+     * @throws {UnimplementedError} Always, because KV does not support collection queries.
+     * @see https://dhoulb.github.io/shelving/cloudflare/CloudflareKVProvider/CloudflareKVProvider/setQuery
+     */
     async setQuery(_collection, _query, _data) {
         throw new UnimplementedError("CloudflareKVProvider does not support querying items");
     }
+    /**
+     * Not supported — KV supports neither updates nor collection queries.
+     *
+     * @param collection The collection to query.
+     * @param query The query selecting items to update.
+     * @param updates The updates to apply to each matching item.
+     * @returns Never returns normally.
+     * @throws {UnimplementedError} Always, because KV does not support item updates.
+     * @see https://dhoulb.github.io/shelving/cloudflare/CloudflareKVProvider/CloudflareKVProvider/updateQuery
+     */
     async updateQuery(_collection, _query, _updates) {
         throw new UnimplementedError("CloudflareKVProvider does not support updates to items");
     }
+    /**
+     * Not supported — KV cannot run the collection query needed to target matching items.
+     *
+     * @param collection The collection to query.
+     * @param query The query selecting items to delete.
+     * @returns Never returns normally.
+     * @throws {UnimplementedError} Always, because KV does not support collection queries.
+     * @see https://dhoulb.github.io/shelving/cloudflare/CloudflareKVProvider/CloudflareKVProvider/deleteQuery
+     */
     async deleteQuery(_collection, _query) {
         throw new UnimplementedError("CloudflareKVProvider does not support querying items");
     }

package/cloudflare/types.d.ts

@@ -1,4 +1,10 @@
-/** Minimal interface matching Cloudflare Workers KV namespace runtime object. */
+/**
+ * Minimal interface matching the Cloudflare Workers KV namespace runtime object.
+ *
+ * Declares only the subset of methods `CloudflareKVProvider` uses, so the `@cloudflare/workers-types` package is not required as a dependency.
+ *
+ * @see https://dhoulb.github.io/shelving/cloudflare/types/KVNamespace
+ */
 export interface KVNamespace {
     get(key: string, options: {
         type: "json";
@@ -6,9 +12,17 @@ export interface KVNamespace {
     put(key: string, value: string): Promise<void>;
     delete(key: string): Promise<void>;
 }
-/** Value that can be passed through the D1 Worker API. */
+/**
+ * Value that can be passed through the D1 Worker API as a bound parameter.
+ *
+ * @see https://dhoulb.github.io/shelving/cloudflare/types/D1Value
+ */
 export type D1Value = boolean | null | number | string;
-/** Metadata returned by the D1 Worker API. */
+/**
+ * Metadata returned by the D1 Worker API alongside a query result.
+ *
+ * @see https://dhoulb.github.io/shelving/cloudflare/types/D1Meta
+ */
 export interface D1Meta {
     readonly changed_db?: boolean | undefined;
     readonly duration?: number | undefined;
@@ -16,18 +30,32 @@ export interface D1Meta {
     readonly rows_read?: number | undefined;
     readonly rows_written?: number | undefined;
 }
-/** Result object returned by `D1PreparedStatement.run()`. */
+/**
+ * Result object returned by `D1PreparedStatement.run()`.
+ *
+ * @see https://dhoulb.github.io/shelving/cloudflare/types/D1Result
+ */
 export interface D1Result<T extends Record<string, unknown> = Record<string, unknown>> {
     readonly success: boolean;
     readonly meta?: D1Meta | undefined;
     readonly results?: readonly T[] | undefined;
 }
-/** Result object returned by `D1Database.exec()`. */
+/**
+ * Result object returned by `D1Database.exec()`.
+ *
+ * @see https://dhoulb.github.io/shelving/cloudflare/types/D1ExecResult
+ */
 export interface D1ExecResult {
     readonly count: number;
     readonly duration: number;
 }
-/** Minimal prepared statement interface for D1 databases and sessions. */
+/**
+ * Minimal prepared statement interface for D1 databases and sessions.
+ *
+ * Declares only the subset of the D1 prepared-statement API used by `CloudflareD1Provider`.
+ *
+ * @see https://dhoulb.github.io/shelving/cloudflare/types/D1PreparedStatement
+ */
 export interface D1PreparedStatement {
     bind(...values: D1Value[]): D1PreparedStatement;
     first<T = Record<string, unknown>>(column?: string): Promise<T | null>;
@@ -36,7 +64,13 @@ export interface D1PreparedStatement {
     }): Promise<readonly T[]>;
     run<T extends Record<string, unknown> = Record<string, unknown>>(): Promise<D1Result<T>>;
 }
-/** Minimal D1 binding/session interface used by `CloudflareD1Provider`. */
+/**
+ * Minimal D1 binding/session interface used by `CloudflareD1Provider`.
+ *
+ * Declares only the subset of the D1 binding API the provider needs, so the `@cloudflare/workers-types` package is not required as a dependency.
+ *
+ * @see https://dhoulb.github.io/shelving/cloudflare/types/D1Database
+ */
 export interface D1Database {
     batch<T extends Record<string, unknown> = Record<string, unknown>>(statements: readonly D1PreparedStatement[]): Promise<readonly D1Result<T>[]>;
     exec?(query: string): Promise<D1ExecResult>;