Skip to content

MustafaKucukcoskun/Refine-agent-kit / .agents/skills/cache-strategy-patterns

cache-strategy-patterns

Verified

Cache Strategy Patterns

"There are only two hard things in computer science: cache invalidation and naming things." — Phil Karlton

When to Use vs. Related Skills

You want to…Use
Design cache layercache-strategy-patterns (this)
Next.js App Router cachenextjs-react-expert + this
Database query optimizationdatabase-design + this
CDN / edge cachingthis (HTTP + CDN section)
API response cachingthis + api-patterns

1. Five Cache Strategies (pick one per cache layer)

Cache-Aside (Lazy Loading) — Most common

App reads from cache; on miss, reads DB, then fills cache.

async function getUser(id: string) {
  const cached = await cache.get(`user:${id}`);
  if (cached) return JSON.parse(cached);
  const user = await db.user.findUnique({ where: { id } });
  await cache.set(`user:${id}`, JSON.stringify(user), "EX", 300);
  return user;
}

Pros: simple, resilient (cache failure = slow, not broken) Cons: first request slow; stale data if DB changes without invalidation

Read-Through — Cache library owns reads

Cache library fetches from DB on miss. App only talks to cache.

Pros: cleaner app code Cons: couples app to cache-aware library

Write-Through — Write to cache AND DB synchronously

async function updateUser(id: string, data: UserUpdate) {
  const user = await db.user.update({ where: { id }, data });
  await cache.set(`user:${id}`, JSON.stringify(user), "EX", 300);
  return user;
}

Pros: cache always consistent with DB Cons: write latency = DB + cache

Write-Behind (Write-Back) — Write to cache, flush to DB async

Pros: fast writes Cons: data loss risk on cache crash; complex consistency

Refresh-Ahead — Pre-refresh before expiry

Cache refreshes popular entries before TTL hits zero. Pros: no latency spike on expiry Cons: wasted work on unpopular keys

Rule: Default to cache-aside unless you have a specific reason.


2. Cache Key Design

Bad keys cause bugs more than bad values. Rules:

RuleExample
Include version prefixv2:user:123 (flush old version by changing prefix)
Include all query paramssearch:q=foo&sort=desc&page=1
Use colons as delimiter (Redis convention)tenant:42:user:123:profile
Include user ID for user-specific datauser:123:cart not cart
Never include secretsNOT user:123:apikey:abc
Normalize casing/whitespacelowercase query strings
function cacheKey(parts: Record<string, string | number>): string {
  return "v1:" + Object.entries(parts).sort().map(([k, v]) => `${k}=${v}`).join(":");
}

3. TTL Selection

Data typeSuggested TTL
User session1–24 hours (match session length)
User profile5 min – 1 hour
Public static list (countries, tags)1 day+
Search results30 sec – 5 min
Rate limit counterWindow duration
Page render (SSG)Infinite + invalidate on mutation

Never use EX 0 or no TTL. Always set a ceiling — otherwise one bug fills memory forever.


4. Invalidation Strategies

StrategyWhen
TTL-onlyData can be stale briefly
Event-drivenOn mutation, delete/update key
Version prefix bumpGlobal flush (deploy time)
Tag-basedRelated entries (tag:article:42) — needs support
Stale-while-revalidateServe stale, refresh in background
// Event-driven on update
async function updateUser(id: string, data: UserUpdate) {
  const user = await db.user.update({ where: { id }, data });
  await cache.del(`user:${id}`);   // or set fresh
  return user;
}

// Stale-while-revalidate
async function getWithSWR(key: string, fetcher: () => Promise<any>, ttl = 60) {
  const entry = await cache.get(key);
  if (entry) {
    const { value, exp } = JSON.parse(entry);
    if (Date.now() < exp) return value;
    // Stale — return but refresh in background
    fetcher().then((fresh) => cache.set(key, JSON.stringify({ value: fresh, exp: Date.now() + ttl * 1000 })));
    return value;
  }
  const fresh = await fetcher();
  await cache.set(key, JSON.stringify({ value: fresh, exp: Date.now() + ttl * 1000 }));
  return fresh;
}

5. Cache Stampede (Thundering Herd)

Problem: hot key expires → 1000 requests all hit DB simultaneously.

Mitigation 1: Probabilistic Early Expiration (XFetch)

// Re-compute before actual expiry, probabilistically, based on age

Mitigation 2: Single-Flight Lock

const inflight = new Map<string, Promise<any>>();

async function getSingleFlight<T>(key: string, fetcher: () => Promise<T>): Promise<T> {
  const existing = inflight.get(key);
  if (existing) return existing;
  const promise = fetcher().finally(() => inflight.delete(key));
  inflight.set(key, promise);
  return promise;
}

Mitigation 3: Redis Lock

// SET key value NX EX 10  — only one worker refreshes, others wait

6. Eviction Policies (Redis)

PolicyWhen
allkeys-lruGeneral-purpose cache (default recommendation)
volatile-lruMix of cache + persistent data with TTL
allkeys-lfuAccess patterns very skewed
noevictionCache MUST never drop (will OOM) — rarely right

Set via maxmemory-policy in redis.conf.


7. HTTP Caching

# Static assets (hashed filenames)
Cache-Control: public, max-age=31536000, immutable

# API responses that are public and can be stale briefly
Cache-Control: public, max-age=60, s-maxage=300, stale-while-revalidate=3600

# User-specific
Cache-Control: private, max-age=0, must-revalidate

# Never cache
Cache-Control: no-store

8. Next.js App Router Cache Notes

CacheScopeInvalidate
fetch() Data CachePer-requestrevalidate, revalidateTag, revalidatePath
Full Route CachePer-routeDeploy, revalidatePath
Router CachePer-session clientSoft navigation, TTL
// Revalidate by tag
const data = await fetch(url, { next: { tags: ["posts"] } });
// Later, after mutation:
revalidateTag("posts");

See nextjs-react-expert/3-server-server-side-performance.md for deep detail.


Anti-Patterns

Anti-patternWhy badFix
Caching user-specific data without user-ID in keyData leak across usersInclude user/tenant ID in key
No TTL on any entryMemory leak over timeAlways set TTL, even long ones
Cache invalidation via "delete all keys"Downtime spikePrefer targeted delete or version bump
Caching the error responseAll users see error until TTLCheck status before caching
Reading cache twice per requestRound-trip wasteCache result in local var per request
Ignoring cache miss metricsCan't tell if cache helpsTrack hit/miss ratio

Pre-Ship Checklist

  • Every key has a TTL
  • Invalidation strategy documented
  • Stampede mitigation for hot keys
  • Hit/miss metrics exposed
  • Eviction policy set explicitly
  • No secrets in keys or values
  • User-specific data keyed by user ID
  • Graceful fallback if cache is down

Related Skills

  • nextjs-react-expert — Next.js-specific cache layers
  • database-design — when to cache vs. fix query
  • api-patterns — HTTP caching headers
  • observability-patterns — cache metrics
  • performance-profiling — measure actual impact
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 196kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 192kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 192kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 192kUpdated Claude CodeCodexVerifiedInstall