API Reference

Get a handle with kv(name) from @alienplatform/sdk (TypeScript) or alien_bindings::Bindings::from_env()?.kv(name).await? (Rust).

Every read returns the value together with an opaque, per-key version. Pass that version back into a later set or delete to make the write conditional — see Behavior & Limits.

get

Retrieves an entry by key. Returns null / None if the key does not exist or has expired.

const entry = await kv.get(key)          // KvEntry<Buffer> | null
const text = await kv.getText(key)       // KvEntry<string> | null
const data = await kv.getJson<T>(key)    // KvEntry<T> | null

// entry: { key: string, value: T, version: string }

Parameter	Type	Required	Description
`key`	`string`	Yes	Max 512 bytes. Charset: `a-z A-Z 0-9 - _ : .`

Returns: a KvEntry — the key, the value (getText decodes UTF-8, getJson parses JSON), and an opaque version for a later conditional write — or null / None if not found or expired.

set / setJson

Stores a value. Unconditional by default; pass ifVersion for an atomic conditional write.

const applied: boolean = await kv.set(key, value, options?)      // string value
const applied: boolean = await kv.setJson(key, value, options?)  // any value, JSON-serialized

// options: { ttl?: number, ifVersion?: string | null }
await kv.set(key, value)                              // unconditional
await kv.set(key, value, { ifVersion: null })         // create only if absent
await kv.set(key, value, { ifVersion: entry.version }) // compare-and-set

Parameter	Type	Required	Description
`key`	`string`	Yes	Max 512 bytes.
`value`	`string` (`set`) / any (`setJson`)	Yes	Max 24 KiB. `setJson` values are JSON-serialized.
`options.ttl`	`number`	No	Time-to-live in seconds.
`options.ifVersion`	`string \| null`	No	`null`: create only when the key is absent (or expired). A version string: replace only when the key still has that version. Omit for an unconditional write.

Returns: true when the write was applied. A conditional write resolves false when its precondition does not match — no exception is thrown. Passing a version that belongs to a different key throws an invalid-input error.

delete

Deletes a key. Deleting a non-existent key is a no-op. Pass ifVersion for an atomic compare-and-delete.

const applied: boolean = await kv.delete(key)
const applied: boolean = await kv.delete(key, { ifVersion: entry.version })

Parameter	Type	Required	Description
`key`	`string`	Yes	Max 512 bytes.
`options.ifVersion`	`string`	No	Delete only when the key still has this version.

Returns: true when the delete was applied. An unconditional delete resolves true even when the key was already absent; a conditional delete resolves false when the key is absent, expired, or has changed.

exists

Checks if a key exists and has not expired.

const found: boolean = await kv.exists(key)

scan

Scans keys by prefix, one page at a time. Results are unordered and may contain duplicates — see Behavior & Limits.

const page = await kv.scan(prefix, limit?, cursor?)
// page.items: Array<{ key: string, value: Buffer, version: string }>
// page.nextCursor: string | undefined

// Follow the cursor across pages
let cursor: string | undefined
do {
  const page = await kv.scan("user:", undefined, cursor)
  for (const { key, value } of page.items) { /* ... */ }
  cursor = page.nextCursor
} while (cursor)

Values come back alongside their keys and versions — a scan needs no follow-up get, and each entry's version is usable for a conditional write. Cursors are opaque and may expire; do not persist them across sessions.

Types

interface KvEntry<T> {
  key: string
  value: T
  version: string         // Opaque, key-bound version for conditional writes
}

interface KvSetOptions {
  ttl?: number            // Time-to-live in seconds
  ifVersion?: string | null  // null = create if absent; string = compare-and-set
}

interface KvDeleteOptions {
  ifVersion?: string      // Compare-and-delete
}

interface KvScanResult {
  items: Array<KvEntry<Buffer>>
  nextCursor?: string
}