Cache and Lock Boundaries in Elpod

Use Elpod cache and lock primitives with explicit providers; choose durable or distributed adapters for production needs.

Elpod keeps cache and lock dependencies explicit in a Bun and Elysia service. Use these boundaries when repeated reads or concurrent work need coordination, while choosing storage and distributed guarantees for the deployment you run.

The idea

A cache is a shortcut, not the source of truth. A lock is a “one person at a time” sign, not a magic force field. Both are useful precisely because their limits are visible.

How Elpod provides it

Caching is explicit; Elpod never silently caches route results. MemoryCache is useful for development and one-process workloads. It supports TTLs, bounded LRU storage, namespaces, tags, and concurrent-loader coalescing.

import { MemoryCache } from "@elpod/core";

const cache = new MemoryCache({ maxEntries: 10_000 });
const user = await cache.getOrSet(`user:${userId}`, () => users.find(userId), {
  ttlMs: 60_000,
  tags: [`user:${userId}`],
});
cache.invalidateTag(`user:${userId}`);

Use a cache when stale data is acceptable or recomputation is expensive. Use tags to invalidate related entries. The bound covers completed entries and unique in-flight loaders; a full store fails closed instead of evicting active work.

Locks

LockStore and withLock express a critical section. MemoryLockStore is process-local.

import { withLock } from "@elpod/core";

await withLock(lockStore, `user:${userId}`, () => rebuildUser(userId), {
  ttlMs: 10_000,
});

Use locks for stampede protection or a short-lived local critical section. A distributed implementation must make acquisition atomic and protect lease ownership.

Common mistakes

Treating a process-local cache or lock as coordination across replicas.
Caching authorization decisions or tenant data without including the tenant and policy inputs in the key.
Setting a TTL longer than the data’s acceptable staleness.
Holding a lock across slow network calls or user interaction.

Production notes

Implement CacheStore and LockStore with a shared system when replicas need coordination. Preserve getOrSet stampede protection atomically. Plan invalidation, outages, eviction, and observability; Elpod does not provide distributed consistency.

Provider boundaries · Jobs and queues · Rate limiting.