Caching Strategies

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