shelving 1.236.0 → 1.236.2

package/api/provider/CachedAPIProvider.js

@@ -3,36 +3,88 @@ import { awaitDispose } from "../../util/dispose.js";
 import { APICache } from "../cache/APICache.js";
 import { ThroughAPIProvider } from "./ThroughAPIProvider.js";
 /**
- * API provider wrapper that serves requests through an `APICache`.
- * - Constructor accepts a `source` provider and an optional default `maxAge`.
+ * API provider wrapper that serves requests through an `APICache` so repeated calls reuse cached results.
  * - On `call(...)`, triggers `cache.refresh(maxAge)` for the endpoint+payload before awaiting `cache.call(...)`.
  * - `invalidate`, `invalidateAll`, `refresh`, and `refreshAll` pass through to the underlying cache and use `this.maxAge` as the default refresh timing.
  *
- * @param `maxAge` The maximum age used when calling `call()` (defaults to `AVOID_REFRESH`, i.e. only refresh if the value is invalidated or still loading).
- * - Note: This is not used for `refresh()` calls — when you call `refresh()` you likely mean "do it now".
- * - When we are using `call()` on a cache, the entire point of the cache is to "cache", so the default isn't `0` like it is for `refresh()`
+ * @example
+ *  const api = new CachedAPIProvider(source);
+ *  const result = await api.call(endpoint, payload);
+ * @see https://dhoulb.github.io/shelving/api/provider/CachedAPIProvider/CachedAPIProvider
  */
 export class CachedAPIProvider extends ThroughAPIProvider {
+    /**
+     * The maximum age used when calling `call()`, defaulting to `AVOID_REFRESH` (only refresh if invalidated or still loading).
+     * - Not used for `refresh()` calls, which always refetch immediately.
+     * @see https://dhoulb.github.io/shelving/api/provider/CachedAPIProvider/CachedAPIProvider/maxAge
+     */
     maxAge;
     _cache;
+    /**
+     * Create a cached provider wrapping a source provider.
+     *
+     * @param source The source provider whose results are cached.
+     * @param maxAge Default maximum age in milliseconds for `call()` (defaults to `AVOID_REFRESH`).
+     * @example new CachedAPIProvider(source)
+     */
     constructor(source, maxAge = AVOID_REFRESH) {
         super(source);
         this.maxAge = maxAge;
         this._cache = new APICache(source);
     }
-    // Override call to use the cache racther than calling fresh each time.
+    /**
+     * Call an endpoint through the cache, reusing a cached result where possible instead of fetching fresh.
+     *
+     * @param endpoint The endpoint to call.
+     * @param payload The payload to call the endpoint with.
+     * @param _options Request options (unused; the cache key is derived from endpoint and payload).
+     * @param caller The calling function used for error stack traces.
+     * @returns Promise resolving to the (possibly cached) result.
+     * @example await api.call(endpoint, payload)
+     * @see https://dhoulb.github.io/shelving/api/provider/CachedAPIProvider/CachedAPIProvider/call
+     */
     call(endpoint, payload, _options, caller = this.call) {
         return this._cache.call(endpoint, payload, this.maxAge, caller);
     }
+    /**
+     * Invalidate the cached result for a specific endpoint and payload.
+     *
+     * @param endpoint The endpoint whose cached result should be invalidated.
+     * @param payload The payload identifying the cached result.
+     * @example api.invalidate(endpoint, payload)
+     * @see https://dhoulb.github.io/shelving/api/provider/CachedAPIProvider/CachedAPIProvider/invalidate
+     */
     invalidate(endpoint, payload) {
         this._cache.invalidate(endpoint, payload);
     }
+    /**
+     * Invalidate every cached result for an endpoint, across all payloads.
+     *
+     * @param endpoint The endpoint whose cached results should be invalidated.
+     * @example api.invalidateAll(endpoint)
+     * @see https://dhoulb.github.io/shelving/api/provider/CachedAPIProvider/CachedAPIProvider/invalidateAll
+     */
     invalidateAll(endpoint) {
         this._cache.invalidateAll(endpoint);
     }
+    /**
+     * Refresh the cached result for a specific endpoint and payload.
+     *
+     * @param endpoint The endpoint whose cached result should be refreshed.
+     * @param payload The payload identifying the cached result.
+     * @example api.refresh(endpoint, payload)
+     * @see https://dhoulb.github.io/shelving/api/provider/CachedAPIProvider/CachedAPIProvider/refresh
+     */
     refresh(endpoint, payload) {
         this._cache.refresh(endpoint, payload, this.maxAge);
     }
+    /**
+     * Refresh every cached result for an endpoint, across all payloads.
+     *
+     * @param endpoint The endpoint whose cached results should be refreshed.
+     * @example api.refreshAll(endpoint)
+     * @see https://dhoulb.github.io/shelving/api/provider/CachedAPIProvider/CachedAPIProvider/refreshAll
+     */
     refreshAll(endpoint) {
         this._cache.refreshAll(endpoint, this.maxAge);
     }

package/api/provider/ClientAPIProvider.d.ts

@@ -5,7 +5,11 @@ import { type PossibleURIParams } from "../../util/uri.js";
 import { type PossibleURL } from "../../util/url.js";
 import type { Endpoint } from "../endpoint/Endpoint.js";
 import { APIProvider } from "./APIProvider.js";
-/** Options for a `ClientAPIProvider`. */
+/**
+ * Options for constructing a `ClientAPIProvider`.
+ *
+ * @see https://dhoulb.github.io/shelving/api/provider/ClientAPIProvider/ClientAPIProviderOptions
+ */
 export interface ClientAPIProviderOptions {
     /**
      * The common base URL for all rendered endpoint requests.
@@ -35,16 +39,69 @@ export interface ClientAPIProviderOptions {
  * - Parses JSON responses and throws `ResponseError` for non-2xx responses.
  * - Extendable with custom request-building and response-parsing logic by overriding `createRequest()` and `parseResponse()`.
  * - Wrap in `ValidationAPIProvider` to add automatic validation of request payloads and response results against endpoint schemas.
+ *
+ * @example
+ * const provider = new ClientAPIProvider({ url: "https://api.example.com" });
+ * const user = await provider.call(getUser, { id: "abc" });
+ *
+ * @see https://dhoulb.github.io/shelving/api/provider/ClientAPIProvider/ClientAPIProvider
  */
 export declare class ClientAPIProvider<P = unknown, R = unknown> extends APIProvider<P, R> {
-    /** The common base URL for all rendered endpoint requests. */
+    /**
+     * The common base URL for all rendered endpoint requests.
+     *
+     * @see https://dhoulb.github.io/shelving/api/provider/ClientAPIProvider/ClientAPIProvider/url
+     */
     readonly url: URL;
-    /** Default options used for HTTP requests created with `this.createRequest()` and `this.fetch()` */
+    /**
+     * Default options used for HTTP requests created with `this.createRequest()` and `this.fetch()`
+     *
+     * @see https://dhoulb.github.io/shelving/api/provider/ClientAPIProvider/ClientAPIProvider/options
+     */
     readonly options: RequestOptions;
-    /** Timeout in milliseconds before the request is aborted, or `0` for no timeout. */
+    /**
+     * Timeout in milliseconds before the request is aborted, or `0` for no timeout.
+     *
+     * @see https://dhoulb.github.io/shelving/api/provider/ClientAPIProvider/ClientAPIProvider/timeout
+     */
     readonly timeout: number;
+    /**
+     * Create a `ClientAPIProvider` from a base URL and request options.
+     *
+     * @param options The `ClientAPIProviderOptions` configuring the base `url`, default request `options`, and `timeout`.
+     * @throws {RequiredError} if `url` cannot be resolved to a valid base URL.
+     * @example new ClientAPIProvider({ url: "https://api.example.com" })
+     * @see https://dhoulb.github.io/shelving/api/provider/ClientAPIProvider/ClientAPIProvider
+     */
     constructor({ url, options, timeout }: ClientAPIProviderOptions);
+    /**
+     * Render the full request URL, appending `?query` params for `HEAD` and `GET` requests.
+     *
+     * @param endpoint The endpoint whose path is rendered into the base URL.
+     * @param payload The payload supplying `{placeholder}` and query-param values.
+     * @param caller The function to attribute thrown errors to (defaults to this method).
+     * @returns The fully resolved request `URL`.
+     * @throws {RequiredError} if this endpoint's path has `{placeholders}` but `payload` is not a data object.
+     * @throws {RequiredError} if this is a `HEAD` or `GET` request but `payload` is not a data object.
+     * @example provider.renderURL(getUser, { id: "abc" })
+     * @see https://dhoulb.github.io/shelving/api/provider/ClientAPIProvider/ClientAPIProvider/renderURL
+     */
     renderURL<PP extends P, RR extends R>(endpoint: Endpoint<PP, RR>, payload: PP, caller?: AnyCaller): URL;
+    /**
+     * Create a `Request` for an endpoint, rendering payload into the URL or body depending on the method.
+     * - `HEAD` and `GET` requests carry their payload as `?query` params; other methods carry it as the body.
+     * - Merges `options` over the provider's default options and attaches a timeout `AbortSignal` when `timeout` is set.
+     *
+     * @param endpoint The endpoint the request targets.
+     * @param payload The payload to embed into the `Request`.
+     * @param options Per-call `RequestOptions` merged over the provider's defaults.
+     * @param caller The function to attribute thrown errors to (defaults to this method).
+     * @returns The created `Request`.
+     * @throws {RequiredError} if this endpoint's path has `{placeholders}` but `payload` is not a data object.
+     * @throws {RequiredError} if this is a `HEAD` or `GET` request but `payload` is not a data object.
+     * @example provider.createRequest(getUser, { id: "abc" })
+     * @see https://dhoulb.github.io/shelving/api/provider/ClientAPIProvider/ClientAPIProvider/createRequest
+     */
     createRequest<PP extends P, RR extends R>(endpoint: Endpoint<PP, RR>, payload: PP, options?: RequestOptions, caller?: AnyCaller): Request;
     /** Internal implementation function for `createRequest()` used for requests that have no body. */
     protected _createHeadRequest(method: RequestHeadMethod, //
@@ -52,6 +109,25 @@ export declare class ClientAPIProvider<P = unknown, R = unknown> extends APIProv
     /** Internal implementation function for `createRequest()` used for requests that have a body.  */
     protected _createBodyRequest(method: RequestBodyMethod, //
     url: PossibleURL, payload: P, options: RequestOptions, caller: AnyCaller): Request;
+    /**
+     * Send the request over the network using the global `fetch()` API.
+     *
+     * @param request The `Request` to send.
+     * @returns A promise resolving to the `Response`.
+     * @example await provider.fetch(request)
+     * @see https://dhoulb.github.io/shelving/api/provider/ClientAPIProvider/ClientAPIProvider/fetch
+     */
     fetch(request: Request): Promise<Response>;
+    /**
+     * Parse a response body into a result, throwing `ResponseError` for non-2xx responses.
+     *
+     * @param _endpoint The endpoint the response was produced for.
+     * @param response The `Response` to parse.
+     * @param caller The function to attribute thrown errors to (defaults to this method).
+     * @returns A promise resolving to the parsed result.
+     * @throws {ResponseError} if the response status is non-2xx.
+     * @example await provider.parseResponse(getUser, response)
+     * @see https://dhoulb.github.io/shelving/api/provider/ClientAPIProvider/ClientAPIProvider/parseResponse
+     */
     parseResponse<PP extends P, RR extends R>(_endpoint: Endpoint<PP, RR>, response: Response, caller?: AnyCaller): Promise<RR>;
 }

package/api/provider/ClientAPIProvider.js

@@ -13,20 +13,58 @@ import { APIProvider } from "./APIProvider.js";
  * - Parses JSON responses and throws `ResponseError` for non-2xx responses.
  * - Extendable with custom request-building and response-parsing logic by overriding `createRequest()` and `parseResponse()`.
  * - Wrap in `ValidationAPIProvider` to add automatic validation of request payloads and response results against endpoint schemas.
+ *
+ * @example
+ * const provider = new ClientAPIProvider({ url: "https://api.example.com" });
+ * const user = await provider.call(getUser, { id: "abc" });
+ *
+ * @see https://dhoulb.github.io/shelving/api/provider/ClientAPIProvider/ClientAPIProvider
  */
 export class ClientAPIProvider extends APIProvider {
-    /** The common base URL for all rendered endpoint requests. */
+    /**
+     * The common base URL for all rendered endpoint requests.
+     *
+     * @see https://dhoulb.github.io/shelving/api/provider/ClientAPIProvider/ClientAPIProvider/url
+     */
     url;
-    /** Default options used for HTTP requests created with `this.createRequest()` and `this.fetch()` */
+    /**
+     * Default options used for HTTP requests created with `this.createRequest()` and `this.fetch()`
+     *
+     * @see https://dhoulb.github.io/shelving/api/provider/ClientAPIProvider/ClientAPIProvider/options
+     */
     options;
-    /** Timeout in milliseconds before the request is aborted, or `0` for no timeout. */
+    /**
+     * Timeout in milliseconds before the request is aborted, or `0` for no timeout.
+     *
+     * @see https://dhoulb.github.io/shelving/api/provider/ClientAPIProvider/ClientAPIProvider/timeout
+     */
     timeout;
+    /**
+     * Create a `ClientAPIProvider` from a base URL and request options.
+     *
+     * @param options The `ClientAPIProviderOptions` configuring the base `url`, default request `options`, and `timeout`.
+     * @throws {RequiredError} if `url` cannot be resolved to a valid base URL.
+     * @example new ClientAPIProvider({ url: "https://api.example.com" })
+     * @see https://dhoulb.github.io/shelving/api/provider/ClientAPIProvider/ClientAPIProvider
+     */
     constructor({ url, options = {}, timeout = 20_000 }) {
         super();
         this.url = requireBaseURL(url, ClientAPIProvider);
         this.options = options;
         this.timeout = timeout;
     }
+    /**
+     * Render the full request URL, appending `?query` params for `HEAD` and `GET` requests.
+     *
+     * @param endpoint The endpoint whose path is rendered into the base URL.
+     * @param payload The payload supplying `{placeholder}` and query-param values.
+     * @param caller The function to attribute thrown errors to (defaults to this method).
+     * @returns The fully resolved request `URL`.
+     * @throws {RequiredError} if this endpoint's path has `{placeholders}` but `payload` is not a data object.
+     * @throws {RequiredError} if this is a `HEAD` or `GET` request but `payload` is not a data object.
+     * @example provider.renderURL(getUser, { id: "abc" })
+     * @see https://dhoulb.github.io/shelving/api/provider/ClientAPIProvider/ClientAPIProvider/renderURL
+     */
     renderURL(endpoint, payload, caller = this.renderURL) {
         // Construct the full URL from `this.url` and the rendered path.
         // Adding the `.` turns the absolute path from `renderPath()` into a relative URL.
@@ -43,6 +81,21 @@ export class ClientAPIProvider extends APIProvider {
         }
         return url;
     }
+    /**
+     * Create a `Request` for an endpoint, rendering payload into the URL or body depending on the method.
+     * - `HEAD` and `GET` requests carry their payload as `?query` params; other methods carry it as the body.
+     * - Merges `options` over the provider's default options and attaches a timeout `AbortSignal` when `timeout` is set.
+     *
+     * @param endpoint The endpoint the request targets.
+     * @param payload The payload to embed into the `Request`.
+     * @param options Per-call `RequestOptions` merged over the provider's defaults.
+     * @param caller The function to attribute thrown errors to (defaults to this method).
+     * @returns The created `Request`.
+     * @throws {RequiredError} if this endpoint's path has `{placeholders}` but `payload` is not a data object.
+     * @throws {RequiredError} if this is a `HEAD` or `GET` request but `payload` is not a data object.
+     * @example provider.createRequest(getUser, { id: "abc" })
+     * @see https://dhoulb.github.io/shelving/api/provider/ClientAPIProvider/ClientAPIProvider/createRequest
+     */
     createRequest(endpoint, payload, options, caller = this.createRequest) {
         // Render the path into the base URL.
         const url = this.renderURL(endpoint, payload, caller);
@@ -67,10 +120,28 @@ export class ClientAPIProvider extends APIProvider {
     url, payload, options, caller) {
         return createRequest(method, url, payload, options, caller);
     }
-    // Override to set default functionality of a client provider to send requests over the network with `fetch()` and parse responses with `parseResponse()`.
+    /**
+     * Send the request over the network using the global `fetch()` API.
+     *
+     * @param request The `Request` to send.
+     * @returns A promise resolving to the `Response`.
+     * @example await provider.fetch(request)
+     * @see https://dhoulb.github.io/shelving/api/provider/ClientAPIProvider/ClientAPIProvider/fetch
+     */
     async fetch(request) {
         return fetch(request);
     }
+    /**
+     * Parse a response body into a result, throwing `ResponseError` for non-2xx responses.
+     *
+     * @param _endpoint The endpoint the response was produced for.
+     * @param response The `Response` to parse.
+     * @param caller The function to attribute thrown errors to (defaults to this method).
+     * @returns A promise resolving to the parsed result.
+     * @throws {ResponseError} if the response status is non-2xx.
+     * @example await provider.parseResponse(getUser, response)
+     * @see https://dhoulb.github.io/shelving/api/provider/ClientAPIProvider/ClientAPIProvider/parseResponse
+     */
     async parseResponse(_endpoint, response, caller = this.parseResponse) {
         const { ok, status } = response;
         const content = await parseResponseBody(response, caller);

package/api/provider/DebugAPIProvider.d.ts

@@ -2,9 +2,48 @@ import type { AnyCaller } from "../../util/function.js";
 import type { RequestOptions } from "../../util/http.js";
 import type { Endpoint } from "../endpoint/Endpoint.js";
 import { ThroughAPIProvider } from "./ThroughAPIProvider.js";
-/** Provider that logs everything to the console in some detail to help diagnose issues in development. */
+/**
+ * Provider that logs every request, response, and error to the console in detail to help diagnose issues in development.
+ *
+ * @example
+ *  const api = new DebugAPIProvider(source);
+ *  await api.call(endpoint, payload); // logs request, response, and result
+ * @see https://dhoulb.github.io/shelving/api/provider/DebugAPIProvider/DebugAPIProvider
+ */
 export declare class DebugAPIProvider<P, R> extends ThroughAPIProvider<P, R> {
+    /**
+     * Build a request via the source provider, logging the endpoint and payload (or any error).
+     *
+     * @param endpoint The endpoint to build a request for.
+     * @param payload The payload to send.
+     * @param options Optional request options.
+     * @param caller The calling function used for error stack traces.
+     * @returns The built request.
+     * @throws Rethrows any error thrown while building the request (after logging it).
+     * @example api.createRequest(endpoint, payload)
+     * @see https://dhoulb.github.io/shelving/api/provider/DebugAPIProvider/DebugAPIProvider/createRequest
+     */
     createRequest<PP extends P, RR extends R>(endpoint: Endpoint<PP, RR>, payload: PP, options?: RequestOptions, caller?: AnyCaller): Request;
+    /**
+     * Fetch a request via the source provider, logging the full request and response (or any error).
+     *
+     * @param request The request to fetch.
+     * @returns Promise resolving to the response.
+     * @throws Rethrows any error thrown by the source provider (after logging it).
+     * @example await api.fetch(request)
+     * @see https://dhoulb.github.io/shelving/api/provider/DebugAPIProvider/DebugAPIProvider/fetch
+     */
     fetch(request: Request): Promise<Response>;
+    /**
+     * Parse a response via the source provider, logging the parsed result (or any error).
+     *
+     * @param endpoint The endpoint the response came from.
+     * @param response The response to parse.
+     * @param caller The calling function used for error stack traces.
+     * @returns Promise resolving to the parsed result.
+     * @throws Rethrows any error thrown while parsing (after logging it).
+     * @example await api.parseResponse(endpoint, response)
+     * @see https://dhoulb.github.io/shelving/api/provider/DebugAPIProvider/DebugAPIProvider/parseResponse
+     */
     parseResponse<PP extends P, RR extends R>(endpoint: Endpoint<PP, RR>, response: Response, caller?: AnyCaller): Promise<RR>;
 }

package/api/provider/DebugAPIProvider.js

@@ -1,8 +1,27 @@
 import { ANSI_FAILURE, ANSI_LEFT, ANSI_RIGHT, ANSI_SUCCESS, ANSI_WAITING } from "../../util/ansi.js";
 import { debugFullRequest, debugFullResponse, debugRequest } from "../../util/debug.js";
 import { ThroughAPIProvider } from "./ThroughAPIProvider.js";
-/** Provider that logs everything to the console in some detail to help diagnose issues in development. */
+/**
+ * Provider that logs every request, response, and error to the console in detail to help diagnose issues in development.
+ *
+ * @example
+ *  const api = new DebugAPIProvider(source);
+ *  await api.call(endpoint, payload); // logs request, response, and result
+ * @see https://dhoulb.github.io/shelving/api/provider/DebugAPIProvider/DebugAPIProvider
+ */
 export class DebugAPIProvider extends ThroughAPIProvider {
+    /**
+     * Build a request via the source provider, logging the endpoint and payload (or any error).
+     *
+     * @param endpoint The endpoint to build a request for.
+     * @param payload The payload to send.
+     * @param options Optional request options.
+     * @param caller The calling function used for error stack traces.
+     * @returns The built request.
+     * @throws Rethrows any error thrown while building the request (after logging it).
+     * @example api.createRequest(endpoint, payload)
+     * @see https://dhoulb.github.io/shelving/api/provider/DebugAPIProvider/DebugAPIProvider/createRequest
+     */
     createRequest(endpoint, payload, options, caller = this.createRequest) {
         try {
             const request = super.createRequest(endpoint, payload, options, caller);
@@ -14,6 +33,15 @@ export class DebugAPIProvider extends ThroughAPIProvider {
             throw reason;
         }
     }
+    /**
+     * Fetch a request via the source provider, logging the full request and response (or any error).
+     *
+     * @param request The request to fetch.
+     * @returns Promise resolving to the response.
+     * @throws Rethrows any error thrown by the source provider (after logging it).
+     * @example await api.fetch(request)
+     * @see https://dhoulb.github.io/shelving/api/provider/DebugAPIProvider/DebugAPIProvider/fetch
+     */
     async fetch(request) {
         try {
             console.debug(`${ANSI_RIGHT} ${await debugFullRequest(request)}`);
@@ -26,6 +54,17 @@ export class DebugAPIProvider extends ThroughAPIProvider {
             throw reason;
         }
     }
+    /**
+     * Parse a response via the source provider, logging the parsed result (or any error).
+     *
+     * @param endpoint The endpoint the response came from.
+     * @param response The response to parse.
+     * @param caller The calling function used for error stack traces.
+     * @returns Promise resolving to the parsed result.
+     * @throws Rethrows any error thrown while parsing (after logging it).
+     * @example await api.parseResponse(endpoint, response)
+     * @see https://dhoulb.github.io/shelving/api/provider/DebugAPIProvider/DebugAPIProvider/parseResponse
+     */
     async parseResponse(endpoint, response, caller = this.parseResponse) {
         try {
             const result = await super.parseResponse(endpoint, response, caller);

package/api/provider/JSONAPIProvider.d.ts

@@ -3,14 +3,30 @@ import { type RequestBodyMethod, type RequestOptions } from "../../util/http.js"
 import type { PossibleURL } from "../../util/url.js";
 import type { Endpoint } from "../endpoint/Endpoint.js";
 import { ClientAPIProvider } from "./ClientAPIProvider.js";
-/** API provider that always sends request bodies as JSON and parses responses as JSON. */
+/**
+ * Client API provider that always sends request bodies as JSON and parses responses as JSON.
+ * - Forces JSON encoding regardless of the `Content-Type` the server returns.
+ *
+ * @example
+ * const provider = new JSONAPIProvider({ url: "https://api.example.com" });
+ * const user = await provider.call(getUser, { id: "abc" });
+ *
+ * @see https://dhoulb.github.io/shelving/api/provider/JSONAPIProvider/JSONAPIProvider
+ */
 export declare class JSONAPIProvider<P = unknown, R = unknown> extends ClientAPIProvider<P, R> {
     protected _createBodyRequest(method: RequestBodyMethod, url: PossibleURL, payload: P, options: RequestOptions, caller: AnyCaller): Request;
     /**
      * Parse a JSON `Response` for an endpoint.
-     *
      * - Non-2xx responses become `ResponseError`.
      * - JSON is parsed even if the server omitted or mis-set the response content type.
+     *
+     * @param _endpoint The endpoint the response was produced for.
+     * @param response The `Response` to parse as JSON.
+     * @param caller The function to attribute thrown errors to (defaults to this method).
+     * @returns A promise resolving to the parsed JSON result.
+     * @throws {ResponseError} if the response status is non-2xx.
+     * @example await provider.parseResponse(getUser, response)
+     * @see https://dhoulb.github.io/shelving/api/provider/JSONAPIProvider/JSONAPIProvider/parseResponse
      */
     parseResponse<PP extends P, RR extends R>(_endpoint: Endpoint<PP, RR>, response: Response, caller?: AnyCaller): Promise<RR>;
 }

package/api/provider/JSONAPIProvider.js

@@ -2,16 +2,32 @@ import { ResponseError } from "../../error/ResponseError.js";
 import { getMessage } from "../../util/error.js";
 import { createJSONRequest, parseResponseJSON } from "../../util/http.js";
 import { ClientAPIProvider } from "./ClientAPIProvider.js";
-/** API provider that always sends request bodies as JSON and parses responses as JSON. */
+/**
+ * Client API provider that always sends request bodies as JSON and parses responses as JSON.
+ * - Forces JSON encoding regardless of the `Content-Type` the server returns.
+ *
+ * @example
+ * const provider = new JSONAPIProvider({ url: "https://api.example.com" });
+ * const user = await provider.call(getUser, { id: "abc" });
+ *
+ * @see https://dhoulb.github.io/shelving/api/provider/JSONAPIProvider/JSONAPIProvider
+ */
 export class JSONAPIProvider extends ClientAPIProvider {
     _createBodyRequest(method, url, payload, options, caller) {
         return createJSONRequest(method, url, payload, options, caller);
     }
     /**
      * Parse a JSON `Response` for an endpoint.
-     *
      * - Non-2xx responses become `ResponseError`.
      * - JSON is parsed even if the server omitted or mis-set the response content type.
+     *
+     * @param _endpoint The endpoint the response was produced for.
+     * @param response The `Response` to parse as JSON.
+     * @param caller The function to attribute thrown errors to (defaults to this method).
+     * @returns A promise resolving to the parsed JSON result.
+     * @throws {ResponseError} if the response status is non-2xx.
+     * @example await provider.parseResponse(getUser, response)
+     * @see https://dhoulb.github.io/shelving/api/provider/JSONAPIProvider/JSONAPIProvider/parseResponse
      */
     async parseResponse(_endpoint, response, caller = this.parseResponse) {
         const { ok, status } = response;

package/api/provider/LoggingAPIProvider.d.ts

@@ -2,13 +2,27 @@ import type { Callback } from "../../util/function.js";
 import type { APIProvider } from "./APIProvider.js";
 import { ThroughAPIProvider } from "./ThroughAPIProvider.js";
 /**
- * Provider that logs fetches to the console to keep useful logs in production.
- * - Defaults to calling `console.log()` for requests/responses and
+ * Provider that logs fetches to the console to keep useful request/response logs in production.
+ * - Defaults to logging requests, responses, and errors via the `log` utilities; each can be overridden.
+ *
+ * @example
+ *  const api = new LoggingAPIProvider(source);
+ *  await api.fetch(request); // logs request and response
+ * @see https://dhoulb.github.io/shelving/api/provider/LoggingAPIProvider/LoggingAPIProvider
  */
 export declare class LoggingAPIProvider<P, R> extends ThroughAPIProvider<P, R> {
     protected _logRequest: Callback<[Request]>;
     protected _logResponse: Callback<[Response, Request]>;
     protected _logError: Callback<[reason: unknown, Request]>;
+    /**
+     * Create a logging provider wrapping a source provider.
+     *
+     * @param source The source provider whose fetches are logged.
+     * @param onRequest Called to log each outgoing request.
+     * @param onResponse Called to log each response.
+     * @param onError Called to log each error.
+     * @example new LoggingAPIProvider(source)
+     */
     constructor(source: APIProvider<P, R>, 
     /** Log requests. */
     onRequest?: Callback<[Request]>, 
@@ -16,5 +30,14 @@ export declare class LoggingAPIProvider<P, R> extends ThroughAPIProvider<P, R> {
     onResponse?: Callback<[Response, Request]>, 
     /** Log errors for requests. */
     onError?: Callback<[reason: unknown, Request]>);
+    /**
+     * Fetch a request through the source provider, logging the request, response, and any error.
+     *
+     * @param request The request to fetch.
+     * @returns Promise resolving to the response.
+     * @throws Rethrows any error thrown by the source provider (after logging it).
+     * @example await api.fetch(request)
+     * @see https://dhoulb.github.io/shelving/api/provider/LoggingAPIProvider/LoggingAPIProvider/fetch
+     */
     fetch(request: Request): Promise<Response>;
 }

package/api/provider/LoggingAPIProvider.js

@@ -1,13 +1,27 @@
 import { logRequest, logRequestError, logRequestResponse } from "../../util/log.js";
 import { ThroughAPIProvider } from "./ThroughAPIProvider.js";
 /**
- * Provider that logs fetches to the console to keep useful logs in production.
- * - Defaults to calling `console.log()` for requests/responses and
+ * Provider that logs fetches to the console to keep useful request/response logs in production.
+ * - Defaults to logging requests, responses, and errors via the `log` utilities; each can be overridden.
+ *
+ * @example
+ *  const api = new LoggingAPIProvider(source);
+ *  await api.fetch(request); // logs request and response
+ * @see https://dhoulb.github.io/shelving/api/provider/LoggingAPIProvider/LoggingAPIProvider
  */
 export class LoggingAPIProvider extends ThroughAPIProvider {
     _logRequest;
     _logResponse;
     _logError;
+    /**
+     * Create a logging provider wrapping a source provider.
+     *
+     * @param source The source provider whose fetches are logged.
+     * @param onRequest Called to log each outgoing request.
+     * @param onResponse Called to log each response.
+     * @param onError Called to log each error.
+     * @example new LoggingAPIProvider(source)
+     */
     constructor(source, 
     /** Log requests. */
     onRequest = logRequest, 
@@ -20,6 +34,15 @@ export class LoggingAPIProvider extends ThroughAPIProvider {
         this._logResponse = onResponse;
         this._logError = onError;
     }
+    /**
+     * Fetch a request through the source provider, logging the request, response, and any error.
+     *
+     * @param request The request to fetch.
+     * @returns Promise resolving to the response.
+     * @throws Rethrows any error thrown by the source provider (after logging it).
+     * @example await api.fetch(request)
+     * @see https://dhoulb.github.io/shelving/api/provider/LoggingAPIProvider/LoggingAPIProvider/fetch
+     */
     async fetch(request) {
         try {
             this._logRequest(request);