shelving 1.178.0 → 1.179.0

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/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

@@ -27,8 +27,8 @@ export declare class MockAPIProvider extends ClientAPIProvider {
     constructor({ handler, ...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

@@ -10,14 +10,14 @@ export class MockAPIProvider extends ClientAPIProvider {
     }
     /**
      * 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,71 @@
+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>;
+    list(options?: {
+        prefix?: string;
+        limit?: number;
+        cursor?: string;
+    }): Promise<{
+        keys: readonly {
+            name: string;
+        }[];
+        list_complete: boolean;
+        cursor?: string;
+    }>;
+}
+/**
+ * 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`.
+ * - Query operations: `getQuery`, `setQuery`, `updateQuery`, `deleteQuery`, `countQuery`.
+ * - All filter operators: equality, not, in, out, contains, gt, gte, lt, lte.
+ * - Sorting (`$order`) and limiting (`$limit`).
+ * - 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.
+ *
+ * ### Performance limitations
+ * - **Querying is expensive:** KV has no native query support. Every `getQuery()` call lists all keys
+ *   in the collection (paginated, 1000 keys per page), fetches each value individually, then applies
+ *   filtering, sorting, and limiting in-memory. Avoid large collections where possible.
+ * - **Non-atomic updates:** `updateItem()` performs a read-modify-write cycle. Concurrent writes to the
+ *   same item may cause one write to be lost.
+ * - **Eventual consistency:** KV is eventually consistent — reads may return stale data, particularly
+ *   shortly after writes. This also affects `updateItem`, `setQuery`, `updateQuery`, and `deleteQuery`
+ *   since they read before writing.
+ * - **No bulk get:** Each item value must be fetched individually — there is no multi-get API.
+ *   Query operations that match N items require N+1 KV requests (one `list` + N `get` calls per page).
+ */
+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>({ name }: 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>;
+    /** Fetch all items in a collection, paginating through `kv.list()`. */
+    private _getAllItems;
+}

package/cloudflare/CloudflareKVProvider.js

@@ -0,0 +1,113 @@
+import { DBProvider } from "../db/provider/DBProvider.js";
+import { UnimplementedError } from "../error/UnimplementedError.js";
+import { requireArray } from "../util/array.js";
+import { getItem } from "../util/item.js";
+import { queryItems } from "../util/query.js";
+import { updateData } from "../util/update.js";
+import { randomUUID } from "../util/uuid.js";
+function _getKey(collection, id) {
+    return `${collection}:${id}`;
+}
+function _getPrefix(collection) {
+    return `${collection}:`;
+}
+/**
+ * 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`.
+ * - Query operations: `getQuery`, `setQuery`, `updateQuery`, `deleteQuery`, `countQuery`.
+ * - All filter operators: equality, not, in, out, contains, gt, gte, lt, lte.
+ * - Sorting (`$order`) and limiting (`$limit`).
+ * - 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.
+ *
+ * ### Performance limitations
+ * - **Querying is expensive:** KV has no native query support. Every `getQuery()` call lists all keys
+ *   in the collection (paginated, 1000 keys per page), fetches each value individually, then applies
+ *   filtering, sorting, and limiting in-memory. Avoid large collections where possible.
+ * - **Non-atomic updates:** `updateItem()` performs a read-modify-write cycle. Concurrent writes to the
+ *   same item may cause one write to be lost.
+ * - **Eventual consistency:** KV is eventually consistent — reads may return stale data, particularly
+ *   shortly after writes. This also affects `updateItem`, `setQuery`, `updateQuery`, and `deleteQuery`
+ *   since they read before writing.
+ * - **No bulk get:** Each item value must be fetched individually — there is no multi-get API.
+ *   Query operations that match N items require N+1 KV requests (one `list` + N `get` calls per page).
+ */
+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) {
+        const existing = await this.getItem(c, id);
+        if (existing)
+            await this.setItem(c, id, updateData(existing, updates));
+    }
+    async deleteItem({ name }, id) {
+        await this._kv.delete(_getKey(name, id));
+    }
+    async getQuery({ name }, q) {
+        const all = await this._getAllItems(name);
+        return q ? requireArray(queryItems(all, q)) : all;
+    }
+    getQuerySequence(_c, _q) {
+        throw new UnimplementedError("CloudflareKVProvider does not support realtime subscriptions");
+    }
+    async setQuery(c, q, data) {
+        const items = await this.getQuery(c, q);
+        await Promise.all(items.map(item => this.setItem(c, item.id, data)));
+    }
+    async updateQuery(c, q, updates) {
+        const items = await this.getQuery(c, q);
+        await Promise.all(items.map(item => this.setItem(c, item.id, updateData(item, updates))));
+    }
+    async deleteQuery(c, q) {
+        const items = await this.getQuery(c, q);
+        await Promise.all(items.map(item => this._kv.delete(_getKey(c.name, item.id))));
+    }
+    /** Fetch all items in a collection, paginating through `kv.list()`. */
+    async _getAllItems(collection) {
+        const prefix = _getPrefix(collection);
+        const items = [];
+        let cursor;
+        do {
+            const result = await this._kv.list(cursor ? { prefix, cursor } : { prefix });
+            const values = await Promise.all(result.keys.map(async (key) => {
+                const id = key.name.slice(prefix.length);
+                const data = (await this._kv.get(key.name, { type: "json" }));
+                if (data)
+                    return getItem(id, data);
+            }));
+            for (const item of values) {
+                if (item)
+                    items.push(item);
+            }
+            cursor = result.list_complete ? undefined : result.cursor;
+        } while (cursor);
+        return items;
+    }
+}

package/cloudflare/index.d.ts

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

package/cloudflare/index.js

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

package/db/collection/Collection.d.ts

@@ -0,0 +1,27 @@
+import { DataSchema } from "../../schema/DataSchema.js";
+import { NumberSchema } from "../../schema/NumberSchema.js";
+import type { Schema, Schemas } from "../../schema/Schema.js";
+import type { Data } from "../../util/data.js";
+import type { Identifier, Item } from "../../util/item.js";
+/** Default identifier schema (integer). */
+export declare const ID: NumberSchema;
+/** Declarative definition of a database collection/table. */
+export declare class Collection<K extends string, I extends Identifier, T extends Data> extends DataSchema<T> {
+    /** Collection name (used as the table/collection key). */
+    readonly name: K;
+    /** Schema for the identifier type. */
+    readonly id: Schema<I>;
+    /** Schema for a complete item (id + data). */
+    readonly item: DataSchema<Item<I, T>>;
+    constructor(name: K, id: Schema<I>, data: Schemas<T> | DataSchema<T>);
+}
+/** Shortcut factory for creating a Collection. */
+export declare function COLLECTION<K extends string, I extends Identifier, T extends Data>(name: K, id: Schema<I>, data: Schemas<T> | DataSchema<T>): Collection<K, I, T>;
+/** A readonly array of Collection instances. */
+export type Collections = ReadonlyArray<Collection<string, Identifier, Data>>;
+/** Extract the union of collection key strings from a Collections type. */
+export type CollectionKeys<C extends Collections> = C[number]["name"];
+/** Convert a Collections array type to a Database-style object mapping. */
+export type CollectionsDatabase<C extends Collections> = {
+    [E in C[number] as E extends Collection<infer K, any, any> ? K : never]: E extends Collection<string, any, infer T> ? T : never;
+};

package/db/collection/Collection.js

@@ -0,0 +1,31 @@
+import { DataSchema, ITEM } from "../../schema/DataSchema.js";
+import { NumberSchema } from "../../schema/NumberSchema.js";
+/** Default identifier schema (integer). */
+export const ID = new NumberSchema({
+    step: 1,
+    min: Number.MIN_SAFE_INTEGER,
+    max: Number.MAX_SAFE_INTEGER,
+    value: 0,
+    one: "ID",
+    title: "ID",
+});
+/** Declarative definition of a database collection/table. */
+export class Collection extends DataSchema {
+    /** Collection name (used as the table/collection key). */
+    name;
+    /** Schema for the identifier type. */
+    id;
+    /** Schema for a complete item (id + data). */
+    item;
+    constructor(name, id, data) {
+        const dataSchema = data instanceof DataSchema ? data : new DataSchema({ props: data });
+        super({ ...dataSchema, props: dataSchema.props });
+        this.name = name;
+        this.id = id;
+        this.item = ITEM(id, dataSchema);
+    }
+}
+/** Shortcut factory for creating a Collection. */
+export function COLLECTION(name, id, data) {
+    return new Collection(name, id, data);
+}

package/db/index.d.ts

@@ -1,10 +1,11 @@
-export * from "./CacheProvider.js";
-export * from "./Change.js";
-export * from "./ChangesProvider.js";
-export * from "./DebugProvider.js";
-export * from "./ItemStore.js";
-export * from "./MemoryProvider.js";
-export * from "./Provider.js";
-export * from "./QueryStore.js";
-export * from "./ThroughProvider.js";
-export * from "./ValidationProvider.js";
+export * from "./collection/Collection.js";
+export * from "./provider/CacheDBProvider.js";
+export * from "./provider/ChangesDBProvider.js";
+export * from "./provider/DBProvider.js";
+export * from "./provider/DebugDBProvider.js";
+export * from "./provider/MemoryDBProvider.js";
+export * from "./provider/MockDBProvider.js";
+export * from "./provider/ThroughDBProvider.js";
+export * from "./provider/ValidationDBProvider.js";
+export * from "./store/ItemStore.js";
+export * from "./store/QueryStore.js";