shelving 1.250.0 → 1.251.1

package/api/cache/APICache.d.ts

@@ -3,8 +3,8 @@ import type { Endpoint } from "../endpoint/Endpoint.js";
 import type { APIProvider } from "../provider/APIProvider.js";
 import { EndpointCache } from "./EndpointCache.js";
 /**
- * Cache of `EndpointCache` objects keyed by `Endpoint`, providing memoised API results across many endpoints.
- * - Use `get(endpoint)` to retrieve or create the `EndpointCache` for a given endpoint, then `get(payload)` on that to get a specific `EndpointStore`.
+ * Cache of [`EndpointCache`](/api/EndpointCache) objects keyed by [`Endpoint`](/api/Endpoint), providing memoised API results across many endpoints.
+ * - Use `get(endpoint)` to retrieve or create the `EndpointCache` for a given endpoint, then `get(payload)` on that to get a specific [`EndpointStore`](/api/EndpointStore).
  * - Disposing the cache disposes every nested `EndpointCache` and clears the map.
  *
  * @example
@@ -16,13 +16,13 @@ import { EndpointCache } from "./EndpointCache.js";
 export declare class APICache<P, R> implements AsyncDisposable {
     private readonly _endpoints;
     /**
-     * The underlying `APIProvider` that backs every cached endpoint.
+     * The underlying [`APIProvider`](/api/APIProvider) that backs every cached endpoint.
      *
      * @see https://dhoulb.github.io/shelving/api/cache/APICache/APICache/provider
      */
     readonly provider: APIProvider<P, R>;
     /**
-     * Create a new `APICache` backed by an `APIProvider`.
+     * Create a new `APICache` backed by an [`APIProvider`](/api/APIProvider).
      *
      * @param provider The `APIProvider` used to fetch results for every cached endpoint.
      * @example new APICache(provider)
@@ -31,7 +31,7 @@ export declare class APICache<P, R> implements AsyncDisposable {
     constructor(provider: APIProvider<P, R>);
     private _get;
     /**
-     * Get (or create) the `EndpointCache` for the given endpoint.
+     * Get (or create) the [`EndpointCache`](/api/EndpointCache) for the given endpoint.
      *
      * @param endpoint The endpoint whose `EndpointCache` should be returned.
      * @returns The existing `EndpointCache` for `endpoint`, or a newly created one.
@@ -43,7 +43,7 @@ export declare class APICache<P, R> implements AsyncDisposable {
      * Fetch (or return a cached result) for the given endpoint and payload.
      * - Returns the cached value immediately if one exists.
      * - Waits for the in-flight fetch if the store is loading.
-     * - Throws if the fetch fails, matching `APIProvider.call` behaviour.
+     * - Throws if the fetch fails, matching [`APIProvider.call`](/api/APIProvider/call) behaviour.
      *
      * @param endpoint The endpoint to fetch a result for.
      * @param payload The payload to send to the endpoint.

package/api/cache/APICache.js

@@ -3,8 +3,8 @@ import { awaitDispose } from "../../util/dispose.js";
 import { setMapItem } from "../../util/map.js";
 import { EndpointCache } from "./EndpointCache.js";
 /**
- * Cache of `EndpointCache` objects keyed by `Endpoint`, providing memoised API results across many endpoints.
- * - Use `get(endpoint)` to retrieve or create the `EndpointCache` for a given endpoint, then `get(payload)` on that to get a specific `EndpointStore`.
+ * Cache of [`EndpointCache`](/api/EndpointCache) objects keyed by [`Endpoint`](/api/Endpoint), providing memoised API results across many endpoints.
+ * - Use `get(endpoint)` to retrieve or create the `EndpointCache` for a given endpoint, then `get(payload)` on that to get a specific [`EndpointStore`](/api/EndpointStore).
  * - Disposing the cache disposes every nested `EndpointCache` and clears the map.
  *
  * @example
@@ -16,13 +16,13 @@ import { EndpointCache } from "./EndpointCache.js";
 export class APICache {
     _endpoints = new Map();
     /**
-     * The underlying `APIProvider` that backs every cached endpoint.
+     * The underlying [`APIProvider`](/api/APIProvider) that backs every cached endpoint.
      *
      * @see https://dhoulb.github.io/shelving/api/cache/APICache/APICache/provider
      */
     provider;
     /**
-     * Create a new `APICache` backed by an `APIProvider`.
+     * Create a new `APICache` backed by an [`APIProvider`](/api/APIProvider).
      *
      * @param provider The `APIProvider` used to fetch results for every cached endpoint.
      * @example new APICache(provider)
@@ -41,7 +41,7 @@ export class APICache {
      * Fetch (or return a cached result) for the given endpoint and payload.
      * - Returns the cached value immediately if one exists.
      * - Waits for the in-flight fetch if the store is loading.
-     * - Throws if the fetch fails, matching `APIProvider.call` behaviour.
+     * - Throws if the fetch fails, matching [`APIProvider.call`](/api/APIProvider/call) behaviour.
      *
      * @param endpoint The endpoint to fetch a result for.
      * @param payload The payload to send to the endpoint.

package/api/cache/EndpointCache.d.ts

@@ -3,7 +3,7 @@ import type { Endpoint } from "../endpoint/Endpoint.js";
 import type { APIProvider } from "../provider/APIProvider.js";
 import { EndpointStore } from "../store/EndpointStore.js";
 /**
- * Cache of `EndpointStore` objects for a single endpoint, keyed by the rendered request URL of each payload.
+ * Cache of [`EndpointStore`](/api/EndpointStore) objects for a single endpoint, keyed by the rendered request URL of each payload.
  * - Use `get(payload)` to retrieve or create the `EndpointStore` for a given payload.
  * - Disposing the cache disposes every nested `EndpointStore` and clears the map.
  *
@@ -22,7 +22,7 @@ export declare class EndpointCache<P = unknown, R = unknown> implements AsyncDis
      */
     readonly endpoint: Endpoint<P, R>;
     /**
-     * The `APIProvider` used to render URLs and fetch results for this endpoint.
+     * The [`APIProvider`](/api/APIProvider) used to render URLs and fetch results for this endpoint.
      *
      * @see https://dhoulb.github.io/shelving/api/cache/EndpointCache/EndpointCache/provider
      */
@@ -31,13 +31,13 @@ export declare class EndpointCache<P = unknown, R = unknown> implements AsyncDis
      * 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.
+     * @param provider The [`APIProvider`](/api/APIProvider) used to render URLs and fetch results.
      * @example new EndpointCache(getUser, provider)
      * @see https://dhoulb.github.io/shelving/api/cache/EndpointCache/EndpointCache
      */
     constructor(endpoint: Endpoint<P, R>, provider: APIProvider<P, R>);
     /**
-     * Get (or create) the `EndpointStore` for the given payload.
+     * Get (or create) the [`EndpointStore`](/api/EndpointStore) for the given payload.
      * - Stores are keyed by the rendered request URL, so equivalent payloads share a store.
      *
      * @param payload The payload identifying the store to return.
@@ -51,7 +51,7 @@ export declare class EndpointCache<P = unknown, R = unknown> implements AsyncDis
      * Fetch (or return a cached result) for the given payload.
      * - Returns the cached value immediately if one exists.
      * - Waits for the in-flight fetch if the store is loading.
-     * - Throws if the fetch fails, matching `APIProvider.call` behaviour.
+     * - Throws if the fetch fails, matching [`APIProvider.call`](/api/APIProvider/call) behaviour.
      *
      * @param payload The payload to send to the endpoint.
      * @param maxAge The maximum age in milliseconds (defaults to only refreshing if the value is still in a loading state).

package/api/cache/EndpointCache.js

@@ -4,7 +4,7 @@ import { awaitDispose } from "../../util/dispose.js";
 import { setMapItem } from "../../util/map.js";
 import { EndpointStore } from "../store/EndpointStore.js";
 /**
- * Cache of `EndpointStore` objects for a single endpoint, keyed by the rendered request URL of each payload.
+ * Cache of [`EndpointStore`](/api/EndpointStore) objects for a single endpoint, keyed by the rendered request URL of each payload.
  * - Use `get(payload)` to retrieve or create the `EndpointStore` for a given payload.
  * - Disposing the cache disposes every nested `EndpointStore` and clears the map.
  *
@@ -23,7 +23,7 @@ export class EndpointCache {
      */
     endpoint;
     /**
-     * The `APIProvider` used to render URLs and fetch results for this endpoint.
+     * The [`APIProvider`](/api/APIProvider) used to render URLs and fetch results for this endpoint.
      *
      * @see https://dhoulb.github.io/shelving/api/cache/EndpointCache/EndpointCache/provider
      */
@@ -32,7 +32,7 @@ export class EndpointCache {
      * 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.
+     * @param provider The [`APIProvider`](/api/APIProvider) used to render URLs and fetch results.
      * @example new EndpointCache(getUser, provider)
      * @see https://dhoulb.github.io/shelving/api/cache/EndpointCache/EndpointCache
      */
@@ -41,7 +41,7 @@ export class EndpointCache {
         this.provider = provider;
     }
     /**
-     * Get (or create) the `EndpointStore` for the given payload.
+     * Get (or create) the [`EndpointStore`](/api/EndpointStore) for the given payload.
      * - Stores are keyed by the rendered request URL, so equivalent payloads share a store.
      *
      * @param payload The payload identifying the store to return.
@@ -58,7 +58,7 @@ export class EndpointCache {
      * Fetch (or return a cached result) for the given payload.
      * - Returns the cached value immediately if one exists.
      * - Waits for the in-flight fetch if the store is loading.
-     * - Throws if the fetch fails, matching `APIProvider.call` behaviour.
+     * - Throws if the fetch fails, matching [`APIProvider.call`](/api/APIProvider/call) behaviour.
      *
      * @param payload The payload to send to the endpoint.
      * @param maxAge The maximum age in milliseconds (defaults to only refreshing if the value is still in a loading state).

package/api/endpoint/Endpoint.d.ts

@@ -13,7 +13,7 @@ import type { EndpointCallback, EndpointHandler } from "./util.js";
  *
  * @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 payload A [`Schema`](/schema/Schema) for the payload of the endpoint.
  * @param result A `Schema` for the result of the endpoint.
  *
  * @example
@@ -41,13 +41,13 @@ export declare class Endpoint<P = unknown, R = unknown> {
      */
     readonly placeholders: TemplatePlaceholders;
     /**
-     * The `Schema` that request payloads are validated against.
+     * The [`Schema`](/schema/Schema) that request payloads are validated against.
      *
      * @see https://dhoulb.github.io/shelving/api/endpoint/Endpoint/Endpoint/payload
      */
     readonly payload: Schema<P>;
     /**
-     * The `Schema` that response results are validated against.
+     * The [`Schema`](/schema/Schema) that response results are validated against.
      *
      * @see https://dhoulb.github.io/shelving/api/endpoint/Endpoint/Endpoint/result
      */
@@ -80,7 +80,7 @@ export declare class Endpoint<P = unknown, R = unknown> {
      * 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.
+     * @returns An [`EndpointHandler`](/api/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
      */
@@ -95,7 +95,7 @@ export declare class Endpoint<P = unknown, R = unknown> {
     toString(): string;
 }
 /**
- * An `Endpoint` with any payload and result type, for use where the specific types don't matter.
+ * An [`Endpoint`](/api/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
  */
@@ -107,13 +107,13 @@ export type AnyEndpoint = Endpoint<any, any>;
  */
 export type Endpoints = ImmutableArray<AnyEndpoint>;
 /**
- * Extract the payload type from an `Endpoint`.
+ * Extract the payload type from an [`Endpoint`](/api/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 an `Endpoint`.
+ * Extract the result type from an [`Endpoint`](/api/Endpoint).
  *
  * @see https://dhoulb.github.io/shelving/api/endpoint/Endpoint/EndpointType
  */
@@ -122,10 +122,10 @@ export type EndpointType<X extends Endpoint<unknown, unknown>> = X extends Endpo
  * 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`.*
+ * *Factory for [`Endpoint`](/api/Endpoint).*
  *
  * @param path The endpoint path, possibly including `{placeholders}`
- * @param payload An optional `Schema` validating the request payload.
+ * @param payload An optional [`Schema`](/schema/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}")
@@ -138,10 +138,10 @@ export declare function HEAD<R>(path: AbsolutePath, payload: undefined, result:
  * 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`.*
+ * *Factory for [`Endpoint`](/api/Endpoint).*
  *
  * @param path The endpoint path, possibly including `{placeholders}`
- * @param payload An optional `Schema` validating the request payload.
+ * @param payload An optional [`Schema`](/schema/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)
@@ -154,10 +154,10 @@ export declare function GET<R>(path: AbsolutePath, payload: undefined, result: S
  * 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`.*
+ * *Factory for [`Endpoint`](/api/Endpoint).*
  *
  * @param path The endpoint path, possibly including `{placeholders}`
- * @param payload An optional `Schema` validating the request payload.
+ * @param payload An optional [`Schema`](/schema/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)
@@ -170,10 +170,10 @@ export declare function POST<R>(path: AbsolutePath, payload: undefined, result:
  * 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`.*
+ * *Factory for [`Endpoint`](/api/Endpoint).*
  *
  * @param path The endpoint path, possibly including `{placeholders}`
- * @param payload An optional `Schema` validating the request payload.
+ * @param payload An optional [`Schema`](/schema/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)
@@ -186,10 +186,10 @@ export declare function PUT<R>(path: AbsolutePath, payload: undefined, result: S
  * 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`.*
+ * *Factory for [`Endpoint`](/api/Endpoint).*
  *
  * @param path The endpoint path, possibly including `{placeholders}`
- * @param payload An optional `Schema` validating the request payload.
+ * @param payload An optional [`Schema`](/schema/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)
@@ -202,10 +202,10 @@ export declare function PATCH<R>(path: AbsolutePath, payload: undefined, result:
  * Define a `DELETE` endpoint at a path, with validated payload and result types.
  * - "The DELETE method deletes the specified resource."
  *
- * *Factory for `Endpoint`.*
+ * *Factory for [`Endpoint`](/api/Endpoint).*
  *
  * @param path The endpoint path, possibly including `{placeholders}`
- * @param payload An optional `Schema` validating the request payload.
+ * @param payload An optional [`Schema`](/schema/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}")

package/api/endpoint/Endpoint.js

@@ -9,7 +9,7 @@ import { getPlaceholders, matchPathTemplate, renderPathTemplate } from "../../ut
  *
  * @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 payload A [`Schema`](/schema/Schema) for the payload of the endpoint.
  * @param result A `Schema` for the result of the endpoint.
  *
  * @example
@@ -37,13 +37,13 @@ export class Endpoint {
      */
     placeholders;
     /**
-     * The `Schema` that request payloads are validated against.
+     * The [`Schema`](/schema/Schema) that request payloads are validated against.
      *
      * @see https://dhoulb.github.io/shelving/api/endpoint/Endpoint/Endpoint/payload
      */
     payload;
     /**
-     * The `Schema` that response results are validated against.
+     * The [`Schema`](/schema/Schema) that response results are validated against.
      *
      * @see https://dhoulb.github.io/shelving/api/endpoint/Endpoint/Endpoint/result
      */
@@ -94,7 +94,7 @@ 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.
+     * @returns An [`EndpointHandler`](/api/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
      */

package/api/endpoint/util.d.ts

@@ -16,7 +16,7 @@ import type { Endpoint } from "./Endpoint.js";
 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.
- * - Created with `Endpoint.handler()`; matched and invoked by `handleEndpoints()`.
+ * - Created with [`.handler()`](/api/Endpoint/handler); matched and invoked by [`handleEndpoints()`](/api/handleEndpoints).
  *
  * @see https://dhoulb.github.io/shelving/api/endpoint/util/EndpointHandler
  */
@@ -25,13 +25,13 @@ export interface EndpointHandler<P, R, C = void> {
     readonly callback: EndpointCallback<P, R, C>;
 }
 /**
- * An `EndpointHandler` with any payload and result type, for use where the specific types don't matter.
+ * An [`EndpointHandler`](/api/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()`](/api/handleEndpoints).
  *
  * @see https://dhoulb.github.io/shelving/api/endpoint/util/EndpointHandlers
  */
@@ -43,7 +43,7 @@ export type EndpointHandlers<C = void> = Iterable<AnyEndpointHandler<C>>;
  *
  * @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 handlers The iterable of [`EndpointHandler`](/api/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).

package/api/provider/APIProvider.d.ts

@@ -2,7 +2,7 @@ import type { AnyCaller } from "../../util/function.js";
 import type { RequestOptions } from "../../util/http.js";
 import type { Endpoint } from "../endpoint/Endpoint.js";
 /**
- * Abstract base for API providers that send requests to a set of `Endpoint` definitions rooted at a common base URL.
+ * Abstract base for API providers that send requests to a set of [`Endpoint`](/api/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.
  *
@@ -41,7 +41,7 @@ export declare abstract class APIProvider<P = unknown, R = unknown> implements A
      * - 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`, merged over the provider's own options.
+     * @param options The [`RequestOptions`](/util/http/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.
@@ -61,8 +61,8 @@ export declare abstract class APIProvider<P = unknown, R = unknown> implements A
     abstract fetch(request: Request): Promise<Response>;
     /**
      * 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.
+     * - Non-2xx responses become [`ResponseError`](/error/ResponseError).
+     * - Does not validate the result against the endpoint schema — use [`ValidationAPIProvider`](/api/ValidationAPIProvider) for that.
      *
      * @param _endpoint The endpoint the response was produced for.
      * @param response The `Response` to parse.
@@ -74,12 +74,12 @@ export declare abstract class APIProvider<P = unknown, R = unknown> implements A
      */
     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 parsed result.
+     * Send a payload to an [`Endpoint`](/api/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 options The [`RequestOptions`](/util/http/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.

package/api/provider/APIProvider.js

@@ -1,5 +1,5 @@
 /**
- * Abstract base for API providers that send requests to a set of `Endpoint` definitions rooted at a common base URL.
+ * Abstract base for API providers that send requests to a set of [`Endpoint`](/api/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.
  *
@@ -11,12 +11,12 @@
  */
 export class APIProvider {
     /**
-     * Send a payload to an `Endpoint` and retrieve the parsed result.
+     * Send a payload to an [`Endpoint`](/api/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 options The [`RequestOptions`](/util/http/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.

package/api/provider/CachedAPIProvider.d.ts

@@ -4,7 +4,7 @@ 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` so repeated calls reuse cached results.
+ * API provider wrapper that serves requests through an [`APICache`](/api/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.
  *
@@ -15,7 +15,7 @@ import { ThroughAPIProvider } from "./ThroughAPIProvider.js";
  */
 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).
+     * The maximum age used when calling `call()`, defaulting to [`AVOID_REFRESH`](/store/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
      */
@@ -25,7 +25,7 @@ export declare class CachedAPIProvider<P, R> extends ThroughAPIProvider<P, R> im
      * 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`).
+     * @param maxAge Default maximum age in milliseconds for `call()` (defaults to [`AVOID_REFRESH`](/store/AVOID_REFRESH)).
      * @example new CachedAPIProvider(source)
      */
     constructor(source: APIProvider<P, R>, maxAge?: number);

package/api/provider/CachedAPIProvider.js

@@ -3,7 +3,7 @@ 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` so repeated calls reuse cached results.
+ * API provider wrapper that serves requests through an [`APICache`](/api/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.
  *
@@ -14,7 +14,7 @@ import { ThroughAPIProvider } from "./ThroughAPIProvider.js";
  */
 export class CachedAPIProvider extends ThroughAPIProvider {
     /**
-     * The maximum age used when calling `call()`, defaulting to `AVOID_REFRESH` (only refresh if invalidated or still loading).
+     * The maximum age used when calling `call()`, defaulting to [`AVOID_REFRESH`](/store/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
      */
@@ -24,7 +24,7 @@ export class CachedAPIProvider extends ThroughAPIProvider {
      * 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`).
+     * @param maxAge Default maximum age in milliseconds for `call()` (defaults to [`AVOID_REFRESH`](/store/AVOID_REFRESH)).
      * @example new CachedAPIProvider(source)
      */
     constructor(source, maxAge = AVOID_REFRESH) {

package/api/provider/ClientAPIProvider.d.ts

@@ -17,7 +17,7 @@ export interface ClientAPIProviderOptions {
      * Note: When resolving URLs for endpoints this is treated as if it ends in a slash.
      * - e.g. in `http://p.com/a/b/c` the path will be relative to `c` as if a `/` trailing slash was present.
      * - This is different to the default behaviour of `new URL()`, but is the more natural expected result
-     * - This is consistent with our e.g. `getURL()` utilities.
+     * - This is consistent with our e.g. [`getURL()`](/util/url/getURL) utilities.
      */
     readonly url: PossibleURL;
     /**
@@ -36,9 +36,9 @@ export interface ClientAPIProviderOptions {
  * A client-side API provider that sends requests over the network using `fetch()`.
  * - Can be used on a server environment to make outgoing API calls, or in a browser environment to call a server API.
  * - Renders endpoint paths and query params into the URL and sends body payloads as JSON.
- * - Parses JSON responses and throws `ResponseError` for non-2xx responses.
+ * - Parses JSON responses and throws [`ResponseError`](/error/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.
+ * - Wrap in [`ValidationAPIProvider`](/api/ValidationAPIProvider) to add automatic validation of request payloads and response results against endpoint schemas.
  *
  * @example
  * const provider = new ClientAPIProvider({ url: "https://api.example.com" });
@@ -93,7 +93,7 @@ export declare class ClientAPIProvider<P = unknown, R = unknown> extends APIProv
      *
      * @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 options Per-call [`RequestOptions`](/util/http/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.
@@ -118,7 +118,7 @@ export declare class ClientAPIProvider<P = unknown, R = unknown> extends APIProv
      */
     fetch(request: Request): Promise<Response>;
     /**
-     * Parse a response body into a result, throwing `ResponseError` for non-2xx responses.
+     * Parse a response body into a result, throwing [`ResponseError`](/error/ResponseError) for non-2xx responses.
      *
      * @param _endpoint The endpoint the response was produced for.
      * @param response The `Response` to parse.

package/api/provider/ClientAPIProvider.js

@@ -10,9 +10,9 @@ import { APIProvider } from "./APIProvider.js";
  * A client-side API provider that sends requests over the network using `fetch()`.
  * - Can be used on a server environment to make outgoing API calls, or in a browser environment to call a server API.
  * - Renders endpoint paths and query params into the URL and sends body payloads as JSON.
- * - Parses JSON responses and throws `ResponseError` for non-2xx responses.
+ * - Parses JSON responses and throws [`ResponseError`](/error/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.
+ * - Wrap in [`ValidationAPIProvider`](/api/ValidationAPIProvider) to add automatic validation of request payloads and response results against endpoint schemas.
  *
  * @example
  * const provider = new ClientAPIProvider({ url: "https://api.example.com" });
@@ -87,7 +87,7 @@ export class ClientAPIProvider extends APIProvider {
      *
      * @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 options Per-call [`RequestOptions`](/util/http/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.
@@ -131,7 +131,7 @@ export class ClientAPIProvider extends APIProvider {
         return fetch(request);
     }
     /**
-     * Parse a response body into a result, throwing `ResponseError` for non-2xx responses.
+     * Parse a response body into a result, throwing [`ResponseError`](/error/ResponseError) for non-2xx responses.
      *
      * @param _endpoint The endpoint the response was produced for.
      * @param response The `Response` to parse.

package/api/provider/JSONAPIProvider.d.ts

@@ -17,7 +17,7 @@ export declare class JSONAPIProvider<P = unknown, R = unknown> extends ClientAPI
     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`.
+     * - Non-2xx responses become [`ResponseError`](/error/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.

package/api/provider/JSONAPIProvider.js

@@ -18,7 +18,7 @@ export class JSONAPIProvider extends ClientAPIProvider {
     }
     /**
      * Parse a JSON `Response` for an endpoint.
-     * - Non-2xx responses become `ResponseError`.
+     * - Non-2xx responses become [`ResponseError`](/error/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.

package/api/provider/MockAPIProvider.d.ts

@@ -32,8 +32,8 @@ export type MockAPIResponseCall = {
 };
 /**
  * Provider that records API calls and serves them from a handler without sending network requests.
- * - Extends `ThroughAPIProvider` to delegate request building and response parsing to a source `APIProvider`.
- * - The source provider's `fetch()` is never called — this provider intercepts all fetches and routes them through a `RequestHandler`.
+ * - Extends [`ThroughAPIProvider`](/api/ThroughAPIProvider) to delegate request building and response parsing to a source [`APIProvider`](/api/APIProvider).
+ * - The source provider's `fetch()` is never called — this provider intercepts all fetches and routes them through a [`RequestHandler`](/util/http/RequestHandler).
  * - Records `requestCalls`, `fetchCalls`, and `responseCalls` so tests can assert on what happened.
  *
  * @example

package/api/provider/MockAPIProvider.js

@@ -7,8 +7,8 @@ async function _mockHandler(request) {
 }
 /**
  * Provider that records API calls and serves them from a handler without sending network requests.
- * - Extends `ThroughAPIProvider` to delegate request building and response parsing to a source `APIProvider`.
- * - The source provider's `fetch()` is never called — this provider intercepts all fetches and routes them through a `RequestHandler`.
+ * - Extends [`ThroughAPIProvider`](/api/ThroughAPIProvider) to delegate request building and response parsing to a source [`APIProvider`](/api/APIProvider).
+ * - The source provider's `fetch()` is never called — this provider intercepts all fetches and routes them through a [`RequestHandler`](/util/http/RequestHandler).
  * - Records `requestCalls`, `fetchCalls`, and `responseCalls` so tests can assert on what happened.
  *
  * @example