shelving 1.183.0 → 1.184.1

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

@@ -3,9 +3,12 @@ export * from "./cache/EndpointCache.js";
 export * from "./endpoint/Endpoint.js";
 export * from "./endpoint/util.js";
 export * from "./provider/APIProvider.js";
+export * from "./provider/ClientAPIProvider.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

@@ -3,9 +3,12 @@ export * from "./cache/EndpointCache.js";
 export * from "./endpoint/Endpoint.js";
 export * from "./endpoint/util.js";
 export * from "./provider/APIProvider.js";
+export * from "./provider/ClientAPIProvider.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,28 +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()`
-     * - 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;
-}
 /** 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;
-    /** Timeout in milliseconds, or `undefined` for no timeout. */
-    readonly timeout: number | undefined;
-    constructor({ url, options, timeout }: 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.
@@ -30,7 +13,7 @@ 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.
      *
@@ -50,12 +33,13 @@ 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.
      */
-    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,95 +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;
-    /** Timeout in milliseconds, or `undefined` for no timeout. */
-    timeout;
-    constructor({ url, options = {}, timeout }) {
-        this.url = requireBaseURL(url, undefined, APIProvider);
-        this.options = options;
-        this.timeout = timeout;
-    }
-    /**
-     * 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.
-     *
-     * @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(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 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, mergedOptions);
-        }
-        // 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, mergedOptions);
-        }
-        // No placeholders.
-        return getRequest(endpoint.method, url, payload, mergedOptions);
-    }
-    /**
-     * 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, 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,13 +1,12 @@
 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 } 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;
@@ -18,14 +17,9 @@ export type MockAPICall = {
  * - 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 declare class MockAPIProvider extends ThroughAPIProvider {
+export declare class MockAPIProvider<P = unknown, R = unknown> extends ThroughAPIProvider<P, R> {
     readonly calls: MockAPICall[];
     readonly handler: RequestHandler;
-    constructor(handler: RequestHandler, source?: APIProvider);
-    /**
-     * 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,6 +1,9 @@
-import { mergeRequestOptions } from "../../util/http.js";
-import { APIProvider } from "./APIProvider.js";
+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`.
@@ -9,21 +12,16 @@ import { ThroughAPIProvider } from "./ThroughAPIProvider.js";
 export class MockAPIProvider extends ThroughAPIProvider {
     calls = [];
     handler;
-    constructor(handler, source = new APIProvider({ url: "https://api.mock.com" })) {
+    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,5 +1,5 @@
 import { type EndpointHandlers } from "../endpoint/util.js";
-import type { APIProvider } from "./APIProvider.js";
+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()`
@@ -12,6 +12,6 @@ import { MockAPIProvider } from "./MockAPIProvider.js";
  *  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: C, source?: APIProvider);
+export declare class MockEndpointAPIProvider<P, R, C> extends MockAPIProvider<P, R> {
+    constructor(handlers: EndpointHandlers<C>, context: C, source?: ClientAPIProvider<P, R>);
 }

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,14 +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;
-    get timeout(): number | undefined;
-    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,16 +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;
-    }
-    get timeout() {
-        return this.source.timeout;
-    }
+    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>;
+}

package/api/provider/XMLAPIProvider.js

@@ -0,0 +1,22 @@
+import { ResponseError } from "../../error/ResponseError.js";
+import { getXMLRequest } from "../../util/http.js";
+import { ClientAPIProvider } from "./ClientAPIProvider.js";
+/** API provider that always sends request bodies as XML and parses responses as plain text. */
+export class XMLAPIProvider extends ClientAPIProvider {
+    _getBodyRequest(method, url, payload, options, caller) {
+        return getXMLRequest(method, url, payload, options, caller);
+    }
+    /**
+     * Parse a text `Response` for an endpoint.
+     *
+     * - Non-2xx responses become `ResponseError`.
+     * - The response body is always returned as raw text.
+     */
+    async parseResponse(_endpoint, response, caller = this.parseResponse) {
+        const { ok, status } = response;
+        const content = await response.text();
+        if (!ok)
+            throw new ResponseError(content || `Error ${status}`, { code: status, cause: response, caller });
+        return content;
+    }
+}

package/api/store/EndpointStore.d.ts

@@ -6,7 +6,7 @@ import type { APIProvider } from "../provider/APIProvider.js";
  * Store object that loads a result from an API endpoint and manages its state.
  */
 export declare class EndpointStore<P, R> extends Store<R> implements Disposable {
-    readonly provider: APIProvider;
+    readonly provider: APIProvider<P, R>;
     readonly endpoint: Endpoint<P, R>;
     private _payload;
     /**
@@ -19,7 +19,7 @@ export declare class EndpointStore<P, R> extends Store<R> implements Disposable
     get loading(): boolean;
     get value(): R;
     set value(value: R | typeof NONE);
-    constructor(endpoint: Endpoint<P, R>, payload: P, provider: APIProvider);
+    constructor(endpoint: Endpoint<P, R>, payload: P, provider: APIProvider<P, R>);
     /** Store the inflight fetch request. */
     private _inflight;
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "shelving",
-	"version": "1.183.0",
+	"version": "1.184.1",
 	"author": "Dave Houlbrooke <dave@shax.com>",
 	"repository": {
 		"type": "git",

package/react/createAPIContext.d.ts

@@ -3,10 +3,11 @@ import type { Endpoint } from "../api/endpoint/Endpoint.js";
 import type { APIProvider } from "../api/provider/APIProvider.js";
 import type { EndpointStore } from "../api/store/EndpointStore.js";
 import type { Nullish } from "../util/null.js";
-export interface APIContext {
+export interface APIContext<P, R> {
     /** Get an `EndpointStore` for the specified endpoint/payload in the current `APIProvider` context. */
-    useAPI<P, R>(this: void, endpoint: Endpoint<P, R>, payload: P, maxAge?: number): EndpointStore<P, R>;
-    useAPI<P, R>(this: void, endpoint: Nullish<Endpoint<P, R>>, payload: P, maxAge?: number): EndpointStore<P, R> | undefined;
+    useAPI<PP extends P, RR extends R>(this: void, endpoint: Endpoint<PP, RR>, payload: PP, maxAge?: number): EndpointStore<PP, RR>;
+    useAPI<PP extends P, RR extends R>(this: void, endpoint: Nullish<Endpoint<PP, RR>>, payload: PP, maxAge?: number): EndpointStore<PP, RR> | undefined;
+    /** The `<APIContext>` wrapper to give your React components access to this API provider. */
     readonly APIContext: ({ children }: {
         children: ReactNode;
     }) => ReactElement;
@@ -18,4 +19,4 @@ export interface APIContext {
  *
  * @todo Use and integreate our `EndpointCache` functionality and use it in this.
  */
-export declare function createAPIContext(provider: APIProvider): APIContext;
+export declare function createAPIContext<P, R>(provider: APIProvider<P, R>): APIContext<P, R>;

package/util/http.d.ts

@@ -1,9 +1,8 @@
-import { RequestError } from "../error/RequestError.js";
-import { ResponseError } from "../error/ResponseError.js";
 import { type Data } from "./data.js";
 import type { ImmutableDictionary } from "./dictionary.js";
 import type { AnyCaller, Arguments } from "./function.js";
 import { type Nullish } from "./null.js";
+import { type PossibleURIParams } from "./uri.js";
 import { type PossibleURL } from "./url.js";
 /** A handler function takes a `Request` and optional extra arguments and returns a `Response` (possibly asynchronously). */
 export type RequestHandler<A extends Arguments = []> = (request: Request, ...args: A) => Response | Promise<Response>;
@@ -11,11 +10,8 @@ export type RequestHandler<A extends Arguments = []> = (request: Request, ...arg
 export type OptionalRequestHandler<A extends Arguments = []> = (request: Request, ...args: A) => Response | Promise<Response> | undefined;
 /** A list of optional request handlers. */
 export type OptionalRequestHandlers<A extends Arguments = []> = Iterable<OptionalRequestHandler<A>>;
-export declare function _getMessageJSON(message: Request | Response, MessageError: typeof RequestError | typeof ResponseError, caller: AnyCaller): Promise<unknown>;
-export declare function _getMessageFormData(message: Request | Response, MessageError: typeof RequestError | typeof ResponseError, caller: AnyCaller): Promise<unknown>;
-export declare function _getMessageContent(message: Request | Response, MessageError: typeof RequestError | typeof ResponseError, caller: AnyCaller): Promise<unknown>;
 /**
- * Get the body content of an HTTP `Request` based on its content type, or throw `RequestError` if the content could not be parsed.
+ * Parse the body content of an HTTP `Request` based on its content type, or throw `RequestError` if the content could not be parsed.
  *
  * @returns undefined If the request method is `GET` or `HEAD` (these request methods have no body).
  * @returns unknown If content type is `application/json` and has valid JSON (including `undefined` if the content is empty).
@@ -24,18 +20,41 @@ export declare function _getMessageContent(message: Request | Response, MessageE
  *
  * @throws RequestError if the content is not `text/plain`, or `application/json` with valid JSON.
  */
-export declare function getRequestContent(request: Request, caller?: AnyCaller): Promise<unknown>;
+export declare function parseRequestBody(request: Request, caller?: AnyCaller): Promise<unknown>;
 /**
- * Get the body content of an HTTP `Response` based on its content type, or throw `ResponseError` if the content could not be parsed.
+ * Parse JSON from an HTTP `Request`, or return `undefined` when the request has no body.
+ *
+ * @throws RequestError If the request body is not valid JSON.
+ */
+export declare function parseRequestJSON(request: Request, caller?: AnyCaller): Promise<unknown>;
+/**
+ * Parse `FormData` from an HTTP `Request`, or return `undefined` when the request has no body.
+ *
+ * @throws RequestError If the request body is not valid multipart form-data.
+ */
+export declare function parseRequestFormData(request: Request, caller?: AnyCaller): Promise<FormData | undefined>;
+/**
+ * Parse the body content of an HTTP `Response` based on its content type, or throw `ResponseError` if the content could not be parsed.
  *
- * @returns undefined If the request status is `204 No Content` (this response has no body).
  * @returns unknown If content type is `application/json` and has valid JSON (including `undefined` if the content is empty).
  * @returns unknown If content type is `multipart/form-data` then convert it to a simple `Data` object.
  * @returns string If content type is `text/plain` or anything else (including `""` empty string if it's empty).
  *
- * @throws RequestError if the content is not `text/plain` or `application/json` with valid JSON.
+ * @throws ResponseError if the content is not `text/plain` or `application/json` with valid JSON.
+ */
+export declare function parseResponseBody(response: Response, caller?: AnyCaller): Promise<unknown>;
+/**
+ * Parse JSON from an HTTP `Response`, or return `undefined` when the response has no body.
+ *
+ * @throws ResponseError If the response body is not valid JSON.
  */
-export declare function getResponseContent(response: Response, caller?: AnyCaller): Promise<unknown>;
+export declare function parseResponseJSON(response: Response, caller?: AnyCaller): Promise<unknown>;
+/**
+ * Parse `FormData` from an HTTP `Response`, or return `undefined` when the response has no body.
+ *
+ * @throws ResponseError If the response body is not valid multipart form-data.
+ */
+export declare function parseResponseFormData(response: Response, caller?: AnyCaller): Promise<FormData>;
 /**
  * Get an HTTP `Response` for an unknown value.
  *
@@ -57,20 +76,16 @@ export declare function getResponse(value: unknown): Response;
  * @param debug If `true` include the error message in the response (for debugging), or `false` to return generic error codes (for security).
  */
 export declare function getErrorResponse(reason: unknown, debug?: boolean): Response;
-/** The set of supported HTTP methods that do not send a request body. */
-export declare const HTTP_HEAD_METHODS: readonly ["HEAD", "GET"];
-/** The set of supported HTTP methods that may send a request body. */
-export declare const HTTP_BODY_METHODS: readonly ["POST", "PUT", "PATCH", "DELETE"];
-/** The full set of supported HTTP methods. */
-export declare const HTTP_METHODS: readonly ["HEAD", "GET", "POST", "PUT", "PATCH", "DELETE"];
 /** HTTP request methods that have no body. */
-export type RequestHeadMethod = (typeof HTTP_HEAD_METHODS)[number];
+export type RequestHeadMethod = "HEAD" | "GET";
 /** HTTP request methods that have a body. */
-export type RequestBodyMethod = (typeof HTTP_BODY_METHODS)[number];
+export type RequestBodyMethod = "POST" | "PUT" | "PATCH" | "DELETE";
 /** HTTP request methods. */
-export type RequestMethod = (typeof HTTP_METHODS)[number];
-/** Check whether an arbitrary method string is one of Shelving's supported request methods. */
+export type RequestMethod = RequestHeadMethod | RequestBodyMethod;
+/** Check whether an HTTP Request method string is a supported request methods. */
 export declare function isRequestMethod(method: string): method is RequestMethod;
+/** Check whether an HTTP Request method string is a supported request method that never sends a body. */
+export declare function isRequestHeadMethod(method: string): method is RequestHeadMethod;
 /** Params in requests are a dictionary of strings. */
 export type RequestParams = ImmutableDictionary<string>;
 /** Configurable options for endpoint requests. */
@@ -83,8 +98,77 @@ export type RequestOptions = Pick<RequestInit, "cache" | "credentials" | "header
  */
 export declare function mergeRequestOptions({ headers: aHeaders, signal: aSignal, ...a }?: RequestOptions, { headers: bHeaders, signal: bSignal, ...b }?: RequestOptions): RequestOptions;
 /**
- * Create a `Request` instance with a valid content type based on the body.
+ * Create a body-less `Request`.
+ * - `HEAD` and `GET` requests never send a body.
+ *
+ * @param method The HTTP method.
+ * @param url The target URL.
+ * @param params `?query` params to encode into the URL.
+ * @param options Additional request options.
+ * @returns A `Request` with no body content.
+ *
+ * @example getHeadRequest("POST", "https://api.example.com/items", { name: "abc" })
+ */
+export declare function getHeadRequest(method: RequestHeadMethod, url: PossibleURL, params: Nullish<PossibleURIParams>, options?: RequestOptions, caller?: AnyCaller): Request;
+/**
+ * Create a plain-text `Request`.
+ *
+ * - `HEAD` and `GET` requests never send a body.
  *
+ * @param method The HTTP method.
+ * @param url The target URL.
+ * @param body The plain-text request body.
+ * @param options Additional request options.
+ * @returns A `Request` with `text/plain` content type.
+ *
+ * @example getTextRequest("POST", "https://api.example.com/items", "hello")
+ */
+export declare function getTextRequest(method: RequestMethod, url: PossibleURL, body: string, options?: RequestOptions, caller?: AnyCaller): Request;
+/**
+ * Create a JSON `Request`.
+ * - `HEAD` and `GET` requests never send a body.
+ * - If the JSON body is a data object for `HEAD` or `GET`, it is appended as `?query` params instead.
+ *
+ * @param method The HTTP method.
+ * @param url The target URL.
+ * @param body The value to JSON-encode.
+ * @param options Additional request options.
+ * @returns A `Request` with `application/json` content type.
+ *
+ * @example getJSONRequest("POST", "https://api.example.com/items", { name: "abc" })
+ */
+export declare function getJSONRequest(method: RequestBodyMethod, url: PossibleURL, body: unknown, options?: RequestOptions, caller?: AnyCaller): Request;
+/**
+ * Create a multipart form-data `Request`.
+ * - `HEAD` and `GET` requests never send a body.
+ *
+ * @param method The HTTP method.
+ * @param url The target URL.
+ * @param body The `FormData` payload.
+ * @param options Additional request options.
+ * @returns A `Request` with a multipart body.
+ *
+ * @example getFormDataRequest("POST", "https://api.example.com/upload", new FormData())
+ */
+export declare function getFormDataRequest(method: RequestBodyMethod, url: PossibleURL, body: FormData, options?: RequestOptions, caller?: AnyCaller): Request;
+/**
+ * Create an XML `Request`.
+ * - `HEAD` and `GET` requests never send a body.
+ * - For `HEAD` and `GET`, the data object is appended as `?query` params instead.
+ *
+ * @param method The HTTP method.
+ * @param url The target URL.
+ * @param data The data object to serialize as XML.
+ * @param options Additional request options.
+ * @returns A `Request` with `application/xml` content type.
+ *
+ * @throws {RequiredError} If the XML data contains invalid element names or values.
+ *
+ * @example getXMLRequest("POST", "https://api.example.com/items", { item: { name: "abc" } })
+ */
+export declare function getXMLRequest(method: RequestBodyMethod, url: PossibleURL, data: Data, options?: RequestOptions, caller?: AnyCaller): Request;
+/**
+ * Create a `Request` instance with a valid content type based on the body.
  * - `undefined` or `null` are sent with no body.
  * - `FormData` is sent with `multipart/formdata`
  * - `string` is sent with `text/plain` header.
@@ -98,4 +182,4 @@ export declare function mergeRequestOptions({ headers: aHeaders, signal: aSignal
  */
 export declare function getRequest(method: RequestMethod, url: PossibleURL, payload: unknown, options?: RequestOptions, caller?: AnyCaller): Request;
 /** Assert that the payload for a HEAD or GET method is a data object, null, or undefined. */
-export declare function assertHeadMethodPayload(payload: unknown, method: RequestHeadMethod, caller?: AnyCaller): asserts payload is Nullish<Data>;
+export declare function assertRequestHeadPayload(payload: unknown, method: RequestHeadMethod, caller?: AnyCaller): asserts payload is Nullish<Data>;

package/util/http.js

@@ -1,13 +1,14 @@
 import { RequestError } from "../error/RequestError.js";
 import { RequiredError } from "../error/RequiredError.js";
 import { ResponseError } from "../error/ResponseError.js";
-import { isArrayItem } from "./array.js";
 import { isData } from "./data.js";
 import { isError } from "./error.js";
 import { isNullish } from "./null.js";
 import { withURIParams } from "./uri.js";
 import { requireURL } from "./url.js";
-export async function _getMessageJSON(message, MessageError, caller) {
+import { getXML } from "./xml.js";
+/** Get parsed `JSON` from a `Request` or `Response`. */
+async function _parseMessageJSON(message, MessageError, caller) {
     const trimmed = (await message.text()).trim();
     if (!trimmed.length)
         return undefined;
@@ -18,7 +19,8 @@ export async function _getMessageJSON(message, MessageError, caller) {
         throw new MessageError("Body must be valid JSON", { received: trimmed, cause, caller });
     }
 }
-export async function _getMessageFormData(message, MessageError, caller) {
+/** Get parsed `FormData` from a `Request` or `Response`. */
+async function _parseMessageFormData(message, MessageError, caller) {
     try {
         return await message.formData();
     }
@@ -26,18 +28,19 @@ export async function _getMessageFormData(message, MessageError, caller) {
         throw new MessageError(`Body must be valid form multipart data`, { cause, caller });
     }
 }
-export function _getMessageContent(message, MessageError, caller) {
+/** Get parsed body from a `Request` or `Response`. */
+function _parseMessageBody(message, MessageError, caller) {
     const type = message.headers.get("Content-Type");
-    if (!type || type?.startsWith("text/"))
+    if (type?.startsWith("text/"))
         return message.text();
     if (type?.startsWith("application/json"))
-        return _getMessageJSON(message, MessageError, caller);
+        return _parseMessageJSON(message, MessageError, caller);
     if (type?.startsWith("multipart/form-data"))
-        return _getMessageFormData(message, MessageError, caller);
-    return Promise.resolve();
+        return _parseMessageFormData(message, MessageError, caller);
+    return Promise.resolve(undefined);
 }
 /**
- * Get the body content of an HTTP `Request` based on its content type, or throw `RequestError` if the content could not be parsed.
+ * Parse the body content of an HTTP `Request` based on its content type, or throw `RequestError` if the content could not be parsed.
  *
  * @returns undefined If the request method is `GET` or `HEAD` (these request methods have no body).
  * @returns unknown If content type is `application/json` and has valid JSON (including `undefined` if the content is empty).
@@ -46,29 +49,52 @@ export function _getMessageContent(message, MessageError, caller) {
  *
  * @throws RequestError if the content is not `text/plain`, or `application/json` with valid JSON.
  */
-export function getRequestContent(request, caller = getRequestContent) {
-    const { method } = request;
-    // The HTTP/1.1 RFC 7231 does not forbid sending a body in GET or HEAD requests, but it is uncommon and not recommended because many servers, proxies, and caches may ignore or mishandle it.
-    if (method === "GET" || method === "HEAD")
-        return Promise.resolve(undefined);
-    return _getMessageContent(request, RequestError, caller);
+export function parseRequestBody(request, caller = parseRequestBody) {
+    return _parseMessageBody(request, RequestError, caller);
 }
 /**
- * Get the body content of an HTTP `Response` based on its content type, or throw `ResponseError` if the content could not be parsed.
+ * Parse JSON from an HTTP `Request`, or return `undefined` when the request has no body.
+ *
+ * @throws RequestError If the request body is not valid JSON.
+ */
+export function parseRequestJSON(request, caller = parseRequestJSON) {
+    return _parseMessageJSON(request, RequestError, caller);
+}
+/**
+ * Parse `FormData` from an HTTP `Request`, or return `undefined` when the request has no body.
+ *
+ * @throws RequestError If the request body is not valid multipart form-data.
+ */
+export function parseRequestFormData(request, caller = parseRequestFormData) {
+    return _parseMessageFormData(request, RequestError, caller);
+}
+/**
+ * Parse the body content of an HTTP `Response` based on its content type, or throw `ResponseError` if the content could not be parsed.
  *
- * @returns undefined If the request status is `204 No Content` (this response has no body).
  * @returns unknown If content type is `application/json` and has valid JSON (including `undefined` if the content is empty).
  * @returns unknown If content type is `multipart/form-data` then convert it to a simple `Data` object.
  * @returns string If content type is `text/plain` or anything else (including `""` empty string if it's empty).
  *
- * @throws RequestError if the content is not `text/plain` or `application/json` with valid JSON.
+ * @throws ResponseError if the content is not `text/plain` or `application/json` with valid JSON.
+ */
+export function parseResponseBody(response, caller = parseResponseBody) {
+    return _parseMessageBody(response, ResponseError, caller);
+}
+/**
+ * Parse JSON from an HTTP `Response`, or return `undefined` when the response has no body.
+ *
+ * @throws ResponseError If the response body is not valid JSON.
  */
-export function getResponseContent(response, caller = getResponseContent) {
-    const { status } = response;
-    // RFC 7230 Section 3.3.3: A server MUST NOT send a Content-Length header field in any response with a status code of 1xx (Informational), 204 (No Content), or 304 (Not Modified).
-    if ((status >= 100 && status < 200) || status === 204 || status === 304)
-        return Promise.resolve(undefined);
-    return _getMessageContent(response, ResponseError, caller);
+export function parseResponseJSON(response, caller = parseResponseJSON) {
+    return _parseMessageJSON(response, ResponseError, caller);
+}
+/**
+ * Parse `FormData` from an HTTP `Response`, or return `undefined` when the response has no body.
+ *
+ * @throws ResponseError If the response body is not valid multipart form-data.
+ */
+export function parseResponseFormData(response, caller = parseResponseFormData) {
+    return _parseMessageFormData(response, ResponseError, caller);
 }
 /**
  * Get an HTTP `Response` for an unknown value.
@@ -117,20 +143,18 @@ export function getErrorResponse(reason, debug = false) {
     // Otherwise return a generic error message with no details.
     return new Response(undefined, { status });
 }
-/** The set of supported HTTP methods that do not send a request body. */
-export const HTTP_HEAD_METHODS = ["HEAD", "GET"];
-/** The set of supported HTTP methods that may send a request body. */
-export const HTTP_BODY_METHODS = ["POST", "PUT", "PATCH", "DELETE"];
-/** The full set of supported HTTP methods. */
-export const HTTP_METHODS = [...HTTP_HEAD_METHODS, ...HTTP_BODY_METHODS];
-/** Check whether an arbitrary method string is one of Shelving's supported request methods. */
+// Method arrays.
+const _REQUEST_HEAD_METHODS = ["HEAD", "GET"];
+const _REQUEST_BODY_METHODS = ["POST", "PUT", "PATCH", "DELETE"];
+const _REQUEST_METHODS = [..._REQUEST_HEAD_METHODS, ..._REQUEST_BODY_METHODS];
+/** Check whether an HTTP Request method string is a supported request methods. */
 export function isRequestMethod(method) {
-    return HTTP_METHODS.includes(method);
+    return _REQUEST_METHODS.includes(method);
+}
+/** Check whether an HTTP Request method string is a supported request method that never sends a body. */
+export function isRequestHeadMethod(method) {
+    return _REQUEST_HEAD_METHODS.includes(method);
 }
-/** Options for a plain text request. */
-const REQUEST_TEXT_OPTIONS = { headers: { "Content-Type": "text/plain" } };
-/** Options for a JSON request. */
-const REQUEST_JSON_OPTIONS = { headers: { "Content-Type": "application/json" } };
 /**
  * Merge provider-level and call-level request options.
  * - Scalar options from `b` override `a`.
@@ -143,8 +167,98 @@ export function mergeRequestOptions({ headers: aHeaders, signal: aSignal, ...a }
     return { ...a, ...b, signal, headers };
 }
 /**
- * Create a `Request` instance with a valid content type based on the body.
+ * Create a body-less `Request`.
+ * - `HEAD` and `GET` requests never send a body.
+ *
+ * @param method The HTTP method.
+ * @param url The target URL.
+ * @param params `?query` params to encode into the URL.
+ * @param options Additional request options.
+ * @returns A `Request` with no body content.
+ *
+ * @example getHeadRequest("POST", "https://api.example.com/items", { name: "abc" })
+ */
+export function getHeadRequest(method, url, params, options = {}, caller = getHeadRequest) {
+    return new Request(withURIParams(requireURL(url, undefined, caller), params), { ...options, method, body: null });
+}
+/**
+ * Create a plain-text `Request`.
  *
+ * - `HEAD` and `GET` requests never send a body.
+ *
+ * @param method The HTTP method.
+ * @param url The target URL.
+ * @param body The plain-text request body.
+ * @param options Additional request options.
+ * @returns A `Request` with `text/plain` content type.
+ *
+ * @example getTextRequest("POST", "https://api.example.com/items", "hello")
+ */
+export function getTextRequest(method, url, body, options = {}, caller = getTextRequest) {
+    return new Request(requireURL(url, undefined, caller), { ...mergeRequestOptions(_REQUEST_TEXT_OPTIONS, options), method, body });
+}
+const _REQUEST_TEXT_OPTIONS = { headers: { "Content-Type": "text/plain" } };
+/**
+ * Create a JSON `Request`.
+ * - `HEAD` and `GET` requests never send a body.
+ * - If the JSON body is a data object for `HEAD` or `GET`, it is appended as `?query` params instead.
+ *
+ * @param method The HTTP method.
+ * @param url The target URL.
+ * @param body The value to JSON-encode.
+ * @param options Additional request options.
+ * @returns A `Request` with `application/json` content type.
+ *
+ * @example getJSONRequest("POST", "https://api.example.com/items", { name: "abc" })
+ */
+export function getJSONRequest(method, url, body, options = {}, caller = getJSONRequest) {
+    return new Request(requireURL(url, undefined, caller), {
+        ...mergeRequestOptions(_REQUEST_JSON_OPTIONS, options),
+        method,
+        body: JSON.stringify(body),
+    });
+}
+const _REQUEST_JSON_OPTIONS = { headers: { "Content-Type": "application/json" } };
+/**
+ * Create a multipart form-data `Request`.
+ * - `HEAD` and `GET` requests never send a body.
+ *
+ * @param method The HTTP method.
+ * @param url The target URL.
+ * @param body The `FormData` payload.
+ * @param options Additional request options.
+ * @returns A `Request` with a multipart body.
+ *
+ * @example getFormDataRequest("POST", "https://api.example.com/upload", new FormData())
+ */
+export function getFormDataRequest(method, url, body, options = {}, caller = getFormDataRequest) {
+    return new Request(requireURL(url, undefined, caller), { ...options, method, body });
+}
+/**
+ * Create an XML `Request`.
+ * - `HEAD` and `GET` requests never send a body.
+ * - For `HEAD` and `GET`, the data object is appended as `?query` params instead.
+ *
+ * @param method The HTTP method.
+ * @param url The target URL.
+ * @param data The data object to serialize as XML.
+ * @param options Additional request options.
+ * @returns A `Request` with `application/xml` content type.
+ *
+ * @throws {RequiredError} If the XML data contains invalid element names or values.
+ *
+ * @example getXMLRequest("POST", "https://api.example.com/items", { item: { name: "abc" } })
+ */
+export function getXMLRequest(method, url, data, options = {}, caller = getXMLRequest) {
+    return new Request(requireURL(url, undefined, caller), {
+        ...mergeRequestOptions(_REQUEST_XML_OPTIONS, options),
+        method,
+        body: `<?xml version="1.0" encoding="UTF-8"?>${getXML(data, caller)}`,
+    });
+}
+const _REQUEST_XML_OPTIONS = { headers: { "Content-Type": "application/xml; charset=UTF-8" } };
+/**
+ * Create a `Request` instance with a valid content type based on the body.
  * - `undefined` or `null` are sent with no body.
  * - `FormData` is sent with `multipart/formdata`
  * - `string` is sent with `text/plain` header.
@@ -162,21 +276,21 @@ export function getRequest(method, url, payload, options = {}, caller = getReque
     if (isNullish(payload))
         return new Request(url, { ...options, method, body: null });
     // HEAD or GET have no body (but payload can only be data object).
-    if (isArrayItem(HTTP_HEAD_METHODS, method)) {
-        assertHeadMethodPayload(payload, method, caller);
+    if (isRequestHeadMethod(method)) {
+        assertRequestHeadPayload(payload, method, caller);
         return new Request(withURIParams(url, payload), { ...options, method, body: null });
     }
     // `FormData` instances in body pass through unaltered and will set their own `Content-Type` with complex boundary information
     if (payload instanceof FormData)
-        return new Request(url, { ...options, method, body: payload });
+        return getFormDataRequest(method, url, payload, options, caller);
     // Strings are sent as plain text.
     if (typeof payload === "string")
-        return new Request(url, { ...mergeRequestOptions(REQUEST_TEXT_OPTIONS, options), method, body: payload });
+        return getTextRequest(method, url, payload, options, caller);
     // JSON is the default.
-    return new Request(url, { ...mergeRequestOptions(REQUEST_JSON_OPTIONS, options), method, body: JSON.stringify(payload) });
+    return getJSONRequest(method, url, payload, options, caller);
 }
 /** Assert that the payload for a HEAD or GET method is a data object, null, or undefined. */
-export function assertHeadMethodPayload(payload, method, caller = assertHeadMethodPayload) {
+export function assertRequestHeadPayload(payload, method, caller = assertRequestHeadPayload) {
     if (!isData(payload) && !isNullish(payload))
         throw new RequiredError(`Payload for ${method} request must be data object, null, or undefined`, { received: payload, caller });
 }

package/util/index.d.ts

@@ -60,3 +60,4 @@ export * from "./uri.js";
 export * from "./url.js";
 export * from "./uuid.js";
 export * from "./validate.js";
+export * from "./xml.js";

package/util/index.js

@@ -60,3 +60,4 @@ export * from "./uri.js";
 export * from "./url.js";
 export * from "./uuid.js";
 export * from "./validate.js";
+export * from "./xml.js";

package/util/object.js

@@ -58,6 +58,8 @@ export function withProps(input, props) {
     return input;
 }
 export function omitProps(input, ...keys) {
+    if (!keys.length)
+        return input;
     for (const key of keys)
         if (key in input)
             return Object.fromEntries(Object.entries(input).filter(_hasntKey, keys));

package/util/xml.d.ts

@@ -0,0 +1,30 @@
+import { type Data } from "./data.js";
+import type { AnyCaller } from "./function.js";
+/**
+ * Escape a string for safe inclusion in XML text content or attribute values.
+ *
+ * @param value The raw string value.
+ * @returns The escaped XML-safe string.
+ *
+ * @example
+ * escapeXML(`Tom & "Jerry"`)
+ */
+export declare function escapeXML(value: string): string;
+/**
+ * Build an XML string from a data object.
+ *
+ * - Only data objects can be converted directly because XML requires named root and child elements.
+ * - `undefined` values are omitted from the output.
+ * - Nested data objects become nested XML elements.
+ *
+ * @param data The data object to serialize.
+ * @param caller The calling function for error context.
+ * @returns The serialized XML string.
+ *
+ * @throws {RequiredError} If a key is not a valid XML element name.
+ * @throws {RequiredError} If a value cannot be converted to XML.
+ *
+ * @example
+ * getXML({ user: { name: "Alice", age: 30 } })
+ */
+export declare function getXML(data: Data, caller?: AnyCaller): string;

package/util/xml.js

@@ -0,0 +1,54 @@
+import { RequiredError } from "../error/RequiredError.js";
+import { getDataProps, isData } from "./data.js";
+import { requireString } from "./string.js";
+import { isDefined } from "./undefined.js";
+/**
+ * Escape a string for safe inclusion in XML text content or attribute values.
+ *
+ * @param value The raw string value.
+ * @returns The escaped XML-safe string.
+ *
+ * @example
+ * escapeXML(`Tom & "Jerry"`)
+ */
+export function escapeXML(value) {
+    return value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll('"', "&quot;").replaceAll("'", "&apos;");
+}
+/**
+ * Build an XML string from a data object.
+ *
+ * - Only data objects can be converted directly because XML requires named root and child elements.
+ * - `undefined` values are omitted from the output.
+ * - Nested data objects become nested XML elements.
+ *
+ * @param data The data object to serialize.
+ * @param caller The calling function for error context.
+ * @returns The serialized XML string.
+ *
+ * @throws {RequiredError} If a key is not a valid XML element name.
+ * @throws {RequiredError} If a value cannot be converted to XML.
+ *
+ * @example
+ * getXML({ user: { name: "Alice", age: 30 } })
+ */
+export function getXML(data, caller = getXML) {
+    return Array.from(_yieldXML(data, caller)).join("");
+}
+function* _yieldXML(data, caller) {
+    for (const [key, value] of getDataProps(data)) {
+        if (!R_XML_KEY.test(key))
+            throw new RequiredError("Invalid XML key", { received: key, caller });
+        if (isDefined(value))
+            yield `<${key}>${_getXMLValue(value, caller)}</${key}>`;
+    }
+}
+function _getXMLValue(value, caller) {
+    if (typeof value === "string")
+        return escapeXML(value);
+    if (typeof value === "number" || typeof value === "boolean")
+        return requireString(value, undefined, undefined, caller);
+    if (isData(value))
+        return getXML(value, caller);
+    throw new RequiredError("Value cannot be converted to XML", { received: value, caller });
+}
+const R_XML_KEY = /^[a-z][a-z0-9]*$/i;