shelving 1.178.0 → 1.179.1

package/api/cache/EndpointCache.d.ts

@@ -1,6 +1,6 @@
 import type { Endpoint } from "../endpoint/Endpoint.js";
 import type { APIProvider } from "../provider/APIProvider.js";
-import { EndpointStore } from "./EndpointStore.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.

package/api/cache/EndpointCache.js

@@ -1,5 +1,5 @@
 import { setMapItem } from "../../util/map.js";
-import { EndpointStore } from "./EndpointStore.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)

package/api/endpoint/Endpoint.d.ts

@@ -2,10 +2,9 @@ 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 { RequestMethod, 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.
@@ -36,18 +35,6 @@ export declare class Endpoint<P, R> {
      * @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.
      */
@@ -58,12 +45,6 @@ export declare class Endpoint<P, R> {
      * @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;
 }

package/api/endpoint/Endpoint.js

@@ -1,12 +1,7 @@
 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.
  *
@@ -50,28 +45,6 @@ export class Endpoint {
         // 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.
      */
@@ -88,26 +61,6 @@ export class Endpoint {
     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}`;
@@ -131,6 +84,7 @@ export function PATCH(path, payload = UNDEFINED, result = UNDEFINED) {
 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", {

package/api/endpoint/util.d.ts

@@ -3,8 +3,13 @@ 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.
+ *
+ * @param payload The payload for the callback combining the `{placeholders}`, `?search` params, and body content (this has been validated against the Endpoint's payload schema).
+ * @param request The original incoming request object.
+ * @param args Any additional arguments to pass into the endpoint callback
+ *
+ * @returns {Response} Returning a `Response` object (this will pass back to the client without validation).
+ * @returns {R} Returning the return type of the handler (this will be validated against the Endpoint's result schema).
  */
 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. */
@@ -12,6 +17,7 @@ export interface EndpointHandler<P = unknown, R = unknown, A extends Arguments =
     readonly endpoint: Endpoint<P, R>;
     readonly callback: EndpointCallback<P, R, A>;
 }
+/** Any endpoint handler. */
 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>>;
@@ -19,6 +25,10 @@ export type EndpointHandlers<A extends Arguments = []> = Iterable<AnyEndpointHan
  * 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/`
+ *
+ * @param request The input request to handle.
+ *
+ * @param base The base URL for the API, e.g. `https://myapi.com/a/b`
+ * - `pathname` of this URL gets trimmed from `request.path` to form the target path when matching against endpoints, e.g. `/a/b/c/d` will produce `/c/d` for matching.
  */
 export declare function handleEndpoints<A extends Arguments = []>(request: Request, base: PossibleURL, handlers: EndpointHandlers<A>, ...args: A): Promise<Response>;

package/api/endpoint/util.js

@@ -8,7 +8,11 @@ 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/`
+ *
+ * @param request The input request to handle.
+ *
+ * @param base The base URL for the API, e.g. `https://myapi.com/a/b`
+ * - `pathname` of this URL gets trimmed from `request.path` to form the target path when matching against endpoints, e.g. `/a/b/c/d` will produce `/c/d` for matching.
  */
 export function handleEndpoints(request, base, handlers, ...args) {
     const caller = handleEndpoints;
@@ -18,27 +22,31 @@ export function handleEndpoints(request, base, handlers, ...args) {
     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);
+        throw new NotFoundError("No matching base origin", { expected: baseOrigin, received: requestOrigin, caller });
+    const targetPath = _stripPathPrefix(requestPath, basePath);
+    if (!targetPath)
+        throw new NotFoundError("No matching base path", { received: requestPath, expected: 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);
+        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 }, 
+async function _handleEndpoint({ endpoint, callback }, 
 /** Params we already matched/parsed from the URL. */
-params, request, args, caller = handleEndpoint) {
+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);
+    if (unsafeResult instanceof Response)
+        return unsafeResult;
     try {
         return getResponse(endpoint.result.validate(unsafeResult));
     }
@@ -49,7 +57,7 @@ params, request, args, caller = handleEndpoint) {
     }
 }
 /** 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) {
+function _stripPathPrefix(path, prefix) {
     prefix = prefix === "/" ? "/" : prefix.replace(/\/$/, "");
     if (prefix === "/")
         return path;
@@ -57,5 +65,4 @@ function _stripPathPrefix(path, prefix, caller) {
         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

@@ -1,9 +1,11 @@
 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/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

@@ -1,9 +1,11 @@
 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/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/ClientAPIProvider.d.ts

@@ -17,5 +17,21 @@ export declare class ClientAPIProvider implements APIProvider {
     /** 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

@@ -1,5 +1,8 @@
-import { mergeRequestOptions } from "../../util/http.js";
-import { requireBaseURL } from "../../util/url.js";
+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. */
@@ -10,9 +13,39 @@ export class ClientAPIProvider {
         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 = endpoint.getRequest(this.url, payload, mergeRequestOptions(this.options, options), caller);
+        const request = this.getRequest(endpoint, payload, mergeRequestOptions(this.options, options), caller);
         const response = await fetch(request);
-        return endpoint.parseResponse(response, caller);
+        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

@@ -12,23 +12,18 @@ export type MockAPICall = {
     readonly response: Response;
     readonly result: unknown;
 };
-/**
- * Construction options for a `MockAPIProvider`.
- * - Accepts the normal `APIProvider` options.
- */
+/** Construction options for a `MockAPIProvider`. */
 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);
+    constructor(handler: RequestHandler, options?: MockAPIProviderOptions);
     /**
      * Log a `fetch()` call without using the network.
-     * - If `getResult` is configured, its return value is validated against the endpoint result schema.
-     * - Otherwise `undefined` is validated against the endpoint result schema.
+     * - 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

@@ -4,20 +4,20 @@ import { ClientAPIProvider } from "./ClientAPIProvider.js";
 export class MockAPIProvider extends ClientAPIProvider {
     calls = [];
     handler;
-    constructor({ handler, ...options }) {
+    constructor(handler, options = { url: "https://api.mock.com" }) {
         super(options);
         this.handler = handler;
     }
     /**
      * Log a `fetch()` call without using the network.
-     * - If `getResult` is configured, its return value is validated against the endpoint result schema.
-     * - Otherwise `undefined` is validated against the endpoint result schema.
+     * - 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 = endpoint.getRequest(this.url, payload, options, caller);
+        const request = this.getRequest(endpoint, payload, options, caller);
         const response = await this.handler(request);
-        const result = await endpoint.parseResponse(response);
+        const result = await this.parseResponse(endpoint, response, caller);
         this.calls.push({ type: "fetch", endpoint, payload, options, request, response, result });
         return result;
     }

package/api/provider/ThroughAPIProvider.d.ts

@@ -2,13 +2,12 @@ import type { AnyCaller } from "../../util/function.js";
 import type { RequestOptions } from "../../util/http.js";
 import type { Endpoint } from "../endpoint/Endpoint.js";
 import type { APIProvider } from "./APIProvider.js";
-import type { ClientAPIProvider } from "./ClientAPIProvider.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: ClientAPIProvider;
-    constructor(source: ClientAPIProvider);
+    readonly source: APIProvider;
+    constructor(source: APIProvider);
     fetch<P, R>(endpoint: Endpoint<P, R>, payload: P, options?: RequestOptions, caller?: AnyCaller): Promise<R>;
 }

package/api/provider/ValidationAPIProvider.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";
+/** 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>;
+}

package/api/provider/ValidationAPIProvider.js

@@ -0,0 +1,26 @@
+import { ResponseError } from "../../error/ResponseError.js";
+import { ThroughAPIProvider } from "./ThroughAPIProvider.js";
+/** Validate an asynchronous source provider (source can have any type because validation guarantees the type). */
+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);
+        // 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);
+    }
+    catch (thrown) {
+        if (typeof thrown === "string")
+            throw new ResponseError(`Invalid result for ${endpoint}:\n${thrown}`, { endpoint, code: 422, caller });
+        throw thrown;
+    }
+}

package/cloudflare/CloudflareKVProvider.d.ts

@@ -0,0 +1,53 @@
+import type { Collection } from "../db/collection/Collection.js";
+import { DBProvider } from "../db/provider/DBProvider.js";
+import type { Data } from "../util/data.js";
+import type { Items, OptionalItem } from "../util/item.js";
+import type { ItemQuery } from "../util/query.js";
+import type { Updates } from "../util/update.js";
+/** Minimal interface matching Cloudflare Workers KV namespace runtime object. */
+export interface KVNamespace {
+    get(key: string, options: {
+        type: "json";
+    }): Promise<unknown>;
+    put(key: string, value: string): Promise<void>;
+    delete(key: string): Promise<void>;
+}
+/**
+ * Cloudflare Workers KV database provider.
+ *
+ * Items are stored as JSON values under keys formatted as `collection:id`.
+ * The `KVNamespace` object is provided by the Cloudflare Workers runtime environment.
+ *
+ * ### Supported
+ * - Single item operations: `getItem`, `setItem`, `addItem`, `updateItem`, `deleteItem`.
+ * - ID generation: `addItem()` generates a UUID v4 identifier automatically.
+ *
+ * ### Not supported
+ * - **Realtime subscriptions:** `getItemSequence()` and `getQuerySequence()` throw `UnimplementedError`.
+ *   KV has no change feed or push notification mechanism.
+ * - **Updates:** `updateItem()` and `updateQuery()` throw `UnimplementedError`.
+ * - **Collection queries:** `getQuery()`, `setQuery()`, `deleteQuery()`, and `countQuery()` are not supported.
+ *   KV does not expose efficient filtering, sorting, or collection scans, so this provider avoids
+ *   the old "read everything and filter in memory" behavior.
+ *
+ * ### Performance limitations
+ * - **Single-key store only:** This provider is intentionally limited to direct key reads and writes.
+ *   If you need collection queries, filtering, sorting, or bulk mutations, use a different backend.
+ * - **Eventual consistency:** KV is eventually consistent, so reads may briefly return stale values
+ *   shortly after writes.
+ */
+export declare class CloudflareKVProvider extends DBProvider<string> {
+    private readonly _kv;
+    constructor(kv: KVNamespace);
+    getItem<T extends Data>({ name }: Collection<string, string, T>, id: string): Promise<OptionalItem<string, T>>;
+    getItemSequence<T extends Data>(_c: Collection<string, string, T>, _id: string): AsyncIterable<OptionalItem<string, T>>;
+    addItem<T extends Data>({ name }: Collection<string, string, T>, data: T): Promise<string>;
+    setItem<T extends Data>({ name }: Collection<string, string, T>, id: string, data: T): Promise<void>;
+    updateItem<T extends Data>(_c: Collection<string, string, T>, _id: string, _updates: Updates<T>): Promise<void>;
+    deleteItem<T extends Data>({ name }: Collection<string, string, T>, id: string): Promise<void>;
+    getQuery<T extends Data>(_c: Collection<string, string, T>, q?: ItemQuery<string, T>): Promise<Items<string, T>>;
+    getQuerySequence<T extends Data>(_c: Collection<string, string, T>, _q?: ItemQuery<string, T>): AsyncIterable<Items<string, T>>;
+    setQuery<T extends Data>(_c: Collection<string, string, T>, _q: ItemQuery<string, T>, _data: T): Promise<void>;
+    updateQuery<T extends Data>(_c: Collection<string, string, T>, _q: ItemQuery<string, T>, _updates: Updates<T>): Promise<void>;
+    deleteQuery<T extends Data>(c: Collection<string, string, T>, q: ItemQuery<string, T>): Promise<void>;
+}

package/cloudflare/CloudflareKVProvider.js

@@ -0,0 +1,75 @@
+import { DBProvider } from "../db/provider/DBProvider.js";
+import { UnimplementedError } from "../error/UnimplementedError.js";
+import { getItem } from "../util/item.js";
+import { randomUUID } from "../util/uuid.js";
+/**
+ * Cloudflare Workers KV database provider.
+ *
+ * Items are stored as JSON values under keys formatted as `collection:id`.
+ * The `KVNamespace` object is provided by the Cloudflare Workers runtime environment.
+ *
+ * ### Supported
+ * - Single item operations: `getItem`, `setItem`, `addItem`, `updateItem`, `deleteItem`.
+ * - ID generation: `addItem()` generates a UUID v4 identifier automatically.
+ *
+ * ### Not supported
+ * - **Realtime subscriptions:** `getItemSequence()` and `getQuerySequence()` throw `UnimplementedError`.
+ *   KV has no change feed or push notification mechanism.
+ * - **Updates:** `updateItem()` and `updateQuery()` throw `UnimplementedError`.
+ * - **Collection queries:** `getQuery()`, `setQuery()`, `deleteQuery()`, and `countQuery()` are not supported.
+ *   KV does not expose efficient filtering, sorting, or collection scans, so this provider avoids
+ *   the old "read everything and filter in memory" behavior.
+ *
+ * ### Performance limitations
+ * - **Single-key store only:** This provider is intentionally limited to direct key reads and writes.
+ *   If you need collection queries, filtering, sorting, or bulk mutations, use a different backend.
+ * - **Eventual consistency:** KV is eventually consistent, so reads may briefly return stale values
+ *   shortly after writes.
+ */
+export class CloudflareKVProvider extends DBProvider {
+    _kv;
+    constructor(kv) {
+        super();
+        this._kv = kv;
+    }
+    async getItem({ name }, id) {
+        const data = (await this._kv.get(_getKey(name, id), { type: "json" }));
+        if (data)
+            return getItem(id, data);
+    }
+    getItemSequence(_c, _id) {
+        throw new UnimplementedError("CloudflareKVProvider does not support realtime subscriptions");
+    }
+    async addItem({ name }, data) {
+        const id = randomUUID();
+        await this._kv.put(_getKey(name, id), JSON.stringify(data));
+        return id;
+    }
+    async setItem({ name }, id, data) {
+        await this._kv.put(_getKey(name, id), JSON.stringify(data));
+    }
+    async updateItem(_c, _id, _updates) {
+        throw new UnimplementedError("CloudflareKVProvider does not support updates to items");
+    }
+    async deleteItem({ name }, id) {
+        await this._kv.delete(_getKey(name, id));
+    }
+    async getQuery(_c, q) {
+        throw new UnimplementedError("CloudflareKVProvider does not support querying items");
+    }
+    getQuerySequence(_c, _q) {
+        throw new UnimplementedError("CloudflareKVProvider does not support realtime subscriptions");
+    }
+    async setQuery(_c, _q, _data) {
+        throw new UnimplementedError("CloudflareKVProvider does not support querying items");
+    }
+    async updateQuery(_c, _q, _updates) {
+        throw new UnimplementedError("CloudflareKVProvider does not support updates to items");
+    }
+    async deleteQuery(c, q) {
+        throw new UnimplementedError("CloudflareKVProvider does not support querying items");
+    }
+}
+function _getKey(collection, id) {
+    return `${collection}:${id}`;
+}

package/cloudflare/index.d.ts

@@ -0,0 +1 @@
+export * from "./CloudflareKVProvider.js";

package/cloudflare/index.js

@@ -0,0 +1 @@
+export * from "./CloudflareKVProvider.js";