shelving 1.182.1 → 1.184.0

package/README.md

@@ -1,6 +1,6 @@
 # Shelving
 
-[![Conventional Commits](https://img.shields.io/badge/Conventional%20Commits-1.0.0-yellow.svg)](https://conventionalcommits.org) [![GitHub Actions](https://github.com/dhoulb/shelving/workflows/CI/badge.svg?branch=main)](https://github.com/dhoulb/shelving/actions) [![npm](https://img.shields.io/npm/dm/shelving.svg)](https://www.npmjs.com/package/shelving)
+[![Conventional Commits](https://img.shields.io/badge/Conventional%20Commits-1.0.0-yellow.svg)](https://conventionalcommits.org) [![Release](https://github.com/dhoulb/shelving/actions/workflows/release.yaml/badge.svg)](https://github.com/dhoulb/shelving/actions/workflows/release.yaml) [![npm](https://img.shields.io/npm/dm/shelving.svg)](https://www.npmjs.com/package/shelving)
 
 Shelving is a TypeScript toolkit for working with typed data. At its core it is a schema validation library — every schema has a `validate()` method that returns a typed value or throws a human-readable error. On top of that it provides a database provider abstraction, an API provider abstraction, observable state stores, React integration, and a large set of typed utility functions.
 

package/api/cache/APICache.d.ts

@@ -5,20 +5,20 @@ import { EndpointCache } from "./EndpointCache.js";
  * Cache of `EndpointCache` objects for multiple endpoints.
  * - Use `get(endpoint)` to retrieve or create the `EndpointCache` for a given endpoint, then `get(payload)` on that to get a specific `EndpointStore`.
  */
-export declare class APICache implements Disposable {
+export declare class APICache<P, R> implements Disposable {
     private readonly _caches;
-    readonly provider: APIProvider;
-    constructor(provider: APIProvider);
+    readonly provider: APIProvider<P, R>;
+    constructor(provider: APIProvider<P, R>);
     private _get;
     /** Get (or create) the `EndpointCache` for the given endpoint. */
-    get<P, R>(endpoint: Endpoint<P, R>): EndpointCache<P, R>;
+    get<PP extends P, RR extends R>(endpoint: Endpoint<PP, RR>): EndpointCache<PP, RR>;
     /** Invalidate a specific store for an endpoint. */
-    invalidate<P, R>(endpoint: Endpoint<P, R>, payload: P): void;
+    invalidate<PP extends P, RR extends R>(endpoint: Endpoint<PP, RR>, payload: PP): void;
     /** Invalidate all stores for an endpoint. */
-    invalidateAll<P, R>(endpoint: Endpoint<P, R>): void;
+    invalidateAll<PP extends P, RR extends R>(endpoint: Endpoint<PP, RR>): void;
     /** Trigger a refetch on a specific store for an endpoint. */
-    refetch<P, R>(endpoint: Endpoint<P, R>, payload: P): void;
+    refetch<PP extends P, RR extends R>(endpoint: Endpoint<PP, RR>, payload: PP): void;
     /** Trigger a refetch on all stores for an endpoint. */
-    refetchAll<P, R>(endpoint: Endpoint<P, R>): void;
+    refetchAll<PP extends P, RR extends R>(endpoint: Endpoint<PP, RR>): void;
     [Symbol.dispose](): void;
 }

package/api/cache/EndpointCache.d.ts

@@ -9,8 +9,8 @@ import { EndpointStore } from "../store/EndpointStore.js";
 export declare class EndpointCache<P = unknown, R = unknown> implements Disposable {
     private readonly _stores;
     readonly endpoint: Endpoint<P, R>;
-    readonly provider: APIProvider;
-    constructor(endpoint: Endpoint<P, R>, provider: APIProvider);
+    readonly provider: APIProvider<P, R>;
+    constructor(endpoint: Endpoint<P, R>, provider: APIProvider<P, R>);
     /** Get (or create) the `EndpointStore` for the given payload. */
     get(payload: P, caller?: AnyCaller): EndpointStore<P, R>;
     /** Invalidate a specific store. */

package/api/endpoint/util.js

@@ -1,7 +1,7 @@
 import { MethodNotAllowedError, NotFoundError } from "../../error/RequestError.js";
 import { ValueError } from "../../error/ValueError.js";
 import { getDictionary } from "../../util/dictionary.js";
-import { getRequestContent, getResponse, isRequestMethod } from "../../util/http.js";
+import { getResponse, isRequestMethod, parseRequestBody } from "../../util/http.js";
 import { isPlainObject } from "../../util/object.js";
 import { requireURL } from "../../util/url.js";
 export function handleEndpoints(base, handlers, request, context, caller = handleEndpoints) {
@@ -30,7 +30,7 @@ export function handleEndpoints(base, handlers, request, context, caller = handl
 async function _handleEndpoint({ endpoint, callback }, 
 /** Params we already matched/parsed from the URL. */
 params, request, context, caller) {
-    const content = await getRequestContent(request, caller);
+    const content = await parseRequestBody(request, caller);
     const unsafePayload = content === undefined ? params : isPlainObject(content) ? { ...content, ...params } : content;
     const payload = endpoint.payload.validate(unsafePayload);
     const unsafeResult = await callback(payload, request, context);

package/api/index.d.ts

@@ -4,8 +4,10 @@ export * from "./endpoint/Endpoint.js";
 export * from "./endpoint/util.js";
 export * from "./provider/APIProvider.js";
 export * from "./provider/DebugAPIProvider.js";
+export * from "./provider/JSONAPIProvider.js";
 export * from "./provider/MockAPIProvider.js";
 export * from "./provider/MockEndpointAPIProvider.js";
 export * from "./provider/ThroughAPIProvider.js";
 export * from "./provider/ValidationAPIProvider.js";
+export * from "./provider/XMLAPIProvider.js";
 export * from "./store/EndpointStore.js";

package/api/index.js

@@ -4,8 +4,10 @@ export * from "./endpoint/Endpoint.js";
 export * from "./endpoint/util.js";
 export * from "./provider/APIProvider.js";
 export * from "./provider/DebugAPIProvider.js";
+export * from "./provider/JSONAPIProvider.js";
 export * from "./provider/MockAPIProvider.js";
 export * from "./provider/MockEndpointAPIProvider.js";
 export * from "./provider/ThroughAPIProvider.js";
 export * from "./provider/ValidationAPIProvider.js";
+export * from "./provider/XMLAPIProvider.js";
 export * from "./store/EndpointStore.js";

package/api/provider/APIProvider.d.ts

@@ -1,21 +1,11 @@
 import type { AnyCaller } from "../../util/function.js";
-import { type RequestOptions } from "../../util/http.js";
-import { type PossibleURL, type URL, type URLString } from "../../util/url.js";
+import type { RequestOptions } from "../../util/http.js";
+import type { URL, URLString } from "../../util/url.js";
 import type { Endpoint } from "../endpoint/Endpoint.js";
-/** Options for an `APIProvider`. */
-export interface APIProviderOptions {
-    /** The common base URL for all rendered endpoint requests. */
-    readonly url: PossibleURL;
-    /** Options used for HTTP requests created with `this.getRequest()` and `this.fetch()` */
-    readonly options?: RequestOptions;
-}
 /** Provider for API endpoints rooted at a common base URL. */
-export declare class APIProvider {
-    /** The common base URL for all rendered endpoint requests. */
-    readonly url: URLString;
-    /** Default options used for HTTP requests created with `this.getRequest()` and `this.fetch()` */
-    readonly options: RequestOptions;
-    constructor({ url, options }: APIProviderOptions);
+export declare abstract class APIProvider<P = unknown, R = unknown> {
+    /** The base URL for this API. */
+    abstract readonly url: URLString;
     /**
      * 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.
@@ -23,22 +13,33 @@ export declare class APIProvider {
      * @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.
      */
-    renderURL<P, R>(endpoint: Endpoint<P, R>, payload: P, caller?: AnyCaller): URL;
+    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.
-     * - Path `{placeholders}` are rendered from the payload.
-     * - For `GET` and `HEAD`, remaining payload fields are appended as `?query` params.
-     * - For all other requests, payload is sent as the body.
+     *
+     * @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 `
      *
      * @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.
      */
-    getRequest<P, R>(endpoint: Endpoint<P, R>, payload: P, options?: RequestOptions, caller?: AnyCaller): Request;
+    abstract getRequest<PP extends P, RR extends R>(endpoint: Endpoint<PP, RR>, payload: PP, options?: RequestOptions, caller?: AnyCaller): Request;
     /**
      * Parse an HTTP `Response` for this endpoint.
      * - Non-2xx responses become `ResponseError`.
      * - Does not validate the result against the endpoint schema — use `ValidationAPIProvider` for that.
      */
-    parseResponse<P, R>(_endpoint: Endpoint<P, R>, response: Response, caller?: AnyCaller): Promise<R>;
-    fetch<P, R>(endpoint: Endpoint<P, R>, payload: P, options?: RequestOptions, caller?: AnyCaller): Promise<R>;
+    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. */
+    abstract fetch<PP extends P, RR extends R>(endpoint: Endpoint<PP, RR>, payload: PP, options?: RequestOptions, caller?: AnyCaller): Promise<RR>;
 }

package/api/provider/APIProvider.js

@@ -1,78 +1,3 @@
-import { ResponseError } from "../../error/ResponseError.js";
-import { isArrayItem } from "../../util/array.js";
-import { getMessage } from "../../util/error.js";
-import { assertHeadMethodPayload, getRequest, getResponseContent, HTTP_HEAD_METHODS, mergeRequestOptions, } from "../../util/http.js";
-import { omitProps } from "../../util/object.js";
-import { withURIParams } from "../../util/uri.js";
-import { requireBaseURL, requireURL } from "../../util/url.js";
 /** Provider for API endpoints rooted at a common base URL. */
 export class APIProvider {
-    /** The common base URL for all rendered endpoint requests. */
-    url;
-    /** Default options used for HTTP requests created with `this.getRequest()` and `this.fetch()` */
-    options;
-    constructor({ url, options = {} }) {
-        this.url = requireBaseURL(url, undefined, APIProvider);
-        this.options = options;
-    }
-    /**
-     * 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.
-     *
-     * @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.
-     */
-    renderURL(endpoint, payload, caller = this.renderURL) {
-        const url = requireURL(`.${endpoint.renderPath(payload, caller)}`, this.url, caller);
-        // HEAD or GET have no body (but payload can only be data object).
-        if (isArrayItem(HTTP_HEAD_METHODS, endpoint.method)) {
-            assertHeadMethodPayload(payload, endpoint.method, caller);
-            if (payload) {
-                const params = endpoint.placeholders.length ? omitProps(payload, ...endpoint.placeholders) : payload; // Omit any params that were already embedded as `{placeholders}`
-                return withURIParams(url, params, caller);
-            }
-        }
-        return url;
-    }
-    /**
-     * Create a `Request` that targets this endpoint with a given base URL.
-     * - Path `{placeholders}` are rendered from the payload.
-     * - For `GET` and `HEAD`, remaining payload fields are appended as `?query` params.
-     * - For all other requests, payload is sent as the body.
-     *
-     * @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.
-     */
-    getRequest(endpoint, payload, options, caller = this.getRequest) {
-        // Render the path into the base URL.
-        const url = this.renderURL(endpoint, payload, caller);
-        // HEAD or GET requests have no payload because it was already rendered into the URL as `?query` params.
-        if (isArrayItem(HTTP_HEAD_METHODS, endpoint.method)) {
-            return getRequest(endpoint.method, url, undefined, options);
-        }
-        // Placeholders are rendered into the path so get omitted from the body payload.
-        if (endpoint.placeholders.length) {
-            const params = omitProps(payload, ...endpoint.placeholders); // Omit any params that were already embedded as `{placeholders}`
-            return getRequest(endpoint.method, url, params, options);
-        }
-        // No placeholders.
-        return getRequest(endpoint.method, url, payload, options);
-    }
-    /**
-     * Parse an HTTP `Response` for this endpoint.
-     * - Non-2xx responses become `ResponseError`.
-     * - Does not validate the result against the endpoint schema — use `ValidationAPIProvider` for that.
-     */
-    async parseResponse(_endpoint, response, caller = this.parseResponse) {
-        const { ok, status } = response;
-        const content = await getResponseContent(response, caller);
-        if (!ok)
-            throw new ResponseError(getMessage(content) ?? `Error ${status}`, { code: status, cause: response, caller });
-        return content;
-    }
-    async fetch(endpoint, payload, options, caller = this.fetch) {
-        const request = this.getRequest(endpoint, payload, mergeRequestOptions(this.options, options), caller);
-        const response = await fetch(request);
-        return this.parseResponse(endpoint, response, caller);
-    }
 }

package/api/provider/ClientAPIProvider.d.ts

@@ -0,0 +1,38 @@
+import type { AnyCaller } from "../../util/function.js";
+import { type RequestBodyMethod, type RequestHeadMethod, type RequestOptions } from "../../util/http.js";
+import type { Nullish } from "../../util/null.js";
+import { type PossibleURIParams } from "../../util/uri.js";
+import { type PossibleURL, type URL, type URLString } from "../../util/url.js";
+import type { Endpoint } from "../endpoint/Endpoint.js";
+import type { APIProvider } from "./APIProvider.js";
+export declare class ClientAPIProvider<P = unknown, R = unknown> implements APIProvider<P, R> {
+    /** The common base URL for all rendered endpoint requests. */
+    readonly url: URLString;
+    /** Default options used for HTTP requests created with `this.getRequest()` and `this.fetch()` */
+    readonly options: RequestOptions;
+    /** Timeout in milliseconds, or `undefined` for no timeout. */
+    readonly timeout: number | undefined;
+    constructor({ url, options, timeout }: ClientAPIProviderOptions);
+    renderURL<PP extends P, RR extends R>(endpoint: Endpoint<PP, RR>, payload: PP, caller?: AnyCaller): URL;
+    getRequest<PP extends P, RR extends R>(endpoint: Endpoint<PP, RR>, payload: PP, options?: RequestOptions, caller?: AnyCaller): Request;
+    /** Internal implementation function for `getRequest()` used for requests that have no body. */
+    protected _getHeadRequest(method: RequestHeadMethod, //
+    url: PossibleURL, params: Nullish<PossibleURIParams>, options: RequestOptions, caller: AnyCaller): Request;
+    /** Internal implementation function for `getRequest()` used for requests that have a body.  */
+    protected _getBodyRequest(method: RequestBodyMethod, //
+    url: PossibleURL, payload: P, options: RequestOptions, caller: AnyCaller): Request;
+    parseResponse<PP extends P, RR extends R>(_endpoint: Endpoint<PP, RR>, response: Response, caller?: AnyCaller): Promise<RR>;
+    fetch<PP extends P, RR extends R>(endpoint: Endpoint<PP, RR>, payload: PP, options?: RequestOptions, caller?: AnyCaller): Promise<RR>;
+}
+/** Options for an `APIProvider`. */
+export interface ClientAPIProviderOptions {
+    /** The common base URL for all rendered endpoint requests. */
+    readonly url: PossibleURL;
+    /**
+     * Options used for HTTP requests created with `this.getRequest()` and `this.fetch()`
+     * - Omits `signal` because it's not relevant at the provider level.
+     */
+    readonly options?: Omit<RequestOptions, "signal">;
+    /** Timeout in milliseconds, or `undefined` for no timeout. */
+    readonly timeout?: number | undefined;
+}

package/api/provider/ClientAPIProvider.js

@@ -0,0 +1,68 @@
+import { ResponseError } from "../../error/ResponseError.js";
+import { isData } from "../../util/data.js";
+import { getMessage } from "../../util/error.js";
+import { assertRequestHeadPayload, getHeadRequest, getRequest, isRequestHeadMethod, mergeRequestOptions, parseResponseBody, } from "../../util/http.js";
+import { omitProps } from "../../util/object.js";
+import { withURIParams } from "../../util/uri.js";
+import { requireBaseURL, requireURL } from "../../util/url.js";
+export class ClientAPIProvider {
+    /** The common base URL for all rendered endpoint requests. */
+    url;
+    /** Default options used for HTTP requests created with `this.getRequest()` and `this.fetch()` */
+    options;
+    /** Timeout in milliseconds, or `undefined` for no timeout. */
+    timeout;
+    constructor({ url, options = {}, timeout }) {
+        this.url = requireBaseURL(url, undefined, ClientAPIProvider);
+        this.options = options;
+        this.timeout = timeout;
+    }
+    renderURL(endpoint, payload, caller = this.renderURL) {
+        const url = requireURL(`.${endpoint.renderPath(payload, caller)}`, this.url, caller);
+        // HEAD or GET have no body (but payload can only be data object).
+        if (isRequestHeadMethod(endpoint.method)) {
+            assertRequestHeadPayload(payload, endpoint.method, caller);
+            if (payload) {
+                const params = endpoint.placeholders.length ? omitProps(payload, ...endpoint.placeholders) : payload; // Omit any params that have already been embedded as `{placeholders}`.
+                return withURIParams(url, params, caller);
+            }
+        }
+        return url;
+    }
+    getRequest(endpoint, payload, options, caller = this.getRequest) {
+        // Render the path into the base URL.
+        const url = this.renderURL(endpoint, payload, caller);
+        // Merge the param options with `this.options`
+        // If we have a timeout set, create an `AbortSignal` for it.
+        const signal = this.timeout ? AbortSignal.timeout(this.timeout) : null;
+        const mergedOptions = mergeRequestOptions({ signal, ...this.options }, options);
+        // HEAD or GET requests need no payload because it was already rendered into the URL as `?query` params by `this.renderURL()`
+        if (isRequestHeadMethod(endpoint.method))
+            return this._getHeadRequest(endpoint.method, url, undefined, mergedOptions, caller);
+        // Body request.
+        const body = isData(payload) ? omitProps(payload, ...endpoint.placeholders) : payload; // Omit any params that have already been embedded as `{placeholders}`.
+        return this._getBodyRequest(endpoint.method, url, body, mergedOptions, caller);
+    }
+    /** Internal implementation function for `getRequest()` used for requests that have no body. */
+    _getHeadRequest(method, //
+    url, params, options, caller) {
+        return getHeadRequest(method, url, params, options, caller);
+    }
+    /** Internal implementation function for `getRequest()` used for requests that have a body.  */
+    _getBodyRequest(method, //
+    url, payload, options, caller) {
+        return getRequest(method, url, payload, options, caller);
+    }
+    async parseResponse(_endpoint, response, caller = this.parseResponse) {
+        const { ok, status } = response;
+        const content = await parseResponseBody(response, caller);
+        if (!ok)
+            throw new ResponseError(getMessage(content) ?? `Error ${status}`, { code: status, cause: response, caller });
+        return content;
+    }
+    async fetch(endpoint, payload, options, caller = this.fetch) {
+        const request = this.getRequest(endpoint, payload, options, caller);
+        const response = await fetch(request);
+        return this.parseResponse(endpoint, response, caller);
+    }
+}

package/api/provider/DebugAPIProvider.d.ts

@@ -3,6 +3,6 @@ import type { RequestOptions } from "../../util/http.js";
 import type { Endpoint } from "../endpoint/Endpoint.js";
 import { ThroughAPIProvider } from "./ThroughAPIProvider.js";
 /** Provider that logs API operations to the console. */
-export declare class DebugAPIProvider extends ThroughAPIProvider {
-    fetch<P, R>(endpoint: Endpoint<P, R>, payload: P, options?: RequestOptions, caller?: AnyCaller): Promise<R>;
+export declare class DebugAPIProvider<P, R> extends ThroughAPIProvider<P, R> {
+    fetch<PP extends P, RR extends R>(endpoint: Endpoint<PP, RR>, payload: PP, options?: RequestOptions, caller?: AnyCaller): Promise<RR>;
 }

package/api/provider/JSONAPIProvider.d.ts

@@ -0,0 +1,16 @@
+import type { AnyCaller } from "../../util/function.js";
+import { type RequestBodyMethod, type RequestOptions } from "../../util/http.js";
+import type { PossibleURL } from "../../util/url.js";
+import type { Endpoint } from "../endpoint/Endpoint.js";
+import { ClientAPIProvider } from "./ClientAPIProvider.js";
+/** API provider that always sends request bodies as JSON and parses responses as JSON. */
+export declare class JSONAPIProvider<P = unknown, R = unknown> extends ClientAPIProvider<P, R> {
+    protected _getBodyRequest(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.
+     */
+    parseResponse<PP extends P, RR extends R>(_endpoint: Endpoint<PP, RR>, response: Response, caller?: AnyCaller): Promise<RR>;
+}

package/api/provider/JSONAPIProvider.js

@@ -0,0 +1,23 @@
+import { ResponseError } from "../../error/ResponseError.js";
+import { getMessage } from "../../util/error.js";
+import { getJSONRequest, parseResponseJSON } from "../../util/http.js";
+import { ClientAPIProvider } from "./ClientAPIProvider.js";
+/** API provider that always sends request bodies as JSON and parses responses as JSON. */
+export class JSONAPIProvider extends ClientAPIProvider {
+    _getBodyRequest(method, url, payload, options, caller) {
+        return getJSONRequest(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.
+     */
+    async parseResponse(_endpoint, response, caller = this.parseResponse) {
+        const { ok, status } = response;
+        const content = await parseResponseJSON(response, caller);
+        if (!ok)
+            throw new ResponseError(getMessage(content) ?? `Error ${status}`, { code: status, cause: response, caller });
+        return content;
+    }
+}

package/api/provider/MockAPIProvider.d.ts

@@ -1,34 +1,25 @@
 import type { AnyCaller } from "../../util/function.js";
-import { type RequestHandler, type RequestOptions } from "../../util/http.js";
+import type { RequestHandler, RequestOptions } from "../../util/http.js";
 import type { AnyEndpoint, Endpoint } from "../endpoint/Endpoint.js";
-import { APIProvider, type APIProviderOptions } from "./APIProvider.js";
+import { ClientAPIProvider } from "./ClientAPIProvider.js";
+import { ThroughAPIProvider } from "./ThroughAPIProvider.js";
 /** A structured log entry emitted by `MockAPIProvider` for one of its provider operations. */
 export type MockAPICall = {
     readonly type: "fetch";
     readonly endpoint: AnyEndpoint;
-    readonly options: RequestOptions;
     readonly payload: unknown;
     readonly request: Request;
     readonly response: Response;
     readonly result: unknown;
 };
 /**
- * Construction options for a `MockAPIProvider`
- * - Same as options for a normal `APIProvider`, but with an optional URL.
+ * Provider that logs API calls 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`.
  */
-export interface MockAPIProviderOptions extends Omit<APIProviderOptions, "url"> {
-    /** Optional URL, defaults to `"https://api.mock.com"` */
-    url?: APIProviderOptions["url"];
-}
-/** Provider that logs API calls without sending network requests. */
-export declare class MockAPIProvider extends APIProvider {
+export declare class MockAPIProvider<P = unknown, R = unknown> extends ThroughAPIProvider<P, R> {
     readonly calls: MockAPICall[];
     readonly handler: RequestHandler;
-    constructor(handler: RequestHandler, { url, ...options }?: MockAPIProviderOptions);
-    /**
-     * Log a `fetch()` call without using the network.
-     * - If `getResult` is configured, its return value is returned as-is (no schema validation).
-     * - Otherwise `undefined` is returned.
-     */
-    fetch<P, R>(endpoint: Endpoint<P, R>, payload: P, _options?: RequestOptions, caller?: AnyCaller): Promise<R>;
+    constructor(handler?: RequestHandler, source?: ClientAPIProvider<P, R>);
+    fetch<PP extends P, RR extends R>(endpoint: Endpoint<PP, RR>, payload: PP, options?: RequestOptions, caller?: AnyCaller): Promise<RR>;
 }

package/api/provider/MockAPIProvider.js

@@ -1,24 +1,27 @@
-import { mergeRequestOptions } from "../../util/http.js";
-import { APIProvider } from "./APIProvider.js";
-/** Provider that logs API calls without sending network requests. */
-export class MockAPIProvider extends APIProvider {
+import { ClientAPIProvider } from "./ClientAPIProvider.js";
+import { ThroughAPIProvider } from "./ThroughAPIProvider.js";
+/** Default handler just echoes back the input request as text. */
+async function _passthroughHandler(request) {
+    return new Response(await request.text());
+}
+/**
+ * Provider that logs API calls 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`.
+ */
+export class MockAPIProvider extends ThroughAPIProvider {
     calls = [];
     handler;
-    constructor(handler, { url = "https://api.mock.com", ...options } = {}) {
-        super({ url, ...options });
+    constructor(handler = _passthroughHandler, source = new ClientAPIProvider({ url: "https://api.mock.com" })) {
+        super(source);
         this.handler = handler;
     }
-    /**
-     * Log a `fetch()` call without using the network.
-     * - If `getResult` is configured, its return value is returned as-is (no schema validation).
-     * - Otherwise `undefined` is returned.
-     */
-    async fetch(endpoint, payload, _options = {}, caller = this.fetch) {
-        const options = mergeRequestOptions(this.options, _options);
+    // Log a `fetch()` call without using the network.
+    async fetch(endpoint, payload, options = {}, caller = this.fetch) {
         const request = this.getRequest(endpoint, payload, options, caller);
         const response = await this.handler(request);
         const result = await this.parseResponse(endpoint, response, caller);
-        this.calls.push({ type: "fetch", endpoint, payload, options, request, response, result });
+        this.calls.push({ type: "fetch", endpoint, payload, request, response, result });
         return result;
     }
 }

package/api/provider/MockEndpointAPIProvider.d.ts

@@ -1,12 +1,6 @@
 import { type EndpointHandlers } from "../endpoint/util.js";
-import { MockAPIProvider, type MockAPIProviderOptions } from "./MockAPIProvider.js";
-/**
- * Construction options for a `MockAPIProvider`
- * - Same as options for a normal `MockAPIProviderOptions`, but with a `context` property for the endpoints.
- */
-export interface MockEndpointAPIProviderOptions<C = void> extends MockAPIProviderOptions {
-    context: C;
-}
+import type { ClientAPIProvider } from "./ClientAPIProvider.js";
+import { MockAPIProvider } from "./MockAPIProvider.js";
 /**
  * Provider that mocks an API that calls and matches an array of `EndpointHandler` objects returned from `Endpoint.handler()`
  * - Used to test server-side API code, calls against an API made up of multiple `Endpoint` instances.
@@ -18,6 +12,6 @@ export interface MockEndpointAPIProviderOptions<C = void> extends MockAPIProvide
  *  const result = await api.fetch(endpoint, 4); // Mock a call to the endpoint through the provider.
  *  expect(result).toBe(16);
  */
-export declare class MockEndpointAPIProvider<C> extends MockAPIProvider {
-    constructor(handlers: EndpointHandlers<C>, { context, ...options }: MockEndpointAPIProviderOptions<C>);
+export declare class MockEndpointAPIProvider<P, R, C> extends MockAPIProvider<P, R> {
+    constructor(handlers: EndpointHandlers<C>, context: C, source?: ClientAPIProvider<P, R>);
 }

package/api/provider/MockEndpointAPIProvider.js

@@ -12,7 +12,7 @@ import { MockAPIProvider } from "./MockAPIProvider.js";
  *  expect(result).toBe(16);
  */
 export class MockEndpointAPIProvider extends MockAPIProvider {
-    constructor(handlers, { context, ...options }) {
-        super(request => handleEndpoints(this.url, handlers, request, context), options);
+    constructor(handlers, context, source) {
+        super(request => handleEndpoints(this.url, handlers, request, context, this.fetch), source);
     }
 }

package/api/provider/ThroughAPIProvider.d.ts

@@ -1,5 +1,6 @@
 import type { AnyCaller } from "../../util/function.js";
 import type { RequestOptions } from "../../util/http.js";
+import type { Sourceable } from "../../util/source.js";
 import type { URL, URLString } from "../../util/url.js";
 import type { Endpoint } from "../endpoint/Endpoint.js";
 import type { APIProvider } from "./APIProvider.js";
@@ -7,13 +8,12 @@ import type { APIProvider } from "./APIProvider.js";
  * Provider wrapper that delegates API operations to a source provider.
  * - Extend this when you want to intercept only selected API operations, such as injecting auth headers or logging.
  */
-export declare class ThroughAPIProvider implements APIProvider {
-    readonly source: APIProvider;
+export declare class ThroughAPIProvider<P, R> implements APIProvider<P, R>, Sourceable<APIProvider<P, R>> {
     get url(): URLString;
-    get options(): RequestOptions;
-    constructor(source: APIProvider);
-    renderURL<P, R>(endpoint: Endpoint<P, R>, payload: P, caller?: AnyCaller): URL;
-    getRequest<P, R>(endpoint: Endpoint<P, R>, payload: P, options?: RequestOptions, caller?: AnyCaller): Request;
-    parseResponse<P, R>(endpoint: Endpoint<P, R>, response: Response, caller?: AnyCaller): Promise<R>;
-    fetch<P, R>(endpoint: Endpoint<P, R>, payload: P, options?: RequestOptions, caller?: AnyCaller): Promise<R>;
+    readonly source: APIProvider<P, R>;
+    constructor(source: APIProvider<P, R>);
+    renderURL<PP extends P, RR extends R>(endpoint: Endpoint<PP, RR>, payload: PP, caller?: AnyCaller): URL;
+    getRequest<PP extends P, RR extends R>(endpoint: Endpoint<PP, RR>, payload: PP, options?: RequestOptions, caller?: AnyCaller): Request;
+    parseResponse<PP extends P, RR extends R>(endpoint: Endpoint<PP, RR>, response: Response, caller?: AnyCaller): Promise<RR>;
+    fetch<PP extends P, RR extends R>(endpoint: Endpoint<PP, RR>, payload: PP, options?: RequestOptions, caller?: AnyCaller): Promise<RR>;
 }

package/api/provider/ThroughAPIProvider.js

@@ -3,13 +3,10 @@
  * - Extend this when you want to intercept only selected API operations, such as injecting auth headers or logging.
  */
 export class ThroughAPIProvider {
-    source;
     get url() {
         return this.source.url;
     }
-    get options() {
-        return this.source.options;
-    }
+    source;
     constructor(source) {
         this.source = source;
     }

package/api/provider/ValidationAPIProvider.d.ts

@@ -3,6 +3,6 @@ import type { RequestOptions } from "../../util/http.js";
 import type { Endpoint } from "../endpoint/Endpoint.js";
 import { ThroughAPIProvider } from "./ThroughAPIProvider.js";
 /** Validate an asynchronous source provider (source can have any type because validation guarantees the type). */
-export declare class ValidationAPIProvider extends ThroughAPIProvider {
-    fetch<P, R>(endpoint: Endpoint<P, R>, payload: P, options?: RequestOptions, caller?: AnyCaller): Promise<R>;
+export declare class ValidationAPIProvider<P, R> extends ThroughAPIProvider<P, R> {
+    fetch<PP extends P, RR extends R>(endpoint: Endpoint<PP, RR>, payload: PP, options?: RequestOptions, caller?: AnyCaller): Promise<RR>;
 }

package/api/provider/ValidationAPIProvider.js

@@ -4,16 +4,13 @@ import { ThroughAPIProvider } from "./ThroughAPIProvider.js";
 export class ValidationAPIProvider extends ThroughAPIProvider {
     async fetch(endpoint, payload, options, caller = this.fetch) {
         // Validate payload — let thrown strings bubble up as user-readable messages for e.g. form handlers.
-        const validPayload = _validatePayload(endpoint, payload);
+        const validPayload = endpoint.payload.validate(payload);
         // Call through to source (raw transport, no schema validation).
         const content = await this.source.fetch(endpoint, validPayload, options, caller);
         // Validate result — wrap in ResponseError as this is a server/transport problem, not user error.
         return _validateResult(endpoint, content, caller);
     }
 }
-function _validatePayload(endpoint, payload) {
-    return endpoint.payload.validate(payload);
-}
 function _validateResult(endpoint, content, caller) {
     try {
         return endpoint.result.validate(content);

package/api/provider/XMLAPIProvider.d.ts

@@ -0,0 +1,17 @@
+import type { Data } from "../../util/data.js";
+import type { AnyCaller } from "../../util/function.js";
+import { type RequestBodyMethod, type RequestOptions } from "../../util/http.js";
+import type { PossibleURL } from "../../util/url.js";
+import type { Endpoint } from "../endpoint/Endpoint.js";
+import { ClientAPIProvider } from "./ClientAPIProvider.js";
+/** API provider that always sends request bodies as XML and parses responses as plain text. */
+export declare class XMLAPIProvider<P extends Data = Data, R = string> extends ClientAPIProvider<P, R> {
+    protected _getBodyRequest(method: RequestBodyMethod, url: PossibleURL, payload: P, options: RequestOptions, caller: AnyCaller): Request;
+    /**
+     * Parse a text `Response` for an endpoint.
+     *
+     * - Non-2xx responses become `ResponseError`.
+     * - The response body is always returned as raw text.
+     */
+    parseResponse<PP extends P, RR extends R>(_endpoint: Endpoint<PP, RR>, response: Response, caller?: AnyCaller): Promise<RR>;
+}