Overview

KV provides a minimal, portable key-value store for fast lookups. Store and retrieve opaque byte values by key, with optional time-to-live (TTL) for automatic expiration. Designed for caching, session state, feature flags, and distributed locks.

Platform Mapping

Platform	Backing Service	Provisioned by
AWS	Amazon DynamoDB (on-demand)	Alien
GCP	Google Cloud Firestore	Alien
Azure	Azure Table Storage	Alien

| Local | sled (embedded database) | Alien |

When to Use

Use KV for fast key-based lookups — caching, session state, feature flags, distributed locks, idempotency tracking. Values are opaque bytes up to 24 KiB, with optional TTL.

Don't use KV for complex queries, relationships, or large documents. For full-text search, joins, or items larger than 24 KiB, use a dedicated database.

Stack Definition

Declare a KV resource in your alien.ts:

const cache = new alien.Kv("cache").build()

Parameter	Type	Description
`id`	`string`	Resource identifier. `[A-Za-z0-9-_]`, max 64 characters.

KV has no additional configuration options. The backing service (DynamoDB, Firestore, Table Storage) is determined by the deployment platform.

Quick Start

import { kv } from "@alienplatform/sdk"

const cache = await kv("cache")

await cache.set("user:123", { name: "Alice", plan: "pro" })
const user = await cache.getJson("user:123")

let cache = ctx.bindings().load_kv("cache").await?;

cache.put("user:123", value.as_bytes(), PutOptions::default()).await?;
let data = cache.get("user:123").await?;

Core Operations

Set a Value

await cache.set("user:123", { name: "Alice" })           // JSON (auto-serialized)
await cache.set("greeting", "hello")                       // String
await cache.set("session:abc", data, { ttlMs: 3600000 })  // Expires in 1 hour

// Atomic create — only if key doesn't exist
const created = await cache.set("lock:res", { owner: "w1" }, { ifNotExists: true })
// true if new, false if already existed

Get a Value

const raw = await cache.get("user:123")       // Uint8Array | undefined
const text = await cache.getText("greeting")   // string | undefined
const user = await cache.getJson("user:123")   // parsed JSON | undefined

Returns undefined if the key does not exist or has expired.

Delete, Exists, Scan

await cache.delete("user:123")

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

for await (const { key, value } of cache.scan("user:")) {
  console.log(key) // "user:123", "user:456", ...
}

Patterns

Distributed Lock

const acquired = await cache.set("lock:report-gen", { owner: workerId }, {
  ifNotExists: true,
  ttlMs: 30_000,
})
if (acquired) {
  try { await generateReport() }
  finally { await cache.delete("lock:report-gen") }
}

Cache with TTL

async function getUser(userId: string) {
  const cached = await cache.getJson(`user:${userId}`)
  if (cached) return cached

  const user = await fetchFromDatabase(userId)
  await cache.set(`user:${userId}`, user, { ttlMs: 5 * 60 * 1000 })
  return user
}

On this page