shelving 1.177.0 → 1.179.0

package/api/cache/APICache.d.ts

@@ -0,0 +1,23 @@
+import type { Endpoint } from "../endpoint/Endpoint.js";
+import type { APIProvider } from "../provider/APIProvider.js";
+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 {
+    private readonly _caches;
+    readonly provider: APIProvider;
+    constructor(provider: APIProvider);
+    /** Get (or create) the `EndpointCache` for the given endpoint. */
+    get<P, R>(endpoint: Endpoint<P, R>): EndpointCache<P, R>;
+    /** Invalidate a specific store for an endpoint. */
+    invalidate<P, R>(endpoint: Endpoint<P, R>, payload: P): void;
+    /** Invalidate all stores for an endpoint. */
+    invalidateAll<P, R>(endpoint: Endpoint<P, R>): void;
+    /** Trigger a refetch on a specific store for an endpoint. */
+    refetch<P, R>(endpoint: Endpoint<P, R>, payload: P): void;
+    /** Trigger a refetch on all stores for an endpoint. */
+    refetchAll<P, R>(endpoint: Endpoint<P, R>): void;
+    [Symbol.dispose](): void;
+}

package/api/cache/APICache.js

@@ -0,0 +1,39 @@
+import { setMapItem } from "../../util/map.js";
+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 class APICache {
+    _caches = new Map();
+    provider;
+    constructor(provider) {
+        this.provider = provider;
+    }
+    /** Get (or create) the `EndpointCache` for the given endpoint. */
+    get(endpoint) {
+        return this._caches.get(endpoint) || setMapItem(this._caches, endpoint, new EndpointCache(endpoint, this.provider));
+    }
+    /** Invalidate a specific store for an endpoint. */
+    invalidate(endpoint, payload) {
+        this._caches.get(endpoint)?.invalidate(payload);
+    }
+    /** Invalidate all stores for an endpoint. */
+    invalidateAll(endpoint) {
+        this._caches.get(endpoint)?.invalidateAll();
+    }
+    /** Trigger a refetch on a specific store for an endpoint. */
+    refetch(endpoint, payload) {
+        this._caches.get(endpoint)?.refetch(payload);
+    }
+    /** Trigger a refetch on all stores for an endpoint. */
+    refetchAll(endpoint) {
+        this._caches.get(endpoint)?.refetchAll();
+    }
+    // Implement Disposable.
+    [Symbol.dispose]() {
+        for (const cache of this._caches.values())
+            cache[Symbol.dispose]();
+        this._caches.clear();
+    }
+}

package/api/cache/EndpointCache.d.ts

@@ -0,0 +1,26 @@
+import type { Endpoint } from "../endpoint/Endpoint.js";
+import type { APIProvider } from "../provider/APIProvider.js";
+import { EndpointStore } from "../store/EndpointStore.js";
+/**
+ * Cache of `EndpointStore` objects for a single endpoint, keyed by serialized payload.
+ * - Use `get(payload)` to retrieve or create the `EndpointStore` for a given payload.
+ */
+export declare class EndpointCache<P, R> implements Disposable {
+    private readonly _stores;
+    readonly endpoint: Endpoint<P, R>;
+    readonly provider: APIProvider;
+    constructor(endpoint: Endpoint<P, R>, provider: APIProvider);
+    /** Get (or create) the `EndpointStore` for the given payload. */
+    get(payload: P): EndpointStore<P, R>;
+    /** Invalidate a specific store. */
+    invalidate(payload: P): void;
+    /** Invalidate all stores. */
+    invalidateAll(): void;
+    /** Trigger a refetch on a specific store. */
+    refetch(payload: P): void;
+    /** Trigger a refetch on all stores. */
+    refetchAll(): void;
+    [Symbol.dispose](): void;
+}
+/** Any endpoint cache. */
+export type AnyEndpointCache = EndpointCache<any, any>;

package/api/cache/EndpointCache.js

@@ -0,0 +1,50 @@
+import { setMapItem } from "../../util/map.js";
+import { EndpointStore } from "../store/EndpointStore.js";
+/** Serialize a payload to a stable string key for use in a `Map`. */
+function _serializePayload(payload) {
+    if (payload === undefined)
+        return "";
+    return JSON.stringify(payload);
+}
+/**
+ * Cache of `EndpointStore` objects for a single endpoint, keyed by serialized payload.
+ * - Use `get(payload)` to retrieve or create the `EndpointStore` for a given payload.
+ */
+export class EndpointCache {
+    _stores = new Map();
+    endpoint;
+    provider;
+    constructor(endpoint, provider) {
+        this.endpoint = endpoint;
+        this.provider = provider;
+    }
+    /** Get (or create) the `EndpointStore` for the given payload. */
+    get(payload) {
+        const key = _serializePayload(payload);
+        return this._stores.get(key) || setMapItem(this._stores, key, new EndpointStore(this.endpoint, payload, this.provider));
+    }
+    /** Invalidate a specific store. */
+    invalidate(payload) {
+        this.get(payload)?.invalidate();
+    }
+    /** Invalidate all stores. */
+    invalidateAll() {
+        for (const store of this._stores.values())
+            store.invalidate();
+    }
+    /** Trigger a refetch on a specific store. */
+    refetch(payload) {
+        this.get(payload)?.fetch();
+    }
+    /** Trigger a refetch on all stores. */
+    refetchAll() {
+        for (const store of this._stores.values())
+            store.fetch();
+    }
+    // Implement Disposable.
+    [Symbol.dispose]() {
+        for (const store of this._stores.values())
+            store[Symbol.dispose]();
+        this._stores.clear();
+    }
+}

package/api/endpoint/Endpoint.d.ts

@@ -0,0 +1,100 @@
+import { type Schema } from "../../schema/Schema.js";
+import type { ImmutableArray } from "../../util/array.js";
+import { type Data } from "../../util/data.js";
+import type { AnyCaller, Arguments } from "../../util/function.js";
+import type { RequestMethod, RequestParams } from "../../util/http.js";
+import type { AbsolutePath } from "../../util/path.js";
+import { type TemplatePlaceholders } from "../../util/template.js";
+import type { EndpointCallback, EndpointHandler } from "./util.js";
+/**
+ * An abstract API resource definition, used to specify types for e.g. serverless functions.
+ *
+ * @param method The method of the endpoint, e.g. `GET`
+ * @param path Endpoint path, possibly including placeholders e.g. `/users/{id}`
+ * @param payload A `Schema` for the payload of the endpoint.
+ * @param result A `Schema` for the result of the endpoint.
+ */
+export declare class Endpoint<P, R> {
+    /** Endpoint method. */
+    readonly method: RequestMethod;
+    /** Endpoint path, possibly including placeholders e.g. `/users/{id}` */
+    readonly path: AbsolutePath;
+    /** Endpoint path, possibly including placeholders e.g. `/users/{id}` */
+    readonly placeholders: TemplatePlaceholders;
+    /** Payload schema. */
+    readonly payload: Schema<P>;
+    /** Result schema. */
+    readonly result: Schema<R>;
+    constructor(method: RequestMethod, path: AbsolutePath, payload: Schema<P>, result: Schema<R>);
+    /**
+     * Render the path for this endpoint with the given payload.
+     * - Path might contain `{placeholder}` values that are replaced with values from `payload`.
+     *
+     * @returns URL string combining `base` with this endpoint's path, with any `{placeholders}` rendered and `?query` params added.
+     *
+     * @throws {RequiredError} if this endpoint's path has `{placeholders}` but `payload` is not a data object.
+     */
+    renderPath(payload: P, caller?: AnyCaller): AbsolutePath;
+    /**
+     * Match a method/path pair against this endpoint and return any matched `{placeholder}` params.
+     */
+    match(method: RequestMethod, path: AbsolutePath, caller?: AnyCaller): RequestParams | undefined;
+    /**
+     * Create an endpoint handler pairing for this endpoint.
+     * @param callback The callback function that implements the logic for this endpoint by receiving the payload and returning the response.
+     * @returns An `EndpointHandler` object combining this endpoint and the callback into a single typed object.
+     */
+    handler<A extends Arguments = []>(callback: EndpointCallback<P, R, A>): EndpointHandler<P, R, A>;
+    /** Convert to string, e.g. `GET /user/{id}` */
+    toString(): string;
+}
+/** Any endpoint. */
+export type AnyEndpoint = Endpoint<any, any>;
+/** List of endpoints. */
+export type Endpoints = ImmutableArray<AnyEndpoint>;
+/** Extract the payload type from a `Endpoint`. */
+export type PayloadType<X extends Endpoint<unknown, unknown>> = X extends Endpoint<infer Y, unknown> ? Y : never;
+/** Extract the result type from a `Endpoint`. */
+export type EndpointType<X extends Endpoint<unknown, unknown>> = X extends Endpoint<unknown, infer Y> ? Y : never;
+/**
+ * Represent a HEAD request to a specified path, with validated payload and return types.
+ * "The HEAD method requests a representation of the specified resource. Requests using HEAD should only retrieve data and should not contain a request content."
+ */
+export declare function HEAD<P extends Data, R>(path: AbsolutePath, payload?: Schema<P>, result?: Schema<R>): Endpoint<P, R>;
+export declare function HEAD<P extends Data>(path: AbsolutePath, payload: Schema<P>): Endpoint<P, undefined>;
+export declare function HEAD<R>(path: AbsolutePath, payload: undefined, result: Schema<R>): Endpoint<undefined, R>;
+/**
+ * Represent a GET request to a specified path, with validated payload and return types.
+ * "The GET method requests a representation of the specified resource. Requests using GET should only retrieve data and should not contain a request content."
+ */
+export declare function GET<P extends Data, R>(path: AbsolutePath, payload?: Schema<P>, result?: Schema<R>): Endpoint<P, R>;
+export declare function GET<P extends Data>(path: AbsolutePath, payload: Schema<P>): Endpoint<P, undefined>;
+export declare function GET<R>(path: AbsolutePath, payload: undefined, result: Schema<R>): Endpoint<undefined, R>;
+/**
+ * Represent a POST request to a specified path, with validated payload and return types.
+ * "The POST method submits an entity to the specified resource, often causing a change in state or side effects on the server.
+ */
+export declare function POST<P, R>(path: AbsolutePath, payload?: Schema<P>, result?: Schema<R>): Endpoint<P, R>;
+export declare function POST<P>(path: AbsolutePath, payload: Schema<P>): Endpoint<P, undefined>;
+export declare function POST<R>(path: AbsolutePath, payload: undefined, result: Schema<R>): Endpoint<undefined, R>;
+/**
+ * Represent a PUT request to a specified path, with validated payload and return types.
+ * "The PUT method replaces all current representations of the target resource with the request content."
+ */
+export declare function PUT<P, R>(path: AbsolutePath, payload?: Schema<P>, result?: Schema<R>): Endpoint<P, R>;
+export declare function PUT<P>(path: AbsolutePath, payload: Schema<P>): Endpoint<P, undefined>;
+export declare function PUT<R>(path: AbsolutePath, payload: undefined, result: Schema<R>): Endpoint<undefined, R>;
+/**
+ * Represent a PATCH request to a specified path, with validated payload and return types.
+ * "The PATCH method applies partial modifications to a resource."
+ */
+export declare function PATCH<P, R>(path: AbsolutePath, payload?: Schema<P>, result?: Schema<R>): Endpoint<P, R>;
+export declare function PATCH<P>(path: AbsolutePath, payload: Schema<P>): Endpoint<P, undefined>;
+export declare function PATCH<R>(path: AbsolutePath, payload: undefined, result: Schema<R>): Endpoint<undefined, R>;
+/**
+ * Represent a DELETE request to a specified path, with validated payload and return types.
+ * "The DELETE method deletes the specified resource."
+ */
+export declare function DELETE<P, R>(path: AbsolutePath, payload?: Schema<P>, result?: Schema<R>): Endpoint<P, R>;
+export declare function DELETE<P>(path: AbsolutePath, payload: Schema<P>): Endpoint<P, undefined>;
+export declare function DELETE<R>(path: AbsolutePath, payload: undefined, result: Schema<R>): Endpoint<undefined, R>;

package/api/endpoint/Endpoint.js

@@ -0,0 +1,95 @@
+import { RequiredError } from "../../error/RequiredError.js";
+import { UNDEFINED } from "../../schema/Schema.js";
+import { isData } from "../../util/data.js";
+import { getPlaceholders, matchTemplate, renderTemplate } from "../../util/template.js";
+/**
+ * An abstract API resource definition, used to specify types for e.g. serverless functions.
+ *
+ * @param method The method of the endpoint, e.g. `GET`
+ * @param path Endpoint path, possibly including placeholders e.g. `/users/{id}`
+ * @param payload A `Schema` for the payload of the endpoint.
+ * @param result A `Schema` for the result of the endpoint.
+ */
+export class Endpoint {
+    /** Endpoint method. */
+    method;
+    /** Endpoint path, possibly including placeholders e.g. `/users/{id}` */
+    path;
+    /** Endpoint path, possibly including placeholders e.g. `/users/{id}` */
+    placeholders;
+    /** Payload schema. */
+    payload;
+    /** Result schema. */
+    result;
+    constructor(method, path, payload, result) {
+        this.method = method;
+        this.path = path;
+        this.placeholders = getPlaceholders(path);
+        this.payload = payload;
+        this.result = result;
+    }
+    /**
+     * Render the path for this endpoint with the given payload.
+     * - Path might contain `{placeholder}` values that are replaced with values from `payload`.
+     *
+     * @returns URL string combining `base` with this endpoint's path, with any `{placeholders}` rendered and `?query` params added.
+     *
+     * @throws {RequiredError} if this endpoint's path has `{placeholders}` but `payload` is not a data object.
+     */
+    renderPath(payload, caller = this.renderPath) {
+        // Placeholders.
+        if (this.placeholders.length) {
+            assertPlaceholderPayload(payload, this, caller);
+            return renderTemplate(this.path, payload, caller);
+        }
+        // No placeholders.
+        return this.path;
+    }
+    /**
+     * Match a method/path pair against this endpoint and return any matched `{placeholder}` params.
+     */
+    match(method, path, caller = this.match) {
+        if (method !== this.method)
+            return undefined;
+        return matchTemplate(this.path, path, caller);
+    }
+    /**
+     * Create an endpoint handler pairing for this endpoint.
+     * @param callback The callback function that implements the logic for this endpoint by receiving the payload and returning the response.
+     * @returns An `EndpointHandler` object combining this endpoint and the callback into a single typed object.
+     */
+    handler(callback) {
+        return { endpoint: this, callback };
+    }
+    /** Convert to string, e.g. `GET /user/{id}` */
+    toString() {
+        return `${this.method} ${this.path}`;
+    }
+}
+export function HEAD(path, payload = UNDEFINED, result = UNDEFINED) {
+    return new Endpoint("HEAD", path, payload, result);
+}
+export function GET(path, payload = UNDEFINED, result = UNDEFINED) {
+    return new Endpoint("GET", path, payload, result);
+}
+export function POST(path, payload = UNDEFINED, result = UNDEFINED) {
+    return new Endpoint("POST", path, payload, result);
+}
+export function PUT(path, payload = UNDEFINED, result = UNDEFINED) {
+    return new Endpoint("PUT", path, payload, result);
+}
+export function PATCH(path, payload = UNDEFINED, result = UNDEFINED) {
+    return new Endpoint("PATCH", path, payload, result);
+}
+export function DELETE(path, payload = UNDEFINED, result = UNDEFINED) {
+    return new Endpoint("DELETE", path, payload, result);
+}
+/** Assert that an endpoint with `{placeholders}` only allows data payloads. */
+function assertPlaceholderPayload(payload, endpoint, caller = assertPlaceholderPayload) {
+    if (!isData(payload))
+        throw new RequiredError("Payload for request with URL {placeholders} must be data object", {
+            endpoint,
+            received: payload,
+            caller,
+        });
+}

package/api/endpoint/util.d.ts

@@ -0,0 +1,24 @@
+import type { Arguments } from "../../util/function.js";
+import { type PossibleURL } from "../../util/url.js";
+import type { Endpoint } from "./Endpoint.js";
+/**
+ * A function that handles an endpoint request, with a payload and returns a result.
+ * - `payload` has already been validated against the endpoint payload schema before the callback is invoked.
+ * - `request` is always the original incoming request object.
+ */
+export type EndpointCallback<P, R, A extends Arguments = []> = (payload: P, request: Request, ...args: A) => R | Response | Promise<R | Response>;
+/** A typed endpoint definition paired with its implementation callback. */
+export interface EndpointHandler<P = unknown, R = unknown, A extends Arguments = []> {
+    readonly endpoint: Endpoint<P, R>;
+    readonly callback: EndpointCallback<P, R, A>;
+}
+export type AnyEndpointHandler<A extends Arguments = []> = EndpointHandler<any, any, A>;
+/** A collection of endpoint handlers that can be matched and invoked by `handleEndpoints()`. */
+export type EndpointHandlers<A extends Arguments = []> = Iterable<AnyEndpointHandler<A>>;
+/**
+ * Handle a `Request` with the first matching endpoint handler after stripping any base-path prefix from the request pathname.
+ * - The original `Request` object is passed through to the callback unchanged.
+ * - Path params and query params are merged before payload validation.
+ * @param base The base URL for the API, e.g. `https://myapi.com/`
+ */
+export declare function handleEndpoints<A extends Arguments = []>(request: Request, base: PossibleURL, handlers: EndpointHandlers<A>, ...args: A): Promise<Response>;

package/api/endpoint/util.js

@@ -0,0 +1,61 @@
+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 { isPlainObject } from "../../util/object.js";
+import { requireURL } from "../../util/url.js";
+/**
+ * Handle a `Request` with the first matching endpoint handler after stripping any base-path prefix from the request pathname.
+ * - The original `Request` object is passed through to the callback unchanged.
+ * - Path params and query params are merged before payload validation.
+ * @param base The base URL for the API, e.g. `https://myapi.com/`
+ */
+export function handleEndpoints(request, base, handlers, ...args) {
+    const caller = handleEndpoints;
+    const { url, method } = request;
+    if (!isRequestMethod(method))
+        throw new MethodNotAllowedError("Unsupported request method", { received: method, caller });
+    const { origin: baseOrigin, pathname: basePath } = requireURL(base, undefined, caller);
+    const { origin: requestOrigin, pathname: requestPath, searchParams } = requireURL(url, base, caller);
+    if (baseOrigin !== requestOrigin)
+        throw new NotFoundError("No matching origin", { expected: baseOrigin, received: requestOrigin, caller });
+    const targetPath = _stripPathPrefix(requestPath, basePath, caller);
+    for (const handler of handlers) {
+        const pathParams = handler.endpoint.match(method, targetPath, caller);
+        if (!pathParams)
+            continue;
+        const params = searchParams.size ? { ...getDictionary(searchParams), ...pathParams } : pathParams;
+        return handleEndpoint(handler, params, request, args, handleEndpoints);
+    }
+    throw new NotFoundError("No matching endpoint", { received: targetPath, caller });
+}
+/**
+ * Validate and invoke an endpoint callback after the routing layer has already matched URL params.
+ */
+async function handleEndpoint({ endpoint, callback }, 
+/** Params we already matched/parsed from the URL. */
+params, request, args, caller = handleEndpoint) {
+    const content = await getRequestContent(request, caller);
+    const unsafePayload = content === undefined ? params : isPlainObject(content) ? { ...content, ...params } : content;
+    const payload = endpoint.payload.validate(unsafePayload);
+    const unsafeResult = await callback(payload, request, ...args);
+    try {
+        return getResponse(endpoint.result.validate(unsafeResult));
+    }
+    catch (thrown) {
+        if (typeof thrown === "string")
+            throw new ValueError(`Invalid result for ${endpoint.toString()}:\n${thrown}`, { endpoint, callback, cause: thrown, caller });
+        throw thrown;
+    }
+}
+/** Strip a prefix like `/a/b` from a path like `/a/b/c/d` to produce a remainder path like `/c/d`. */
+function _stripPathPrefix(path, prefix, caller) {
+    prefix = prefix === "/" ? "/" : prefix.replace(/\/$/, "");
+    if (prefix === "/")
+        return path;
+    if (path === prefix)
+        return "/";
+    if (path.startsWith(`${prefix}/`))
+        return path.slice(prefix.length);
+    throw new NotFoundError("No matching endpoint", { received: path, expected: prefix, caller });
+}

package/api/index.d.ts

@@ -0,0 +1,11 @@
+export * from "./cache/APICache.js";
+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/MockAPIProvider.js";
+export * from "./provider/ThroughAPIProvider.js";
+export * from "./provider/ValidationAPIProvider.js";
+export * from "./store/EndpointStore.js";

package/api/index.js

@@ -0,0 +1,11 @@
+export * from "./cache/APICache.js";
+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/MockAPIProvider.js";
+export * from "./provider/ThroughAPIProvider.js";
+export * from "./provider/ValidationAPIProvider.js";
+export * from "./store/EndpointStore.js";

package/api/provider/APIProvider.d.ts

@@ -0,0 +1,9 @@
+import type { AnyCaller } from "../../util/function.js";
+import type { RequestOptions } from "../../util/http.js";
+import type { Endpoint } from "../endpoint/Endpoint.js";
+export declare abstract class APIProvider {
+    /**
+     * Perform a fetch to an endpoint via this provider and validate the returned response against the endpoint result schema.
+     */
+    abstract fetch<P, R>(endpoint: Endpoint<P, R>, payload: P, options?: RequestOptions, caller?: AnyCaller): Promise<R>;
+}

package/api/provider/APIProvider.js

@@ -0,0 +1,2 @@
+export class APIProvider {
+}

package/api/provider/ClientAPIProvider.d.ts

@@ -0,0 +1,37 @@
+import type { AnyCaller } from "../../util/function.js";
+import { type RequestOptions } from "../../util/http.js";
+import { type PossibleURL, type URLString } from "../../util/url.js";
+import type { Endpoint } from "../endpoint/Endpoint.js";
+import type { APIProvider } from "./APIProvider.js";
+/** 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()` */
+    readonly options?: RequestOptions;
+}
+/** Provider for API endpoints rooted at a common base URL. */
+export declare class ClientAPIProvider implements 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 }: ClientAPIProviderOptions);
+    /**
+     * 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<P, R>(endpoint: Endpoint<P, R>, payload: P, 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>;
+}

package/api/provider/ClientAPIProvider.js

@@ -0,0 +1,51 @@
+import { ResponseError } from "../../error/ResponseError.js";
+import { getMessage } from "../../util/error.js";
+import { getRequest, getResponseContent, mergeRequestOptions } from "../../util/http.js";
+import { omitProps } from "../../util/object.js";
+import { requireBaseURL, requireURL } from "../../util/url.js";
+/** Provider for API endpoints rooted at a common base URL. */
+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;
+    constructor({ url, options = {} }) {
+        this.url = requireBaseURL(url, undefined, ClientAPIProvider);
+        this.options = options;
+    }
+    /**
+     * 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 = requireURL(`.${endpoint.renderPath(payload, caller)}`, requireBaseURL(this.url, undefined, caller), caller).href;
+        // Placeholders are rendered into the path so get omitted from the body payload.
+        if (endpoint.placeholders.length)
+            return getRequest(endpoint.method, url, omitProps(payload, ...endpoint.placeholders), 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/DebugAPIProvider.d.ts

@@ -0,0 +1,8 @@
+import type { AnyCaller } from "../../util/function.js";
+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>;
+}

package/api/provider/DebugAPIProvider.js

@@ -0,0 +1,16 @@
+import { ThroughAPIProvider } from "./ThroughAPIProvider.js";
+/** Provider that logs API operations to the console. */
+export class DebugAPIProvider extends ThroughAPIProvider {
+    async fetch(endpoint, payload, options, caller = this.fetch) {
+        try {
+            console.debug("⋯ FETCH", endpoint.method, endpoint.path, payload);
+            const result = await super.fetch(endpoint, payload, options, caller);
+            console.debug("↩ FETCH", endpoint.method, endpoint.path, result);
+            return result;
+        }
+        catch (reason) {
+            console.error("✘ FETCH", endpoint.method, endpoint.path, payload, reason);
+            throw reason;
+        }
+    }
+}

package/api/provider/MockAPIProvider.d.ts

@@ -0,0 +1,34 @@
+import type { AnyCaller } from "../../util/function.js";
+import { type RequestHandler, type RequestOptions } from "../../util/http.js";
+import type { AnyEndpoint, Endpoint } from "../endpoint/Endpoint.js";
+import { ClientAPIProvider, type ClientAPIProviderOptions } from "./ClientAPIProvider.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`.
+ * - Accepts the normal `APIProvider` options.
+ */
+export interface MockAPIProviderOptions extends ClientAPIProviderOptions {
+    /** Implement this handler to mock the the request/response input/output. */
+    readonly handler: RequestHandler;
+}
+/** Provider that logs API calls without sending network requests. */
+export declare class MockAPIProvider extends ClientAPIProvider {
+    readonly calls: MockAPICall[];
+    readonly handler: RequestHandler;
+    constructor({ handler, ...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>;
+}

package/api/provider/MockAPIProvider.js

@@ -0,0 +1,24 @@
+import { mergeRequestOptions } from "../../util/http.js";
+import { ClientAPIProvider } from "./ClientAPIProvider.js";
+/** Provider that logs API calls without sending network requests. */
+export class MockAPIProvider extends ClientAPIProvider {
+    calls = [];
+    handler;
+    constructor({ handler, ...options }) {
+        super(options);
+        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);
+        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 });
+        return result;
+    }
+}