Caching | Alepha

alepha@docs:~/docs/guides/data$
cat 2-caching.md
3 min read
Last commit: 
#CachingThe fastest database query is the one you don't make.
Caching in most frameworks involves Redis setup, serialization headaches, and cache invalidation bugs that haunt you at 3 AM. Alepha tries to make it boring.
#Basic Caching with $cacheThe simplest use: cache a function's result.
typescript
import { $cache } from "alepha/cache"; class ProductService {  // cache expensive computation for 10 minutes  getPopularProducts = $cache({    name: "popular-products",    ttl: [10, "minutes"],    handler: async () => {      // this runs only once per 10 minutes      return await this.db.products.findMany({        orderBy: { sales: "desc" },        limit: 100,      });    },  });}
First call: runs the handler, stores result, returns it.
Next calls (within 10 min): returns cached result instantly.
#Caching with ArgumentsMost caches depend on input parameters:
typescript
class UserService {  getUserProfile = $cache({    name: "user-profile",    ttl: [5, "minutes"],    handler: async (userId: string) => {      return await this.db.users.findById(userId);    },  });} // usageconst profile = await this.getUserProfile("user-123");// cached separately for each userId
The cache key automatically includes the arguments. getUserProfile("a") and getUserProfile("b") are cached independently.
#Manual Cache OperationsSometimes you need direct control:
typescript
      
class SessionService {  // define cache without handler  sessions = $cache<UserSession>({    name: "sessions",    ttl: [1, "hour"],  });   async createSession(userId: string): Promise<string> {    const sessionId = crypto.randomUUID();    const session = { userId, createdAt: Date.now() };     // manually set    await this.sessions.set(sessionId, session);     return sessionId;  }   async getSession(sessionId: string): Promise<UserSession | null> {    // manually get    return await this.sessions.get(sessionId);  }   async destroySession(sessionId: string): Promise<void> {    // manually delete    await this.sessions.delete(sessionId);  }}
#Cache InvalidationThe two hardest problems in computer science: cache invalidation and naming things.
#Invalidate by Keytypescript
// delete specific entryawait this.getUserProfile.invalidate("user-123");
#Invalidate by Patterntypescript
// delete all entries matching patternawait this.sessions.invalidate("user:*:sessions");
#Invalidate on EventsCommon pattern: invalidate cache when data changes.
typescript
class UserService {  getUserProfile = $cache({    name: "user-profile",    ttl: [5, "minutes"],    handler: async (userId: string) => {      return await this.db.users.findById(userId);    },  });   async updateProfile(userId: string, data: UpdateData) {    await this.db.users.update(userId, data);     // clear the cache for this user    await this.getUserProfile.invalidate(userId);  }}
#HTTP Response CachingFor API responses, use the cache option on actions:
typescript
class ProductApi {  // cache the entire HTTP response  listProducts = $action({    path: "/products",    cache: true, // uses default settings    handler: async () => {      return await this.db.products.findMany();    },  });   // with custom TTL  getProduct = $action({    path: "/products/:id",    cache: { ttl: [30, "seconds"] },    handler: async ({ params }) => {      return await this.db.products.findById(params.id);    },  });}
This sets proper HTTP headers (Cache-Control, ETag) so browsers and CDNs can cache too.
#ETag SupportAlepha automatically generates ETags for cached responses:
typescript
// first requestGET /products/123-> 200 OK-> ETag: "abc123" // second request with ETagGET /products/123If-None-Match: "abc123"-> 304 Not Modified (no body, saves bandwidth)
You don't write any code for this. It just works.
#Storage Backends
#Memory (Default)typescript
// stored in process memory, lost on restartconst cache = $cache({  name: "my-cache",  ttl: [10, "minutes"],  handler: async () => { /* ... */ },});
Good for: development, single-instance apps, short-lived data.
#Redistypescript
import { RedisCacheProvider } from "alepha/cache/redis"; const alepha = Alepha.create()  .with({ provide: CacheProvider, use: RedisCacheProvider }); // set REDIS_URL in your environment
Good for: production, multi-instance apps, persistent cache.
Your cache code stays the same. Only the provider changes.
#Cache WarmingPre-populate cache on startup:
typescript
class CacheWarmer {  products = $inject(ProductService);   warmup = $hook({    on: "ready",    handler: async () => {      // pre-fetch popular products into cache      await this.products.getPopularProducts();       // pre-fetch top categories      for (const cat of ["electronics", "clothing", "home"]) {        await this.products.getByCategory(cat);      }    },  });}
First users don't wait for cold cache.
#Common Patterns
#Cache AsideThe default pattern. Check cache, if miss, compute and store.
typescript
// this is what $cache does internallyasync getUser(id: string) {  const cached = await cache.get(id);  if (cached) return cached;   const user = await this.db.users.findById(id);  await cache.set(id, user);  return user;} // with $cache, just:getUser = $cache({  name: "users",  ttl: [5, "minutes"],  handler: (id) => this.db.users.findById(id),});
#Write ThroughUpdate cache when writing:
typescript
async updateUser(id: string, data: UpdateData) {  const user = await this.db.users.update(id, data);   // update cache with fresh data  await this.userCache.set(id, user);   return user;}
#Cache Stampede PreventionWhen cache expires, you don't want 1000 requests all hitting the database. Alepha handles this:
typescript
// only one request computes, others waitgetExpensiveData = $cache({  name: "expensive",  ttl: [1, "minute"],  // implicit: lock while computing  handler: async () => {    // only runs once even if 1000 requests hit simultaneously    return await this.heavyComputation();  },});
#Comparison: Redis Direct vs AlephaRedis directly:
typescript
const redis = new Redis(); async function getUser(id: string) {  const cached = await redis.get(`user:${id}`);  if (cached) return JSON.parse(cached);   const user = await db.users.findById(id);  await redis.setex(`user:${id}`, 300, JSON.stringify(user));  return user;} // don't forget to invalidate...async function updateUser(id: string, data: any) {  await db.users.update(id, data);  await redis.del(`user:${id}`);  // easy to forget}
Alepha:
typescript
getUser = $cache({  name: "users",  ttl: [5, "minutes"],  handler: (id) => this.db.users.findById(id),}); // invalidation is explicit, hard to missawait this.getUser.invalidate(id);
Less boilerplate. Serialization handled. TTL is readable.
#When Not To CacheHighly personalized data - Cache hit rate will be low
Frequently changing data - You'll invalidate more than you cache
Security-sensitive data - Stale auth state is dangerous
Write-heavy operations - Cache invalidation overhead
#TipsStart without caching - Add it when you have performance data
Cache at the right layer - Database results, not API responses
Use short TTLs initially - Increase when confident
Log cache hits/misses - Monitor effectiveness
Test invalidation - Stale data causes subtle bugs
#Summary

Need
Solution


Cache function results
$cache({ handler })

Manual cache control
$cache() + set/get/delete

HTTP response caching
$action({ cache: true })

Pattern-based invalidation
cache.invalidate("pattern:*")

Production caching
Swap to RedisCacheProvider
Caching doesn't have to be complicated. Define TTL, define handler, forget about it until you need to invalidate.
On This Page
No headings found...

Need	Solution
Cache function results	`$cache({ handler })`
Manual cache control	`$cache()` + `set/get/delete`
HTTP response caching	`$action({ cache: true })`
Pattern-based invalidation	`cache.invalidate("pattern:*")`
Production caching	Swap to `RedisCacheProvider`

ready
│main│TypeScript
│UTF-8│guides_data_caching.md│