references/kv/api.md

# KV API Reference

## Read Operations

```typescript
// Single key (string)
const value = await env.MY_KV.get("user:123");

// JSON type (auto-parsed)
const config = await env.MY_KV.get<AppConfig>("config", "json");

// ArrayBuffer for binary
const buffer = await env.MY_KV.get("image", "arrayBuffer");

// Stream for large values
const stream = await env.MY_KV.get("large-file", "stream");

// With cache TTL (min 60s)
const value = await env.MY_KV.get("key", { type: "text", cacheTtl: 300 });

// Bulk get (max 100 keys, counts as 1 operation)
const keys = ["user:1", "user:2", "user:3", "missing:key"];
const results = await env.MY_KV.get(keys);
// Returns Map<string, string | null>

console.log(results.get("user:1"));     // "John" (if exists)
console.log(results.get("missing:key")); // null

// Process results with null handling
for (const [key, value] of results) {
  if (value !== null) {
    // Handle found keys
    console.log(`${key}: ${value}`);
  }
}

// TypeScript with generics (type-safe JSON parsing)
interface UserProfile { name: string; email: string; }
const profile = await env.USERS.get<UserProfile>("user:123", "json");
// profile is typed as UserProfile | null
if (profile) {
  console.log(profile.name); // Type-safe access
}

// Bulk get with type
const configs = await env.MY_KV.get<Config>(["config:app", "config:feature"], "json");
// Map<string, Config | null>
```

## Write Operations

```typescript
// Basic put
await env.MY_KV.put("key", "value");
await env.MY_KV.put("config", JSON.stringify({ theme: "dark" }));

// With expiration (UNIX timestamp)
await env.MY_KV.put("session", token, {
  expiration: Math.floor(Date.now() / 1000) + 3600
});

// With TTL (seconds from now, min 60)
await env.MY_KV.put("cache", data, { expirationTtl: 300 });

// With metadata (max 1024 bytes)
await env.MY_KV.put("user:profile", userData, {
  metadata: { version: 2, lastUpdated: Date.now() }
});

// Combined
await env.MY_KV.put("temp", value, {
  expirationTtl: 3600,
  metadata: { temporary: true }
});
```

## Get with Metadata

```typescript
// Single key
const result = await env.MY_KV.getWithMetadata("user:profile");
// { value: string | null, metadata: any | null }

if (result.value && result.metadata) {
  const { version, lastUpdated } = result.metadata;
}

// Multiple keys (bulk)
const keys = ["key1", "key2", "key3"];
const results = await env.MY_KV.getWithMetadata(keys);
// Returns Map<string, { value, metadata, cacheStatus? }>

for (const [key, result] of results) {
  if (result.value) {
    console.log(`${key}: ${result.value}`);
    console.log(`Metadata: ${JSON.stringify(result.metadata)}`);
    // cacheStatus field indicates cache hit/miss (when available)
  }
}

// With type
const result = await env.MY_KV.getWithMetadata<UserData>("user:123", "json");
// result: { value: UserData | null, metadata: any | null, cacheStatus?: string }
```

## Delete Operations

```typescript
await env.MY_KV.delete("key"); // Always succeeds (even if key missing)
```

## List Operations

```typescript
// List all
const keys = await env.MY_KV.list();
// { keys: [...], list_complete: boolean, cursor?: string }

// With prefix
const userKeys = await env.MY_KV.list({ prefix: "user:" });

// Pagination
let cursor: string | undefined;
let allKeys = [];
do {
  const result = await env.MY_KV.list({ cursor, limit: 1000 });
  allKeys.push(...result.keys);
  cursor = result.cursor;
} while (!result.list_complete);
```

## Performance Considerations

### Type Selection

| Type | Use Case | Performance |
|------|----------|-------------|
| `stream` | Large values (>1MB) | Fastest - no buffering |
| `arrayBuffer` | Binary data | Fast - single allocation |
| `text` | String values | Medium |
| `json` | Objects (parse overhead) | Slowest - parsing cost |

### Parallel Reads

```typescript
// Efficient parallel reads with Promise.all()
const [user, settings, cache] = await Promise.all([
  env.USERS.get("user:123", "json"),
  env.SETTINGS.get("config:app", "json"),
  env.CACHE.get("data:latest")
]);
```

## Error Handling

- **Missing keys:** Return `null` (not an error)
- **Rate limit (429):** Retry with exponential backoff (see gotchas.md)
- **Response too large (413):** Values >25MB fail with 413 error

See [gotchas.md](./gotchas.md) for detailed error patterns and solutions.