DenoKvStore — Deno KV (serverless KV over KV Connect)

DenoKvStore — Deno KV (serverless KV over KV Connect) Overview Deno KV is a globally-distributed, serverless key-value database. Inside a Deno runtime it is reached directly; outside one it is reached over the network with the KV Connect protocol, an HTTP/JSON transport. It has no SQL query surface, so DenoKvStore implements the minimal NoSqlStore marker interface (src/nosql/store.ts) — connection lifecycle plus a getClient() escape hatch — and exposes an edge-KV get/set/del/list/incr surface. Identity: Property | Value | --------- | ----------- | name | 'deno-kv' | library | 'fetch' | No canonical Node driver — HTTP over fetch (KV Connect assumption) There is no first-party Node client for Deno KV, so library is 'fetch' rather than a package name. This store assumes a KV Connect-style HTTP gateway exposing a small REST surface, and talks to it with the global fetch. There is no lazy require() of an SDK — when no client is injected, connect() builds a tiny internal fetch-based client (createFetchClient) from the url/accessToken options. Importing this module therefore never requires any external package. Keys are treated as opaque strings (Deno KV's array key parts are joined by the caller). The wrapped REST surface: get(key) → GET /kv/values/<key> (404 → null) set(k,v) → PUT /kv/values/<key> (body + optional expireIn) del(key) → DELETE /kv/values/<key> list(pref?) → GET /kv/keys?prefix= incr(k,by?) → read-modify-write over get/set (non-atomic; the native atomic().sum() op is not modeled) Injected client DenoKvStoreOptions accepts a pre-built client implementing the DenoKvHttpClient interface (a single request(method, path, init?) method). When provided, connect() uses it verbatim. This is how the test suite injects a mock HTTP client (no network), and how callers can supply their own transport. Values are serialized before writing: strings are stored verbatim; every other value is JSON.stringify'd. Connection Build a store from connection options and call connect(): Connection options: Option | Type | Purpose | ------------- | ------------------ | ----------------------------------------------------------------------------------- | url | string | Base URL of the KV Connect HTTP gateway. | accessToken | string | Access token sent as a Bearer credential. | client | DenoKvHttpClient | Pre-built HTTP client; when set, connect() uses it verbatim (no fetch client is built). | All options are optional (DenoKvStoreOptions = {}); when no client is given, the built-in fetch client is built against url ?? ''. Injected-client form Methods Every operation issues an HTTP request via the client. Transport failures are wrapped in a DatabaseError; using any method before connect() (or after disconnect()) throws a ConnectionError. Lifecycle Method | Signature | Behavior | ------------- | ------------------------------- | ------------------------------------------------------------------------------------------------- | connect | connect(): Promise<void> | Uses an injected client if provided, otherwise builds an internal fetch-based client from the options. Idempotent. Wraps failures in ConnectionError. | disconnect | disconnect(): Promise<void> | Clears the client and connection state. | isConnected | isConnected(): boolean | true only when connected and a client is present. | getClient | getClient(): DenoKvHttpClient | Returns the underlying (internal or injected) HTTP client. Throws ConnectionError if not connected. | Key-value operations Method | Signature | REST call | Behavior | ------- | -------------------------------------------------------------------------- | ---------------------------- | -------------------------------------------------------------------------------------------------- | get | get(key: string): Promise<string \| null> | GET /kv/values/<key> | Reads a key. Returns the response text, or null on a 404 (missing key). | set | set(key: string, value: unknown, options?: DenoKvSetOptions): Promise<void> | PUT /kv/values/<key> | Writes value (serialized). options.ttl maps to expireIn (milliseconds), options.expiration to expireAt (absolute Unix ms). | del | del(key: string): Promise<void> | DELETE /kv/values/<key> | Deletes a key. A 404 is treated as success. | list | list(prefix?: string): Promise<string[]> | GET /kv/keys?prefix= | Lists key names, optionally filtered by prefix. Returns the keys array from the response body. | incr | incr(key: string, by?: number): Promise<number> | get + set | Increments the numeric value at key by by (default 1). Non-atomic read-modify-write. | DenoKvSetOptions Example Verification status Unit / mock-verified only. The tests in tests/nosql/deno-kv.test.ts inject a mock DenoKvHttpClient via DenoKvStoreOptions.client that records each request (method/path/init) and returns canned Response-like objects. There is no network and no Deno KV gateway in the test run. What this proves: Each method issues the correct HTTP method and path (e.g. get → GET /kv/values/<encoded-key>, list → GET /kv/keys), with keys URL-encoded. set serializes non-strings ({ a: 1 } → '{"a":1}') and maps ttl → { expireIn: '1000' } query param. get returns null on a 404; list maps the keys array; incr performs a read-modify-write (GET then PUT with the new value). Lifecycle: connect/idempotent-connect/disconnect, getClient returning the injected client, and ConnectionError before connect(). Error handling: transport failures wrapped in DatabaseError. What this does not prove: live execution against a real Deno KV / KV Connect gateway. The REST surface is an assumed KV Connect-style shape and end-to-end execution over the wire has not been exercised here. Related reading All data stores — the full catalogue, grouped by purpose Database types — where this sits among the 22 categories