Cloudflare.KV reference

InstantNamespace

Source: src/Cloudflare/KV/InstantNamespace.ts

A Cloudflare Workers KV Instant namespace, powered by Quicksilver.

Requires private beta access. Uses the same Worker binding as classic KV, with fast global replication and no cold reads. Namespace mode is fixed at creation; switching between Namespace and InstantNamespace replaces it.

Metadata is unsupported. Use get instead of getWithMetadata, and do not pass metadata to put. Listing returns all matching keys without pagination. The beta limits namespaces to 1 MB and 10,000 pairs, keys to 300 bytes, and writes to one per namespace per second.

Storage and put/delete/list operations cost substantially more than classic KV; reads cost less. See https://blog.cloudflare.com/workers-kv-instant/ for pricing and private beta availability.

InstantNamespace: Creating an Instant Namespace

const config = yield* Cloudflare.KV.InstantNamespace("Config");

InstantNamespace: Binding to a Worker

const client = yield* Cloudflare.KV.ReadNamespace(config);
const enabled = yield* client.get("feature-enabled");

Provide ReadNamespaceBinding on the Worker runtime. WriteNamespace and ReadWriteNamespace also accept Instant namespaces, as do their Http and Local capability implementations.

During alchemy dev, the namespace uses persistent local KV storage without cloud credentials or beta access. Local mode rejects metadata and lists all matching keys in one response. Local keys are limited to 300 UTF-8 bytes. Namespace storage quotas, key-count limits, global replication, billing, and write throttling are not emulated. Use Alchemy.remote() to opt into a live namespace during development (requires beta access).

Namespace

Source: src/Cloudflare/KV/Namespace.ts

A Cloudflare Workers KV namespace for key-value storage at the edge.

KV provides eventually-consistent, low-latency reads with global replication. Create a namespace as a resource, then bind it to a Worker to get/put values at runtime.

Namespace: Creating a Namespace

const kv = yield* Cloudflare.KV.Namespace("MyKV");

Namespace: Binding to a Worker

const kv = yield* Cloudflare.KV.ReadWriteNamespace(MyKV);

// Read a value
const value = yield* kv.get("my-key");

// Write a value
yield* kv.put("my-key", "hello world");

Provide Cloudflare.KV.ReadWriteNamespaceBinding (native Worker binding) or Cloudflare.KV.ReadWriteNamespaceHttp (scoped HTTP token) in the worker’s runtime layer. Use Cloudflare.KV.ReadNamespace / Cloudflare.KV.WriteNamespace for least-privilege read- or write-only access.

ReadNamespace

Source: src/Cloudflare/KV/ReadNamespace.ts

Bind a Namespace to a Worker with read access and obtain the Effect-native KV client (get, getWithMetadata, list).

ReadNamespace is a single identifier that is simultaneously the binding’s Context tag, its type, and the callable — yield* Cloudflare.KV.ReadNamespace(ns).

Also accepts InstantNamespace, returning a client without metadata or paginated listing options.

ReadWriteNamespace

Source: src/Cloudflare/KV/ReadWriteNamespace.ts

Bind a Namespace to a Worker with read + write access and obtain the Effect-native KV client (get, getWithMetadata, list, put, delete).

ReadWriteNamespace is a single identifier that is simultaneously the binding’s Context tag, its type, and the callable — yield* Cloudflare.KV.ReadWriteNamespace(ns).

Also accepts InstantNamespace, returning a client without metadata or paginated listing options.

WriteNamespace

Source: src/Cloudflare/KV/WriteNamespace.ts

Bind a Namespace to a Worker with write access and obtain the Effect-native KV client (put, delete).

WriteNamespace is a single identifier that is simultaneously the binding’s Context tag, its type, and the callable — yield* Cloudflare.KV.WriteNamespace(ns).

Also accepts InstantNamespace, returning a client without metadata or paginated listing options.