caching-strategies

Caching Strategies

The project employs a dual-layer caching architecture: CDN (HTTP headers) and KV (Cloudflare KV storage).

CDN Layer (HTTP Headers)

Control browser and CDN caching via response headers. Set headers through page routes or Hono routes.

Setting Cache Headers in Page Routes

For TanStack Start routes, set headers in the headers function:

// routes/sitemap[.]xml.ts
export const Route = createFileRoute("/sitemap.xml")({
  headers: () => ({
    "Cache-Control": "public, max-age=3600, s-maxage=3600",
  }),
});

Cache Control Constants (lib/constants.ts)

Predefined constants for common scenarios. Each constant is an object with two headers: Cache-Control (browser) and CDN-Cache-Control (CDN edge). This dual-header pattern lets you control browser and CDN caching independently.

Hono Route Caching

Hono API routes use middleware for cache headers:

// lib/hono/middlewares.ts
app.use("/api/*", cacheMiddleware());

Invalidation

Purge CDN cache using the Cloudflare API:

await purgePostCDNCache(context.env, post.slug);

KV Layer (Cloudflare KV)

Used for persistent caching of longer-lived data (post lists, details).

Cache Key Definition

The CacheKey type supports both strings and readonly arrays (tuples), allowing for type-safe key construction using as const.

// features/cache/types.ts
export type CacheKey =
  | string
  | readonly (string | number | boolean | null | undefined)[];

Cache Key Factory Pattern

Instead of hardcoding key arrays in services, define Cache Key Factories in the feature's schema.ts. This provides a single source of truth and ensures types match the requirements of the cache key.

1. Define Factory in schema.ts

// features/posts/posts.schema.ts
export const POSTS_CACHE_KEYS = {
  /** Post detail cache key (includes version) */
  detail: (version: string, slug: string) => [version, "post", slug] as const,
} as const;

2. Use in Service Layer

Pass the tuple directly to CacheService functions. No spread ([...]) is needed since CacheKey supports readonly arrays.

const version = await CacheService.getVersion(context, "posts:detail");
return await CacheService.get(
  context,
  POSTS_CACHE_KEYS.detail(version, data.slug),
  PostSchema,
  fetcher,
);

Versioned Key Invalidation Strategy

This pattern enables efficient bulk invalidation without iterating through keys:

1. Get Current Version

const version = await CacheService.getVersion(context, "posts:detail");
// Returns "v1", "v2", etc.

2. Bump Version to Invalidate

When data changes, increment the version number:

await CacheService.bumpVersion(context, "posts:detail");
// All old keys with the previous version become unreachable

3. Direct Key Deletion

For single-record invalidation, delete the specific key using the factory:

const version = await CacheService.getVersion(context, "posts:detail");
await CacheService.deleteKey(context, POSTS_CACHE_KEYS.detail(version, slug));

Complete Example

// posts.service.ts
import { POSTS_CACHE_KEYS } from "./posts.schema";

export async function updatePost(
  context: DbContext & { executionCtx: ExecutionContext },
  data: UpdatePostInput,
) {
  // 1. Update in database
  const post = await PostRepo.updatePost(context.db, data);

  // 2. Invalidate KV cache
  await CacheService.bumpVersion(context, "posts:list");
  const version = await CacheService.getVersion(context, "posts:detail");
  await CacheService.deleteKey(context, POSTS_CACHE_KEYS.detail(version, post.slug));

  // 3. Purge CDN cache
  await purgePostCDNCache(context.env, post.slug);

  return post;
}

Cache Namespace Conventions

When to Use Each Layer

Debugging Cache Issues

1. Stale data after update?

   • Check if bumpVersion() was called
   • Verify CDN purge completed
   • Check cache key construction

2. Cache misses?

   • Verify version string consistency
   • Check TTL settings
   • Inspect key serialization

3. Memory issues?

   • Review cached data size
   • Consider selective field caching