shelving 1.176.2 → 1.178.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 "./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 "./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/cache/EndpointStore.d.ts

@@ -0,0 +1,43 @@
+import { Store } from "../../store/Store.js";
+import { NONE } from "../../util/constants.js";
+import type { Endpoint } from "../endpoint/Endpoint.js";
+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 endpoint: Endpoint<P, R>;
+    private _payload;
+    /**
+     * The current payload set for this endpoint.
+     * - Value will only change if the new payload is not deeply equal to the current one.
+     * - If a new payload is set, it will abort any current in-flight request
+     */
+    get payload(): P;
+    set payload(next: P);
+    get loading(): boolean;
+    get value(): R;
+    set value(value: R | typeof NONE);
+    constructor(endpoint: Endpoint<P, R>, payload: P, provider: APIProvider);
+    /** Store the inflight fetch request. */
+    private _inflight;
+    /**
+     * Invalidate this endpoint, so that calls to `this.value` trigger a new fetch immediately.
+     */
+    invalidate(): void;
+    /**
+     * Fetch the result for this endpoint now.
+     * - Triggered automatically when someone reads `value` or `loading`
+     */
+    fetch(): Promise<void>;
+    /** Fetch the result if the current value is older than `maxAge` milliseconds. */
+    refreshStale(maxAge: number): void;
+    /** Abort any in-flight request now. */
+    private abort;
+    /** Fetch the result from the API endpoint now. */
+    private _fetch;
+    [Symbol.dispose](): void;
+}
+/** Any endpoint store. */
+export type AnyEndpointStore = EndpointStore<any, any>;

package/api/cache/EndpointStore.js

@@ -0,0 +1,117 @@
+import { Store } from "../../store/Store.js";
+import { NONE } from "../../util/constants.js";
+import { isDeepEqual } from "../../util/equal.js";
+const _CANCELLED = Symbol("EndpointStore/CANCELLED");
+const _TIMEOUT = Symbol("EndpointStore/TIMEOUT");
+/**
+ * Store object that loads a result from an API endpoint and manages its state.
+ */
+export class EndpointStore extends Store {
+    provider;
+    endpoint;
+    _payload;
+    /**
+     * The current payload set for this endpoint.
+     * - Value will only change if the new payload is not deeply equal to the current one.
+     * - If a new payload is set, it will abort any current in-flight request
+     */
+    get payload() {
+        return this._payload;
+    }
+    set payload(next) {
+        const current = this._payload;
+        // Did the payload actually change?
+        if (!isDeepEqual(current, next)) {
+            this._payload = next;
+            this.abort(); // Abort any in-flight requst now (as it would've been sent with the previous payload).
+            this.fetch();
+        }
+    }
+    // Override to possibly trigger a fetch when `this.loading` is read.
+    // This is because when we check `store.loading` in a component we are signalling intent that we wish to use that value.
+    get loading() {
+        const loading = super.loading;
+        if (loading)
+            this.fetch();
+        return loading;
+    }
+    // Override to possibly trigger a fetch when `this.value` is first read.
+    // This is because when we check `store.loading` in a component we are signalling intent that we wish to use that value.
+    get value() {
+        if (super.loading)
+            this.fetch();
+        return super.value;
+    }
+    set value(value) {
+        super.value = value;
+    }
+    constructor(endpoint, payload, provider) {
+        super(NONE);
+        this.endpoint = endpoint;
+        this.provider = provider;
+        this.payload = payload;
+    }
+    /** Store the inflight fetch request. */
+    _inflight = undefined;
+    /**
+     * Invalidate this endpoint, so that calls to `this.value` trigger a new fetch immediately.
+     */
+    invalidate() {
+        this.abort();
+        // @todo Implement this by setting the _age_ to `undefined` instead, so that the current value continues to exist but is so old that it triggers a refetch.
+        // That means we need to have an age system built into this somehow, we can't just implement it in `useAPI()`
+        // Don't know if I like that.....
+        this.value = NONE;
+    }
+    /**
+     * Fetch the result for this endpoint now.
+     * - Triggered automatically when someone reads `value` or `loading`
+     */
+    fetch() {
+        // Re-use existing fetch if it exists.
+        if (this._inflight)
+            return this._inflight.promise;
+        // Create a new fetch.
+        const abort = new AbortController();
+        const promise = this._fetch(abort);
+        this._inflight = { abort, promise };
+        return promise;
+    }
+    /** Fetch the result if the current value is older than `maxAge` milliseconds. */
+    refreshStale(maxAge) {
+        if (this.age > maxAge)
+            void this.fetch();
+    }
+    /** Abort any in-flight request now. */
+    abort() {
+        if (this._inflight) {
+            const { abort } = this._inflight;
+            this._inflight = undefined;
+            abort.abort(_CANCELLED);
+        }
+    }
+    /** Fetch the result from the API endpoint now. */
+    async _fetch(abort) {
+        try {
+            const value = await this.provider.fetch(this.endpoint, this._payload, { signal: abort.signal });
+            this.reason = undefined;
+            this.value = value;
+        }
+        catch (thrown) {
+            console.error(thrown);
+            if (thrown === _CANCELLED)
+                return; // Cancelled on purpose.
+            else if (thrown === _TIMEOUT)
+                this.reason = "Timed out"; // Request timed out.
+            else
+                this.reason = thrown;
+        }
+        finally {
+            this._inflight = undefined;
+        }
+    }
+    // Implement Disposable.
+    [Symbol.dispose]() {
+        this.abort();
+    }
+}

package/api/endpoint/Endpoint.d.ts

@@ -0,0 +1,119 @@
+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, type RequestOptions, type RequestParams } from "../../util/http.js";
+import type { AbsolutePath } from "../../util/path.js";
+import { type TemplatePlaceholders } from "../../util/template.js";
+import { type PossibleURL } from "../../util/url.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;
+    /**
+     * Create a `Request` that targets this endpoint with a given base URL.
+     * - Path `{placeholders}` are rendered from the payload.
+     * - For `GET` and `HEAD`, remaining payload fields are appended as `?query` params.
+     * - For all other requests, payload is sent as the body.
+     *
+     * @param base The base URL where this endpoint is targeted. Base URL conversion rules from `getBaseURL()` apply so only the `origin` and `pathname` are kept and always has a trailing slash.
+     *
+     * @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(base: PossibleURL, payload: P, options?: RequestOptions, caller?: AnyCaller): Request;
+    /**
+     * 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>;
+    /**
+     * Parse an HTTP `Response` for this endpoint and validate it against the result schema.
+     * - Non-2xx responses become `ResponseError`.
+     * - Invalid success payloads also become `ResponseError`.
+     */
+    parseResponse(response: Response, caller?: AnyCaller): Promise<R>;
+    /** 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,141 @@
+import { RequiredError } from "../../error/RequiredError.js";
+import { ResponseError } from "../../error/ResponseError.js";
+import { UNDEFINED } from "../../schema/Schema.js";
+import { isData } from "../../util/data.js";
+import { getMessage } from "../../util/error.js";
+import { getRequest, getResponseContent } from "../../util/http.js";
+import { omitProps } from "../../util/object.js";
+import { getPlaceholders, matchTemplate, renderTemplate } from "../../util/template.js";
+import { requireBaseURL, requireURL } from "../../util/url.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;
+    }
+    /**
+     * Create a `Request` that targets this endpoint with a given base URL.
+     * - Path `{placeholders}` are rendered from the payload.
+     * - For `GET` and `HEAD`, remaining payload fields are appended as `?query` params.
+     * - For all other requests, payload is sent as the body.
+     *
+     * @param base The base URL where this endpoint is targeted. Base URL conversion rules from `getBaseURL()` apply so only the `origin` and `pathname` are kept and always has a trailing slash.
+     *
+     * @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(base, payload, options, caller = this.getRequest) {
+        // Render the path into the base URL.
+        const url = requireURL(`.${this.renderPath(payload, caller)}`, requireBaseURL(base, undefined, caller), caller).href;
+        // Placeholders are rendered into the path so get omitted from the body payload.
+        if (this.placeholders.length) {
+            assertPlaceholderPayload(payload, this, caller);
+            return getRequest(this.method, url, omitProps(payload, ...this.placeholders), options);
+        }
+        // No placeholders.
+        return getRequest(this.method, url, payload, options);
+    }
+    /**
+     * 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 };
+    }
+    /**
+     * Parse an HTTP `Response` for this endpoint and validate it against the result schema.
+     * - Non-2xx responses become `ResponseError`.
+     * - Invalid success payloads also become `ResponseError`.
+     */
+    async parseResponse(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 });
+        try {
+            return this.result.validate(content);
+        }
+        catch (thrown) {
+            // Thrown string indicates a validation error in the returned response.
+            if (typeof thrown === "string")
+                throw new ResponseError(`Invalid result for ${this.toString()}:\n${thrown}`, { endpoint: this, code: 422, caller });
+            throw thrown;
+        }
+    }
+    /** 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);
+}
+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,9 @@
+export * from "./cache/APICache.js";
+export * from "./cache/EndpointCache.js";
+export * from "./cache/EndpointStore.js";
+export * from "./endpoint/Endpoint.js";
+export * from "./endpoint/util.js";
+export * from "./provider/APIProvider.js";
+export * from "./provider/ClientAPIProvider.js";
+export * from "./provider/MockAPIProvider.js";
+export * from "./provider/ThroughAPIProvider.js";