Initial commit

2025-11-30 08:24:21 +08:00
commit a5d916d454
11 changed files with 3951 additions and 0 deletions
--- a/.claude-plugin/plugin.json
+++ b/.claude-plugin/plugin.json
@@ -0,0 +1,12 @@
 {
  "name": "cloudflare-kv",
  "description": "Store key-value data globally with Cloudflare KVs edge network. Use when: caching API responses, storing configuration, managing user preferences, handling TTL expiration, or troubleshooting KV_ERROR, 429 rate limits, eventual consistency, or cacheTtl errors.",
  "version": "1.0.0",
  "author": {
    "name": "Jeremy Dawes",
    "email": "jeremy@jezweb.net"
  },
  "skills": [
    "./"
  ]
 }
--- a/README.md
+++ b/README.md
@@ -0,0 +1,3 @@
 # cloudflare-kv
 Store key-value data globally with Cloudflare KVs edge network. Use when: caching API responses, storing configuration, managing user preferences, handling TTL expiration, or troubleshooting KV_ERROR, 429 rate limits, eventual consistency, or cacheTtl errors.
--- a/SKILL.md
+++ b/SKILL.md
@@ -0,0 +1,429 @@
 ---
 name: cloudflare-kv
 description: |
  Store key-value data globally with Cloudflare KV's edge network. Use when: caching API responses, storing configuration, managing user preferences, handling TTL expiration, or troubleshooting KV_ERROR, 429 rate limits, eventual consistency, or cacheTtl errors.
 license: MIT
 ---
 # Cloudflare Workers KV
 **Status**: Production Ready ✅
 **Last Updated**: 2025-11-24
 **Dependencies**: cloudflare-worker-base (for Worker setup)
 **Latest Versions**: wrangler@4.50.0, @cloudflare/workers-types@4.20251121.0
 **Recent Updates (2025)**:
 - **August 2025**: Architecture redesign (40x performance gain, <5ms p99 latency, hybrid storage with R2)
 - **January 2025**: Namespace limit increased (200 → 1,000 namespaces per account for Free and Paid plans)
 ---
 ## Quick Start (5 Minutes)
 ```bash
 # Create namespace
 npx wrangler kv namespace create MY_NAMESPACE
 # Output: [[kv_namespaces]] binding = "MY_NAMESPACE" id = "<UUID>"
 ```
 **wrangler.jsonc:**
 ```jsonc
 {
  "kv_namespaces": [{
    "binding": "MY_NAMESPACE",  // Access as env.MY_NAMESPACE
    "id": "<production-uuid>",
    "preview_id": "<preview-uuid>"  // Optional: local dev
  }]
 }
 ```
 **Basic Usage:**
 ```typescript
 type Bindings = { MY_NAMESPACE: KVNamespace };
 app.post('/set/:key', async (c) => {
  await c.env.MY_NAMESPACE.put(c.req.param('key'), await c.req.text());
  return c.json({ success: true });
 });
 app.get('/get/:key', async (c) => {
  const value = await c.env.MY_NAMESPACE.get(c.req.param('key'));
  return value ? c.json({ value }) : c.json({ error: 'Not found' }, 404);
 });
 ```
 ---
 ## KV API Reference
 ### Read Operations
 ```typescript
 // Get single key
 const value = await env.MY_KV.get('key');  // string | null
 const data = await env.MY_KV.get('key', { type: 'json' });  // object | null
 const buffer = await env.MY_KV.get('key', { type: 'arrayBuffer' });
 const stream = await env.MY_KV.get('key', { type: 'stream' });
 // Get with cache (minimum 60s)
 const value = await env.MY_KV.get('key', { cacheTtl: 300 });  // 5 min edge cache
 // Bulk read (counts as 1 operation)
 const values = await env.MY_KV.get(['key1', 'key2']);  // Map<string, string | null>
 // With metadata
 const { value, metadata } = await env.MY_KV.getWithMetadata('key');
 const result = await env.MY_KV.getWithMetadata(['key1', 'key2']);  // Bulk with metadata
 ```
 ### Write Operations
 ```typescript
 // Basic write (max 1/second per key)
 await env.MY_KV.put('key', 'value');
 await env.MY_KV.put('user:123', JSON.stringify({ name: 'John' }));
 // With expiration
 await env.MY_KV.put('session', data, { expirationTtl: 3600 });  // 1 hour
 await env.MY_KV.put('token', value, { expiration: Math.floor(Date.now()/1000) + 86400 });
 // With metadata (max 1024 bytes)
 await env.MY_KV.put('config', 'dark', {
  metadata: { updatedAt: Date.now(), version: 2 }
 });
 ```
 **Critical Limits:**
 - Key: 512 bytes max
 - Value: 25 MiB max
 - Metadata: 1024 bytes max
 - Write rate: 1/second per key (429 error if exceeded)
 - Expiration: 60 seconds minimum
 ### List Operations
 ```typescript
 // List with pagination
 const result = await env.MY_KV.list({ prefix: 'user:', limit: 1000, cursor });
 // result: { keys: [], list_complete: boolean, cursor?: string }
 // CRITICAL: Always check list_complete, not keys.length === 0
 let cursor: string | undefined;
 do {
  const result = await env.MY_KV.list({ prefix: 'user:', cursor });
  processKeys(result.keys);
  cursor = result.list_complete ? undefined : result.cursor;
 } while (cursor);
 ```
 ### Delete Operations
 ```typescript
 // Delete single key
 await env.MY_KV.delete('key');  // Always succeeds
 // Bulk delete (CLI only, up to 10,000 keys)
 // npx wrangler kv bulk delete --binding=MY_KV keys.json
 ```
 ---
 ## Advanced Patterns
 ### Caching Pattern with CacheTtl
 ```typescript
 async function getCachedData(kv: KVNamespace, key: string, fetchFn: () => Promise<any>, ttl = 300) {
  const cached = await kv.get(key, { type: 'json', cacheTtl: ttl });
  if (cached) return cached;
  const data = await fetchFn();
  await kv.put(key, JSON.stringify(data), { expirationTtl: ttl * 2 });
  return data;
 }
 ```
 **Guidelines**: Minimum 60s, use for read-heavy workloads (100:1 read/write ratio)
 ### Metadata Optimization
 ```typescript
 // Store small values (<1024 bytes) in metadata to avoid separate get() calls
 await env.MY_KV.put('user:123', '', {
  metadata: { status: 'active', plan: 'pro', lastSeen: Date.now() }
 });
 // list() returns metadata automatically (no additional get() calls)
 const users = await env.MY_KV.list({ prefix: 'user:' });
 users.keys.forEach(({ name, metadata }) => console.log(name, metadata.status));
 ```
 ### Key Coalescing
 ```typescript
 // ❌ Bad: Many cold keys
 await kv.put('user:123:name', 'John');
 await kv.put('user:123:email', 'john@example.com');
 // ✅ Good: Single hot key
 await kv.put('user:123', JSON.stringify({ name: 'John', email: 'john@example.com' }));
 ```
 **Benefit**: Cold keys benefit from hot key caching, fewer operations
 **Trade-off**: Requires read-modify-write for updates
 ### Pagination Helper
 ```typescript
 async function* paginateKV(kv: KVNamespace, options: { prefix?: string } = {}) {
  let cursor: string | undefined;
  do {
    const result = await kv.list({ ...options, cursor });
    yield result.keys;
    cursor = result.list_complete ? undefined : result.cursor;
  } while (cursor);
 }
 // Usage
 for await (const keys of paginateKV(env.MY_KV, { prefix: 'user:' })) {
  processKeys(keys);
 }
 ```
 ### Rate Limit Retry with Exponential Backoff
 ```typescript
 async function putWithRetry(kv: KVNamespace, key: string, value: string, opts?: KVPutOptions) {
  let attempts = 0, delay = 1000;
  while (attempts < 5) {
    try {
      await kv.put(key, value, opts);
      return;
    } catch (error) {
      if ((error as Error).message.includes('429')) {
        attempts++;
        if (attempts >= 5) throw new Error('Max retry attempts');
        await new Promise(r => setTimeout(r, delay));
        delay *= 2;  // Exponential backoff
      } else throw error;
    }
  }
 }
 ```
 ---
 ## Understanding Eventual Consistency
 KV is **eventually consistent** across Cloudflare's global network (Aug 2025 redesign: hybrid storage, <5ms p99 latency):
 **How It Works:**
 1. Writes immediately visible in same location
 2. Other locations see update within ~60 seconds (or cacheTtl value)
 3. Cached reads may return stale data during propagation
 **Example:**
 ```typescript
 // Tokyo: Write
 await env.MY_KV.put('counter', '1');
 const value = await env.MY_KV.get('counter'); // "1" ✅
 // London (within 60s): May be stale ⚠️
 const value2 = await env.MY_KV.get('counter'); // Might be old value
 // After 60+ seconds: Consistent ✅
 ```
 **Use KV for**: Read-heavy workloads (100:1 ratio), config, feature flags, caching, user preferences
 **Don't use KV for**: Financial transactions, strong consistency, >1/second writes per key, critical data
 **Need strong consistency?** Use [Durable Objects](https://developers.cloudflare.com/durable-objects/)
 ---
 ## Wrangler CLI Essentials
 ```bash
 # Create namespace
 npx wrangler kv namespace create MY_NAMESPACE [--preview]
 # Manage keys
 npx wrangler kv key put --binding=MY_KV "key" "value" [--ttl=3600] [--metadata='{}']
 npx wrangler kv key get --binding=MY_KV "key"
 npx wrangler kv key list --binding=MY_KV [--prefix="user:"]
 npx wrangler kv key delete --binding=MY_KV "key"
 # Bulk operations (up to 10,000 keys)
 npx wrangler kv bulk put --binding=MY_KV data.json
 npx wrangler kv bulk delete --binding=MY_KV keys.json
 ```
 ---
 ## Limits & Quotas
 | Feature | Free Plan | Paid Plan |
 |---------|-----------|-----------|
 | Reads per day | 100,000 | Unlimited |
 | Writes per day (different keys) | 1,000 | Unlimited |
 | **Writes per key per second** | **1** | **1** |
 | Operations per Worker invocation | 1,000 | 1,000 |
 | **Namespaces per account** | **1,000** | **1,000** |
 | Storage per account | 1 GB | Unlimited |
 | Key size | 512 bytes | 512 bytes |
 | Metadata size | 1024 bytes | 1024 bytes |
 | Value size | 25 MiB | 25 MiB |
 | Minimum cacheTtl | 60 seconds | 60 seconds |
 **Critical**: 1 write/second per key (429 if exceeded), bulk operations count as 1 operation, namespace limit increased from 200 → 1,000 (Jan 2025)
 ---
 ## Error Handling
 ### 1. Rate Limit (429 Too Many Requests)
 **Cause**: Writing to same key >1/second
 **Solution**: Use retry with exponential backoff (see Advanced Patterns)
 ```typescript
 // ❌ Bad
 await env.MY_KV.put('counter', '1');
 await env.MY_KV.put('counter', '2'); // 429 error!
 // ✅ Good
 await putWithRetry(env.MY_KV, 'counter', '2');
 ```
 ### 2. Value Too Large
 **Cause**: Value exceeds 25 MiB
 **Solution**: Validate size before writing
 ```typescript
 if (value.length > 25 * 1024 * 1024) throw new Error('Value exceeds 25 MiB');
 ```
 ### 3. Metadata Too Large
 **Cause**: Metadata exceeds 1024 bytes when serialized
 **Solution**: Validate serialized size
 ```typescript
 const serialized = JSON.stringify(metadata);
 if (serialized.length > 1024) throw new Error('Metadata exceeds 1024 bytes');
 ```
 ### 4. Invalid CacheTtl
 **Cause**: cacheTtl <60 seconds
 **Solution**: Use minimum 60
 ```typescript
 // ❌ Error
 await env.MY_KV.get('key', { cacheTtl: 30 });
 // ✅ Correct
 await env.MY_KV.get('key', { cacheTtl: 60 });
 ```
 ---
 ## Critical Rules
 ### Always Do ✅
 1. Use bulk operations when reading multiple keys (counts as 1 operation)
 2. Set cacheTtl for frequently-read, infrequently-updated data (min 60s)
 3. Store small values (<1024 bytes) in metadata when using `list()` frequently
 4. Check `list_complete` when paginating, not `keys.length === 0`
 5. Use retry logic with exponential backoff for write operations
 6. Validate sizes before writing (key 512B, value 25MiB, metadata 1KB)
 7. Coalesce related keys for better caching performance
 8. Use KV for read-heavy workloads (100:1 read/write ratio ideal)
 ### Never Do ❌
 1. Never write to same key >1/second (causes 429 rate limit errors)
 2. Never assume immediate global consistency (takes ~60 seconds to propagate)
 3. Never use KV for atomic operations (use Durable Objects instead)
 4. Never set cacheTtl <60 seconds (will fail)
 5. Never commit namespace IDs to public repos (use environment variables)
 6. Never exceed 1000 operations per invocation (use bulk operations)
 7. Never rely on write order (eventual consistency = no guarantees)
 8. Never forget to handle null values (`get()` returns `null` if key doesn't exist)
 ---
 ## Troubleshooting
 ### Issue 1: "429 Too Many Requests" on writes
 **Cause**: Writing to same key >1/second
 **Solution**: Consolidate writes or use retry with exponential backoff
 ```typescript
 // ❌ Bad: Rate limit
 for (let i = 0; i < 10; i++) await kv.put('counter', String(i));
 // ✅ Good: Single write
 await kv.put('counter', '9');
 // ✅ Good: Retry with backoff
 await putWithRetry(kv, 'counter', String(i));
 ```
 ### Issue 2: Stale reads after write
 **Cause**: Eventual consistency (~60 seconds propagation)
 **Solution**: Accept stale reads, use Durable Objects for strong consistency, or implement app-level cache invalidation
 ### Issue 3: "Operations limit exceeded"
 **Cause**: >1000 KV operations in single Worker invocation
 **Solution**: Use bulk operations
 ```typescript
 // ❌ Bad: 5000 operations
 for (const key of 5000keys) await kv.get(key);
 // ✅ Good: 1 operation
 const values = await kv.get(keys);  // Bulk read
 ```
 ### Issue 4: List returns empty but cursor exists
 **Cause**: Deleted/expired keys create "tombstones"
 **Solution**: Always check `list_complete`, not `keys.length`
 ```typescript
 // ✅ Correct pagination
 let cursor: string | undefined;
 do {
  const result = await kv.list({ cursor });
  processKeys(result.keys);  // Even if empty
  cursor = result.list_complete ? undefined : result.cursor;
 } while (cursor);
 ```
 ---
 ## Production Checklist
 - [ ] Environment-specific namespaces configured (`id` vs `preview_id`)
 - [ ] Namespace IDs stored in environment variables (not hardcoded)
 - [ ] Rate limit retry logic implemented for writes
 - [ ] Appropriate `cacheTtl` values set for reads (min 60s)
 - [ ] Sizes validated (key 512B, value 25MiB, metadata 1KB)
 - [ ] Bulk operations used where possible
 - [ ] Pagination with `list_complete` check (not `keys.length`)
 - [ ] Error handling for null values
 - [ ] Monitoring/alerting for rate limits
 ---
 ## Related Documentation
 - [Cloudflare KV Docs](https://developers.cloudflare.com/kv/)
 - [KV API Reference](https://developers.cloudflare.com/kv/api/)
 - [KV Limits](https://developers.cloudflare.com/kv/platform/limits/)
 - [How KV Works](https://developers.cloudflare.com/kv/concepts/how-kv-works/)
 - [Wrangler KV Commands](https://developers.cloudflare.com/workers/wrangler/commands/#kv)
 ---
 **Last Updated**: 2025-11-24
 **Package Versions**: wrangler@4.50.0, @cloudflare/workers-types@4.20251121.0
--- a/plugin.lock.json
+++ b/plugin.lock.json
@@ -0,0 +1,73 @@
 {
  "$schema": "internal://schemas/plugin.lock.v1.json",
  "pluginId": "gh:jezweb/claude-skills:skills/cloudflare-kv",
  "normalized": {
    "repo": null,
    "ref": "refs/tags/v20251128.0",
    "commit": "ce8453586663e42be92dc68ac0d9688e1b5f3bca",
    "treeHash": "91ed0423c52d84b688f4dbc23f5e35d4906098a8c19ee220485da4e066ebf4aa",
    "generatedAt": "2025-11-28T10:18:56.373969Z",
    "toolVersion": "publish_plugins.py@0.2.0"
  },
  "origin": {
    "remote": "git@github.com:zhongweili/42plugin-data.git",
    "branch": "master",
    "commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390",
    "repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data"
  },
  "manifest": {
    "name": "cloudflare-kv",
    "description": "Store key-value data globally with Cloudflare KVs edge network. Use when: caching API responses, storing configuration, managing user preferences, handling TTL expiration, or troubleshooting KV_ERROR, 429 rate limits, eventual consistency, or cacheTtl errors.",
    "version": "1.0.0"
  },
  "content": {
    "files": [
      {
        "path": "README.md",
        "sha256": "d2d5798f1e8aecce1df20b5de0992ccb2c942ff8740492203842fa5296d8c214"
      },
      {
        "path": "SKILL.md",
        "sha256": "0bbb7062c7baae72de902f85520d307f996d65c6a11be9a4b45014b0f3534e17"
      },
      {
        "path": "references/best-practices.md",
        "sha256": "0adc9505c4d050e21db41917daaa7e9bfa37b6c558c0a910056045938aa45f58"
      },
      {
        "path": "references/workers-api.md",
        "sha256": "d3283b7c8395c3eb22936522185aa08ef1948802c3501a1532c68475aa819974"
      },
      {
        "path": ".claude-plugin/plugin.json",
        "sha256": "858fd909ff72e8b3013fa0de105b29ebee5ae2526c336d950d6880060653f62d"
      },
      {
        "path": "templates/wrangler-kv-config.jsonc",
        "sha256": "52694be4cfd90f6e2d5501d0da0e2910e2b041b5c8b86140e08020e9a6fc5131"
      },
      {
        "path": "templates/kv-metadata-pattern.ts",
        "sha256": "fbb3377064dc79b52a93ebd8ea6fdced88bc179981d62c985c3eb13c1e89c480"
      },
      {
        "path": "templates/kv-list-pagination.ts",
        "sha256": "9efca329c0a35a7b47acd4671245b46191c9413d2d80286408404acdfa226e0a"
      },
      {
        "path": "templates/kv-basic-operations.ts",
        "sha256": "850dd2be4f78ae2fac9057bf44424a7b94202c91ba2b789b73e65c8a3f67f798"
      },
      {
        "path": "templates/kv-caching-pattern.ts",
        "sha256": "1e16eb83f3e355b2e5c5f90ef470d9c7433fde3d1cc1d8d015073491d9fc459f"
      }
    ],
    "dirSha256": "91ed0423c52d84b688f4dbc23f5e35d4906098a8c19ee220485da4e066ebf4aa"
  },
  "security": {
    "scannedAt": null,
    "scannerVersion": null,
    "flags": []
  }
 }
--- a/references/best-practices.md
+++ b/references/best-practices.md
@@ -0,0 +1,720 @@
 # Cloudflare Workers KV - Best Practices
 This document contains production-tested best practices for Cloudflare Workers KV.
 ---
 ## Table of Contents
 1. [Performance Optimization](#performance-optimization)
 2. [Caching Strategies](#caching-strategies)
 3. [Key Design](#key-design)
 4. [Metadata Usage](#metadata-usage)
 5. [Error Handling](#error-handling)
 6. [Security](#security)
 7. [Cost Optimization](#cost-optimization)
 8. [Monitoring & Debugging](#monitoring--debugging)
 ---
 ## Performance Optimization
 ### 1. Use Bulk Operations
 **❌ Bad: Individual reads**
 ```typescript
 const value1 = await kv.get('key1'); // 1 operation
 const value2 = await kv.get('key2'); // 1 operation
 const value3 = await kv.get('key3'); // 1 operation
 // Total: 3 operations
 ```
 **✅ Good: Bulk read**
 ```typescript
 const values = await kv.get(['key1', 'key2', 'key3']); // 1 operation
 // Total: 1 operation
 ```
 **Benefits:**
 - Counts as 1 operation against the 1000/invocation limit
 - Faster execution
 - Lower latency
 ---
 ### 2. Use CacheTtl for Frequently-Read Data
 **❌ Bad: No edge caching**
 ```typescript
 const value = await kv.get('config'); // Fetches from KV every time
 ```
 **✅ Good: Edge caching**
 ```typescript
 const value = await kv.get('config', {
  cacheTtl: 300, // Cache at edge for 5 minutes
 });
 ```
 **Guidelines:**
 - Use `cacheTtl` for data that changes infrequently
 - Minimum: 60 seconds
 - Typical values:
  - Configuration: 300-600 seconds (5-10 minutes)
  - Static content: 3600+ seconds (1+ hour)
  - Frequently changing: 60-120 seconds
 **Trade-off:** Higher `cacheTtl` = faster reads but slower updates propagate
 ---
 ### 3. Coalesce Related Keys
 **❌ Bad: Many small keys**
 ```typescript
 await kv.put('user:123:name', 'John');
 await kv.put('user:123:email', 'john@example.com');
 await kv.put('user:123:age', '30');
 // Reading requires 3 operations
 const name = await kv.get('user:123:name');
 const email = await kv.get('user:123:email');
 const age = await kv.get('user:123:age');
 ```
 **✅ Good: Coalesced key**
 ```typescript
 await kv.put('user:123', JSON.stringify({
  name: 'John',
  email: 'john@example.com',
  age: 30,
 }));
 // Reading requires 1 operation
 const user = await kv.get<User>('user:123', { type: 'json' });
 ```
 **Benefits:**
 - Fewer operations
 - Single cache entry
 - Faster reads
 **When to use:**
 - Related data that's always accessed together
 - Data that doesn't update frequently
 - Values stay under 25 MiB total
 ---
 ### 4. Store Small Values in Metadata
 **❌ Bad: Separate keys for metadata**
 ```typescript
 await kv.put('user:123', 'data');
 await kv.put('user:123:status', 'active');
 // List requires additional get() calls
 const users = await kv.list({ prefix: 'user:' });
 for (const key of users.keys) {
  const status = await kv.get(`${key.name}:status`); // Extra operation!
 }
 ```
 **✅ Good: Metadata pattern**
 ```typescript
 await kv.put('user:123', 'data', {
  metadata: { status: 'active', plan: 'pro' },
 });
 // List includes metadata, no extra get() calls!
 const users = await kv.list({ prefix: 'user:' });
 for (const key of users.keys) {
  console.log(key.name, key.metadata.status); // No extra operations
 }
 ```
 **When to use:**
 - Values fit in 1024 bytes
 - Frequently use `list()` operations
 - Need to filter/process many keys
 ---
 ## Caching Strategies
 ### 1. Cache-Aside Pattern (Read-Through)
 ```typescript
 async function getCached<T>(
  kv: KVNamespace,
  key: string,
  fetchFn: () => Promise<T>,
  ttl = 3600
 ): Promise<T> {
  // Try cache
  const cached = await kv.get<T>(key, {
    type: 'json',
    cacheTtl: 300,
  });
  if (cached !== null) return cached;
  // Cache miss - fetch and store
  const data = await fetchFn();
  await kv.put(key, JSON.stringify(data), { expirationTtl: ttl });
  return data;
 }
 ```
 **Use when:**
 - Data is expensive to compute/fetch
 - Read >> Write ratio
 - Acceptable to serve slightly stale data
 ---
 ### 2. Write-Through Cache
 ```typescript
 async function updateCached<T>(
  kv: KVNamespace,
  key: string,
  data: T,
  ttl = 3600
 ): Promise<void> {
  // Update database
  await database.update(data);
  // Update cache immediately
  await kv.put(key, JSON.stringify(data), { expirationTtl: ttl });
 }
 ```
 **Use when:**
 - Need cache consistency
 - Write operations are infrequent
 - Cache must always reflect latest data
 ---
 ### 3. Stale-While-Revalidate
 ```typescript
 async function staleWhileRevalidate<T>(
  kv: KVNamespace,
  key: string,
  fetchFn: () => Promise<T>,
  ctx: ExecutionContext,
  staleThreshold = 300
 ): Promise<T> {
  const { value, metadata } = await kv.getWithMetadata<T, { timestamp: number }>(
    key,
    { type: 'json' }
  );
  if (value !== null && metadata) {
    const age = Date.now() - metadata.timestamp;
    // Refresh in background if stale
    if (age > staleThreshold * 1000) {
      ctx.waitUntil(
        (async () => {
          const fresh = await fetchFn();
          await kv.put(key, JSON.stringify(fresh), {
            metadata: { timestamp: Date.now() },
          });
        })()
      );
    }
    return value;
  }
  // Cache miss
  const data = await fetchFn();
  await kv.put(key, JSON.stringify(data), {
    metadata: { timestamp: Date.now() },
  });
  return data;
 }
 ```
 **Use when:**
 - Fast response time is critical
 - Acceptable to serve slightly stale data
 - Background refresh is acceptable
 ---
 ## Key Design
 ### 1. Use Hierarchical Namespaces
 **✅ Good key patterns:**
 ```
 user:123:profile
 user:123:settings
 user:123:sessions
 session:abc123:data
 session:abc123:metadata
 cache:api:users:list
 cache:api:posts:123
 cache:db:query:hash123
 ```
 **Benefits:**
 - Easy to filter with `list({ prefix: 'user:123:' })`
 - Easy to invalidate groups
 - Clear organization
 ---
 ### 2. Use Lexicographic Ordering
 Keys are always sorted lexicographically, so design keys to take advantage:
 ```typescript
 // Date-based keys (ISO format sorts correctly)
 'log:2025-10-21:entry1'
 'log:2025-10-22:entry1'
 // Numeric IDs (zero-padded)
 'user:00000001'
 'user:00000123'
 'user:00001000'
 // Priority-based (prefix with number)
 'task:1:high-priority'
 'task:2:medium-priority'
 'task:3:low-priority'
 ```
 ---
 ### 3. Avoid Key Collisions
 **❌ Bad:**
 ```
 user:123        // User data
 user:123:count  // Some counter
 user:123        // Different data? Collision!
 ```
 **✅ Good:**
 ```
 user:data:123
 user:counter:123
 user:session:123
 ```
 ---
 ## Metadata Usage
 ### 1. Track Versions
 ```typescript
 await kv.put('config', JSON.stringify(data), {
  metadata: {
    version: 2,
    updatedAt: Date.now(),
    updatedBy: 'admin',
  },
 });
 ```
 ---
 ### 2. Audit Trails
 ```typescript
 await kv.put(key, value, {
  metadata: {
    createdAt: Date.now(),
    createdBy: userId,
    accessCount: 0,
  },
 });
 ```
 ---
 ### 3. Feature Flags
 ```typescript
 // Store flags in metadata for fast list() access
 await kv.put(`flag:${name}`, JSON.stringify(config), {
  metadata: {
    enabled: true,
    rolloutPercentage: 50,
  },
 });
 // List all flags without additional get() calls
 const flags = await kv.list({ prefix: 'flag:' });
 ```
 ---
 ## Error Handling
 ### 1. Handle Rate Limits (429)
 ```typescript
 async function putWithRetry(
  kv: KVNamespace,
  key: string,
  value: string,
  maxAttempts = 5
 ): Promise<void> {
  let attempts = 0;
  let delay = 1000;
  while (attempts < maxAttempts) {
    try {
      await kv.put(key, value);
      return;
    } catch (error) {
      const message = (error as Error).message;
      if (message.includes('429') || message.includes('Too Many Requests')) {
        attempts++;
        if (attempts >= maxAttempts) {
          throw new Error('Max retry attempts reached');
        }
        await new Promise(resolve => setTimeout(resolve, delay));
        delay *= 2; // Exponential backoff
      } else {
        throw error;
      }
    }
  }
 }
 ```
 ---
 ### 2. Handle Null Values
 ```typescript
 // ❌ Bad
 const value = await kv.get('key');
 console.log(value.toUpperCase()); // Error if key doesn't exist
 // ✅ Good
 const value = await kv.get('key');
 if (value !== null) {
  console.log(value.toUpperCase());
 }
 // ✅ Good: Default value
 const value = await kv.get('key') ?? 'default';
 ```
 ---
 ### 3. Validate Input Sizes
 ```typescript
 function validateKVInput(key: string, value: string, metadata?: any): void {
  // Key size
  if (new TextEncoder().encode(key).length > 512) {
    throw new Error('Key exceeds 512 bytes');
  }
  // Value size
  if (new TextEncoder().encode(value).length > 25 * 1024 * 1024) {
    throw new Error('Value exceeds 25 MiB');
  }
  // Metadata size
  if (metadata) {
    const serialized = JSON.stringify(metadata);
    if (new TextEncoder().encode(serialized).length > 1024) {
      throw new Error('Metadata exceeds 1024 bytes');
    }
  }
 }
 ```
 ---
 ## Security
 ### 1. Never Commit Namespace IDs
 **❌ Bad:**
 ```jsonc
 {
  "kv_namespaces": [
    {
      "binding": "MY_KV",
      "id": "abc123def456..." // Hardcoded!
    }
  ]
 }
 ```
 **✅ Good:**
 ```jsonc
 {
  "kv_namespaces": [
    {
      "binding": "MY_KV",
      "id": "${KV_NAMESPACE_ID}" // Environment variable
    }
  ]
 }
 ```
 ---
 ### 2. Encrypt Sensitive Data
 ```typescript
 // Encrypt before storing
 const encrypted = await encrypt(sensitiveData, encryptionKey);
 await kv.put('sensitive:123', encrypted);
 // Decrypt after reading
 const encrypted = await kv.get('sensitive:123');
 const decrypted = await decrypt(encrypted, encryptionKey);
 ```
 ---
 ### 3. Use Separate Namespaces for Environments
 ```jsonc
 {
  "kv_namespaces": [
    {
      "binding": "MY_KV",
      "id": "production-namespace-id",
      "preview_id": "development-namespace-id"
    }
  ]
 }
 ```
 ---
 ## Cost Optimization
 ### 1. Minimize Write Operations (Free Tier)
 **Free tier limits:**
 - 1,000 writes per day
 - 100,000 reads per day
 **Strategies:**
 - Batch writes when possible
 - Use longer TTLs to reduce rewrites
 - Cache data in memory if accessed frequently within same invocation
 ---
 ### 2. Use Metadata Instead of Separate Keys
 **❌ Expensive: 3 writes, 3 reads**
 ```typescript
 await kv.put('user:123:status', 'active');
 await kv.put('user:123:plan', 'pro');
 await kv.put('user:123:updated', Date.now().toString());
 ```
 **✅ Cheaper: 1 write, 1 read**
 ```typescript
 await kv.put('user:123', '', {
  metadata: { status: 'active', plan: 'pro', updated: Date.now() },
 });
 ```
 ---
 ### 3. Set Appropriate TTLs
 Longer TTLs = fewer rewrites = lower costs
 ```typescript
 // ❌ Expensive: Rewrites every minute
 await kv.put('cache:data', data, { expirationTtl: 60 });
 // ✅ Better: Rewrites every hour
 await kv.put('cache:data', data, { expirationTtl: 3600 });
 ```
 ---
 ## Monitoring & Debugging
 ### 1. Track Cache Hit Rates
 ```typescript
 let stats = { hits: 0, misses: 0 };
 async function getCached<T>(kv: KVNamespace, key: string): Promise<T | null> {
  const value = await kv.get<T>(key, { type: 'json' });
  if (value !== null) {
    stats.hits++;
  } else {
    stats.misses++;
  }
  return value;
 }
 // View stats
 app.get('/stats', (c) => {
  const total = stats.hits + stats.misses;
  const hitRate = total > 0 ? (stats.hits / total) * 100 : 0;
  return c.json({
    hits: stats.hits,
    misses: stats.misses,
    hitRate: `${hitRate.toFixed(2)}%`,
  });
 });
 ```
 ---
 ### 2. Log KV Operations
 ```typescript
 async function loggedGet<T>(
  kv: KVNamespace,
  key: string
 ): Promise<T | null> {
  const start = Date.now();
  const value = await kv.get<T>(key, { type: 'json' });
  const duration = Date.now() - start;
  console.log({
    operation: 'get',
    key,
    found: value !== null,
    duration,
  });
  return value;
 }
 ```
 ---
 ### 3. Use Namespace Prefixes for Testing
 ```typescript
 const namespace = env.ENVIRONMENT === 'production' ? 'prod' : 'test';
 await kv.put(`${namespace}:user:123`, data);
 // Cleanup test data
 if (env.ENVIRONMENT === 'test') {
  // Delete all test: keys
  let cursor: string | undefined;
  do {
    const result = await kv.list({ prefix: 'test:', cursor });
    await Promise.all(result.keys.map(k => kv.delete(k.name)));
    cursor = result.list_complete ? undefined : result.cursor;
  } while (cursor);
 }
 ```
 ---
 ## Production Checklist
 Before deploying to production:
 - [ ] Environment-specific namespaces configured
 - [ ] Namespace IDs stored in environment variables
 - [ ] Rate limit retry logic implemented
 - [ ] Appropriate `cacheTtl` values set
 - [ ] Input validation for key/value/metadata sizes
 - [ ] Bulk operations used where possible
 - [ ] Pagination implemented correctly for `list()`
 - [ ] Error handling for null values
 - [ ] Monitoring/alerting for rate limits
 - [ ] Documentation for eventual consistency behavior
 - [ ] Security review for sensitive data
 - [ ] Cost analysis for expected usage
 ---
 ## Common Patterns
 ### 1. Session Management
 ```typescript
 // Store session
 await kv.put(`session:${sessionId}`, JSON.stringify(sessionData), {
  expirationTtl: 3600, // 1 hour
  metadata: { userId, createdAt: Date.now() },
 });
 // Read session
 const session = await kv.get<SessionData>(`session:${sessionId}`, {
  type: 'json',
  cacheTtl: 60, // Cache for 1 minute
 });
 ```
 ---
 ### 2. API Response Caching
 ```typescript
 const cacheKey = `api:${endpoint}:${JSON.stringify(params)}`;
 let response = await kv.get<ApiResponse>(cacheKey, {
  type: 'json',
  cacheTtl: 300,
 });
 if (!response) {
  response = await fetchFromAPI(endpoint, params);
  await kv.put(cacheKey, JSON.stringify(response), {
    expirationTtl: 600,
  });
 }
 return response;
 ```
 ---
 ### 3. Configuration Management
 ```typescript
 // Update config
 await kv.put('config:app', JSON.stringify(config), {
  metadata: {
    version: 2,
    updatedAt: Date.now(),
    updatedBy: adminId,
  },
 });
 // Read config (with long cache)
 const config = await kv.get<AppConfig>('config:app', {
  type: 'json',
  cacheTtl: 3600, // Cache for 1 hour
 });
 ```
 ---
 ## References
 - [Cloudflare KV Documentation](https://developers.cloudflare.com/kv/)
 - [How KV Works](https://developers.cloudflare.com/kv/concepts/how-kv-works/)
 - [KV Limits](https://developers.cloudflare.com/kv/platform/limits/)
 - [KV Pricing](https://developers.cloudflare.com/kv/platform/pricing/)
--- a/references/workers-api.md
+++ b/references/workers-api.md
@@ -0,0 +1,483 @@
 # Cloudflare Workers KV - Complete API Reference
 This document provides the complete Workers KV API reference based on official Cloudflare documentation.
 ---
 ## KVNamespace Interface
 ```typescript
 interface KVNamespace {
  get(key: string, options?: Partial<KVGetOptions<undefined>>): Promise<string | null>;
  get(key: string, type: "text"): Promise<string | null>;
  get<ExpectedValue = unknown>(key: string, type: "json"): Promise<ExpectedValue | null>;
  get(key: string, type: "arrayBuffer"): Promise<ArrayBuffer | null>;
  get(key: string, type: "stream"): Promise<ReadableStream | null>;
  get(keys: string[]): Promise<Map<string, string | null>>;
  get<ExpectedValue = unknown>(keys: string[], type: "json"): Promise<Map<string, ExpectedValue | null>>;
  getWithMetadata<Metadata = unknown>(key: string, options?: Partial<KVGetOptions<undefined>>): Promise<KVGetWithMetadataResult<string, Metadata>>;
  getWithMetadata<ExpectedValue = unknown, Metadata = unknown>(key: string, type: "json"): Promise<KVGetWithMetadataResult<ExpectedValue, Metadata>>;
  getWithMetadata<Metadata = unknown>(keys: string[]): Promise<Map<string, KVGetWithMetadataResult<string, Metadata>>>;
  put(key: string, value: string | ArrayBuffer | ArrayBufferView | ReadableStream, options?: KVPutOptions): Promise<void>;
  delete(key: string): Promise<void>;
  list<Metadata = unknown>(options?: KVListOptions): Promise<KVListResult<Metadata>>;
 }
 ```
 ---
 ## Read Operations
 ### `get()` - Single Key
 Read a single key-value pair.
 **Signature:**
 ```typescript
 get(key: string, options?: KVGetOptions): Promise<T | null>
 ```
 **Parameters:**
 - `key` (string, required) - The key to read
 - `options` (object, optional):
  - `type` - Return type: `"text"` (default), `"json"`, `"arrayBuffer"`, `"stream"`
  - `cacheTtl` (number) - Edge cache duration in seconds (minimum: 60)
 **Returns:**
 - `Promise<T | null>` - Value or `null` if key doesn't exist
 **Examples:**
 ```typescript
 // Text (default)
 const value = await env.MY_KV.get('my-key');
 // JSON
 const data = await env.MY_KV.get<MyType>('my-key', { type: 'json' });
 // With cache optimization
 const value = await env.MY_KV.get('my-key', {
  type: 'text',
  cacheTtl: 300, // Cache for 5 minutes
 });
 // ArrayBuffer
 const buffer = await env.MY_KV.get('binary-key', { type: 'arrayBuffer' });
 // Stream (for large values)
 const stream = await env.MY_KV.get('large-file', { type: 'stream' });
 ```
 ---
 ### `get()` - Multiple Keys (Bulk)
 Read multiple keys in a single operation.
 **Signature:**
 ```typescript
 get(keys: string[], type?: 'text' | 'json'): Promise<Map<string, T | null>>
 ```
 **Parameters:**
 - `keys` (string[], required) - Array of keys to read
 - `type` (optional) - Return type: `"text"` (default) or `"json"`
 **Returns:**
 - `Promise<Map<string, T | null>>` - Map of key-value pairs
 **Important:**
 - Counts as **1 operation** regardless of number of keys
 - Only supports `text` and `json` types (not `arrayBuffer` or `stream`)
 - For binary/stream types, use individual `get()` calls with `Promise.all()`
 **Examples:**
 ```typescript
 // Read multiple keys
 const keys = ['key1', 'key2', 'key3'];
 const values = await env.MY_KV.get(keys);
 // Access values
 const value1 = values.get('key1');
 const value2 = values.get('key2');
 // Convert to object
 const obj = Object.fromEntries(values);
 // Read as JSON
 const values = await env.MY_KV.get<MyType>(keys, 'json');
 ```
 ---
 ### `getWithMetadata()` - Single Key
 Read key-value pair with metadata.
 **Signature:**
 ```typescript
 getWithMetadata<Value, Metadata>(
  key: string,
  options?: KVGetOptions
 ): Promise<KVGetWithMetadataResult<Value, Metadata>>
 ```
 **Parameters:**
 - Same as `get()`
 **Returns:**
 ```typescript
 {
  value: Value | null,
  metadata: Metadata | null
 }
 ```
 **Examples:**
 ```typescript
 // Get with metadata
 const { value, metadata } = await env.MY_KV.getWithMetadata('my-key');
 // Get as JSON with metadata
 const { value, metadata } = await env.MY_KV.getWithMetadata<MyType>('my-key', {
  type: 'json',
  cacheTtl: 300,
 });
 if (value !== null) {
  console.log('Value:', value);
  console.log('Metadata:', metadata);
 }
 ```
 ---
 ### `getWithMetadata()` - Multiple Keys (Bulk)
 Read multiple keys with metadata.
 **Signature:**
 ```typescript
 getWithMetadata<Metadata>(
  keys: string[],
  type?: 'text' | 'json'
 ): Promise<Map<string, KVGetWithMetadataResult<T, Metadata>>>
 ```
 **Examples:**
 ```typescript
 const keys = ['key1', 'key2'];
 const results = await env.MY_KV.getWithMetadata(keys);
 for (const [key, data] of results) {
  console.log(key, data.value, data.metadata);
 }
 ```
 ---
 ## Write Operations
 ### `put()` - Write Key-Value Pair
 Write or update a key-value pair.
 **Signature:**
 ```typescript
 put(
  key: string,
  value: string | ArrayBuffer | ArrayBufferView | ReadableStream,
  options?: KVPutOptions
 ): Promise<void>
 ```
 **Parameters:**
 - `key` (string, required) - Maximum 512 bytes
 - `value` (required) - Maximum 25 MiB
 - `options` (object, optional):
  - `expiration` (number) - Absolute expiration time (seconds since epoch)
  - `expirationTtl` (number) - TTL in seconds from now (minimum: 60)
  - `metadata` (any) - JSON-serializable metadata (maximum: 1024 bytes)
 **Returns:**
 - `Promise<void>`
 **Examples:**
 ```typescript
 // Simple write
 await env.MY_KV.put('key', 'value');
 // Write JSON
 await env.MY_KV.put('user:123', JSON.stringify({ name: 'John' }));
 // Write with TTL
 await env.MY_KV.put('session', sessionData, {
  expirationTtl: 3600, // Expire in 1 hour
 });
 // Write with absolute expiration
 const expirationTime = Math.floor(Date.now() / 1000) + 86400; // 24 hours
 await env.MY_KV.put('token', tokenValue, {
  expiration: expirationTime,
 });
 // Write with metadata
 await env.MY_KV.put('config', configData, {
  metadata: {
    updatedAt: Date.now(),
    updatedBy: 'admin',
    version: 2,
  },
 });
 // Write with everything
 await env.MY_KV.put('key', 'value', {
  expirationTtl: 600,
  metadata: { source: 'api' },
 });
 ```
 **Limits:**
 - **Key size**: Maximum 512 bytes
 - **Value size**: Maximum 25 MiB
 - **Metadata size**: Maximum 1024 bytes (JSON serialized)
 - **Write rate**: Maximum **1 write per second per key**
 - **Expiration minimum**: 60 seconds
 ---
 ## Delete Operations
 ### `delete()` - Delete Key
 Delete a key-value pair.
 **Signature:**
 ```typescript
 delete(key: string): Promise<void>
 ```
 **Parameters:**
 - `key` (string, required) - Key to delete
 **Returns:**
 - `Promise<void>` - Always succeeds, even if key doesn't exist
 **Examples:**
 ```typescript
 // Delete single key
 await env.MY_KV.delete('my-key');
 // Delete multiple keys
 const keys = ['key1', 'key2', 'key3'];
 await Promise.all(keys.map(key => env.MY_KV.delete(key)));
 ```
 **Note:** For bulk delete of >10,000 keys, use the REST API.
 ---
 ## List Operations
 ### `list()` - List Keys
 List keys in the namespace.
 **Signature:**
 ```typescript
 list<Metadata>(options?: KVListOptions): Promise<KVListResult<Metadata>>
 ```
 **Parameters:**
 ```typescript
 interface KVListOptions {
  prefix?: string;  // Filter keys by prefix
  limit?: number;   // Max keys to return (default: 1000, max: 1000)
  cursor?: string;  // Pagination cursor
 }
 ```
 **Returns:**
 ```typescript
 interface KVListResult<Metadata> {
  keys: {
    name: string;
    expiration?: number;  // Seconds since epoch
    metadata?: Metadata;
  }[];
  list_complete: boolean;  // true if no more keys
  cursor?: string;         // Use for next page
 }
 ```
 **Examples:**
 ```typescript
 // List all keys (up to 1000)
 const result = await env.MY_KV.list();
 // List with prefix
 const users = await env.MY_KV.list({ prefix: 'user:' });
 // List with limit
 const recent = await env.MY_KV.list({ limit: 100 });
 // Pagination
 let cursor: string | undefined;
 do {
  const result = await env.MY_KV.list({ cursor });
  // Process keys
  console.log(result.keys);
  cursor = result.list_complete ? undefined : result.cursor;
 } while (cursor);
 ```
 **Important:**
 - Keys are **always** sorted lexicographically (UTF-8)
 - **Always check `list_complete`**, not `keys.length === 0`
 - Empty `keys` array doesn't mean no more data (tombstones exist)
 - When paginating with `prefix`, pass `prefix` with each cursor request
 ---
 ## Type Definitions
 ### KVGetOptions
 ```typescript
 interface KVGetOptions<Type> {
  type: Type;        // "text" | "json" | "arrayBuffer" | "stream"
  cacheTtl?: number; // Edge cache duration (minimum: 60 seconds)
 }
 ```
 ### KVPutOptions
 ```typescript
 interface KVPutOptions {
  expiration?: number;     // Seconds since epoch
  expirationTtl?: number;  // Seconds from now (minimum: 60)
  metadata?: any;          // Max 1024 bytes serialized
 }
 ```
 ### KVGetWithMetadataResult
 ```typescript
 interface KVGetWithMetadataResult<Value, Metadata> {
  value: Value | null;
  metadata: Metadata | null;
 }
 ```
 ### KVListOptions
 ```typescript
 interface KVListOptions {
  prefix?: string;
  limit?: number;   // Default: 1000, max: 1000
  cursor?: string;
 }
 ```
 ### KVListResult
 ```typescript
 interface KVListResult<Metadata = unknown> {
  keys: {
    name: string;
    expiration?: number;
    metadata?: Metadata;
  }[];
  list_complete: boolean;
  cursor?: string;
 }
 ```
 ---
 ## Limits
 | Feature | Limit |
 |---------|-------|
 | Key size | 512 bytes |
 | Value size | 25 MiB |
 | Metadata size | 1024 bytes (JSON) |
 | Writes per key per second | 1 |
 | Operations per Worker invocation | 1,000 |
 | List limit | 1,000 keys |
 | Minimum cacheTtl | 60 seconds |
 | Minimum expiration | 60 seconds |
 | Namespaces per account (Free) | 1,000 |
 | Namespaces per account (Paid) | 1,000 |
 | Storage per account (Free) | 1 GB |
 | Storage per account (Paid) | Unlimited |
 | Read operations per day (Free) | 100,000 |
 | Read operations per day (Paid) | Unlimited |
 | Write operations per day (Free) | 1,000 |
 | Write operations per day (Paid) | Unlimited |
 ---
 ## Consistency Model
 ### Eventually Consistent
 - Writes are **immediately visible** in the same location
 - Writes take **up to 60 seconds** to propagate globally
 - Cached reads may return stale data during propagation
 ### Implications
 ```typescript
 // Tokyo datacenter
 await env.KV.put('counter', '1');
 const value1 = await env.KV.get('counter'); // "1" ✅
 // London datacenter (within 60 seconds)
 const value2 = await env.KV.get('counter'); // Might be old value ⚠️
 // After 60+ seconds globally
 const value3 = await env.KV.get('counter'); // "1" ✅
 ```
 **For strong consistency, use [Durable Objects](https://developers.cloudflare.com/durable-objects/).**
 ---
 ## Error Handling
 ### Common Errors
 1. **429 Too Many Requests**
   - Cause: >1 write/second to same key
   - Solution: Implement retry with exponential backoff
 2. **Value too large**
   - Cause: Value >25 MiB
   - Solution: Validate size before writing
 3. **Metadata too large**
   - Cause: Metadata >1024 bytes serialized
   - Solution: Validate JSON size before writing
 4. **Invalid cacheTtl**
   - Cause: cacheTtl <60 seconds
   - Solution: Use minimum 60 seconds
 5. **Operations limit exceeded**
   - Cause: >1000 KV operations in Worker invocation
   - Solution: Use bulk operations
 ---
 ## References
 - [Official KV Documentation](https://developers.cloudflare.com/kv/)
 - [KV API Reference](https://developers.cloudflare.com/kv/api/)
 - [KV Limits](https://developers.cloudflare.com/kv/platform/limits/)
 - [How KV Works](https://developers.cloudflare.com/kv/concepts/how-kv-works/)
--- a/templates/kv-basic-operations.ts
+++ b/templates/kv-basic-operations.ts
@@ -0,0 +1,538 @@
 /**
 * Cloudflare Workers KV - Basic CRUD Operations
 *
 * This template demonstrates all basic KV operations:
 * - Create (PUT)
 * - Read (GET)
 * - Update (PUT)
 * - Delete (DELETE)
 * - List keys
 * - Metadata handling
 * - TTL/Expiration
 * - Error handling
 */
 import { Hono } from 'hono';
 type Bindings = {
  MY_KV: KVNamespace;
 };
 const app = new Hono<{ Bindings: Bindings }>();
 // ============================================================================
 // CREATE / UPDATE - Write key-value pairs
 // ============================================================================
 // Simple write
 app.put('/kv/:key', async (c) => {
  const key = c.req.param('key');
  const value = await c.req.text();
  try {
    await c.env.MY_KV.put(key, value);
    return c.json({
      success: true,
      message: `Key "${key}" created/updated`,
    });
  } catch (error) {
    return c.json(
      {
        success: false,
        error: (error as Error).message,
      },
      500
    );
  }
 });
 // Write with TTL expiration
 app.put('/kv/:key/ttl/:seconds', async (c) => {
  const key = c.req.param('key');
  const ttl = parseInt(c.req.param('seconds'), 10);
  const value = await c.req.text();
  // Validate TTL (minimum 60 seconds)
  if (ttl < 60) {
    return c.json(
      {
        success: false,
        error: 'TTL must be at least 60 seconds',
      },
      400
    );
  }
  try {
    await c.env.MY_KV.put(key, value, {
      expirationTtl: ttl,
    });
    return c.json({
      success: true,
      message: `Key "${key}" will expire in ${ttl} seconds`,
      expiresAt: new Date(Date.now() + ttl * 1000).toISOString(),
    });
  } catch (error) {
    return c.json(
      {
        success: false,
        error: (error as Error).message,
      },
      500
    );
  }
 });
 // Write with metadata
 app.put('/kv/:key/metadata', async (c) => {
  const key = c.req.param('key');
  const body = await c.req.json<{ value: string; metadata: any }>();
  // Validate metadata size (max 1024 bytes serialized)
  const metadataJson = JSON.stringify(body.metadata);
  if (metadataJson.length > 1024) {
    return c.json(
      {
        success: false,
        error: `Metadata too large: ${metadataJson.length} bytes (max 1024)`,
      },
      400
    );
  }
  try {
    await c.env.MY_KV.put(key, body.value, {
      metadata: body.metadata,
    });
    return c.json({
      success: true,
      message: `Key "${key}" created with metadata`,
      metadata: body.metadata,
    });
  } catch (error) {
    return c.json(
      {
        success: false,
        error: (error as Error).message,
      },
      500
    );
  }
 });
 // Write JSON data
 app.post('/kv/json/:key', async (c) => {
  const key = c.req.param('key');
  const data = await c.req.json();
  try {
    await c.env.MY_KV.put(key, JSON.stringify(data));
    return c.json({
      success: true,
      message: `JSON data stored at key "${key}"`,
    });
  } catch (error) {
    return c.json(
      {
        success: false,
        error: (error as Error).message,
      },
      500
    );
  }
 });
 // ============================================================================
 // READ - Get key-value pairs
 // ============================================================================
 // Simple read (text)
 app.get('/kv/:key', async (c) => {
  const key = c.req.param('key');
  try {
    const value = await c.env.MY_KV.get(key);
    if (value === null) {
      return c.json(
        {
          success: false,
          error: `Key "${key}" not found`,
        },
        404
      );
    }
    return c.json({
      success: true,
      key,
      value,
    });
  } catch (error) {
    return c.json(
      {
        success: false,
        error: (error as Error).message,
      },
      500
    );
  }
 });
 // Read JSON data
 app.get('/kv/json/:key', async (c) => {
  const key = c.req.param('key');
  try {
    const value = await c.env.MY_KV.get(key, { type: 'json' });
    if (value === null) {
      return c.json(
        {
          success: false,
          error: `Key "${key}" not found`,
        },
        404
      );
    }
    return c.json({
      success: true,
      key,
      value,
    });
  } catch (error) {
    return c.json(
      {
        success: false,
        error: (error as Error).message,
      },
      500
    );
  }
 });
 // Read with metadata
 app.get('/kv/:key/metadata', async (c) => {
  const key = c.req.param('key');
  try {
    const { value, metadata } = await c.env.MY_KV.getWithMetadata(key);
    if (value === null) {
      return c.json(
        {
          success: false,
          error: `Key "${key}" not found`,
        },
        404
      );
    }
    return c.json({
      success: true,
      key,
      value,
      metadata,
    });
  } catch (error) {
    return c.json(
      {
        success: false,
        error: (error as Error).message,
      },
      500
    );
  }
 });
 // Read with cache optimization
 app.get('/kv/:key/cached', async (c) => {
  const key = c.req.param('key');
  const cacheTtl = parseInt(c.req.query('cacheTtl') || '300', 10);
  // Validate cacheTtl (minimum 60 seconds)
  if (cacheTtl < 60) {
    return c.json(
      {
        success: false,
        error: 'cacheTtl must be at least 60 seconds',
      },
      400
    );
  }
  try {
    const value = await c.env.MY_KV.get(key, {
      type: 'text',
      cacheTtl,
    });
    if (value === null) {
      return c.json(
        {
          success: false,
          error: `Key "${key}" not found`,
        },
        404
      );
    }
    return c.json({
      success: true,
      key,
      value,
      cached: true,
      cacheTtl,
    });
  } catch (error) {
    return c.json(
      {
        success: false,
        error: (error as Error).message,
      },
      500
    );
  }
 });
 // Bulk read (multiple keys)
 app.post('/kv/bulk/get', async (c) => {
  const { keys } = await c.req.json<{ keys: string[] }>();
  if (!Array.isArray(keys) || keys.length === 0) {
    return c.json(
      {
        success: false,
        error: 'keys must be a non-empty array',
      },
      400
    );
  }
  try {
    // Bulk read counts as 1 operation!
    const values = await c.env.MY_KV.get(keys);
    // Convert Map to object
    const result: Record<string, string | null> = {};
    for (const [key, value] of values) {
      result[key] = value;
    }
    return c.json({
      success: true,
      count: keys.length,
      values: result,
    });
  } catch (error) {
    return c.json(
      {
        success: false,
        error: (error as Error).message,
      },
      500
    );
  }
 });
 // ============================================================================
 // LIST - List keys with pagination
 // ============================================================================
 // List all keys (with pagination)
 app.get('/kv/list', async (c) => {
  const prefix = c.req.query('prefix') || '';
  const cursor = c.req.query('cursor');
  const limit = parseInt(c.req.query('limit') || '1000', 10);
  try {
    const result = await c.env.MY_KV.list({
      prefix,
      limit,
      cursor: cursor || undefined,
    });
    return c.json({
      success: true,
      keys: result.keys,
      count: result.keys.length,
      hasMore: !result.list_complete,
      cursor: result.cursor,
    });
  } catch (error) {
    return c.json(
      {
        success: false,
        error: (error as Error).message,
      },
      500
    );
  }
 });
 // List all keys with prefix (fully paginated)
 app.get('/kv/list/all/:prefix', async (c) => {
  const prefix = c.req.param('prefix');
  let cursor: string | undefined;
  const allKeys: any[] = [];
  try {
    // Paginate through all keys
    do {
      const result = await c.env.MY_KV.list({
        prefix,
        cursor,
      });
      allKeys.push(...result.keys);
      cursor = result.list_complete ? undefined : result.cursor;
    } while (cursor);
    return c.json({
      success: true,
      prefix,
      keys: allKeys,
      totalCount: allKeys.length,
    });
  } catch (error) {
    return c.json(
      {
        success: false,
        error: (error as Error).message,
      },
      500
    );
  }
 });
 // ============================================================================
 // DELETE - Delete key-value pairs
 // ============================================================================
 // Delete single key
 app.delete('/kv/:key', async (c) => {
  const key = c.req.param('key');
  try {
    // Delete always succeeds, even if key doesn't exist
    await c.env.MY_KV.delete(key);
    return c.json({
      success: true,
      message: `Key "${key}" deleted`,
    });
  } catch (error) {
    return c.json(
      {
        success: false,
        error: (error as Error).message,
      },
      500
    );
  }
 });
 // Delete multiple keys
 app.post('/kv/bulk/delete', async (c) => {
  const { keys } = await c.req.json<{ keys: string[] }>();
  if (!Array.isArray(keys) || keys.length === 0) {
    return c.json(
      {
        success: false,
        error: 'keys must be a non-empty array',
      },
      400
    );
  }
  try {
    // Delete all keys in parallel
    await Promise.all(keys.map((key) => c.env.MY_KV.delete(key)));
    return c.json({
      success: true,
      message: `${keys.length} keys deleted`,
      count: keys.length,
    });
  } catch (error) {
    return c.json(
      {
        success: false,
        error: (error as Error).message,
      },
      500
    );
  }
 });
 // ============================================================================
 // UTILITY - Helper endpoints
 // ============================================================================
 // Check if key exists
 app.get('/kv/:key/exists', async (c) => {
  const key = c.req.param('key');
  try {
    const value = await c.env.MY_KV.get(key);
    return c.json({
      exists: value !== null,
      key,
    });
  } catch (error) {
    return c.json(
      {
        success: false,
        error: (error as Error).message,
      },
      500
    );
  }
 });
 // Get namespace stats
 app.get('/kv/stats', async (c) => {
  try {
    const result = await c.env.MY_KV.list();
    let totalKeys = result.keys.length;
    let cursor = result.cursor;
    // Count all keys (with pagination)
    while (!result.list_complete && cursor) {
      const nextResult = await c.env.MY_KV.list({ cursor });
      totalKeys += nextResult.keys.length;
      cursor = nextResult.cursor;
    }
    return c.json({
      success: true,
      totalKeys,
      sample: result.keys.slice(0, 10), // First 10 keys
    });
  } catch (error) {
    return c.json(
      {
        success: false,
        error: (error as Error).message,
      },
      500
    );
  }
 });
 // Health check
 app.get('/health', (c) => {
  return c.json({
    status: 'ok',
    timestamp: new Date().toISOString(),
  });
 });
 export default app;
--- a/templates/kv-caching-pattern.ts
+++ b/templates/kv-caching-pattern.ts
@@ -0,0 +1,518 @@
 /**
 * Cloudflare Workers KV - Caching Pattern
 *
 * This template demonstrates optimal caching patterns with KV:
 * - Cache-aside pattern (read-through cache)
 * - Write-through cache
 * - CacheTtl optimization for edge caching
 * - Stale-while-revalidate pattern
 * - Cache invalidation
 */
 import { Hono } from 'hono';
 type Bindings = {
  CACHE: KVNamespace;
  DB: D1Database; // Example: database for cache misses
 };
 const app = new Hono<{ Bindings: Bindings }>();
 // ============================================================================
 // Cache-Aside Pattern (Read-Through Cache)
 // ============================================================================
 /**
 * Generic cache-aside helper
 *
 * 1. Try to read from cache
 * 2. On miss, fetch from source
 * 3. Store in cache
 * 4. Return data
 */
 async function getCached<T>(
  kv: KVNamespace,
  cacheKey: string,
  fetchFn: () => Promise<T>,
  options: {
    ttl?: number; // KV expiration (default: 3600)
    cacheTtl?: number; // Edge cache TTL (default: 300)
  } = {}
 ): Promise<T> {
  const ttl = options.ttl ?? 3600; // 1 hour default
  const cacheTtl = options.cacheTtl ?? 300; // 5 minutes default
  // Try cache first (with edge caching)
  const cached = await kv.get<T>(cacheKey, {
    type: 'json',
    cacheTtl: Math.max(cacheTtl, 60), // Minimum 60 seconds
  });
  if (cached !== null) {
    return cached;
  }
  // Cache miss - fetch from source
  const data = await fetchFn();
  // Store in cache (fire-and-forget)
  await kv.put(cacheKey, JSON.stringify(data), {
    expirationTtl: Math.max(ttl, 60), // Minimum 60 seconds
  });
  return data;
 }
 // Example: Cache API response
 app.get('/api/user/:id', async (c) => {
  const userId = c.req.param('id');
  const cacheKey = `user:${userId}`;
  try {
    const user = await getCached(
      c.env.CACHE,
      cacheKey,
      async () => {
        // Simulate database fetch
        const result = await c.env.DB.prepare(
          'SELECT * FROM users WHERE id = ?'
        )
          .bind(userId)
          .first();
        if (!result) {
          throw new Error('User not found');
        }
        return result;
      },
      {
        ttl: 3600, // Cache in KV for 1 hour
        cacheTtl: 300, // Cache at edge for 5 minutes
      }
    );
    return c.json({
      success: true,
      user,
      cached: true,
    });
  } catch (error) {
    return c.json(
      {
        success: false,
        error: (error as Error).message,
      },
      500
    );
  }
 });
 // ============================================================================
 // Write-Through Cache Pattern
 // ============================================================================
 /**
 * Write-through cache: Update cache when data changes
 */
 app.put('/api/user/:id', async (c) => {
  const userId = c.req.param('id');
  const userData = await c.req.json();
  const cacheKey = `user:${userId}`;
  try {
    // Update database
    await c.env.DB.prepare(
      'UPDATE users SET name = ?, email = ? WHERE id = ?'
    )
      .bind(userData.name, userData.email, userId)
      .run();
    // Update cache immediately
    await c.env.CACHE.put(cacheKey, JSON.stringify(userData), {
      expirationTtl: 3600,
    });
    return c.json({
      success: true,
      message: 'User updated and cache refreshed',
    });
  } catch (error) {
    return c.json(
      {
        success: false,
        error: (error as Error).message,
      },
      500
    );
  }
 });
 // ============================================================================
 // Cache Invalidation
 // ============================================================================
 /**
 * Invalidate cache when data changes
 */
 app.delete('/api/user/:id', async (c) => {
  const userId = c.req.param('id');
  const cacheKey = `user:${userId}`;
  try {
    // Delete from database
    await c.env.DB.prepare('DELETE FROM users WHERE id = ?').bind(userId).run();
    // Invalidate cache
    await c.env.CACHE.delete(cacheKey);
    return c.json({
      success: true,
      message: 'User deleted and cache invalidated',
    });
  } catch (error) {
    return c.json(
      {
        success: false,
        error: (error as Error).message,
      },
      500
    );
  }
 });
 // Invalidate multiple cache keys
 app.post('/api/cache/invalidate', async (c) => {
  const { keys } = await c.req.json<{ keys: string[] }>();
  try {
    // Delete all cache keys in parallel
    await Promise.all(keys.map((key) => c.env.CACHE.delete(key)));
    return c.json({
      success: true,
      message: `${keys.length} cache keys invalidated`,
      count: keys.length,
    });
  } catch (error) {
    return c.json(
      {
        success: false,
        error: (error as Error).message,
      },
      500
    );
  }
 });
 // Invalidate by prefix (requires list + delete)
 app.post('/api/cache/invalidate/prefix', async (c) => {
  const { prefix } = await c.req.json<{ prefix: string }>();
  try {
    let cursor: string | undefined;
    let deletedCount = 0;
    // List all keys with prefix and delete them
    do {
      const result = await c.env.CACHE.list({ prefix, cursor });
      // Delete batch in parallel
      await Promise.all(result.keys.map((key) => c.env.CACHE.delete(key.name)));
      deletedCount += result.keys.length;
      cursor = result.list_complete ? undefined : result.cursor;
    } while (cursor);
    return c.json({
      success: true,
      message: `Cache invalidated for prefix "${prefix}"`,
      deletedCount,
    });
  } catch (error) {
    return c.json(
      {
        success: false,
        error: (error as Error).message,
      },
      500
    );
  }
 });
 // ============================================================================
 // Stale-While-Revalidate Pattern
 // ============================================================================
 /**
 * Return cached data immediately, refresh in background
 */
 async function staleWhileRevalidate<T>(
  kv: KVNamespace,
  cacheKey: string,
  fetchFn: () => Promise<T>,
  ctx: ExecutionContext,
  options: {
    ttl?: number;
    staleThreshold?: number; // Refresh if older than this
  } = {}
 ): Promise<T> {
  const ttl = options.ttl ?? 3600;
  const staleThreshold = options.staleThreshold ?? 300; // 5 minutes
  // Get cached value with metadata
  const { value, metadata } = await kv.getWithMetadata<
    T,
    { timestamp: number }
  >(cacheKey, { type: 'json' });
  // If cached and not too stale, return immediately
  if (value !== null && metadata) {
    const age = Date.now() - metadata.timestamp;
    // If stale, refresh in background
    if (age > staleThreshold * 1000) {
      ctx.waitUntil(
        (async () => {
          try {
            const fresh = await fetchFn();
            await kv.put(cacheKey, JSON.stringify(fresh), {
              expirationTtl: ttl,
              metadata: { timestamp: Date.now() },
            });
          } catch (error) {
            console.error('Background refresh failed:', error);
          }
        })()
      );
    }
    return value;
  }
  // Cache miss - fetch and store
  const data = await fetchFn();
  await kv.put(cacheKey, JSON.stringify(data), {
    expirationTtl: ttl,
    metadata: { timestamp: Date.now() },
  });
  return data;
 }
 // Example usage
 app.get('/api/stats', async (c) => {
  try {
    const stats = await staleWhileRevalidate(
      c.env.CACHE,
      'global:stats',
      async () => {
        // Expensive computation
        const result = await c.env.DB.prepare(
          'SELECT COUNT(*) as total FROM users'
        ).first();
        return result;
      },
      c.executionCtx,
      {
        ttl: 3600, // Cache for 1 hour
        staleThreshold: 300, // Refresh if older than 5 minutes
      }
    );
    return c.json({
      success: true,
      stats,
    });
  } catch (error) {
    return c.json(
      {
        success: false,
        error: (error as Error).message,
      },
      500
    );
  }
 });
 // ============================================================================
 // Multi-Layer Cache (KV + Memory)
 // ============================================================================
 /**
 * Two-tier cache: In-memory cache + KV cache
 * Useful for frequently accessed data within same Worker instance
 */
 const memoryCache = new Map<string, { value: any; expires: number }>();
 async function getMultiLayerCache<T>(
  kv: KVNamespace,
  cacheKey: string,
  fetchFn: () => Promise<T>,
  options: {
    ttl?: number;
    memoryTtl?: number; // In-memory cache duration
  } = {}
 ): Promise<T> {
  const ttl = options.ttl ?? 3600;
  const memoryTtl = (options.memoryTtl ?? 60) * 1000; // Convert to ms
  // Check memory cache first (fastest)
  const memoryCached = memoryCache.get(cacheKey);
  if (memoryCached && memoryCached.expires > Date.now()) {
    return memoryCached.value;
  }
  // Check KV cache (fast, global)
  const kvCached = await kv.get<T>(cacheKey, {
    type: 'json',
    cacheTtl: 300,
  });
  if (kvCached !== null) {
    // Store in memory cache
    memoryCache.set(cacheKey, {
      value: kvCached,
      expires: Date.now() + memoryTtl,
    });
    return kvCached;
  }
  // Cache miss - fetch from source
  const data = await fetchFn();
  // Store in both caches
  memoryCache.set(cacheKey, {
    value: data,
    expires: Date.now() + memoryTtl,
  });
  await kv.put(cacheKey, JSON.stringify(data), {
    expirationTtl: ttl,
  });
  return data;
 }
 // Example usage
 app.get('/api/config', async (c) => {
  try {
    const config = await getMultiLayerCache(
      c.env.CACHE,
      'app:config',
      async () => {
        // Fetch from database or API
        return {
          theme: 'dark',
          features: ['feature1', 'feature2'],
          version: '1.0.0',
        };
      },
      {
        ttl: 3600, // KV cache: 1 hour
        memoryTtl: 60, // Memory cache: 1 minute
      }
    );
    return c.json({
      success: true,
      config,
    });
  } catch (error) {
    return c.json(
      {
        success: false,
        error: (error as Error).message,
      },
      500
    );
  }
 });
 // ============================================================================
 // Cache Warming
 // ============================================================================
 /**
 * Pre-populate cache with frequently accessed data
 */
 app.post('/api/cache/warm', async (c) => {
  try {
    // Example: Warm cache with top 100 users
    const topUsers = await c.env.DB.prepare(
      'SELECT * FROM users ORDER BY activity DESC LIMIT 100'
    ).all();
    // Store each user in cache
    const promises = topUsers.results.map((user: any) =>
      c.env.CACHE.put(`user:${user.id}`, JSON.stringify(user), {
        expirationTtl: 3600,
      })
    );
    await Promise.all(promises);
    return c.json({
      success: true,
      message: `Warmed cache with ${topUsers.results.length} users`,
      count: topUsers.results.length,
    });
  } catch (error) {
    return c.json(
      {
        success: false,
        error: (error as Error).message,
      },
      500
    );
  }
 });
 // ============================================================================
 // Cache Statistics
 // ============================================================================
 /**
 * Track cache hit/miss rates
 */
 let cacheStats = {
  hits: 0,
  misses: 0,
  errors: 0,
 };
 app.get('/api/cache/stats', (c) => {
  const total = cacheStats.hits + cacheStats.misses;
  const hitRate = total > 0 ? (cacheStats.hits / total) * 100 : 0;
  return c.json({
    success: true,
    stats: {
      hits: cacheStats.hits,
      misses: cacheStats.misses,
      errors: cacheStats.errors,
      total,
      hitRate: `${hitRate.toFixed(2)}%`,
    },
  });
 });
 // Reset stats
 app.post('/api/cache/stats/reset', (c) => {
  cacheStats = { hits: 0, misses: 0, errors: 0 };
  return c.json({
    success: true,
    message: 'Cache stats reset',
  });
 });
 // Health check
 app.get('/health', (c) => {
  return c.json({
    status: 'ok',
    timestamp: new Date().toISOString(),
  });
 });
 export default app;
--- a/templates/kv-list-pagination.ts
+++ b/templates/kv-list-pagination.ts
@@ -0,0 +1,551 @@
 /**
 * Cloudflare Workers KV - List & Pagination Patterns
 *
 * This template demonstrates:
 * - Basic listing with cursor pagination
 * - Prefix filtering
 * - Async iterator pattern
 * - Batch processing
 * - Key search and filtering
 */
 import { Hono } from 'hono';
 type Bindings = {
  MY_KV: KVNamespace;
 };
 const app = new Hono<{ Bindings: Bindings }>();
 // ============================================================================
 // Basic Pagination
 // ============================================================================
 // List keys with cursor pagination
 app.get('/kv/list', async (c) => {
  const prefix = c.req.query('prefix') || '';
  const cursor = c.req.query('cursor');
  const limit = parseInt(c.req.query('limit') || '100', 10);
  try {
    const result = await c.env.MY_KV.list({
      prefix,
      limit: Math.min(limit, 1000), // Max 1000
      cursor: cursor || undefined,
    });
    return c.json({
      success: true,
      keys: result.keys.map((k) => ({
        name: k.name,
        expiration: k.expiration,
        metadata: k.metadata,
      })),
      count: result.keys.length,
      hasMore: !result.list_complete,
      nextCursor: result.cursor,
    });
  } catch (error) {
    return c.json(
      {
        success: false,
        error: (error as Error).message,
      },
      500
    );
  }
 });
 // ============================================================================
 // Async Iterator Pattern
 // ============================================================================
 /**
 * Async generator for paginating through all keys
 */
 async function* paginateKeys(
  kv: KVNamespace,
  options: {
    prefix?: string;
    limit?: number;
  } = {}
 ) {
  let cursor: string | undefined;
  do {
    const result = await kv.list({
      prefix: options.prefix,
      limit: options.limit || 1000,
      cursor,
    });
    yield result.keys;
    cursor = result.list_complete ? undefined : result.cursor;
  } while (cursor);
 }
 // Get all keys (fully paginated)
 app.get('/kv/all', async (c) => {
  const prefix = c.req.query('prefix') || '';
  try {
    const allKeys: any[] = [];
    // Use async iterator to get all keys
    for await (const batch of paginateKeys(c.env.MY_KV, { prefix })) {
      allKeys.push(...batch);
    }
    return c.json({
      success: true,
      keys: allKeys.map((k) => k.name),
      totalCount: allKeys.length,
    });
  } catch (error) {
    return c.json(
      {
        success: false,
        error: (error as Error).message,
      },
      500
    );
  }
 });
 // ============================================================================
 // Prefix Filtering
 // ============================================================================
 // List keys by namespace prefix
 app.get('/kv/namespace/:namespace', async (c) => {
  const namespace = c.req.param('namespace');
  const cursor = c.req.query('cursor');
  try {
    const result = await c.env.MY_KV.list({
      prefix: `${namespace}:`, // e.g., "user:", "session:", "cache:"
      cursor: cursor || undefined,
    });
    return c.json({
      success: true,
      namespace,
      keys: result.keys,
      count: result.keys.length,
      hasMore: !result.list_complete,
      nextCursor: result.cursor,
    });
  } catch (error) {
    return c.json(
      {
        success: false,
        error: (error as Error).message,
      },
      500
    );
  }
 });
 // Count keys by prefix
 app.get('/kv/count/:prefix', async (c) => {
  const prefix = c.req.param('prefix');
  try {
    let count = 0;
    let cursor: string | undefined;
    do {
      const result = await c.env.MY_KV.list({
        prefix,
        cursor,
      });
      count += result.keys.length;
      cursor = result.list_complete ? undefined : result.cursor;
    } while (cursor);
    return c.json({
      success: true,
      prefix,
      count,
    });
  } catch (error) {
    return c.json(
      {
        success: false,
        error: (error as Error).message,
      },
      500
    );
  }
 });
 // ============================================================================
 // Batch Processing
 // ============================================================================
 /**
 * Process keys in batches
 */
 async function processBatches<T>(
  kv: KVNamespace,
  options: {
    prefix?: string;
    batchSize?: number;
  },
  processor: (keys: any[]) => Promise<T[]>
 ): Promise<T[]> {
  const results: T[] = [];
  let cursor: string | undefined;
  do {
    const result = await kv.list({
      prefix: options.prefix,
      limit: options.batchSize || 100,
      cursor,
    });
    // Process this batch
    const batchResults = await processor(result.keys);
    results.push(...batchResults);
    cursor = result.list_complete ? undefined : result.cursor;
  } while (cursor);
  return results;
 }
 // Example: Export all keys with values
 app.get('/kv/export', async (c) => {
  const prefix = c.req.query('prefix') || '';
  try {
    const exported = await processBatches(
      c.env.MY_KV,
      { prefix, batchSize: 100 },
      async (keys) => {
        // Get values for all keys in batch (bulk read)
        const keyNames = keys.map((k) => k.name);
        const values = await c.env.MY_KV.get(keyNames);
        // Combine keys with values
        return keys.map((key) => ({
          key: key.name,
          value: values.get(key.name),
          metadata: key.metadata,
          expiration: key.expiration,
        }));
      }
    );
    return c.json({
      success: true,
      data: exported,
      count: exported.length,
    });
  } catch (error) {
    return c.json(
      {
        success: false,
        error: (error as Error).message,
      },
      500
    );
  }
 });
 // ============================================================================
 // Search & Filtering
 // ============================================================================
 // Search keys by pattern (client-side filtering)
 app.get('/kv/search', async (c) => {
  const query = c.req.query('q') || '';
  const prefix = c.req.query('prefix') || '';
  if (!query) {
    return c.json(
      {
        success: false,
        error: 'Query parameter "q" is required',
      },
      400
    );
  }
  try {
    const matches: any[] = [];
    let cursor: string | undefined;
    do {
      const result = await c.env.MY_KV.list({
        prefix,
        cursor,
      });
      // Filter keys that match the search query
      const filteredKeys = result.keys.filter((key) =>
        key.name.toLowerCase().includes(query.toLowerCase())
      );
      matches.push(...filteredKeys);
      cursor = result.list_complete ? undefined : result.cursor;
    } while (cursor);
    return c.json({
      success: true,
      query,
      matches: matches.map((k) => k.name),
      count: matches.length,
    });
  } catch (error) {
    return c.json(
      {
        success: false,
        error: (error as Error).message,
      },
      500
    );
  }
 });
 // Filter by metadata
 app.get('/kv/filter/metadata', async (c) => {
  const metadataKey = c.req.query('key');
  const metadataValue = c.req.query('value');
  if (!metadataKey) {
    return c.json(
      {
        success: false,
        error: 'Query parameter "key" is required',
      },
      400
    );
  }
  try {
    const matches: any[] = [];
    let cursor: string | undefined;
    do {
      const result = await c.env.MY_KV.list({ cursor });
      // Filter by metadata
      const filteredKeys = result.keys.filter((key) => {
        if (!key.metadata) return false;
        return metadataValue
          ? key.metadata[metadataKey] === metadataValue
          : metadataKey in key.metadata;
      });
      matches.push(...filteredKeys);
      cursor = result.list_complete ? undefined : result.cursor;
    } while (cursor);
    return c.json({
      success: true,
      matches: matches.map((k) => ({
        name: k.name,
        metadata: k.metadata,
      })),
      count: matches.length,
    });
  } catch (error) {
    return c.json(
      {
        success: false,
        error: (error as Error).message,
      },
      500
    );
  }
 });
 // ============================================================================
 // Cleanup & Maintenance
 // ============================================================================
 // Delete expired keys (manual cleanup)
 app.post('/kv/cleanup/expired', async (c) => {
  try {
    let deletedCount = 0;
    let cursor: string | undefined;
    do {
      const result = await c.env.MY_KV.list({ cursor });
      // Filter keys that have expired
      const now = Math.floor(Date.now() / 1000);
      const expiredKeys = result.keys
        .filter((key) => key.expiration && key.expiration < now)
        .map((key) => key.name);
      // Delete expired keys
      await Promise.all(expiredKeys.map((key) => c.env.MY_KV.delete(key)));
      deletedCount += expiredKeys.length;
      cursor = result.list_complete ? undefined : result.cursor;
    } while (cursor);
    return c.json({
      success: true,
      message: `Deleted ${deletedCount} expired keys`,
      deletedCount,
    });
  } catch (error) {
    return c.json(
      {
        success: false,
        error: (error as Error).message,
      },
      500
    );
  }
 });
 // Delete all keys with prefix (DANGEROUS!)
 app.post('/kv/delete/prefix', async (c) => {
  const { prefix } = await c.req.json<{ prefix: string }>();
  if (!prefix) {
    return c.json(
      {
        success: false,
        error: 'Prefix is required',
      },
      400
    );
  }
  try {
    let deletedCount = 0;
    let cursor: string | undefined;
    do {
      const result = await c.env.MY_KV.list({ prefix, cursor });
      // Delete batch
      await Promise.all(result.keys.map((key) => c.env.MY_KV.delete(key.name)));
      deletedCount += result.keys.length;
      cursor = result.list_complete ? undefined : result.cursor;
    } while (cursor);
    return c.json({
      success: true,
      message: `Deleted ${deletedCount} keys with prefix "${prefix}"`,
      deletedCount,
    });
  } catch (error) {
    return c.json(
      {
        success: false,
        error: (error as Error).message,
      },
      500
    );
  }
 });
 // ============================================================================
 // Namespace Statistics
 // ============================================================================
 // Get detailed namespace stats
 app.get('/kv/stats/detailed', async (c) => {
  try {
    let totalKeys = 0;
    let withMetadata = 0;
    let withExpiration = 0;
    const prefixes = new Map<string, number>();
    let cursor: string | undefined;
    do {
      const result = await c.env.MY_KV.list({ cursor });
      totalKeys += result.keys.length;
      // Analyze keys
      for (const key of result.keys) {
        if (key.metadata) withMetadata++;
        if (key.expiration) withExpiration++;
        // Extract prefix (before first ":")
        const prefix = key.name.split(':')[0];
        prefixes.set(prefix, (prefixes.get(prefix) || 0) + 1);
      }
      cursor = result.list_complete ? undefined : result.cursor;
    } while (cursor);
    return c.json({
      success: true,
      stats: {
        totalKeys,
        withMetadata,
        withExpiration,
        prefixCounts: Object.fromEntries(prefixes),
      },
    });
  } catch (error) {
    return c.json(
      {
        success: false,
        error: (error as Error).message,
      },
      500
    );
  }
 });
 // Group keys by prefix
 app.get('/kv/groups', async (c) => {
  try {
    const groups = new Map<string, string[]>();
    let cursor: string | undefined;
    do {
      const result = await c.env.MY_KV.list({ cursor });
      for (const key of result.keys) {
        const prefix = key.name.split(':')[0];
        if (!groups.has(prefix)) {
          groups.set(prefix, []);
        }
        groups.get(prefix)!.push(key.name);
      }
      cursor = result.list_complete ? undefined : result.cursor;
    } while (cursor);
    return c.json({
      success: true,
      groups: Object.fromEntries(groups),
      groupCount: groups.size,
    });
  } catch (error) {
    return c.json(
      {
        success: false,
        error: (error as Error).message,
      },
      500
    );
  }
 });
 // Health check
 app.get('/health', (c) => {
  return c.json({
    status: 'ok',
    timestamp: new Date().toISOString(),
  });
 });
 export default app;
--- a/templates/kv-metadata-pattern.ts
+++ b/templates/kv-metadata-pattern.ts
@@ -0,0 +1,568 @@
 /**
 * Cloudflare Workers KV - Metadata Patterns
 *
 * This template demonstrates:
 * - Storing data in metadata for list() efficiency
 * - Metadata-based filtering
 * - Versioning with metadata
 * - Audit trails
 * - Feature flags with metadata
 */
 import { Hono } from 'hono';
 type Bindings = {
  MY_KV: KVNamespace;
 };
 const app = new Hono<{ Bindings: Bindings }>();
 // ============================================================================
 // Metadata Optimization Pattern
 // ============================================================================
 /**
 * Store small values in metadata to avoid separate get() calls
 * Maximum metadata size: 1024 bytes (JSON serialized)
 */
 // ❌ BAD: Requires 2 operations per key
 async function getStatusBad(kv: KVNamespace, userId: string) {
  const status = await kv.get(`user:${userId}:status`);
  const lastSeen = await kv.get(`user:${userId}:lastseen`);
  return { status, lastSeen };
 }
 // ✅ GOOD: Single list() operation gets metadata for all users
 async function getStatusGood(kv: KVNamespace) {
  const users = await kv.list({ prefix: 'user:' });
  return users.keys.map((key) => ({
    userId: key.name.split(':')[1],
    status: key.metadata?.status,
    lastSeen: key.metadata?.lastSeen,
  }));
 }
 // Example: User status with metadata
 app.post('/users/:id/status', async (c) => {
  const userId = c.req.param('id');
  const { status } = await c.req.json<{ status: string }>();
  try {
    // Store empty value, all data in metadata
    await c.env.MY_KV.put(`user:${userId}`, '', {
      metadata: {
        status,
        lastSeen: Date.now(),
        plan: 'free',
      },
    });
    return c.json({
      success: true,
      message: 'Status updated',
    });
  } catch (error) {
    return c.json(
      {
        success: false,
        error: (error as Error).message,
      },
      500
    );
  }
 });
 // List all users with status (no additional get() calls needed!)
 app.get('/users/status', async (c) => {
  try {
    const users = await c.env.MY_KV.list({ prefix: 'user:' });
    const statuses = users.keys.map((key) => ({
      userId: key.name.split(':')[1],
      status: key.metadata?.status || 'unknown',
      lastSeen: key.metadata?.lastSeen,
      plan: key.metadata?.plan,
    }));
    return c.json({
      success: true,
      users: statuses,
      count: statuses.length,
    });
  } catch (error) {
    return c.json(
      {
        success: false,
        error: (error as Error).message,
      },
      500
    );
  }
 });
 // ============================================================================
 // Versioning with Metadata
 // ============================================================================
 interface VersionedData {
  content: any;
  version: number;
  updatedAt: number;
  updatedBy: string;
 }
 // Write with versioning
 app.put('/config/:key', async (c) => {
  const key = c.req.param('key');
  const content = await c.req.json();
  const updatedBy = c.req.header('X-User-ID') || 'system';
  try {
    // Get current version
    const existing = await c.env.MY_KV.getWithMetadata<
      VersionedData,
      { version: number }
    >(`config:${key}`, { type: 'json' });
    const currentVersion = existing.metadata?.version || 0;
    const newVersion = currentVersion + 1;
    // Store new version
    const data: VersionedData = {
      content,
      version: newVersion,
      updatedAt: Date.now(),
      updatedBy,
    };
    await c.env.MY_KV.put(`config:${key}`, JSON.stringify(data), {
      metadata: {
        version: newVersion,
        updatedAt: data.updatedAt,
        updatedBy,
      },
    });
    // Store version history (optional)
    await c.env.MY_KV.put(
      `config:${key}:v${newVersion}`,
      JSON.stringify(data),
      {
        expirationTtl: 86400 * 30, // Keep versions for 30 days
      }
    );
    return c.json({
      success: true,
      version: newVersion,
      previousVersion: currentVersion,
    });
  } catch (error) {
    return c.json(
      {
        success: false,
        error: (error as Error).message,
      },
      500
    );
  }
 });
 // Get config with version info
 app.get('/config/:key', async (c) => {
  const key = c.req.param('key');
  try {
    const { value, metadata } = await c.env.MY_KV.getWithMetadata<
      VersionedData,
      { version: number; updatedAt: number; updatedBy: string }
    >(`config:${key}`, { type: 'json' });
    if (!value) {
      return c.json(
        {
          success: false,
          error: 'Config not found',
        },
        404
      );
    }
    return c.json({
      success: true,
      data: value,
      metadata,
    });
  } catch (error) {
    return c.json(
      {
        success: false,
        error: (error as Error).message,
      },
      500
    );
  }
 });
 // Get specific version
 app.get('/config/:key/version/:version', async (c) => {
  const key = c.req.param('key');
  const version = c.req.param('version');
  try {
    const data = await c.env.MY_KV.get<VersionedData>(
      `config:${key}:v${version}`,
      { type: 'json' }
    );
    if (!data) {
      return c.json(
        {
          success: false,
          error: `Version ${version} not found`,
        },
        404
      );
    }
    return c.json({
      success: true,
      data,
    });
  } catch (error) {
    return c.json(
      {
        success: false,
        error: (error as Error).message,
      },
      500
    );
  }
 });
 // ============================================================================
 // Audit Trail with Metadata
 // ============================================================================
 interface AuditMetadata {
  createdBy: string;
  createdAt: number;
  updatedBy: string;
  updatedAt: number;
  accessCount: number;
 }
 // Write with audit trail
 app.post('/data/:key', async (c) => {
  const key = c.req.param('key');
  const value = await c.req.text();
  const userId = c.req.header('X-User-ID') || 'anonymous';
  try {
    // Check if key exists
    const existing = await c.env.MY_KV.getWithMetadata<string, AuditMetadata>(
      key
    );
    const metadata: AuditMetadata = existing.metadata
      ? {
          ...existing.metadata,
          updatedBy: userId,
          updatedAt: Date.now(),
        }
      : {
          createdBy: userId,
          createdAt: Date.now(),
          updatedBy: userId,
          updatedAt: Date.now(),
          accessCount: 0,
        };
    await c.env.MY_KV.put(key, value, { metadata });
    return c.json({
      success: true,
      audit: metadata,
    });
  } catch (error) {
    return c.json(
      {
        success: false,
        error: (error as Error).message,
      },
      500
    );
  }
 });
 // Read with access tracking
 app.get('/data/:key', async (c) => {
  const key = c.req.param('key');
  try {
    const { value, metadata } = await c.env.MY_KV.getWithMetadata<
      string,
      AuditMetadata
    >(key);
    if (!value) {
      return c.json(
        {
          success: false,
          error: 'Key not found',
        },
        404
      );
    }
    // Increment access count (fire-and-forget)
    if (metadata) {
      c.executionCtx.waitUntil(
        c.env.MY_KV.put(key, value, {
          metadata: {
            ...metadata,
            accessCount: metadata.accessCount + 1,
          },
        })
      );
    }
    return c.json({
      success: true,
      value,
      audit: metadata,
    });
  } catch (error) {
    return c.json(
      {
        success: false,
        error: (error as Error).message,
      },
      500
    );
  }
 });
 // ============================================================================
 // Feature Flags with Metadata
 // ============================================================================
 interface FeatureFlag {
  enabled: boolean;
  rolloutPercentage: number;
  targetUsers?: string[];
  metadata: {
    createdAt: number;
    updatedAt: number;
    description: string;
  };
 }
 // Create feature flag
 app.post('/flags/:name', async (c) => {
  const name = c.req.param('name');
  const flag = await c.req.json<FeatureFlag>();
  try {
    await c.env.MY_KV.put(`flag:${name}`, JSON.stringify(flag), {
      metadata: {
        enabled: flag.enabled,
        rolloutPercentage: flag.rolloutPercentage,
        updatedAt: Date.now(),
      },
    });
    return c.json({
      success: true,
      message: `Feature flag "${name}" created`,
    });
  } catch (error) {
    return c.json(
      {
        success: false,
        error: (error as Error).message,
      },
      500
    );
  }
 });
 // List all feature flags (metadata only)
 app.get('/flags', async (c) => {
  try {
    const flags = await c.env.MY_KV.list({ prefix: 'flag:' });
    const flagList = flags.keys.map((key) => ({
      name: key.name.replace('flag:', ''),
      enabled: key.metadata?.enabled || false,
      rolloutPercentage: key.metadata?.rolloutPercentage || 0,
      updatedAt: key.metadata?.updatedAt,
    }));
    return c.json({
      success: true,
      flags: flagList,
      count: flagList.length,
    });
  } catch (error) {
    return c.json(
      {
        success: false,
        error: (error as Error).message,
      },
      500
    );
  }
 });
 // Check feature flag for user
 app.get('/flags/:name/check/:userId', async (c) => {
  const name = c.req.param('name');
  const userId = c.req.param('userId');
  try {
    const flag = await c.env.MY_KV.get<FeatureFlag>(`flag:${name}`, {
      type: 'json',
    });
    if (!flag) {
      return c.json(
        {
          success: false,
          error: 'Feature flag not found',
        },
        404
      );
    }
    // Check if enabled
    if (!flag.enabled) {
      return c.json({ enabled: false, reason: 'Flag disabled globally' });
    }
    // Check target users
    if (flag.targetUsers && flag.targetUsers.length > 0) {
      const enabled = flag.targetUsers.includes(userId);
      return c.json({
        enabled,
        reason: enabled ? 'User in target list' : 'User not in target list',
      });
    }
    // Check rollout percentage
    const userHash =
      parseInt(userId.split('').reduce((a, b) => a + b.charCodeAt(0), 0).toString()) %
      100;
    const enabled = userHash < flag.rolloutPercentage;
    return c.json({
      enabled,
      reason: enabled
        ? `User in ${flag.rolloutPercentage}% rollout`
        : `User not in ${flag.rolloutPercentage}% rollout`,
    });
  } catch (error) {
    return c.json(
      {
        success: false,
        error: (error as Error).message,
      },
      500
    );
  }
 });
 // ============================================================================
 // Metadata Size Validation
 // ============================================================================
 // Validate metadata size before writing
 app.post('/validate/metadata', async (c) => {
  const { metadata } = await c.req.json<{ metadata: any }>();
  const serialized = JSON.stringify(metadata);
  const size = new TextEncoder().encode(serialized).length;
  if (size > 1024) {
    return c.json({
      valid: false,
      size,
      maxSize: 1024,
      error: `Metadata too large: ${size} bytes (max 1024)`,
    });
  }
  return c.json({
    valid: true,
    size,
    maxSize: 1024,
  });
 });
 // ============================================================================
 // Metadata Migration
 // ============================================================================
 // Migrate existing keys to add metadata
 app.post('/migrate/add-metadata', async (c) => {
  const { prefix, metadata } = await c.req.json<{
    prefix: string;
    metadata: any;
  }>();
  try {
    let migratedCount = 0;
    let cursor: string | undefined;
    do {
      const result = await c.env.MY_KV.list({ prefix, cursor });
      // Migrate batch
      for (const key of result.keys) {
        // Get existing value
        const value = await c.env.MY_KV.get(key.name);
        if (value !== null) {
          // Re-write with metadata
          await c.env.MY_KV.put(key.name, value, {
            metadata: {
              ...key.metadata,
              ...metadata,
              migratedAt: Date.now(),
            },
          });
          migratedCount++;
        }
      }
      cursor = result.list_complete ? undefined : result.cursor;
    } while (cursor);
    return c.json({
      success: true,
      message: `Migrated ${migratedCount} keys`,
      migratedCount,
    });
  } catch (error) {
    return c.json(
      {
        success: false,
        error: (error as Error).message,
      },
      500
    );
  }
 });
 // Health check
 app.get('/health', (c) => {
  return c.json({
    status: 'ok',
    timestamp: new Date().toISOString(),
  });
 });
 export default app;
--- a/templates/wrangler-kv-config.jsonc
+++ b/templates/wrangler-kv-config.jsonc
@@ -0,0 +1,56 @@
 {
  "$schema": "node_modules/wrangler/config-schema.json",
  "name": "my-worker",
  "main": "src/index.ts",
  "compatibility_date": "2025-10-11",
  "observability": {
    "enabled": true
  },
  // KV Namespace Bindings
  "kv_namespaces": [
    {
      // The binding name - accessible as env.CACHE in your Worker
      "binding": "CACHE",
      // Production namespace ID (from: wrangler kv namespace create CACHE)
      "id": "<YOUR_PRODUCTION_NAMESPACE_ID>",
      // Preview/local namespace ID (from: wrangler kv namespace create CACHE --preview)
      // This is optional but recommended for local development
      "preview_id": "<YOUR_PREVIEW_NAMESPACE_ID>"
    },
    // Multiple namespaces example
    {
      "binding": "CONFIG",
      "id": "<CONFIG_PRODUCTION_ID>",
      "preview_id": "<CONFIG_PREVIEW_ID>"
    },
    {
      "binding": "SESSIONS",
      "id": "<SESSIONS_PRODUCTION_ID>",
      "preview_id": "<SESSIONS_PREVIEW_ID>"
    }
  ]
  // IMPORTANT NOTES:
  //
  // 1. Create namespaces first:
  //    npx wrangler kv namespace create CACHE
  //    npx wrangler kv namespace create CACHE --preview
  //
  // 2. Copy the IDs from the command output to this file
  //
  // 3. NEVER commit real namespace IDs to public repos
  //    Use environment variables for sensitive namespaces:
  //    "id": "${KV_CACHE_ID}"
  //
  // 4. preview_id is optional but recommended for local development
  //    It creates a separate namespace for testing
  //
  // 5. Binding names must be valid JavaScript identifiers
  //    Good: CACHE, MY_KV, UserData
  //    Bad: my-kv, user.data, 123kv
 }
		`@@ -0,0 +1,3 @@`
							`# cloudflare-kv`

							`Store key-value data globally with Cloudflare KVs edge network. Use when: caching API responses, storing configuration, managing user preferences, handling TTL expiration, or troubleshooting KV_ERROR, 429 rate limits, eventual consistency, or cacheTtl errors.`