epic-caching_skill

Overview

This skill provides practical guidance and utilities for caching in Epic Stack using cachified, a persistent SQLite cache (replicated with LiteFS), and an in-memory LRU cache. It focuses on when to cache, how to structure keys and TTLs, stale-while-revalidate patterns, validation with Zod, and safe invalidation patterns. The goal is measurable performance wins with minimal complexity.

How this skill works

The skill explains using @epic-web/cachified as the unified API that delegates to either the SQLite cache or an LRU in-memory cache. Use SQLite for persistent, replicated data and LRU for short-lived deduplication or temporary values. It shows how to define keys, TTL, stale-while-revalidate, and checkValue validation using Zod. It also covers server timing integration and multi-region write guarantees via ensurePrimary().

When to use it

• Cache expensive external API calls or slow queries that are called frequently.
• Return stale data immediately while revalidating in the background (SWR) to improve UX.
• Deduplicate simultaneous requests or store very short-lived values using LRU.
• Persist infrequently changing data across restarts and instances with SQLite/LiteFS.
• Invalidate related caches after mutations or when underlying data changes.

Best practices

• Measure performance before adding cache; avoid caching without clear benefit.
• Use concise, descriptive keys like entity:identifier:data and avoid special characters.
• Validate cached data with Zod (checkValue); fetch fresh data if validation fails.
• Prefer short TTLs and use staleWhileRevalidate for safe background refreshes.
• Invalidate specific keys after mutations and search/delete matching keys when needed.
• Use ensurePrimary() before writes in multi-region setups to guarantee replication.

Example use cases

• Cache GitHub events for a username with a 1-hour TTL and 24-hour SWR to reduce API calls.
• Cache aggregated user stats from Prisma for 5 minutes and revalidate in the background.
• Deduplicate identical outgoing fetches for 1 second using an LRU or request map.
• Invalidate user-related caches after creating or updating a note (delete relevant keys).
• Use SQLite cache for feature flags or scheduled-event lists that change infrequently.