1# KV API Reference
2 
3## Read Operations
4 
5```typescript
6// Single key (string)
7const value = await env.MY_KV.get("user:123");
8 
9// JSON type (auto-parsed)
10const config = await env.MY_KV.get<AppConfig>("config", "json");
11 
12// ArrayBuffer for binary
13const buffer = await env.MY_KV.get("image", "arrayBuffer");
14 
15// Stream for large values
16const stream = await env.MY_KV.get("large-file", "stream");
17 
18// With cache TTL (min 60s)
19const value = await env.MY_KV.get("key", { type: "text", cacheTtl: 300 });
20 
21// Bulk get (max 100 keys, counts as 1 operation)
22const keys = ["user:1", "user:2", "user:3", "missing:key"];
23const results = await env.MY_KV.get(keys);
24// Returns Map<string, string | null>
25 
26console.log(results.get("user:1"));     // "John" (if exists)
27console.log(results.get("missing:key")); // null
28 
29// Process results with null handling
30for (const [key, value] of results) {
31  if (value !== null) {
32    // Handle found keys
33    console.log(`${key}: ${value}`);
34  }
35}
36 
37// TypeScript with generics (type-safe JSON parsing)
38interface UserProfile { name: string; email: string; }
39const profile = await env.USERS.get<UserProfile>("user:123", "json");
40// profile is typed as UserProfile | null
41if (profile) {
42  console.log(profile.name); // Type-safe access
43}
44 
45// Bulk get with type
46const configs = await env.MY_KV.get<Config>(["config:app", "config:feature"], "json");
47// Map<string, Config | null>
48```
49 
50## Write Operations
51 
52```typescript
53// Basic put
54await env.MY_KV.put("key", "value");
55await env.MY_KV.put("config", JSON.stringify({ theme: "dark" }));
56 
57// With expiration (UNIX timestamp)
58await env.MY_KV.put("session", token, {
59  expiration: Math.floor(Date.now() / 1000) + 3600
60});
61 
62// With TTL (seconds from now, min 60)
63await env.MY_KV.put("cache", data, { expirationTtl: 300 });
64 
65// With metadata (max 1024 bytes)
66await env.MY_KV.put("user:profile", userData, {
67  metadata: { version: 2, lastUpdated: Date.now() }
68});
69 
70// Combined
71await env.MY_KV.put("temp", value, {
72  expirationTtl: 3600,
73  metadata: { temporary: true }
74});
75```
76 
77## Get with Metadata
78 
79```typescript
80// Single key
81const result = await env.MY_KV.getWithMetadata("user:profile");
82// { value: string | null, metadata: any | null }
83 
84if (result.value && result.metadata) {
85  const { version, lastUpdated } = result.metadata;
86}
87 
88// Multiple keys (bulk)
89const keys = ["key1", "key2", "key3"];
90const results = await env.MY_KV.getWithMetadata(keys);
91// Returns Map<string, { value, metadata, cacheStatus? }>
92 
93for (const [key, result] of results) {
94  if (result.value) {
95    console.log(`${key}: ${result.value}`);
96    console.log(`Metadata: ${JSON.stringify(result.metadata)}`);
97    // cacheStatus field indicates cache hit/miss (when available)
98  }
99}
100 
101// With type
102const result = await env.MY_KV.getWithMetadata<UserData>("user:123", "json");
103// result: { value: UserData | null, metadata: any | null, cacheStatus?: string }
104```
105 
106## Delete Operations
107 
108```typescript
109await env.MY_KV.delete("key"); // Always succeeds (even if key missing)
110```
111 
112## List Operations
113 
114```typescript
115// List all
116const keys = await env.MY_KV.list();
117// { keys: [...], list_complete: boolean, cursor?: string }
118 
119// With prefix
120const userKeys = await env.MY_KV.list({ prefix: "user:" });
121 
122// Pagination
123let cursor: string | undefined;
124let allKeys = [];
125do {
126  const result = await env.MY_KV.list({ cursor, limit: 1000 });
127  allKeys.push(...result.keys);
128  cursor = result.cursor;
129} while (!result.list_complete);
130```
131 
132## Performance Considerations
133 
134### Type Selection
135 
136| Type | Use Case | Performance |
137|------|----------|-------------|
138| `stream` | Large values (>1MB) | Fastest - no buffering |
139| `arrayBuffer` | Binary data | Fast - single allocation |
140| `text` | String values | Medium |
141| `json` | Objects (parse overhead) | Slowest - parsing cost |
142 
143### Parallel Reads
144 
145```typescript
146// Efficient parallel reads with Promise.all()
147const [user, settings, cache] = await Promise.all([
148  env.USERS.get("user:123", "json"),
149  env.SETTINGS.get("config:app", "json"),
150  env.CACHE.get("data:latest")
151]);
152```
153 
154## Error Handling
155 
156- **Missing keys:** Return `null` (not an error)
157- **Rate limit (429):** Retry with exponential backoff (see gotchas.md)
158- **Response too large (413):** Values >25MB fail with 413 error
159 
160See [gotchas.md](./gotchas.md) for detailed error patterns and solutions.
161