1# KV Patterns & Best Practices
2 
3## Multi-Tier Caching
4 
5```typescript
6// Memory → KV → Origin (3-tier cache)
7const memoryCache = new Map<string, { data: any; expires: number }>();
8 
9async function getCached(env: Env, key: string): Promise<any> {
10  const now = Date.now();
11  
12  // L1: Memory cache (fastest)
13  const cached = memoryCache.get(key);
14  if (cached && cached.expires > now) {
15    return cached.data;
16  }
17  
18  // L2: KV cache (fast)
19  const kvValue = await env.CACHE.get(key, "json");
20  if (kvValue) {
21    memoryCache.set(key, { data: kvValue, expires: now + 60000 }); // 1min in memory
22    return kvValue;
23  }
24  
25  // L3: Origin (slow)
26  const origin = await fetch(`https://api.example.com/${key}`).then(r => r.json());
27  
28  // Backfill caches
29  await env.CACHE.put(key, JSON.stringify(origin), { expirationTtl: 300 }); // 5min in KV
30  memoryCache.set(key, { data: origin, expires: now + 60000 });
31  
32  return origin;
33}
34```
35 
36## API Response Caching
37 
38```typescript
39async function getCachedData(env: Env, key: string, fetcher: () => Promise<any>): Promise<any> {
40  const cached = await env.MY_KV.get(key, "json");
41  if (cached) return cached;
42  
43  const data = await fetcher();
44  await env.MY_KV.put(key, JSON.stringify(data), { expirationTtl: 300 });
45  return data;
46}
47 
48const apiData = await getCachedData(
49  env,
50  "cache:users",
51  () => fetch("https://api.example.com/users").then(r => r.json())
52);
53```
54 
55## Session Management
56 
57```typescript
58interface Session { userId: string; expiresAt: number; }
59 
60async function createSession(env: Env, userId: string): Promise<string> {
61  const sessionId = crypto.randomUUID();
62  const expiresAt = Date.now() + (24 * 60 * 60 * 1000);
63  
64  await env.SESSIONS.put(
65    `session:${sessionId}`,
66    JSON.stringify({ userId, expiresAt }),
67    { expirationTtl: 86400, metadata: { createdAt: Date.now() } }
68  );
69  
70  return sessionId;
71}
72 
73async function getSession(env: Env, sessionId: string): Promise<Session | null> {
74  const data = await env.SESSIONS.get<Session>(`session:${sessionId}`, "json");
75  if (!data || data.expiresAt < Date.now()) return null;
76  return data;
77}
78```
79 
80## Coalesce Cold Keys
81 
82```typescript
83// ❌ BAD: Many individual keys
84await env.KV.put("user:123:name", "John");
85await env.KV.put("user:123:email", "[email protected]");
86 
87// ✅ GOOD: Single coalesced object
88await env.USERS.put("user:123:profile", JSON.stringify({
89  name: "John",
90  email: "[email protected]",
91  role: "admin"
92}));
93 
94// Benefits: Hot key cache, single read, reduced operations
95// Trade-off: Harder to update individual fields
96```
97 
98## Prefix-Based Namespacing
99 
100```typescript
101// Logical partitioning within single namespace
102const PREFIXES = {
103  users: "user:",
104  sessions: "session:",
105  cache: "cache:",
106  features: "feature:"
107} as const;
108 
109// Write with prefix
110async function setUser(env: Env, id: string, data: any) {
111  await env.KV.put(`${PREFIXES.users}${id}`, JSON.stringify(data));
112}
113 
114// Read with prefix
115async function getUser(env: Env, id: string) {
116  return await env.KV.get(`${PREFIXES.users}${id}`, "json");
117}
118 
119// List by prefix
120async function listUserIds(env: Env): Promise<string[]> {
121  const result = await env.KV.list({ prefix: PREFIXES.users });
122  return result.keys.map(k => k.name.replace(PREFIXES.users, ""));
123}
124 
125// Example hierarchy
126"user:123:profile"
127"user:123:settings"
128"cache:api:users"
129"session:abc-def"
130"feature:flags:beta"
131```
132 
133## Metadata Versioning
134 
135```typescript
136interface VersionedData {
137  version: number;
138  data: any;
139}
140 
141async function migrateIfNeeded(env: Env, key: string) {
142  const result = await env.DATA.getWithMetadata(key, "json");
143  
144  if (!result.value) return null;
145  
146  const currentVersion = result.metadata?.version || 1;
147  const targetVersion = 2;
148  
149  if (currentVersion < targetVersion) {
150    // Migrate data format
151    const migrated = migrate(result.value, currentVersion, targetVersion);
152    
153    // Store with new version
154    await env.DATA.put(key, JSON.stringify(migrated), {
155      metadata: { version: targetVersion, migratedAt: Date.now() }
156    });
157    
158    return migrated;
159  }
160  
161  return result.value;
162}
163 
164function migrate(data: any, from: number, to: number): any {
165  if (from === 1 && to === 2) {
166    // V1 → V2: Rename field
167    return { ...data, userName: data.name };
168  }
169  return data;
170}
171```
172 
173## Error Boundary Pattern
174 
175```typescript
176// Resilient get with fallback
177async function resilientGet<T>(
178  env: Env,
179  key: string,
180  fallback: T
181): Promise<T> {
182  try {
183    const value = await env.KV.get<T>(key, "json");
184    return value ?? fallback;
185  } catch (err) {
186    console.error(`KV error for ${key}:`, err);
187    return fallback;
188  }
189}
190 
191// Usage
192const config = await resilientGet(env, "config:app", {
193  theme: "light",
194  maxItems: 10
195});
196```
197