shelving 1.258.6 → 1.258.7

package/api/cache/APICache.d.ts

@@ -21,13 +21,6 @@ export declare class APICache<P, R> implements AsyncDisposable {
      * @see https://shelving.cc/api/APICache/provider
      */
     readonly provider: APIProvider<P, R>;
-    /**
-     * Create a new `APICache` backed by an `APIProvider`.
-     *
-     * @param provider The `APIProvider` used to fetch results for every cached endpoint.
-     * @example new APICache(provider)
-     * @see https://shelving.cc/api/APICache
-     */
     constructor(provider: APIProvider<P, R>);
     private _get;
     /**

package/api/cache/APICache.js

@@ -21,13 +21,6 @@ export class APICache {
      * @see https://shelving.cc/api/APICache/provider
      */
     provider;
-    /**
-     * Create a new `APICache` backed by an `APIProvider`.
-     *
-     * @param provider The `APIProvider` used to fetch results for every cached endpoint.
-     * @example new APICache(provider)
-     * @see https://shelving.cc/api/APICache
-     */
     constructor(provider) {
         this.provider = provider;
     }

package/api/cache/EndpointCache.d.ts

@@ -27,14 +27,6 @@ export declare class EndpointCache<P = unknown, R = unknown> implements AsyncDis
      * @see https://shelving.cc/api/EndpointCache/provider
      */
     readonly provider: APIProvider<P, R>;
-    /**
-     * Create a new `EndpointCache` for a single endpoint and provider.
-     *
-     * @param endpoint The endpoint that every cached store fetches from.
-     * @param provider The `APIProvider` used to render URLs and fetch results.
-     * @example new EndpointCache(getUser, provider)
-     * @see https://shelving.cc/api/EndpointCache
-     */
     constructor(endpoint: Endpoint<P, R>, provider: APIProvider<P, R>);
     /**
      * Get (or create) the `EndpointStore` for the given payload.

package/api/cache/EndpointCache.js

@@ -28,14 +28,6 @@ export class EndpointCache {
      * @see https://shelving.cc/api/EndpointCache/provider
      */
     provider;
-    /**
-     * Create a new `EndpointCache` for a single endpoint and provider.
-     *
-     * @param endpoint The endpoint that every cached store fetches from.
-     * @param provider The `APIProvider` used to render URLs and fetch results.
-     * @example new EndpointCache(getUser, provider)
-     * @see https://shelving.cc/api/EndpointCache
-     */
     constructor(endpoint, provider) {
         this.endpoint = endpoint;
         this.provider = provider;

package/api/endpoint/Endpoint.d.ts

@@ -11,14 +11,7 @@ import type { EndpointCallback, EndpointHandler } from "./util.js";
  * - 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);
- *
+ * @example const getUser = new Endpoint("GET", "/users/{id}", USER_PAYLOAD, USER_RESULT);
  * @see https://shelving.cc/api/Endpoint
  */
 export declare class Endpoint<P = unknown, R = unknown> {

package/api/endpoint/Endpoint.js

@@ -7,14 +7,7 @@ import { getPlaceholders, matchPathTemplate, renderPathTemplate } from "../../ut
  * - 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);
- *
+ * @example const getUser = new Endpoint("GET", "/users/{id}", USER_PAYLOAD, USER_RESULT);
  * @see https://shelving.cc/api/Endpoint
  */
 export class Endpoint {

package/api/provider/APIProvider.d.ts

@@ -6,10 +6,6 @@ import type { Endpoint } from "../endpoint/Endpoint.js";
  * - 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://shelving.cc/api/APIProvider
  */
 export declare abstract class APIProvider<P = unknown, R = unknown> implements AsyncDisposable {
@@ -83,7 +79,6 @@ export declare abstract class APIProvider<P = unknown, R = unknown> implements A
      * @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://shelving.cc/api/APIProvider/call
      */
     call<PP extends P, RR extends R>(endpoint: Endpoint<PP, RR>, payload: PP, options?: RequestOptions, caller?: AnyCaller): Promise<RR>;

package/api/provider/APIProvider.js

@@ -3,10 +3,6 @@
  * - 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://shelving.cc/api/APIProvider
  */
 export class APIProvider {
@@ -20,7 +16,6 @@ export class APIProvider {
      * @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://shelving.cc/api/APIProvider/call
      */
     async call(endpoint, payload, options, caller) {

package/api/provider/CachedAPIProvider.d.ts

@@ -8,9 +8,6 @@ import { ThroughAPIProvider } from "./ThroughAPIProvider.js";
  * - 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.
  *
- * @example
- *  const api = new CachedAPIProvider(source);
- *  const result = await api.call(endpoint, payload);
  * @see https://shelving.cc/api/CachedAPIProvider
  */
 export declare class CachedAPIProvider<P, R> extends ThroughAPIProvider<P, R> implements AsyncDisposable {
@@ -21,32 +18,14 @@ export declare class CachedAPIProvider<P, R> extends ThroughAPIProvider<P, R> im
      */
     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://shelving.cc/api/CachedAPIProvider/call
-     */
+    /** Serves the call through the cache, reusing a cached result where possible; request options are ignored as the cache key is derived from `endpoint` and `payload`. */
     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://shelving.cc/api/CachedAPIProvider/invalidate
      */
     invalidate<PP extends P, RR extends R>(endpoint: Endpoint<PP, RR>, payload: PP): void;
@@ -54,7 +33,6 @@ export declare class CachedAPIProvider<P, R> extends ThroughAPIProvider<P, R> im
      * 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://shelving.cc/api/CachedAPIProvider/invalidateAll
      */
     invalidateAll<PP extends P, RR extends R>(endpoint: Endpoint<PP, RR>): void;
@@ -63,7 +41,6 @@ export declare class CachedAPIProvider<P, R> extends ThroughAPIProvider<P, R> im
      *
      * @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://shelving.cc/api/CachedAPIProvider/refresh
      */
     refresh<PP extends P, RR extends R>(endpoint: Endpoint<PP, RR>, payload: PP): void;
@@ -71,7 +48,6 @@ export declare class CachedAPIProvider<P, R> extends ThroughAPIProvider<P, R> im
      * 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://shelving.cc/api/CachedAPIProvider/refreshAll
      */
     refreshAll<PP extends P, RR extends R>(endpoint: Endpoint<PP, RR>): void;

package/api/provider/CachedAPIProvider.js

@@ -7,9 +7,6 @@ import { ThroughAPIProvider } from "./ThroughAPIProvider.js";
  * - 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.
  *
- * @example
- *  const api = new CachedAPIProvider(source);
- *  const result = await api.call(endpoint, payload);
  * @see https://shelving.cc/api/CachedAPIProvider
  */
 export class CachedAPIProvider extends ThroughAPIProvider {
@@ -20,29 +17,12 @@ export class CachedAPIProvider extends ThroughAPIProvider {
      */
     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);
     }
-    /**
-     * 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://shelving.cc/api/CachedAPIProvider/call
-     */
+    /** Serves the call through the cache, reusing a cached result where possible; request options are ignored as the cache key is derived from `endpoint` and `payload`. */
     call(endpoint, payload, _options, caller = this.call) {
         return this._cache.call(endpoint, payload, this.maxAge, caller);
     }
@@ -51,7 +31,6 @@ export class CachedAPIProvider extends ThroughAPIProvider {
      *
      * @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://shelving.cc/api/CachedAPIProvider/invalidate
      */
     invalidate(endpoint, payload) {
@@ -61,7 +40,6 @@ export class CachedAPIProvider extends ThroughAPIProvider {
      * 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://shelving.cc/api/CachedAPIProvider/invalidateAll
      */
     invalidateAll(endpoint) {
@@ -72,7 +50,6 @@ export class CachedAPIProvider extends ThroughAPIProvider {
      *
      * @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://shelving.cc/api/CachedAPIProvider/refresh
      */
     refresh(endpoint, payload) {
@@ -82,7 +59,6 @@ export class CachedAPIProvider extends ThroughAPIProvider {
      * 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://shelving.cc/api/CachedAPIProvider/refreshAll
      */
     refreshAll(endpoint) {

package/api/provider/ClientAPIProvider.d.ts

@@ -40,18 +40,9 @@ export interface ClientAPIProviderOptions {
  * - 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://shelving.cc/api/ClientAPIProvider
  */
 export declare class ClientAPIProvider<P = unknown, R = unknown> extends APIProvider<P, R> {
-    /**
-     * The common base URL for all rendered endpoint requests.
-     *
-     * @see https://shelving.cc/api/ClientAPIProvider/url
-     */
     readonly url: URL;
     /**
      * Default options used for HTTP requests created with `this.createRequest()` and `this.fetch()`
@@ -65,42 +56,10 @@ export declare class ClientAPIProvider<P = unknown, R = unknown> extends APIProv
      * @see https://shelving.cc/api/ClientAPIProvider/timeout
      */
     readonly timeout: number;
-    /**
-     * Create a `ClientAPIProvider` from a base URL and request options.
-     *
-     * @throws {RequiredError} if `url` cannot be resolved to a valid base URL.
-     * @example new ClientAPIProvider({ url: "https://api.example.com" })
-     * @see https://shelving.cc/api/ClientAPIProvider
-     */
+    /** @throws {RequiredError} if `url` cannot be resolved to a valid base URL. */
     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://shelving.cc/api/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://shelving.cc/api/ClientAPIProvider/createRequest
-     */
+    /** Merges `options` over the provider's defaults and attaches a timeout `AbortSignal` when `timeout` is set. */
     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, //
@@ -108,25 +67,8 @@ 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://shelving.cc/api/ClientAPIProvider/fetch
-     */
+    /** Sends the request over the network using the global `fetch()` API. */
     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://shelving.cc/api/ClientAPIProvider/parseResponse
-     */
+    /** Parses the response body as JSON. */
     parseResponse<PP extends P, RR extends R>(_endpoint: Endpoint<PP, RR>, response: Response, caller?: AnyCaller): Promise<RR>;
 }

package/api/provider/ClientAPIProvider.js

@@ -14,18 +14,9 @@ import { APIProvider } from "./APIProvider.js";
  * - 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://shelving.cc/api/ClientAPIProvider
  */
 export class ClientAPIProvider extends APIProvider {
-    /**
-     * The common base URL for all rendered endpoint requests.
-     *
-     * @see https://shelving.cc/api/ClientAPIProvider/url
-     */
     url;
     /**
      * Default options used for HTTP requests created with `this.createRequest()` and `this.fetch()`
@@ -39,31 +30,13 @@ export class ClientAPIProvider extends APIProvider {
      * @see https://shelving.cc/api/ClientAPIProvider/timeout
      */
     timeout;
-    /**
-     * Create a `ClientAPIProvider` from a base URL and request options.
-     *
-     * @throws {RequiredError} if `url` cannot be resolved to a valid base URL.
-     * @example new ClientAPIProvider({ url: "https://api.example.com" })
-     * @see https://shelving.cc/api/ClientAPIProvider
-     */
+    /** @throws {RequiredError} if `url` cannot be resolved to a valid base URL. */
     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://shelving.cc/api/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.
@@ -80,21 +53,7 @@ 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://shelving.cc/api/ClientAPIProvider/createRequest
-     */
+    /** Merges `options` over the provider's defaults and attaches a timeout `AbortSignal` when `timeout` is set. */
     createRequest(endpoint, payload, options, caller = this.createRequest) {
         // Render the path into the base URL.
         const url = this.renderURL(endpoint, payload, caller);
@@ -119,28 +78,11 @@ export class ClientAPIProvider extends APIProvider {
     url, payload, options, caller) {
         return createRequest(method, url, payload, options, caller);
     }
-    /**
-     * 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://shelving.cc/api/ClientAPIProvider/fetch
-     */
+    /** Sends the request over the network using the global `fetch()` API. */
     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://shelving.cc/api/ClientAPIProvider/parseResponse
-     */
+    /** Parses the response body as JSON. */
     async parseResponse(_endpoint, response, caller = this.parseResponse) {
         const { ok, status } = response;
         const content = await parseResponseBody(response, caller);

package/api/provider/DebugAPIProvider.d.ts

@@ -5,45 +5,13 @@ import { ThroughAPIProvider } from "./ThroughAPIProvider.js";
 /**
  * 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://shelving.cc/api/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://shelving.cc/api/DebugAPIProvider/createRequest
-     */
+    /** Log the endpoint and payload (or any error) while building the request. */
     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://shelving.cc/api/DebugAPIProvider/fetch
-     */
+    /** Log the full request and response (or any error) while fetching. */
     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://shelving.cc/api/DebugAPIProvider/parseResponse
-     */
+    /** Log the parsed result (or any error) while parsing the response. */
     parseResponse<PP extends P, RR extends R>(endpoint: Endpoint<PP, RR>, response: Response, caller?: AnyCaller): Promise<RR>;
 }

package/api/provider/DebugAPIProvider.js

@@ -4,24 +4,10 @@ import { ThroughAPIProvider } from "./ThroughAPIProvider.js";
 /**
  * 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://shelving.cc/api/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://shelving.cc/api/DebugAPIProvider/createRequest
-     */
+    /** Log the endpoint and payload (or any error) while building the request. */
     createRequest(endpoint, payload, options, caller = this.createRequest) {
         try {
             const request = super.createRequest(endpoint, payload, options, caller);
@@ -33,15 +19,7 @@ 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://shelving.cc/api/DebugAPIProvider/fetch
-     */
+    /** Log the full request and response (or any error) while fetching. */
     async fetch(request) {
         try {
             console.debug(`${ANSI_RIGHT} ${await debugFullRequest(request)}`);
@@ -54,17 +32,7 @@ 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://shelving.cc/api/DebugAPIProvider/parseResponse
-     */
+    /** Log the parsed result (or any error) while parsing the response. */
     async parseResponse(endpoint, response, caller = this.parseResponse) {
         try {
             const result = await super.parseResponse(endpoint, response, caller);

package/api/provider/JSONAPIProvider.d.ts

@@ -7,26 +7,10 @@ import { ClientAPIProvider } from "./ClientAPIProvider.js";
  * 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://shelving.cc/api/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://shelving.cc/api/JSONAPIProvider/parseResponse
-     */
+    /** Parse the response body as JSON, even if the server omitted or mis-set the content type. */
     parseResponse<PP extends P, RR extends R>(_endpoint: Endpoint<PP, RR>, response: Response, caller?: AnyCaller): Promise<RR>;
 }

package/api/provider/JSONAPIProvider.js

@@ -6,29 +6,13 @@ import { ClientAPIProvider } from "./ClientAPIProvider.js";
  * 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://shelving.cc/api/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://shelving.cc/api/JSONAPIProvider/parseResponse
-     */
+    /** Parse the response body as JSON, even if the server omitted or mis-set the content type. */
     async parseResponse(_endpoint, response, caller = this.parseResponse) {
         const { ok, status } = response;
         const content = await parseResponseJSON(response, caller);