shelving 1.236.0 → 1.236.2

package/api/endpoint/Endpoint.d.ts

@@ -7,93 +7,209 @@ import type { AbsolutePath } from "../../util/path.js";
 import { type TemplatePlaceholders } from "../../util/template.js";
 import type { EndpointCallback, EndpointHandler } from "./util.js";
 /**
- * An abstract API resource definition, used to specify types for e.g. serverless functions.
+ * A typed API resource definition pairing a method and path with payload and result schemas.
+ * - Acts as the contract both ends of an API agree on: providers render requests from it, handlers validate against it.
+ * - Path may contain `{placeholder}` segments that are filled from the payload at request time.
  *
  * @param method The method of the endpoint, e.g. `GET`
  * @param path Endpoint path, possibly including placeholders e.g. `/users/{id}`
  * @param payload A `Schema` for the payload of the endpoint.
  * @param result A `Schema` for the result of the endpoint.
+ *
+ * @example
+ * const getUser = new Endpoint("GET", "/users/{id}", USER_PAYLOAD, USER_RESULT);
+ *
+ * @see https://dhoulb.github.io/shelving/api/endpoint/Endpoint/Endpoint
  */
 export declare class Endpoint<P = unknown, R = unknown> {
-    /** Endpoint method. */
+    /**
+     * The HTTP method this endpoint responds to, e.g. `GET`
+     *
+     * @see https://dhoulb.github.io/shelving/api/endpoint/Endpoint/Endpoint/method
+     */
     readonly method: RequestMethod;
-    /** Endpoint path, possibly including placeholders e.g. `/users/{id}` */
+    /**
+     * Endpoint path, possibly including placeholders e.g. `/users/{id}`
+     *
+     * @see https://dhoulb.github.io/shelving/api/endpoint/Endpoint/Endpoint/path
+     */
     readonly path: AbsolutePath;
-    /** Endpoint path, possibly including placeholders e.g. `/users/{id}` */
+    /**
+     * The `{placeholder}` segments extracted from `path`, used to render and match URLs.
+     *
+     * @see https://dhoulb.github.io/shelving/api/endpoint/Endpoint/Endpoint/placeholders
+     */
     readonly placeholders: TemplatePlaceholders;
-    /** Payload schema. */
+    /**
+     * The `Schema` that request payloads are validated against.
+     *
+     * @see https://dhoulb.github.io/shelving/api/endpoint/Endpoint/Endpoint/payload
+     */
     readonly payload: Schema<P>;
-    /** Result schema. */
+    /**
+     * The `Schema` that response results are validated against.
+     *
+     * @see https://dhoulb.github.io/shelving/api/endpoint/Endpoint/Endpoint/result
+     */
     readonly result: Schema<R>;
     constructor(method: RequestMethod, path: AbsolutePath, payload: Schema<P>, result: Schema<R>);
     /**
      * Render the path for this endpoint with the given payload.
      * - Path might contain `{placeholder}` values that are replaced with values from `payload`.
      *
-     * @returns URL string combining `base` with this endpoint's path, with any `{placeholders}` rendered and `?query` params added.
-     *
+     * @param payload The payload supplying values for any `{placeholders}` in the path.
+     * @param caller The function to attribute thrown errors to (defaults to this method).
+     * @returns The rendered absolute path, with any `{placeholders}` filled from `payload`.
      * @throws {RequiredError} if this endpoint's path has `{placeholders}` but `payload` is not a data object.
+     * @example endpoint.renderPath({ id: "abc" }) // "/users/abc"
+     * @see https://dhoulb.github.io/shelving/api/endpoint/Endpoint/Endpoint/renderPath
      */
     renderPath(payload: P, caller?: AnyCaller): AbsolutePath;
     /**
      * Match a method/path pair against this endpoint and return any matched `{placeholder}` params.
+     *
+     * @param method The request method to compare against this endpoint's method.
+     * @param path The request path to match against this endpoint's path template.
+     * @param caller The function to attribute thrown errors to (defaults to this method).
+     * @returns A dictionary of matched `{placeholder}` params, or `undefined` if the method or path doesn't match.
+     * @example endpoint.match("GET", "/users/abc") // { id: "abc" }
+     * @see https://dhoulb.github.io/shelving/api/endpoint/Endpoint/Endpoint/match
      */
     match(method: RequestMethod, path: AbsolutePath, caller?: AnyCaller): RequestParams | undefined;
     /**
      * Create an endpoint handler pairing for this endpoint.
+     *
      * @param callback The callback function that implements the logic for this endpoint by receiving the payload and returning the response.
      * @returns An `EndpointHandler` object combining this endpoint and the callback into a single typed object.
+     * @example endpoint.handler((payload, request) => ({ ...payload }))
+     * @see https://dhoulb.github.io/shelving/api/endpoint/Endpoint/Endpoint/handler
      */
     handler<C>(callback: EndpointCallback<P, R, C>): EndpointHandler<P, R, C>;
-    /** Convert to string, e.g. `GET /user/{id}` */
+    /**
+     * Convert this endpoint to a string in `METHOD /path` form, e.g. `GET /user/{id}`
+     *
+     * @returns The method and path joined with a space, e.g. `GET /user/{id}`
+     * @example endpoint.toString() // "GET /users/{id}"
+     * @see https://dhoulb.github.io/shelving/api/endpoint/Endpoint/Endpoint/toString
+     */
     toString(): string;
 }
-/** Any endpoint. */
+/**
+ * An `Endpoint` with any payload and result type, for use where the specific types don't matter.
+ *
+ * @see https://dhoulb.github.io/shelving/api/endpoint/Endpoint/AnyEndpoint
+ */
 export type AnyEndpoint = Endpoint<any, any>;
-/** List of endpoints. */
+/**
+ * An immutable list of endpoints.
+ *
+ * @see https://dhoulb.github.io/shelving/api/endpoint/Endpoint/Endpoints
+ */
 export type Endpoints = ImmutableArray<AnyEndpoint>;
-/** Extract the payload type from a `Endpoint`. */
+/**
+ * Extract the payload type from an `Endpoint`.
+ *
+ * @see https://dhoulb.github.io/shelving/api/endpoint/Endpoint/PayloadType
+ */
 export type PayloadType<X extends Endpoint<unknown, unknown>> = X extends Endpoint<infer Y, unknown> ? Y : never;
-/** Extract the result type from a `Endpoint`. */
+/**
+ * Extract the result type from an `Endpoint`.
+ *
+ * @see https://dhoulb.github.io/shelving/api/endpoint/Endpoint/EndpointType
+ */
 export type EndpointType<X extends Endpoint<unknown, unknown>> = X extends Endpoint<unknown, infer Y> ? Y : never;
 /**
- * Represent a HEAD request to a specified path, with validated payload and return types.
- * "The HEAD method requests a representation of the specified resource. Requests using HEAD should only retrieve data and should not contain a request content."
+ * Define a `HEAD` endpoint at a path, with validated payload and result types.
+ * - "The HEAD method requests a representation of the specified resource. Requests using HEAD should only retrieve data and should not contain a request content."
+ *
+ * *Factory for `Endpoint`.*
+ *
+ * @param path The endpoint path, possibly including `{placeholders}`
+ * @param payload An optional `Schema` validating the request payload.
+ * @param result An optional `Schema` validating the response result.
+ * @returns An `Endpoint` configured for the `HEAD` method.
+ * @example HEAD("/users/{id}")
+ * @see https://dhoulb.github.io/shelving/api/endpoint/Endpoint/HEAD
  */
 export declare function HEAD<P extends Data, R>(path: AbsolutePath, payload?: Schema<P>, result?: Schema<R>): Endpoint<P, R>;
 export declare function HEAD<P extends Data>(path: AbsolutePath, payload: Schema<P>): Endpoint<P, undefined>;
 export declare function HEAD<R>(path: AbsolutePath, payload: undefined, result: Schema<R>): Endpoint<undefined, R>;
 /**
- * Represent a GET request to a specified path, with validated payload and return types.
- * "The GET method requests a representation of the specified resource. Requests using GET should only retrieve data and should not contain a request content."
+ * Define a `GET` endpoint at a path, with validated payload and result types.
+ * - "The GET method requests a representation of the specified resource. Requests using GET should only retrieve data and should not contain a request content."
+ *
+ * *Factory for `Endpoint`.*
+ *
+ * @param path The endpoint path, possibly including `{placeholders}`
+ * @param payload An optional `Schema` validating the request payload.
+ * @param result An optional `Schema` validating the response result.
+ * @returns An `Endpoint` configured for the `GET` method.
+ * @example GET("/users/{id}", undefined, USER)
+ * @see https://dhoulb.github.io/shelving/api/endpoint/Endpoint/GET
  */
 export declare function GET<P extends Data, R>(path: AbsolutePath, payload?: Schema<P>, result?: Schema<R>): Endpoint<P, R>;
 export declare function GET<P extends Data>(path: AbsolutePath, payload: Schema<P>): Endpoint<P, undefined>;
 export declare function GET<R>(path: AbsolutePath, payload: undefined, result: Schema<R>): Endpoint<undefined, R>;
 /**
- * Represent a POST request to a specified path, with validated payload and return types.
- * "The POST method submits an entity to the specified resource, often causing a change in state or side effects on the server.
+ * Define a `POST` endpoint at a path, with validated payload and result types.
+ * - "The POST method submits an entity to the specified resource, often causing a change in state or side effects on the server."
+ *
+ * *Factory for `Endpoint`.*
+ *
+ * @param path The endpoint path, possibly including `{placeholders}`
+ * @param payload An optional `Schema` validating the request payload.
+ * @param result An optional `Schema` validating the response result.
+ * @returns An `Endpoint` configured for the `POST` method.
+ * @example POST("/users", USER, USER_RESULT)
+ * @see https://dhoulb.github.io/shelving/api/endpoint/Endpoint/POST
  */
 export declare function POST<P, R>(path: AbsolutePath, payload?: Schema<P>, result?: Schema<R>): Endpoint<P, R>;
 export declare function POST<P>(path: AbsolutePath, payload: Schema<P>): Endpoint<P, undefined>;
 export declare function POST<R>(path: AbsolutePath, payload: undefined, result: Schema<R>): Endpoint<undefined, R>;
 /**
- * Represent a PUT request to a specified path, with validated payload and return types.
- * "The PUT method replaces all current representations of the target resource with the request content."
+ * Define a `PUT` endpoint at a path, with validated payload and result types.
+ * - "The PUT method replaces all current representations of the target resource with the request content."
+ *
+ * *Factory for `Endpoint`.*
+ *
+ * @param path The endpoint path, possibly including `{placeholders}`
+ * @param payload An optional `Schema` validating the request payload.
+ * @param result An optional `Schema` validating the response result.
+ * @returns An `Endpoint` configured for the `PUT` method.
+ * @example PUT("/users/{id}", USER)
+ * @see https://dhoulb.github.io/shelving/api/endpoint/Endpoint/PUT
  */
 export declare function PUT<P, R>(path: AbsolutePath, payload?: Schema<P>, result?: Schema<R>): Endpoint<P, R>;
 export declare function PUT<P>(path: AbsolutePath, payload: Schema<P>): Endpoint<P, undefined>;
 export declare function PUT<R>(path: AbsolutePath, payload: undefined, result: Schema<R>): Endpoint<undefined, R>;
 /**
- * Represent a PATCH request to a specified path, with validated payload and return types.
- * "The PATCH method applies partial modifications to a resource."
+ * Define a `PATCH` endpoint at a path, with validated payload and result types.
+ * - "The PATCH method applies partial modifications to a resource."
+ *
+ * *Factory for `Endpoint`.*
+ *
+ * @param path The endpoint path, possibly including `{placeholders}`
+ * @param payload An optional `Schema` validating the request payload.
+ * @param result An optional `Schema` validating the response result.
+ * @returns An `Endpoint` configured for the `PATCH` method.
+ * @example PATCH("/users/{id}", PARTIAL_USER)
+ * @see https://dhoulb.github.io/shelving/api/endpoint/Endpoint/PATCH
  */
 export declare function PATCH<P, R>(path: AbsolutePath, payload?: Schema<P>, result?: Schema<R>): Endpoint<P, R>;
 export declare function PATCH<P>(path: AbsolutePath, payload: Schema<P>): Endpoint<P, undefined>;
 export declare function PATCH<R>(path: AbsolutePath, payload: undefined, result: Schema<R>): Endpoint<undefined, R>;
 /**
- * Represent a DELETE request to a specified path, with validated payload and return types.
- * "The DELETE method deletes the specified resource."
+ * Define a `DELETE` endpoint at a path, with validated payload and result types.
+ * - "The DELETE method deletes the specified resource."
+ *
+ * *Factory for `Endpoint`.*
+ *
+ * @param path The endpoint path, possibly including `{placeholders}`
+ * @param payload An optional `Schema` validating the request payload.
+ * @param result An optional `Schema` validating the response result.
+ * @returns An `Endpoint` configured for the `DELETE` method.
+ * @example DELETE("/users/{id}")
+ * @see https://dhoulb.github.io/shelving/api/endpoint/Endpoint/DELETE
  */
 export declare function DELETE<P, R>(path: AbsolutePath, payload?: Schema<P>, result?: Schema<R>): Endpoint<P, R>;
 export declare function DELETE<P>(path: AbsolutePath, payload: Schema<P>): Endpoint<P, undefined>;

package/api/endpoint/Endpoint.js

@@ -3,23 +3,50 @@ import { UNDEFINED } from "../../schema/Schema.js";
 import { isData } from "../../util/data.js";
 import { getPlaceholders, matchPathTemplate, renderPathTemplate } from "../../util/template.js";
 /**
- * An abstract API resource definition, used to specify types for e.g. serverless functions.
+ * A typed API resource definition pairing a method and path with payload and result schemas.
+ * - Acts as the contract both ends of an API agree on: providers render requests from it, handlers validate against it.
+ * - Path may contain `{placeholder}` segments that are filled from the payload at request time.
  *
  * @param method The method of the endpoint, e.g. `GET`
  * @param path Endpoint path, possibly including placeholders e.g. `/users/{id}`
  * @param payload A `Schema` for the payload of the endpoint.
  * @param result A `Schema` for the result of the endpoint.
+ *
+ * @example
+ * const getUser = new Endpoint("GET", "/users/{id}", USER_PAYLOAD, USER_RESULT);
+ *
+ * @see https://dhoulb.github.io/shelving/api/endpoint/Endpoint/Endpoint
  */
 export class Endpoint {
-    /** Endpoint method. */
+    /**
+     * The HTTP method this endpoint responds to, e.g. `GET`
+     *
+     * @see https://dhoulb.github.io/shelving/api/endpoint/Endpoint/Endpoint/method
+     */
     method;
-    /** Endpoint path, possibly including placeholders e.g. `/users/{id}` */
+    /**
+     * Endpoint path, possibly including placeholders e.g. `/users/{id}`
+     *
+     * @see https://dhoulb.github.io/shelving/api/endpoint/Endpoint/Endpoint/path
+     */
     path;
-    /** Endpoint path, possibly including placeholders e.g. `/users/{id}` */
+    /**
+     * The `{placeholder}` segments extracted from `path`, used to render and match URLs.
+     *
+     * @see https://dhoulb.github.io/shelving/api/endpoint/Endpoint/Endpoint/placeholders
+     */
     placeholders;
-    /** Payload schema. */
+    /**
+     * The `Schema` that request payloads are validated against.
+     *
+     * @see https://dhoulb.github.io/shelving/api/endpoint/Endpoint/Endpoint/payload
+     */
     payload;
-    /** Result schema. */
+    /**
+     * The `Schema` that response results are validated against.
+     *
+     * @see https://dhoulb.github.io/shelving/api/endpoint/Endpoint/Endpoint/result
+     */
     result;
     constructor(method, path, payload, result) {
         this.method = method;
@@ -32,9 +59,12 @@ export class Endpoint {
      * Render the path for this endpoint with the given payload.
      * - Path might contain `{placeholder}` values that are replaced with values from `payload`.
      *
-     * @returns URL string combining `base` with this endpoint's path, with any `{placeholders}` rendered and `?query` params added.
-     *
+     * @param payload The payload supplying values for any `{placeholders}` in the path.
+     * @param caller The function to attribute thrown errors to (defaults to this method).
+     * @returns The rendered absolute path, with any `{placeholders}` filled from `payload`.
      * @throws {RequiredError} if this endpoint's path has `{placeholders}` but `payload` is not a data object.
+     * @example endpoint.renderPath({ id: "abc" }) // "/users/abc"
+     * @see https://dhoulb.github.io/shelving/api/endpoint/Endpoint/Endpoint/renderPath
      */
     renderPath(payload, caller = this.renderPath) {
         // Placeholders.
@@ -47,6 +77,13 @@ export class Endpoint {
     }
     /**
      * Match a method/path pair against this endpoint and return any matched `{placeholder}` params.
+     *
+     * @param method The request method to compare against this endpoint's method.
+     * @param path The request path to match against this endpoint's path template.
+     * @param caller The function to attribute thrown errors to (defaults to this method).
+     * @returns A dictionary of matched `{placeholder}` params, or `undefined` if the method or path doesn't match.
+     * @example endpoint.match("GET", "/users/abc") // { id: "abc" }
+     * @see https://dhoulb.github.io/shelving/api/endpoint/Endpoint/Endpoint/match
      */
     match(method, path, caller = this.match) {
         if (method !== this.method)
@@ -55,13 +92,22 @@ export class Endpoint {
     }
     /**
      * Create an endpoint handler pairing for this endpoint.
+     *
      * @param callback The callback function that implements the logic for this endpoint by receiving the payload and returning the response.
      * @returns An `EndpointHandler` object combining this endpoint and the callback into a single typed object.
+     * @example endpoint.handler((payload, request) => ({ ...payload }))
+     * @see https://dhoulb.github.io/shelving/api/endpoint/Endpoint/Endpoint/handler
      */
     handler(callback) {
         return { endpoint: this, callback };
     }
-    /** Convert to string, e.g. `GET /user/{id}` */
+    /**
+     * Convert this endpoint to a string in `METHOD /path` form, e.g. `GET /user/{id}`
+     *
+     * @returns The method and path joined with a space, e.g. `GET /user/{id}`
+     * @example endpoint.toString() // "GET /users/{id}"
+     * @see https://dhoulb.github.io/shelving/api/endpoint/Endpoint/Endpoint/toString
+     */
     toString() {
         return `${this.method} ${this.path}`;
     }

package/api/endpoint/util.d.ts

@@ -2,7 +2,7 @@ import type { AnyCaller } from "../../util/function.js";
 import { type PossibleURL } from "../../util/url.js";
 import type { Endpoint } from "./Endpoint.js";
 /**
- * A function that handles an endpoint request, with a payload and returns a result.
+ * A function that handles an endpoint request, receiving a validated payload and returning a result.
  *
  * @param payload The payload for the callback combining the `{placeholders}`, `?search` params, and body content (this has been validated against the Endpoint's payload schema).
  * @param request The original incoming request object.
@@ -10,26 +10,48 @@ import type { Endpoint } from "./Endpoint.js";
  *
  * @returns {Response} Returning a `Response` object (this will pass back to the client without validation).
  * @returns {R} Returning the return type of the handler (this will be validated against the Endpoint's result schema).
+ *
+ * @see https://dhoulb.github.io/shelving/api/endpoint/util/EndpointCallback
  */
 export type EndpointCallback<P, R, C = void> = (payload: P, request: Request, context: C) => R | Response | Promise<R | Response>;
-/** A typed endpoint definition paired with its implementation callback. */
+/**
+ * A typed endpoint definition paired with its implementation callback.
+ * - Created with `Endpoint.handler()`; matched and invoked by `handleEndpoints()`.
+ *
+ * @see https://dhoulb.github.io/shelving/api/endpoint/util/EndpointHandler
+ */
 export interface EndpointHandler<P, R, C = void> {
     readonly endpoint: Endpoint<P, R>;
     readonly callback: EndpointCallback<P, R, C>;
 }
-/** Any endpoint handler. */
+/**
+ * An `EndpointHandler` with any payload and result type, for use where the specific types don't matter.
+ *
+ * @see https://dhoulb.github.io/shelving/api/endpoint/util/AnyEndpointHandler
+ */
 export type AnyEndpointHandler<C = any> = EndpointHandler<any, any, C>;
-/** A collection of endpoint handlers that can be matched and invoked by `handleEndpoints()`. */
+/**
+ * A collection of endpoint handlers that can be matched and invoked by `handleEndpoints()`.
+ *
+ * @see https://dhoulb.github.io/shelving/api/endpoint/util/EndpointHandlers
+ */
 export type EndpointHandlers<C = void> = Iterable<AnyEndpointHandler<C>>;
 /**
  * Handle a `Request` with the first matching endpoint handler after stripping any base-path prefix from the request pathname.
  * - The original `Request` object is passed through to the callback unchanged.
  * - Path params and query params are merged before payload validation.
  *
- * @param request The input request to handle.
- *
  * @param base The base URL for the API, e.g. `https://myapi.com/a/b`
  * - `pathname` of this URL gets trimmed from `request.path` to form the target path when matching against endpoints, e.g. `/a/b/c/d` will produce `/c/d` for matching.
+ * @param handlers The iterable of `EndpointHandler` objects to match the request against, in order.
+ * @param request The input request to handle.
+ * @param context The additional context value passed through to the matched handler's callback.
+ * @param caller The function to attribute thrown errors to (defaults to this function).
+ * @returns A promise resolving to the `Response` produced by the matching handler.
+ * @throws {MethodNotAllowedError} if the request method is not a supported HTTP method.
+ * @throws {NotFoundError} if no base path matches, or no endpoint matches the target path.
+ * @example await handleEndpoints("https://myapi.com", [getUser.handler(loadUser)], request, undefined)
+ * @see https://dhoulb.github.io/shelving/api/endpoint/util/handleEndpoints
  */
 export declare function handleEndpoints<C>(base: PossibleURL, handlers: EndpointHandlers<C>, request: Request, context: C, caller?: AnyCaller): Promise<Response>;
 export declare function handleEndpoints(base: PossibleURL, handlers: EndpointHandlers<void>, request: Request, context?: undefined, caller?: AnyCaller): Promise<Response>;

package/api/provider/APIProvider.d.ts

@@ -1,47 +1,91 @@
 import type { AnyCaller } from "../../util/function.js";
 import type { RequestOptions } from "../../util/http.js";
 import type { Endpoint } from "../endpoint/Endpoint.js";
-/** Provider for API endpoints rooted at a common base URL. */
+/**
+ * Abstract base for API providers that send requests to a set of `Endpoint` definitions rooted at a common base URL.
+ * - Concrete subclasses implement `renderURL()`, `createRequest()`, `fetch()`, and `parseResponse()`; `call()` orchestrates them.
+ * - Implements `AsyncDisposable` so providers can be wrapped and disposed in a chain.
+ *
+ * @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/APIProvider/APIProvider
+ */
 export declare abstract class APIProvider<P = unknown, R = unknown> implements AsyncDisposable {
-    /** The base URL for this API. */
+    /**
+     * The common base URL that every endpoint request is resolved against.
+     *
+     * @see https://dhoulb.github.io/shelving/api/provider/APIProvider/APIProvider/url
+     */
     abstract readonly url: URL;
     /**
      * Render the full final URL for an API request to a given endpoint with a given payload.
      * - Includes `?query` params if this is a `HEAD` or `GET` request.
      *
+     * @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" }) // URL("https://api.example.com/users/abc")
+     * @see https://dhoulb.github.io/shelving/api/provider/APIProvider/APIProvider/renderURL
      */
     abstract renderURL<PP extends P, RR extends R>(endpoint: Endpoint<PP, RR>, payload: PP, caller?: AnyCaller): URL;
     /**
      * Create a `Request` that targets this endpoint with a given base URL.
      *
+     * @param endpoint The endpoint the request targets.
      * @param payload The payload to embed into the `Request` to send to the endpoint.
      * - Path `{placeholders}` are rendered from `payload`
      * - For `GET` and `HEAD`, remaining `payload` fields are appended as `?query` params.
      * - For all other requests, `payload` is sent as the body.
-     *
-     * @param options The `RequestOptions` to use when creating the `Request`
-     * - Merges `options` with `this.options` to make the final request options.
-     *
-     * @returns The created request.
-     * - Merges `options` with `this.options` to make the final request options.
-     * - Includes an `AbortSignal` based on `this.timeout` if it's set to a number in milliseconds.
-     * - The timeout `AbortSignal` is merged with any manual signal set in `
-     *
+     * @param options The `RequestOptions` to use when creating the `Request`, merged over the provider's own options.
+     * @param caller The function to attribute thrown errors to (defaults to this method).
+     * @returns The created `Request`, including any timeout `AbortSignal` configured on the provider.
      * @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/APIProvider/APIProvider/createRequest
      */
     abstract createRequest<PP extends P, RR extends R>(endpoint: Endpoint<PP, RR>, payload: PP, options?: RequestOptions, caller?: AnyCaller): Request;
-    /** Fetch a `Resource` using this provider (defaults to Javascript `fetch()` API). */
+    /**
+     * Send a `Request` and return its `Response` (defaults to the JavaScript `fetch()` API).
+     *
+     * @param request The `Request` to send.
+     * @returns A promise resolving to the `Response`.
+     * @example const response = await provider.fetch(request);
+     * @see https://dhoulb.github.io/shelving/api/provider/APIProvider/APIProvider/fetch
+     */
     abstract fetch(request: Request): Promise<Response>;
     /**
-     * Parse an HTTP `Response` for this endpoint.
+     * Parse an HTTP `Response` for this endpoint into a result value.
      * - Non-2xx responses become `ResponseError`.
      * - Does not validate the result against the endpoint schema — use `ValidationAPIProvider` for that.
+     *
+     * @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 const result = await provider.parseResponse(getUser, response);
+     * @see https://dhoulb.github.io/shelving/api/provider/APIProvider/APIProvider/parseResponse
      */
     abstract parseResponse<PP extends P, RR extends R>(_endpoint: Endpoint<PP, RR>, response: Response, caller?: AnyCaller): Promise<RR>;
-    /** Send a payload to an `Endpoint` and retrieve the result. */
+    /**
+     * Send a payload to an `Endpoint` and retrieve the parsed result.
+     * - Composes `createRequest()`, `fetch()`, and `parseResponse()` into a single round trip.
+     *
+     * @param endpoint The endpoint to call.
+     * @param payload The payload to send to the endpoint.
+     * @param options The `RequestOptions` to use, merged over the provider's own options.
+     * @param caller The function to attribute thrown errors to.
+     * @returns A promise resolving to the parsed result.
+     * @throws {ResponseError} if the response status is non-2xx.
+     * @example const user = await provider.call(getUser, { id: "abc" });
+     * @see https://dhoulb.github.io/shelving/api/provider/APIProvider/APIProvider/call
+     */
     call<PP extends P, RR extends R>(endpoint: Endpoint<PP, RR>, payload: PP, options?: RequestOptions, caller?: AnyCaller): Promise<RR>;
     [Symbol.asyncDispose](): Promise<void>;
 }

package/api/provider/APIProvider.js

@@ -1,6 +1,28 @@
-/** Provider for API endpoints rooted at a common base URL. */
+/**
+ * Abstract base for API providers that send requests to a set of `Endpoint` definitions rooted at a common base URL.
+ * - Concrete subclasses implement `renderURL()`, `createRequest()`, `fetch()`, and `parseResponse()`; `call()` orchestrates them.
+ * - Implements `AsyncDisposable` so providers can be wrapped and disposed in a chain.
+ *
+ * @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/APIProvider/APIProvider
+ */
 export class APIProvider {
-    /** Send a payload to an `Endpoint` and retrieve the result. */
+    /**
+     * Send a payload to an `Endpoint` and retrieve the parsed result.
+     * - Composes `createRequest()`, `fetch()`, and `parseResponse()` into a single round trip.
+     *
+     * @param endpoint The endpoint to call.
+     * @param payload The payload to send to the endpoint.
+     * @param options The `RequestOptions` to use, merged over the provider's own options.
+     * @param caller The function to attribute thrown errors to.
+     * @returns A promise resolving to the parsed result.
+     * @throws {ResponseError} if the response status is non-2xx.
+     * @example const user = await provider.call(getUser, { id: "abc" });
+     * @see https://dhoulb.github.io/shelving/api/provider/APIProvider/APIProvider/call
+     */
     async call(endpoint, payload, options, caller) {
         const request = this.createRequest(endpoint, payload, options, caller);
         const response = await this.fetch(request);

package/api/provider/CachedAPIProvider.d.ts

@@ -4,23 +4,76 @@ import type { Endpoint } from "../endpoint/Endpoint.js";
 import type { APIProvider } from "./APIProvider.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 declare class CachedAPIProvider<P, R> extends ThroughAPIProvider<P, R> implements AsyncDisposable {
+    /**
+     * 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
+     */
     readonly maxAge: number | undefined;
     private readonly _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: APIProvider<P, R>, maxAge?: number);
+    /**
+     * 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<PP extends P, RR extends R>(endpoint: Endpoint<PP, RR>, payload: PP, _options?: RequestOptions, caller?: AnyCaller): Promise<RR>;
+    /**
+     * 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<PP extends P, RR extends R>(endpoint: Endpoint<PP, RR>, payload: PP): void;
+    /**
+     * 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<PP extends P, RR extends R>(endpoint: Endpoint<PP, RR>): void;
+    /**
+     * 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<PP extends P, RR extends R>(endpoint: Endpoint<PP, RR>, payload: PP): void;
+    /**
+     * 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<PP extends P, RR extends R>(endpoint: Endpoint<PP, RR>): void;
     [Symbol.asyncDispose](): Promise<void>;
 }