KVNamespace

class KVNamespace(namespace)

A namespaced key-value store.

KV data is scoped to the current deployment and namespace. It persists across publishes and rollbacks until it is explicitly deleted, cleared, expires by TTL, or the deployment is deleted. Completed writes are immediately visible to later reads, including from another runtime instance.

const storage = new weeble.KVNamespace('my-data');
await storage.put('counter', 42);
const count = await storage.get<number>('counter');

exported from runtime.d

Arguments:

namespace (string)

Properties

KVNamespace.namespace: type: readonly string

Methods

async KVNamespace.batch(operations: readonly KVBatchOperation[]) → Promise<void>: Applies up to 100 puts and deletes atomically within this namespace.

async KVNamespace.clear() → Promise<number>: Permanently deletes every key in this namespace and returns the number removed.

async KVNamespace.compareAndSet(key: string, compare: JsonValue, set: JsonValue, options: KVCompareAndSetOptions) → Promise<boolean>: Replaces a value only when its serialized JSON equals compare. Object key order is significant.

async KVNamespace.count() → Promise<number>: Returns the exact number of keys in this namespace.

async KVNamespace.delete(key: string, options: KVDeleteOptions) → Promise<boolean>: Deletes a value and reports whether it existed and, when supplied, matched prevValue.

async KVNamespace.get<T>(key: string) → Promise<T | undefined>

Type parameters:: T – (extends JsonValue)

async KVNamespace.getMany<T>(keys: readonly string[]) → Promise<(T | undefined)[]>

Reads up to 100 keys in one storage operation. Results match the input order.

Type parameters:: T – (extends JsonValue)

async KVNamespace.increment(key: string, amount: number, options: KVIncrementOptions) → Promise<number>: Atomically adds amount (default 1) to a number. Missing keys start at zero; negatives subtract.

async KVNamespace.items(options: KVListOptions) → Promise<KVItem[]>: Returns one lexicographically ordered page of entries (100 by default).

async KVNamespace.itemsPage(options: KVPageOptions) → Promise<KVPage<KVItem>>: Returns lexicographically ordered entries and an opaque cursor for the next page.

async KVNamespace.list(options: KVListOptions) → Promise<string[]>: Returns one lexicographically ordered page of keys (100 by default).

async KVNamespace.listPage(options: KVPageOptions) → Promise<KVPage<string>>: Returns lexicographically ordered keys and an opaque cursor for the next page.

async KVNamespace.put(key: string, value: JsonValue, options: KVPutOptions) → Promise<boolean>: Writes a value and returns false only when ifNotExists prevents the write.

async KVNamespace.transact<T>(key: string, transaction: (prev: T | undefined) => T | undefined) → Promise<T | undefined>

Atomically updates a key, retrying when another execution changes it. Return undefined from the callback to delete the key. The callback may run up to eight times and must not perform side effects.

Type parameters:: T – (extends JsonValue)