Caching

Typed Redis cache examples, stampede protection, and cache boundaries.

Caching

Complete Example

import { loadService } from '@hile/core'
import redisService from '@hile/ioredis'
import { Cache, defineCache, RedisCache } from '@hile/cache'

const userProfileCache = defineCache(
  'user:{id:string}:profile',
  async ({ id }) => {
    const profile = await loadProfileFromDatabase(id)
    if (!profile) return new Cache(undefined)
    return new Cache(profile).setExpire(300)
  },
  {
    singleflight: { ttl: 10_000, wait: 10_000 },
    stale: { ttl: 60 },
    negative: { ttl: 30 },
    tags: (params, data) => data ? [`user:${params.id}`] : [],
  },
)

const redis = await loadService(redisService)
const cache = new RedisCache('app:', redis)
const userProfiles = await cache.loadCache(userProfileCache)

const profile = await userProfiles.read({ id: 'u1' })
await userProfiles.remove({ id: 'u1' })
await cache.removeTag('user:u1')

Runtime And Lifecycle Notes

• Cache(undefined) removes the key unless negative caching is configured.
• Cache#setExpire(seconds) uses seconds.
• defineCache typed placeholders support string, number, and boolean.
• RedisCache.loadCache() returns read, write, remove, has, and multi.
• RedisCache.removeTag(tag) removes tagged cache entries.
• fieldable caches use Redis hashes and cannot combine with stale or negative cache options.
• Scheduler.add() supports cron strings and { delay }.
• Scheduler.load() reads default exports from *.schedule.* files produced by defineJob().
• scanDirectory() matches .ts, .js, .tsx, .jsx, and .mjs.
• scanDirectory() only parses and returns the structured route when routing consumers opt in with fileRoutes: true; that AST covers the file-relative route while routePath retains the configured prefix. This keeps router-native prefixes out of the portable file-name DSL and preserves non-routing loaders’ filename contracts. .d.ts and source-map files do not match.
• parseFileRoute() accepts static, [id], and final required [...paths] segments, and rejects duplicate or object-meta dynamic names. compileFileRoute() targets either find-my-way or rou3, compiles configured native or bracket-style prefixes separately, and rejects parameter-name collisions across the complete route.

Anti-Patterns

• Returning raw values from defineCache handlers instead of new Cache(value).
• Treating cache as source of truth.
• Forgetting to destroy manually created Redis or TypeORM clients.
• Scheduling jobs without idempotency when side effects can repeat.