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
| TypeScript | Python | Rust | What it does |
|---|---|---|---|
get, getText, getJson | get(key) | get(key) | Read an entry and its version. |
set, setJson | put(key, value, *, ttl_seconds, condition, version) | put(key, value, options) | Write, optionally with a TTL and a condition. |
delete | delete(key, *, if_version) | delete(key, if_version) | Delete, optionally only if unchanged. |
exists | exists(key) | exists(key) | Check for a key without reading its value. |
scan | scan(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.
getTextdecodes the value as UTF-8.getJsonparses it withJSON.parseand throws if it isn't valid JSON.
set
Writes value to key.
settakes a string and stores its UTF-8 bytes.setJsonserializes the value withJSON.stringifyfirst.- 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 })| Parameter | Type | Description |
|---|---|---|
key | string | 1 to 512 bytes, a-z A-Z 0-9 - _ : . |
value | string (set), any JSON value (setJson) | See the value limit per platform. |
options.ttl | number | Seconds until the key expires. Omit for no expiry. |
options.ifVersion | string | null | null: 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)| Parameter | Type | Description |
|---|---|---|
prefix | string | Key prefix. Validated like a key. |
limit | number (optional) | Maximum items on this page. Defaults to 1,000. A page can hold fewer, even when more keys match. |
cursor | string (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
| Code | Retryable | When |
|---|---|---|
INVALID_INPUT | No | Invalid key or prefix, value over the limit, a version for another key, or an invalid cursor. |
KV_OPERATION_FAILED | Yes | A local store operation failed. |
BINDING_NOT_CONFIGURED | No | The 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.