shelving/cloudflare/CloudflareKVProvider.d.ts

Toolkit for using data in JavaScript.

import type { Collection } from "../db/collection/Collection.js";
import { DBProvider } from "../db/provider/DBProvider.js";
import type { Data } from "../util/data.js";
import { type Item, type Items, type ItemsSequence, type OptionalItem, type OptionalItemSequence } from "../util/item.js";
import type { Query } from "../util/query.js";
import type { Updates } from "../util/update.js";
import type { KVNamespace } from "./types.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 declare class CloudflareKVProvider<I extends string = string, T extends Data = Data> extends DBProvider<I, T> {
    private readonly _kv;
    constructor(kv: KVNamespace);
    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): OptionalItemSequence<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>>): ItemsSequence<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>;
}