JavaScript KV API

Call kv.namespace(name) to obtain a handle synchronously. Operations on that handle are async and share the selected disk’s state with HTTP and shell KV calls.

const app = kv.namespace('app');
await app.put('settings', {theme:'dark'});
return await app.get('settings');

Methods

Method	Result
ns.get(key)	Stored value, or undefined for an absent key.
ns.put(key, value)	Replace value and type; resolves with no value.
ns.exists(key)	Boolean.
ns.delete(key)	Remove if present; resolves with no value.
ns.scan(options)	Async iterable of {key, value, revision}.
ns.batch(operations)	Atomically publish ordered puts/deletes; resolves with no value.

Keys and types

Keys accept a string or Uint8Array, up to 16 KiB of UTF-8/raw bytes. A string and byte array containing identical bytes address the same key. Convert numeric identifiers explicitly, for example String(id).

Values accept strings, Uint8Array, and JSON-compatible values up to 1 MiB of stored payload. Undefined, BigInt and cyclic values cannot be serialized. JSON uses ordinary JavaScript number and serialization behavior. Unsupported object members may be omitted by JSON serialization.

null is a stored JSON value. It remains distinct from an absent key’s undefined result. put accepts exactly key and value; a third options argument, including TTL, is rejected.

Scan options

const app = kv.namespace('app');
for await (const entry of app.scan({
  prefix:'user:', after:'user:100', limit:50, reverse:false,
})) {
  print(entry.key, JSON.stringify(entry.value), entry.revision);
}

prefix defaults to an empty string. after is exclusive and must share the prefix. limit is an optional nonnegative safe integer; zero emits no entries. reverse defaults to false. Keys sort by bytes. Valid UTF-8 keys return strings; other keys return Uint8Array. Revisions are opaque decimal strings.

A scan stays in the selected namespace. Paginated invocations do not share a snapshot. Unknown options are rejected.

Batch operations

const app = kv.namespace('app');
await app.batch([
  {op:'put', key:'job:42:result', value:{files:3}},
  {op:'put', key:'job:42:status', value:'done'},
  {op:'delete', key:'job:42:pending'},
]);

Only put/delete mutations are accepted. The batch has an 8 MiB encoded budget and applies within this namespace. It cannot include file mutations or conditional reads. If validation fails, the high-level batch publishes nothing.

Memory and persistence

All retained KV values, incomplete KV write buffers and open batches in one invocation share an 8 MiB staging budget in the supervisor. Exceeding it raises an error. Completion, abort, reader closure and cancellation release reservations. This budget covers retained KV data; it does not set total process RSS. A batch can hit the shared budget before reaching its own encoded limit.

KV operations do not trigger flush. Default buffered writes acknowledge RAM publication. Optional remote writes wait for background or explicit persistence. await fs.flush() confirms prior writes across the disk. See durability and all runtime limits.

Redis string, counter, expiration and list commands use a separate keyspace on the same disk. See the Redis SDK.