API Reference
Complete API reference for Alien KV bindings.
get
Retrieves a value by key. Returns undefined / None if the key does not exist or has expired.
const value: Uint8Array | undefined = await kv.get(key)
const text: string | undefined = await kv.getText(key)
const data: T | undefined = await kv.getJson<T>(key)let value: Option<Vec<u8>> = kv.get(key).await?;| Parameter | Type | Required | Description |
|---|---|---|---|
key | string | Yes | Max 512 bytes. Charset: a-z A-Z 0-9 - _ : . |
Returns: The value as bytes, or undefined / None if not found or expired.
set
Stores a value. Overwrites any existing value unless ifNotExists is set.
const created: boolean = await kv.set(key, value, options?)
// value accepts: string | Uint8Array | object (auto-serialized as JSON)
// options: { ttlMs?: number, ifNotExists?: boolean }let created: bool = kv.put(key, value_bytes, PutOptions {
ttl: Some(Duration::from_secs(3600)),
if_not_exists: true,
}).await?;| Parameter | Type | Required | Description |
|---|---|---|---|
key | string | Yes | Max 512 bytes. |
value | string | Uint8Array | object | Yes | Max 24 KiB. Objects are JSON-serialized. |
options.ttlMs | number | No | Time-to-live in milliseconds. |
options.ifNotExists | boolean | No | Only store if key doesn't exist. |
Returns: true if the key was newly created (relevant with ifNotExists), false if it already existed.
delete
Deletes a key. Deleting a non-existent key is a no-op.
await kv.delete(key)kv.delete(key).await?;exists
Checks if a key exists and has not expired.
const found: boolean = await kv.exists(key)let found: bool = kv.exists(key).await?;scan / scanPage
Scans keys by prefix. Results are unordered and may contain duplicates — see Behavior & Limits.
// Async iterator (recommended)
for await (const { key, value } of kv.scan(prefix, { limit: 100 })) {
// ...
}
// Manual pagination
const page = await kv.scanPage(prefix, limit?, cursor?)
// page.items: Array<{ key: string, value: Uint8Array }>
// page.nextCursor: string | undefinedlet result: ScanResult = kv.scan_prefix(prefix, Some(100), None).await?;
// result.items: Vec<(String, Vec<u8>)>
// result.next_cursor: Option<String>Cursors are opaque and may expire. Do not persist them across sessions.
Types
interface KvPutOptions {
ttlMs?: number // Time-to-live in milliseconds
ifNotExists?: boolean // Only store if key doesn't exist
}
interface KvScanResult {
items: Array<{ key: string; value: Uint8Array }>
nextCursor?: string
}pub struct PutOptions {
pub ttl: Option<Duration>,
pub if_not_exists: bool,
}
pub struct ScanResult {
pub items: Vec<(String, Vec<u8>)>,
pub next_cursor: Option<String>,
}