shelving 1.181.2 → 1.182.0

package/api/cache/APICache.d.ts

@@ -9,6 +9,7 @@ export declare class APICache implements Disposable {
     private readonly _caches;
     readonly provider: APIProvider;
     constructor(provider: APIProvider);
+    private _get;
     /** 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. */

package/api/cache/APICache.js

@@ -10,25 +10,27 @@ export class APICache {
     constructor(provider) {
         this.provider = provider;
     }
-    /** Get (or create) the `EndpointCache` for the given endpoint. */
+    _get(endpoint) {
+        return this._caches.get(endpoint);
+    }
     get(endpoint) {
-        return this._caches.get(endpoint) || setMapItem(this._caches, endpoint, new EndpointCache(endpoint, this.provider));
+        return this._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);
+        this._get(endpoint)?.invalidate(payload);
     }
     /** Invalidate all stores for an endpoint. */
     invalidateAll(endpoint) {
-        this._caches.get(endpoint)?.invalidateAll();
+        this._get(endpoint)?.invalidateAll();
     }
     /** Trigger a refetch on a specific store for an endpoint. */
     refetch(endpoint, payload) {
-        this._caches.get(endpoint)?.refetch(payload);
+        this._get(endpoint)?.refetch(payload);
     }
     /** Trigger a refetch on all stores for an endpoint. */
     refetchAll(endpoint) {
-        this._caches.get(endpoint)?.refetchAll();
+        this._get(endpoint)?.refetchAll();
     }
     // Implement Disposable.
     [Symbol.dispose]() {

package/api/cache/EndpointCache.d.ts

@@ -1,3 +1,4 @@
+import type { AnyCaller } from "../../util/function.js";
 import type { Endpoint } from "../endpoint/Endpoint.js";
 import type { APIProvider } from "../provider/APIProvider.js";
 import { EndpointStore } from "../store/EndpointStore.js";
@@ -5,22 +6,20 @@ import { EndpointStore } from "../store/EndpointStore.js";
  * Cache of `EndpointStore` objects for a single endpoint, keyed by serialized payload.
  * - Use `get(payload)` to retrieve or create the `EndpointStore` for a given payload.
  */
-export declare class EndpointCache<P, R> implements Disposable {
+export declare class EndpointCache<P = unknown, R = unknown> implements Disposable {
     private readonly _stores;
     readonly endpoint: Endpoint<P, R>;
     readonly provider: APIProvider;
     constructor(endpoint: Endpoint<P, R>, provider: APIProvider);
     /** Get (or create) the `EndpointStore` for the given payload. */
-    get(payload: P): EndpointStore<P, R>;
+    get(payload: P, caller?: AnyCaller): EndpointStore<P, R>;
     /** Invalidate a specific store. */
-    invalidate(payload: P): void;
+    invalidate(payload: P, caller?: AnyCaller): void;
     /** Invalidate all stores. */
     invalidateAll(): void;
     /** Trigger a refetch on a specific store. */
-    refetch(payload: P): void;
+    refetch(payload: P, caller?: AnyCaller): 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

@@ -1,11 +1,5 @@
 import { setMapItem } from "../../util/map.js";
 import { EndpointStore } from "../store/EndpointStore.js";
-/** Serialize a payload to a stable string key for use in a `Map`. */
-function _serializePayload(payload) {
-    if (payload === undefined)
-        return "";
-    return JSON.stringify(payload);
-}
 /**
  * Cache of `EndpointStore` objects for a single endpoint, keyed by serialized payload.
  * - Use `get(payload)` to retrieve or create the `EndpointStore` for a given payload.
@@ -19,13 +13,13 @@ export class EndpointCache {
         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));
+    get(payload, caller = this.get) {
+        const url = this.provider.renderURL(this.endpoint, payload, caller).href;
+        return this._stores.get(url) || setMapItem(this._stores, url, new EndpointStore(this.endpoint, payload, this.provider));
     }
     /** Invalidate a specific store. */
-    invalidate(payload) {
-        this.get(payload)?.invalidate();
+    invalidate(payload, caller = this.invalidate) {
+        this.get(payload, caller)?.invalidate();
     }
     /** Invalidate all stores. */
     invalidateAll() {
@@ -33,8 +27,8 @@ export class EndpointCache {
             store.invalidate();
     }
     /** Trigger a refetch on a specific store. */
-    refetch(payload) {
-        this.get(payload)?.fetch();
+    refetch(payload, caller = this.invalidate) {
+        this.get(payload, caller)?.fetch();
     }
     /** Trigger a refetch on all stores. */
     refetchAll() {

package/api/endpoint/Endpoint.d.ts

@@ -14,7 +14,7 @@ import type { EndpointCallback, EndpointHandler } from "./util.js";
  * @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> {
+export declare class Endpoint<P = unknown, R = unknown> {
     /** Endpoint method. */
     readonly method: RequestMethod;
     /** Endpoint path, possibly including placeholders e.g. `/users/{id}` */

package/api/index.d.ts

@@ -3,7 +3,6 @@ export * from "./cache/EndpointCache.js";
 export * from "./endpoint/Endpoint.js";
 export * from "./endpoint/util.js";
 export * from "./provider/APIProvider.js";
-export * from "./provider/ClientAPIProvider.js";
 export * from "./provider/DebugAPIProvider.js";
 export * from "./provider/MockAPIProvider.js";
 export * from "./provider/MockEndpointAPIProvider.js";

package/api/index.js

@@ -3,7 +3,6 @@ export * from "./cache/EndpointCache.js";
 export * from "./endpoint/Endpoint.js";
 export * from "./endpoint/util.js";
 export * from "./provider/APIProvider.js";
-export * from "./provider/ClientAPIProvider.js";
 export * from "./provider/DebugAPIProvider.js";
 export * from "./provider/MockAPIProvider.js";
 export * from "./provider/MockEndpointAPIProvider.js";

package/api/provider/APIProvider.d.ts

@@ -1,9 +1,44 @@
 import type { AnyCaller } from "../../util/function.js";
-import type { RequestOptions } from "../../util/http.js";
+import { type RequestOptions } from "../../util/http.js";
+import { type PossibleURL, type URL, type URLString } from "../../util/url.js";
 import type { Endpoint } from "../endpoint/Endpoint.js";
-export declare abstract class APIProvider {
+/** Options for an `APIProvider`. */
+export interface APIProviderOptions {
+    /** The common base URL for all rendered endpoint requests. */
+    readonly url: PossibleURL;
+    /** Options used for HTTP requests created with `this.getRequest()` and `this.fetch()` */
+    readonly options?: RequestOptions;
+}
+/** Provider for API endpoints rooted at a common base URL. */
+export declare class APIProvider {
+    /** The common base URL for all rendered endpoint requests. */
+    readonly url: URLString;
+    /** Default options used for HTTP requests created with `this.getRequest()` and `this.fetch()` */
+    readonly options: RequestOptions;
+    constructor({ url, options }: APIProviderOptions);
+    /**
+     * Render the full final URL for an API request to a given endpoint with a given payload.
+     * - Includes `?query` params if this is a `HEAD` or `GET` request.
+     *
+     * @throws {RequiredError} if this endpoint's path has `{placeholders}` but `payload` is not a data object.
+     * @throws {RequiredError} if this is a `HEAD` or `GET` request but `payload` is not a data object.
+     */
+    renderURL<P, R>(endpoint: Endpoint<P, R>, payload: P, caller?: AnyCaller): URL;
+    /**
+     * 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;
     /**
-     * Perform a fetch to an endpoint via this provider and validate the returned response against the endpoint result schema.
+     * 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.
      */
-    abstract fetch<P, R>(endpoint: Endpoint<P, R>, payload: P, options?: RequestOptions, caller?: AnyCaller): Promise<R>;
+    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/APIProvider.js

@@ -1,2 +1,78 @@
+import { ResponseError } from "../../error/ResponseError.js";
+import { isArrayItem } from "../../util/array.js";
+import { getMessage } from "../../util/error.js";
+import { assertHeadMethodPayload, getRequest, getResponseContent, HTTP_HEAD_METHODS, mergeRequestOptions, } from "../../util/http.js";
+import { omitProps } from "../../util/object.js";
+import { withURIParams } from "../../util/uri.js";
+import { requireBaseURL, requireURL } from "../../util/url.js";
+/** Provider for API endpoints rooted at a common base URL. */
 export class APIProvider {
+    /** The common base URL for all rendered endpoint requests. */
+    url;
+    /** Default options used for HTTP requests created with `this.getRequest()` and `this.fetch()` */
+    options;
+    constructor({ url, options = {} }) {
+        this.url = requireBaseURL(url, undefined, APIProvider);
+        this.options = options;
+    }
+    /**
+     * Render the full final URL for an API request to a given endpoint with a given payload.
+     * - Includes `?query` params if this is a `HEAD` or `GET` request.
+     *
+     * @throws {RequiredError} if this endpoint's path has `{placeholders}` but `payload` is not a data object.
+     * @throws {RequiredError} if this is a `HEAD` or `GET` request but `payload` is not a data object.
+     */
+    renderURL(endpoint, payload, caller = this.renderURL) {
+        const url = requireURL(`.${endpoint.renderPath(payload, caller)}`, this.url, caller);
+        // HEAD or GET have no body (but payload can only be data object).
+        if (isArrayItem(HTTP_HEAD_METHODS, endpoint.method)) {
+            assertHeadMethodPayload(payload, endpoint.method, caller);
+            if (payload) {
+                const params = endpoint.placeholders.length ? omitProps(payload, ...endpoint.placeholders) : payload; // Omit any params that were already embedded as `{placeholders}`
+                return withURIParams(url, params, caller);
+            }
+        }
+        return url;
+    }
+    /**
+     * Create a `Request` that targets this endpoint with a given base URL.
+     * - 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 = this.renderURL(endpoint, payload, caller);
+        // HEAD or GET requests have no payload because it was already rendered into the URL as `?query` params.
+        if (isArrayItem(HTTP_HEAD_METHODS, endpoint.method)) {
+            return getRequest(endpoint.method, url, undefined, options);
+        }
+        // Placeholders are rendered into the path so get omitted from the body payload.
+        if (endpoint.placeholders.length) {
+            const params = omitProps(payload, ...endpoint.placeholders); // Omit any params that were already embedded as `{placeholders}`
+            return getRequest(endpoint.method, url, params, options);
+        }
+        // No placeholders.
+        return getRequest(endpoint.method, url, payload, options);
+    }
+    /**
+     * Parse an HTTP `Response` for this endpoint.
+     * - Non-2xx responses become `ResponseError`.
+     * - Does not validate the result against the endpoint schema — use `ValidationAPIProvider` for that.
+     */
+    async parseResponse(_endpoint, response, caller = this.parseResponse) {
+        const { ok, status } = response;
+        const content = await getResponseContent(response, caller);
+        if (!ok)
+            throw new ResponseError(getMessage(content) ?? `Error ${status}`, { code: status, cause: response, caller });
+        return content;
+    }
+    async fetch(endpoint, payload, options, caller = this.fetch) {
+        const request = this.getRequest(endpoint, payload, mergeRequestOptions(this.options, options), caller);
+        const response = await fetch(request);
+        return this.parseResponse(endpoint, response, caller);
+    }
 }

package/api/provider/MockAPIProvider.d.ts

@@ -1,7 +1,7 @@
 import type { AnyCaller } from "../../util/function.js";
 import { type RequestHandler, type RequestOptions } from "../../util/http.js";
 import type { AnyEndpoint, Endpoint } from "../endpoint/Endpoint.js";
-import { ClientAPIProvider, type ClientAPIProviderOptions } from "./ClientAPIProvider.js";
+import { APIProvider, type APIProviderOptions } from "./APIProvider.js";
 /** A structured log entry emitted by `MockAPIProvider` for one of its provider operations. */
 export type MockAPICall = {
     readonly type: "fetch";
@@ -14,14 +14,14 @@ export type MockAPICall = {
 };
 /**
  * Construction options for a `MockAPIProvider`
- * - Same as options for a normal `ClientAPIProvider`, but with an optional URL.
+ * - Same as options for a normal `APIProvider`, but with an optional URL.
  */
-export interface MockAPIProviderOptions extends Omit<ClientAPIProviderOptions, "url"> {
+export interface MockAPIProviderOptions extends Omit<APIProviderOptions, "url"> {
     /** Optional URL, defaults to `"https://api.mock.com"` */
-    url?: ClientAPIProviderOptions["url"];
+    url?: APIProviderOptions["url"];
 }
 /** Provider that logs API calls without sending network requests. */
-export declare class MockAPIProvider extends ClientAPIProvider {
+export declare class MockAPIProvider extends APIProvider {
     readonly calls: MockAPICall[];
     readonly handler: RequestHandler;
     constructor(handler: RequestHandler, { url, ...options }?: MockAPIProviderOptions);

package/api/provider/MockAPIProvider.js

@@ -1,7 +1,7 @@
 import { mergeRequestOptions } from "../../util/http.js";
-import { ClientAPIProvider } from "./ClientAPIProvider.js";
+import { APIProvider } from "./APIProvider.js";
 /** Provider that logs API calls without sending network requests. */
-export class MockAPIProvider extends ClientAPIProvider {
+export class MockAPIProvider extends APIProvider {
     calls = [];
     handler;
     constructor(handler, { url = "https://api.mock.com", ...options } = {}) {

package/api/provider/ThroughAPIProvider.d.ts

@@ -1,5 +1,6 @@
 import type { AnyCaller } from "../../util/function.js";
 import type { RequestOptions } from "../../util/http.js";
+import type { URL, URLString } from "../../util/url.js";
 import type { Endpoint } from "../endpoint/Endpoint.js";
 import type { APIProvider } from "./APIProvider.js";
 /**
@@ -8,6 +9,11 @@ import type { APIProvider } from "./APIProvider.js";
  */
 export declare class ThroughAPIProvider implements APIProvider {
     readonly source: APIProvider;
+    get url(): URLString;
+    get options(): RequestOptions;
     constructor(source: APIProvider);
+    renderURL<P, R>(endpoint: Endpoint<P, R>, payload: P, caller?: AnyCaller): URL;
+    getRequest<P, R>(endpoint: Endpoint<P, R>, payload: P, options?: RequestOptions, caller?: AnyCaller): Request;
+    parseResponse<P, R>(endpoint: Endpoint<P, R>, response: Response, caller?: AnyCaller): Promise<R>;
     fetch<P, R>(endpoint: Endpoint<P, R>, payload: P, options?: RequestOptions, caller?: AnyCaller): Promise<R>;
 }

package/api/provider/ThroughAPIProvider.js

@@ -4,9 +4,24 @@
  */
 export class ThroughAPIProvider {
     source;
+    get url() {
+        return this.source.url;
+    }
+    get options() {
+        return this.source.options;
+    }
     constructor(source) {
         this.source = source;
     }
+    renderURL(endpoint, payload, caller = this.renderURL) {
+        return this.source.renderURL(endpoint, payload, caller);
+    }
+    getRequest(endpoint, payload, options, caller = this.getRequest) {
+        return this.source.getRequest(endpoint, payload, options, caller);
+    }
+    parseResponse(endpoint, response, caller = this.parseResponse) {
+        return this.source.parseResponse(endpoint, response, caller);
+    }
     fetch(endpoint, payload, options, caller = this.fetch) {
         return this.source.fetch(endpoint, payload, options, caller);
     }

package/bun/BunPostgreSQLProvider.d.ts

@@ -2,9 +2,10 @@ import type { SQL } from "bun";
 import { PostgreSQLProvider, type SQLFragment } from "../db/index.js";
 import type { ImmutableArray } from "../util/array.js";
 import type { Data } from "../util/data.js";
-export declare class BunPostgreSQLProvider extends PostgreSQLProvider {
+import type { Identifier } from "../util/item.js";
+export declare class BunPostgreSQLProvider<I extends Identifier = Identifier, T extends Data = Data> extends PostgreSQLProvider<I, T> {
     private _sql;
     constructor(sql: SQL);
-    exec<T extends Data>(strings: TemplateStringsArray, ...values: ImmutableArray<unknown>): Promise<ImmutableArray<T>>;
+    exec<X extends Data>(strings: TemplateStringsArray, ...values: ImmutableArray<unknown>): Promise<ImmutableArray<X>>;
     sqlIdentifier(name: string): SQLFragment;
 }

package/cloudflare/CloudflareD1Provider.d.ts

@@ -1,14 +1,15 @@
 import { SQLiteProvider } from "../db/provider/SQLiteProvider.js";
 import { type ImmutableArray } from "../util/array.js";
 import type { Data } from "../util/data.js";
+import type { Identifier } from "../util/item.js";
 import type { D1Database } from "./types.js";
 /**
  * Cloudflare D1 database provider.
  *
  * Uses the D1 Worker API for execution and standard SQL from `SQLProvider`.
  */
-export declare class CloudflareD1Provider extends SQLiteProvider {
+export declare class CloudflareD1Provider<I extends Identifier = Identifier, T extends Data = Data> extends SQLiteProvider<I, T> {
     private readonly _db;
     constructor(db: D1Database);
-    exec<T extends Data = Data>(strings: TemplateStringsArray, ...values: ImmutableArray<unknown>): Promise<readonly T[]>;
+    exec<X extends Data>(strings: TemplateStringsArray, ...values: ImmutableArray<unknown>): Promise<readonly X[]>;
 }

package/cloudflare/CloudflareKVProvider.d.ts

@@ -1,8 +1,8 @@
 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 Item, type Items, type OptionalItem } from "../util/item.js";
+import type { Query } from "../util/query.js";
 import type { Updates } from "../util/update.js";
 import type { KVNamespace } from "./types.js";
 /**
@@ -20,27 +20,25 @@ import type { KVNamespace } from "./types.js";
  *   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.
+ *   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.
+ * - **Eventual consistency:** KV is eventually consistent, so reads may briefly return stale values shortly after writes.
  */
-export declare class CloudflareKVProvider extends DBProvider<string> {
+export declare class CloudflareKVProvider<I extends string = string, T extends Data = Data> extends DBProvider<I, T> {
     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>;
+    getItem<II extends I, TT extends T>({ name }: Collection<string, II, TT>, id: II): Promise<OptionalItem<II, TT>>;
+    getItemSequence<II extends I, TT extends T>(_collection: Collection<string, II, TT>, _id: II): AsyncIterable<OptionalItem<II, TT>>;
+    addItem<II extends I, TT extends T>({ name }: Collection<string, II, TT>, data: TT): Promise<II>;
+    setItem<II extends I, TT extends T>({ name }: Collection<string, II, TT>, id: II, data: TT): Promise<void>;
+    updateItem<II extends I, TT extends T>(_collection: Collection<string, II, TT>, _id: II, _updates: Updates<Item<II, TT>>): Promise<void>;
+    deleteItem<II extends I, TT extends T>({ name }: Collection<string, II, TT>, id: II): Promise<void>;
+    getQuery<II extends I, TT extends T>(_collection: Collection<string, II, TT>, _query?: Query<Item<II, TT>>): Promise<Items<II, TT>>;
+    getQuerySequence<II extends I, TT extends T>(_collection: Collection<string, II, TT>, _query?: Query<Item<II, TT>>): AsyncIterable<Items<II, TT>>;
+    setQuery<II extends I, TT extends T>(_collection: Collection<string, II, TT>, _query: Query<Item<II, TT>>, _data: TT): Promise<void>;
+    updateQuery<II extends I, TT extends T>(_collection: Collection<string, II, TT>, _query: Query<Item<II, TT>>, _updates: Updates<TT>): Promise<void>;
+    deleteQuery<II extends I, TT extends T>(_collection: Collection<string, II, TT>, _query: Query<Item<II, TT>>): Promise<void>;
 }

package/cloudflare/CloudflareKVProvider.js

@@ -17,14 +17,12 @@ import { randomUUID } from "../util/uuid.js";
  *   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.
+ *   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.
+ * - **Eventual consistency:** KV is eventually consistent, so reads may briefly return stale values shortly after writes.
  */
 export class CloudflareKVProvider extends DBProvider {
     _kv;
@@ -33,40 +31,40 @@ export class CloudflareKVProvider extends DBProvider {
         this._kv = kv;
     }
     async getItem({ name }, id) {
-        const data = (await this._kv.get(_getKey(name, id), { type: "json" }));
+        const data = (await this._kv.get(_getKey(name, id), { type: "json" })); // `as TT` needed: KV returns unknown from JSON parse.
         if (data)
             return getItem(id, data);
     }
-    getItemSequence(_c, _id) {
+    getItemSequence(_collection, _id) {
         throw new UnimplementedError("CloudflareKVProvider does not support realtime subscriptions");
     }
     async addItem({ name }, data) {
-        const id = randomUUID();
+        const id = randomUUID(); // `as II` needed: TypeScript can't narrow II from string return type.
         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) {
+    async updateItem(_collection, _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) {
+    async getQuery(_collection, _query) {
         throw new UnimplementedError("CloudflareKVProvider does not support querying items");
     }
-    getQuerySequence(_c, _q) {
+    getQuerySequence(_collection, _query) {
         throw new UnimplementedError("CloudflareKVProvider does not support realtime subscriptions");
     }
-    async setQuery(_c, _q, _data) {
+    async setQuery(_collection, _query, _data) {
         throw new UnimplementedError("CloudflareKVProvider does not support querying items");
     }
-    async updateQuery(_c, _q, _updates) {
+    async updateQuery(_collection, _query, _updates) {
         throw new UnimplementedError("CloudflareKVProvider does not support updates to items");
     }
-    async deleteQuery(_c, _q) {
+    async deleteQuery(_collection, _query) {
         throw new UnimplementedError("CloudflareKVProvider does not support querying items");
     }
 }

package/db/cache/CollectionCache.d.ts

@@ -0,0 +1,37 @@
+import type { Data } from "../../util/data.js";
+import type { Identifier, Item } from "../../util/item.js";
+import type { Query } from "../../util/query.js";
+import type { Collection } from "../collection/Collection.js";
+import type { DBProvider } from "../provider/DBProvider.js";
+import type { MemoryDBProvider } from "../provider/MemoryDBProvider.js";
+import { ItemStore } from "../store/ItemStore.js";
+import { QueryStore } from "../store/QueryStore.js";
+/**
+ * Cache of `ItemStore` and `QueryStore` objects for a single collection.
+ * - Use `getItem(id)` to retrieve or create the `ItemStore` for a given id.
+ * - Use `getQuery(query)` to retrieve or create the `QueryStore` for a given query.
+ */
+export declare class CollectionCache<I extends Identifier, T extends Data> implements Disposable {
+    private readonly _items;
+    private readonly _queries;
+    readonly collection: Collection<string, I, T>;
+    readonly provider: DBProvider<I>;
+    readonly memory: MemoryDBProvider<I> | undefined;
+    constructor(collection: Collection<string, I, T>, provider: DBProvider<I>, memory?: MemoryDBProvider<I>);
+    /** Get (or create) the `ItemStore` for the given id. */
+    getItem(id: I): ItemStore<I, T>;
+    /** Get (or create) the `QueryStore` for the given query. */
+    getQuery(query: Query<Item<I, T>>): QueryStore<I, T>;
+    /** Refresh a specific item store. */
+    refreshItem(id: I): void;
+    /** Refresh every cached item store. */
+    refreshItems(): void;
+    /** Refresh a specific query store. */
+    refreshQuery(query: Query<Item<I, T>>): void;
+    /** Refresh every cached query store. */
+    refreshQueries(): void;
+    /** Refresh every cached store (items and queries). */
+    refreshAll(): void;
+    private _queryKey;
+    [Symbol.dispose](): void;
+}

package/db/cache/CollectionCache.js

@@ -0,0 +1,62 @@
+import { setMapItem } from "../../util/map.js";
+import { ItemStore } from "../store/ItemStore.js";
+import { QueryStore } from "../store/QueryStore.js";
+/**
+ * Cache of `ItemStore` and `QueryStore` objects for a single collection.
+ * - Use `getItem(id)` to retrieve or create the `ItemStore` for a given id.
+ * - Use `getQuery(query)` to retrieve or create the `QueryStore` for a given query.
+ */
+export class CollectionCache {
+    _items = new Map();
+    _queries = new Map();
+    collection;
+    provider;
+    memory;
+    constructor(collection, provider, memory) {
+        this.collection = collection;
+        this.provider = provider;
+        this.memory = memory;
+    }
+    /** Get (or create) the `ItemStore` for the given id. */
+    getItem(id) {
+        const key = String(id);
+        return this._items.get(key) || setMapItem(this._items, key, new ItemStore(this.collection, id, this.provider, this.memory));
+    }
+    /** Get (or create) the `QueryStore` for the given query. */
+    getQuery(query) {
+        const key = this._queryKey(query);
+        return this._queries.get(key) || setMapItem(this._queries, key, new QueryStore(this.collection, query, this.provider, this.memory));
+    }
+    /** Refresh a specific item store. */
+    refreshItem(id) {
+        this._items.get(String(id))?.refresh();
+    }
+    /** Refresh every cached item store. */
+    refreshItems() {
+        for (const store of this._items.values())
+            store.refresh();
+    }
+    /** Refresh a specific query store. */
+    refreshQuery(query) {
+        this._queries.get(this._queryKey(query))?.refresh();
+    }
+    /** Refresh every cached query store. */
+    refreshQueries() {
+        for (const store of this._queries.values())
+            store.refresh();
+    }
+    /** Refresh every cached store (items and queries). */
+    refreshAll() {
+        this.refreshItems();
+        this.refreshQueries();
+    }
+    _queryKey(query) {
+        return JSON.stringify(query);
+    }
+    // Implement Disposable.
+    [Symbol.dispose]() {
+        // Note: `ItemStore`/`QueryStore` are not themselves `Disposable`, so we only drop references.
+        this._items.clear();
+        this._queries.clear();
+    }
+}