cache-optimization

Cache Optimization Patterns

Metadata:

• Status: ✅ Active (v1.0)
• Always Apply: false (Fantasy402-specific)
• Topics: #caching #performance #kv #optimization
• Last Updated: 2025-10-08

🔍 Code Searchability Patterns

Find cache-optimization Issues with ast-grep

# Find KV cache writes
ast-grep --pattern 'env.FANTASY_CACHE.put($KEY, $VALUE, { expirationTtl: $TTL })' src/
sg -p 'env.FANTASY_CACHE.put($KEY, $VALUE, { expirationTtl: $TTL })' src/

# Find hash-based change detection
ast-grep --pattern 'JSON.stringify($$$)' src/
sg -p 'JSON.stringify($$$)' src/

# Find cache metric increments
ast-grep --pattern 'incrementCacheMetric($$$)' src/
sg -p 'incrementCacheMetric($$$)' src/

# Find cache key patterns
ast-grep --pattern 'fantasy402:$$$:$$$' src/
sg -p 'fantasy402:' src/

cache-optimization Discovery Commands

sg search "FANTASY_CACHE.put" src/
sg search "expirationTtl" src/
sg search "incrementCacheMetric" src/
sg search "fantasy402:" src/
sg search "hash:" src/

Search Examples

# Find all KV cache operations
sg search 'env.FANTASY_CACHE.put($KEY, $VALUE, { expirationTtl: $TTL })' src/

# Find change detection patterns
sg search 'JSON.stringify($$$)' src/

# Find cache metrics
sg search 'incrementCacheMetric($$$)' src/

# Find cache keys
sg search 'fantasy402:' src/

Overview

Fantasy402 cache optimization patterns implemented in v1.0-cache-optimization achieving:

• 90%+ cache hit rate
• 93.3% D1 write reduction
• 1-hour TTL (safe during iteration, 24h in production)

Critical Performance Patterns

1. Multi-Key KV Caching (CRITICAL)

Why: Fantasy402 agent lists need multiple lookup patterns for different use cases.

// ✅ CORRECT: Multi-key caching with 3 lookup patterns
const agentOwner = agents[0]?.agentOwner;
const agentID = agents[0]?.agentID;

const cacheKeys = [
  `fantasy402:agents:by-owner:${agentOwner}`,   // Primary: lookup by owner
  `fantasy402:agents:by-agent:${agentID}`,       // Secondary: lookup by agent
  `fantasy402:agents:latest:${agentOwner}`       // Fallback: latest data
].filter(Boolean);

const cacheData = {
  agents,
  timestamp: new Date().toISOString(),
  requestId
};

// Write to all keys in parallel
await Promise.all(
  cacheKeys.map(key =>
    env.FANTASY_CACHE!.put(key, JSON.stringify(cacheData), {
      expirationTtl: 3600 // 1 hour (adjust to 86400 for 24h in production)
    })
  )
);

// ❌ WRONG: Single key only
await env.FANTASY_CACHE.put(
  `fantasy402:agents:${agentOwner}`,
  JSON.stringify(cacheData)
);