鱼皮AI导航
鱼皮AI导航
  • 主页
  • 社区
  • AI工具
  • AI知识库
  • AI提示词
  • MCP
  • Skills
  • AI学习资源
  • AI资讯
  • GitHub开源
登录/注册

epic-caching

提供面向高性能 Web 应用的缓存策略支持,涵盖外部 API 响应、低频变更数据的持久化存储与内存级临时缓存,集成自动验证、细粒度失效、服务端计时监控及多实例同步能力,强调按需引入与成本收益权衡。

数据库
访问 GitHub
文档Skills.MD
name
epic-caching
description
Guide on caching with cachified, SQLite cache, and LRU cache for Epic Stack
categories["caching","performance","optimization"]

Epic Stack: Caching

When to use this skill

Use this skill when you need to:

  • Cache results of expensive queries
  • Cache responses from external APIs
  • Optimize performance of data that doesn't change frequently
  • Implement stale-while-revalidate
  • Manage cache invalidation
  • Integrate cache with server timing

Patterns and conventions

Caching Philosophy

Following Epic Web principles:

Weigh the cost-benefit of performance optimizations - Caching adds complexity. Only add cache when there's a clear, measurable benefit. Don't cache "just in case" - cache when you have a real performance problem that caching solves.

When NOT to use cache:

  • Data that changes frequently (cache invalidation becomes a problem)
  • Data that's already fast to fetch (no measurable benefit)
  • Data that's only fetched once (no benefit from caching)
  • Simple queries that don't need optimization
  • When cache invalidation logic becomes more complex than the problem it solves

Example - Evaluating cost-benefit:

▼
typescript
复制代码
// ✅ Good - Cache expensive external API call export async function getGitHubEvents({ username, timings }: { username: string; timings?: Timings }) { return await cachified({ key: `github:${username}:events`, cache, timings, getFreshValue: async () => { // Expensive: External API call, rate limits, network latency const response = await fetch(`https://api.github.com/users/${username}/events/public`) return await response.json() }, checkValue: GitHubEventSchema.array(), ttl: 1000 * 60 * 60, // 1 hour - reasonable for external data }) } // ❌ Avoid - Caching simple, fast database query export async function getUser({ userId }: { userId: string }) { // This query is already fast - caching adds complexity without benefit return await cachified({ key: `user:${userId}`, cache, getFreshValue: async () => { // Simple query, already fast return await prisma.user.findUnique({ where: { id: userId }, select: { id: true, username: true }, }) }, ttl: 1000 * 60 * 5, }) // Better: Just query directly without cache }

Two Types of Cache

Epic Stack provides two types of cache:

  1. SQLite Cache - Long-lived, replicated with LiteFS

    • Persistent across restarts
    • Replicated across all instances
    • Ideal for data that changes infrequently
  2. LRU Cache - Short-lived, in-memory

    • Cleared on restart
    • Not replicated (only on current instance)
    • Ideal for deduplication and temporary cache

Using cachified

Epic Stack uses @epic-web/cachified as an abstraction for cache management.

Basic import:

▼
typescript
复制代码
import { cachified, cache } from '#app/utils/cache.server.ts' import { type Timings } from '#app/utils/timing.server.ts'

Basic structure:

▼
typescript
复制代码
export async function getCachedData({ timings, }: { timings?: Timings } = {}) { return await cachified({ key: 'my-cache-key', cache, timings, getFreshValue: async () => { // Get fresh data return await fetchDataFromAPI() }, checkValue: z.object({ /* schema */ }), // Validation with Zod ttl: 1000 * 60 * 60 * 24, // 24 hours staleWhileRevalidate: 1000 * 60 * 60 * 24 * 30, // 30 days }) }

Cache Keys

Naming conventions:

  • Use format: entity:identifier:data
  • Examples:
    • user:${userId}:profile
    • note:${noteId}:full
    • api:github:events
    • tito:scheduled-events

Avoid:

  • Keys that are too long
  • Keys with special characters
  • Keys that don't clearly identify the content

TTL (Time To Live)

Define TTL:

▼
typescript
复制代码
await cachified({ key: 'my-key', cache, getFreshValue: () => fetchData(), ttl: 1000 * 60 * 60 * 24, // 24 hours in milliseconds })

Null TTL to never expire:

▼
typescript
复制代码
ttl: null, // Never expires (not recommended unless necessary)

Stale-While-Revalidate (SWR)

SWR allows returning stale data while fresh data is fetched in the background.

Example:

▼
typescript
复制代码
await cachified({ key: 'my-key', cache, getFreshValue: () => fetchData(), ttl: 1000 * 60 * 60 * 24, // 24 hours - after this it's considered stale staleWhileRevalidate: 1000 * 60 * 60 * 24 * 30, // 30 days - up to here returns stale while revalidating })

Behavior:

  • Less than 24h: Returns cache, no request made
  • 24h - 30 days: Returns stale cache immediately, updates in background
  • More than 30 days: Waits for fresh data before returning

Validation with Zod

Always validate cached data with Zod:

▼
typescript
复制代码
import { z } from 'zod' const EventSchema = z.object({ id: z.string(), title: z.string(), date: z.string(), }) export async function getEvents({ timings }: { timings?: Timings } = {}) { return await cachified({ key: 'events:all', cache, timings, getFreshValue: async () => { const response = await fetch('https://api.example.com/events') return await response.json() }, checkValue: EventSchema.array(), // Validates it's an array of events ttl: 1000 * 60 * 60 * 24, // 24 hours }) }

If cached data doesn't pass validation, fresh data is fetched.

Server Timing Integration

Integrate cache with server timing for monitoring:

▼
typescript
复制代码
import { type Timings } from '#app/utils/timing.server.ts' export async function loader({ request }: Route.LoaderArgs) { const timings: Timings = {} const events = await getEvents({ timings }) // Timings are automatically added to headers return json({ events }, { headers: combineServerTimings(timings), }) }

Cache Invalidation

Invalidate by key:

▼
typescript
复制代码
import { cache } from '#app/utils/cache.server.ts' await cache.delete('user:123:profile')

Invalidate multiple keys:

▼
typescript
复制代码
// Search and delete matching keys import { searchCacheKeys } from '#app/utils/cache.server.ts' const keys = await searchCacheKeys('user:123', 100) await Promise.all(keys.map(key => cache.delete(key)))

Invalidate entire SQLite cache:

▼
typescript
复制代码
// Use admin dashboard or await cache.clear() // If available

Using LRU Cache

For temporary data, use LRU cache directly:

▼
typescript
复制代码
import { lru } from '#app/utils/cache.server.ts' // LRU cache is useful for: // - Request deduplication // - Very temporary cache (< 5 minutes) // - Data that doesn't need to persist const cachedValue = lru.get('temp-key') if (!cachedValue) { const freshValue = await computeExpensiveValue() lru.set('temp-key', freshValue, { ttl: 1000 * 60 * 5 }) // 5 minutes return freshValue } return cachedValue

Multi-Region Cache

With LiteFS, SQLite cache is automatically replicated:

Behavior:

  • Only the primary instance writes to cache
  • Replicas can read from cache
  • Writes are automatically synchronized

Best practices:

  • Don't assume all writes are immediate
  • Use ensurePrimary() if you need to guarantee writes
▼
typescript
复制代码
import { ensurePrimary } from '#app/utils/litefs.server.ts' export async function action({ request }: Route.ActionArgs) { await ensurePrimary() // Ensure we're on primary instance // Invalidate cache await cache.delete('my-key') // ... }

Error Handling

Handle errors in getFreshValue:

▼
typescript
复制代码
await cachified({ key: 'my-key', cache, getFreshValue: async () => { try { return await fetchData() } catch (error) { console.error('Failed to fetch fresh data:', error) throw error // Re-throw so cachified handles it } }, // If getFreshValue fails and there's stale cache, it returns it fallbackToCache: true, // Default: true })

Cache Admin Dashboard

Epic Stack includes a dashboard to manage cache:

Route: /admin/cache

Features:

  • View all cache keys
  • Search keys
  • View details of a key
  • Delete keys
  • Clear entire cache

Common examples

Example 1: Cache external API response

▼
typescript
复制代码
// app/utils/api.server.ts import { cachified, cache } from '#app/utils/cache.server.ts' import { type Timings } from '#app/utils/timing.server.ts' import { z } from 'zod' const GitHubEventSchema = z.object({ id: z.string(), type: z.string(), actor: z.object({ login: z.string(), }), created_at: z.string(), }) export async function getGitHubEvents({ username, timings, }: { username: string timings?: Timings }) { return await cachified({ key: `github:${username}:events`, cache, timings, getFreshValue: async () => { const response = await fetch( `https://api.github.com/users/${username}/events/public`, ) if (!response.ok) { throw new Error(`GitHub API error: ${response.statusText}`) } const data = await response.json() return data }, checkValue: GitHubEventSchema.array(), ttl: 1000 * 60 * 60, // 1 hour staleWhileRevalidate: 1000 * 60 * 60 * 24, // 24 hours }) }

Example 2: Cache Prisma query

▼
typescript
复制代码
// app/utils/user.server.ts import { cachified, cache } from '#app/utils/cache.server.ts' import { prisma } from '#app/utils/db.server.ts' import { z } from 'zod' const UserStatsSchema = z.object({ totalNotes: z.number(), totalLikes: z.number(), joinDate: z.string(), }) export async function getUserStats({ userId, timings, }: { userId: string timings?: Timings }) { return await cachified({ key: `user:${userId}:stats`, cache, timings, getFreshValue: async () => { const [totalNotes, totalLikes, user] = await Promise.all([ prisma.note.count({ where: { ownerId: userId } }), prisma.like.count({ where: { userId } }), prisma.user.findUnique({ where: { id: userId }, select: { createdAt: true }, }), ]) return { totalNotes, totalLikes, joinDate: user?.createdAt.toISOString() ?? '', } }, checkValue: UserStatsSchema, ttl: 1000 * 60 * 5, // 5 minutes staleWhileRevalidate: 1000 * 60 * 60, // 1 hour }) }

Example 3: Invalidate cache after mutation

▼
typescript
复制代码
// app/routes/users/$username/notes/new.tsx export async function action({ request }: Route.ActionArgs) { const userId = await requireUserId(request) const formData = await request.formData() // ... validate and create note const note = await prisma.note.create({ data: { title, content, ownerId: userId, }, include: { owner: true }, }) // Invalidate related cache await Promise.all([ cache.delete(`user:${userId}:notes`), cache.delete(`user:${userId}:stats`), cache.delete(`note:${note.id}:full`), ]) return redirect(`/users/${note.owner.username}/notes/${note.id}`) }

Example 4: Cache with dependencies

▼
typescript
复制代码
export async function getUserWithNotes({ userId, timings, }: { userId: string timings?: Timings }) { const user = await cachified({ key: `user:${userId}:profile`, cache, timings, getFreshValue: async () => { return await prisma.user.findUnique({ where: { id: userId }, select: { id: true, username: true, name: true, }, }) }, checkValue: z.object({ id: z.string(), username: z.string(), name: z.string().nullable(), }).nullable(), ttl: 1000 * 60 * 30, // 30 minutes }) const notes = await cachified({ key: `user:${userId}:notes`, cache, timings, getFreshValue: async () => { return await prisma.note.findMany({ where: { ownerId: userId }, select: { id: true, title: true, updatedAt: true, }, orderBy: { updatedAt: 'desc' }, }) }, checkValue: z.array(z.object({ id: z.string(), title: z.string(), updatedAt: z.date(), })), ttl: 1000 * 60 * 10, // 10 minutes }) return { user, notes } }

Example 5: Use LRU for deduplication

▼
typescript
复制代码
// Avoid multiple simultaneous requests to the same URL const requestCache = new Map<string, Promise<any>>() export async function fetchWithDedup(url: string) { if (requestCache.has(url)) { return requestCache.get(url) } const promise = fetch(url).then(res => res.json()) requestCache.set(url, promise) // Clean up after 1 second setTimeout(() => { requestCache.delete(url) }, 1000) return promise }

Common mistakes to avoid

  • ❌ Caching without measuring benefit: Only add cache when there's a clear, measurable performance problem
  • ❌ Caching simple, fast queries: Don't cache data that's already fast to fetch - it adds complexity without benefit
  • ❌ Caching frequently changing data: Cache invalidation becomes more complex than the problem it solves
  • ❌ Caching sensitive data: Never cache passwords, tokens, or sensitive personal data
  • ❌ TTL too long: Avoid very long TTLs (> 1 week) unless absolutely necessary
  • ❌ Not validating cached data: Always use checkValue with Zod to validate data
  • ❌ Forgetting to invalidate cache: Invalidate cache after mutations
  • ❌ Assuming cache always works: Cache can fail, always handle errors
  • ❌ Keys too long or ambiguous: Use consistent and descriptive format
  • ❌ Not using timings: Integrate with server timing for monitoring
  • ❌ Forgetting stale-while-revalidate: Use SWR for better UX when appropriate
  • ❌ Over-caching: Too much caching makes the system harder to understand and debug

References

  • Epic Stack Caching Docs
  • Epic Web Principles
  • @epic-web/cachified
  • app/utils/cache.server.ts - Cache implementation
  • app/routes/admin/cache/ - Admin dashboard
  • app/utils/timing.server.ts - Server timing utilities
数据库

快捷安装

复制到终端去安装 Skill

npxskillsaddepicweb-dev/epic-stack--skill"epic-caching"
站长:程序员鱼皮 老鱼简历 商务合作 增值电信业务经营许可证
2026 鱼皮AI导航 | 沪ICP备19026706号-6
站长:程序员鱼皮 老鱼简历 商务合作 增值电信业务经营许可证
2026 鱼皮AI导航 | 沪ICP备19026706号-6
🔥热门工具
朱雀AI检测朱雀AI检测
朱雀AI检测助手朱雀AI检测助手
LovartLovart
老鱼简历老鱼简历
WritePass官网WritePass官网
面多多面多多
CursorCursor
星月写作星月写作
朱雀AI检测助手朱雀AI检测助手
零感AI零感AI
Skills 推荐
relational-database-mcp-cloudbase
面向 CloudBase 关系型数据库的自动化管理,支持安全执行只读查询、写入与结构变更操作,并可检视及调整表级安全规则,确保在无应用上下文的代理环境中精准控制数据访问与修改权限。
database-index-advisor
通过分析数据库查询负载和现有索引配置,自动识别缺失的高效索引以加速慢查询,同时发现长期未被使用的冗余索引以便清理,从而在提升读取性能的同时节省存储空间并优化写入效率。
detecting-sql-injection-vulnerabilities
自动识别和分析应用程序代码及数据库查询中的 SQL 注入风险,覆盖输入点检测、查询构造审查、参数化验证与安全模式推荐,生成结构化安全报告并提供修复建议。
database
规范 NestJS 应用的数据访问层设计,涵盖 ORM 选型、连接池与分片等可扩展架构,强制使用仓库模式隔离数据库逻辑,通过异步配置加载敏感信息,禁用生产环境自动同步,依赖迁移脚本实现零停机演进,并统一要求分页、索引声明与事务保护。
prisma-schema-helper
提供 Prisma 数据模型定义的自动化辅助能力,涵盖模式校验、关系配置、字段类型推导及迁移脚本生成,支持 Node.js 等后端技术栈的数据库层快速搭建与维护。