Docs

KV API reference

The KV API is the set of methods your code calls on a linked KV store, in the TypeScript, Python, and Rust SDKs. A binding is the connection details Alien injects into each workload linked to the resource, which the SDK client reads.

A handle comes from kv(name) in @alienplatform/sdk (TypeScript) or alienplatform (Python), or Bindings::from_env()?.kv(name).await? in alien-sdk (Rust). name is the resource ID from alien.ts.

Creating the handle does no I/O. The binding resolves on the first call and is cached. If the workload isn't linked to the resource, the first call throws BINDING_NOT_CONFIGURED.

Methods at a glance

TypeScriptPythonRustWhat it does
get, getText, getJsonget(key)get(key)Read an entry and its version.
set, setJsonput(key, value, *, ttl_seconds, condition, version)put(key, value, options)Write, optionally with a TTL and a condition.
deletedelete(key, *, if_version)delete(key, if_version)Delete, optionally only if unchanged.
existsexists(key)exists(key)Check for a key without reading its value.
scanscan(prefix, *, limit, cursor)scan_prefix(prefix, limit, cursor)Page through keys under a prefix.

Every key is validated before any request: 1 to 512 bytes, characters a-z A-Z 0-9 - _ : . only. An invalid key fails with INVALID_INPUT.

get

Reads the entry for key. Returns null (Python None) when the key is absent or expired.

const raw = await store.get("user:123")             // KvEntry<Buffer> | null
const text = await store.getText("greeting")        // KvEntry<string> | null
const user = await store.getJson<User>("user:123")  // KvEntry<User> | null

if (user) console.log(user.value.name, user.version)

Returns a KvEntry: the key, the value, and an opaque version for a later conditional write.

  • getText decodes the value as UTF-8.
  • getJson parses it with JSON.parse and throws if it isn't valid JSON.

set

Writes value to key.

  • set takes a string and stores its UTF-8 bytes.
  • setJson serializes the value with JSON.stringify first.
  • Python and Rust take bytes.
await store.set("greeting", "hello")
await store.setJson("user:123", { name: "Ada" }, { ttl: 3600 })

// Create only if absent (or expired)
const created = await store.setJson("lock:job-1", { owner: "a" }, { ifVersion: null, ttl: 60 })

// Replace only if unchanged since the read
const applied = await store.setJson("user:123", updated, { ifVersion: entry.version })
ParameterTypeDescription
keystring1 to 512 bytes, a-z A-Z 0-9 - _ : .
valuestring (set), any JSON value (setJson)See the value limit per platform.
options.ttlnumberSeconds until the key expires. Omit for no expiry.
options.ifVersionstring | nullnull: write only if the key is absent or expired. A version string: write only if the key still has that version. Omit for an unconditional write.

Python uses ttl_seconds, and condition="absent" or condition="version" with version=. Rust uses PutOptions.

Returns boolean. An unconditional write always returns true. A conditional write returns false when its condition doesn't hold, and writes nothing.

Errors: INVALID_INPUT for an invalid key, a value over the limit, or a version that belongs to a different key.

delete

Deletes key.

await store.delete("user:123")
const deleted = await store.delete("lock:job-1", { ifVersion: lock.version })

Returns boolean. An unconditional delete returns true, including when the key didn't exist. A conditional delete returns false when the key is absent, expired, or changed.

exists

Returns whether key exists and hasn't expired, without reading its value.

if (await store.exists("user:123")) { /* ... */ }

scan

Returns one page of entries whose key starts with prefix, values included.

const seen = new Set<string>()
let cursor: string | undefined

do {
  const page = await store.scan("user:", 100, cursor)
  for (const item of page.items) {
    if (seen.has(item.key)) continue // pages can repeat keys
    seen.add(item.key)
    console.log(item.key, item.value.toString("utf8"))
  }
  cursor = page.nextCursor
} while (cursor)
ParameterTypeDescription
prefixstringKey prefix. Validated like a key.
limitnumber (optional)Maximum items on this page. Defaults to 1,000. A page can hold fewer, even when more keys match.
cursorstring (optional)nextCursor from the previous page. Only valid with the same prefix.

Returns KvScanResult: items with key, value, and version, and nextCursor, which is absent when there are no more pages. Read the scan semantics before relying on order or completeness.

Types

KvEntry

interface KvEntry<T> {
  key: string
  value: T          // Buffer, string, or parsed JSON depending on the method
  version: string   // Opaque. Only pass it back as ifVersion.
}

Python KvEntry(key: str, value: bytes, version: str). Rust KvEntry { key: String, value: Vec<u8>, version: String }.

KvSetOptions

interface KvSetOptions {
  ttl?: number                // seconds
  ifVersion?: string | null   // null: must be absent; string: must match
}

KvDeleteOptions

interface KvDeleteOptions {
  ifVersion?: string
}

KvScanResult

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

Python KvPage(items: tuple[KvEntry, ...], next_cursor: str | None). Rust ScanResult { items: Vec<KvEntry>, next_cursor: Option<String> }.

PutOptions

Rust only.

pub struct PutOptions {
    pub ttl: Option<Duration>,
    pub condition: PutCondition,
}

pub enum PutCondition {
    None,             // default: unconditional
    Absent,           // create only if absent or expired
    Version(String),  // replace only if the version still matches
}

Errors

CodeRetryableWhen
INVALID_INPUTNoInvalid key or prefix, value over the limit, a version for another key, or an invalid cursor.
KV_OPERATION_FAILEDYesA local store operation failed.
BINDING_NOT_CONFIGUREDNoThe workload isn't linked to this resource.

Cloud backend failures keep the cloud client's error code and retryable flag, for example CLOUD_PLATFORM_ERROR, REMOTE_ACCESS_DENIED, RATE_LIMIT_EXCEEDED, or TIMEOUT.

A failed condition is not an error. It returns false.

On this page