
A cache for the results of async calls that tells you whether you got a fresh value or an old one kept because the upstream failed.
You give it a key, a store and the time windows. It decides whether to serve the cached value, refresh it in the background, call the action, or fall back to the old value when the action throws. The windows are RFC 5861's stale-while-revalidate and stale-if-error. No runtime dependencies.
Node 22 or newer, ESM only, types included.
npm install repletes
import { Cache, MemoryStore, fixed } from "repletes";
interface User {
id: string;
name: string;
}
const users = new Cache<User>({
store: new MemoryStore({ maxEntries: 1_000 }),
freshness: fixed({
freshFor: 30_000,
staleWhileRevalidate: 60_000,
staleIfError: 300_000,
}),
namespace: "users",
version: 1,
});
async function loadUser(id: string): Promise<User> {
const res = await fetch(`https://api.example.com/users/${id}`);
if (!res.ok) throw new Error(`upstream returned ${res.status}`);
return (await res.json()) as User;
}
const id = "1";
const { value, state, age } = await users.read(`user:${id}`, () => loadUser(id));
if (state === "retained") {
console.warn(`upstream failed, serving a user from ${age}ms ago`);
}
With these numbers a user is served from memory for 30 seconds, then for 60 more seconds while a refresh runs behind it. After that, up to 5.5 minutes old (freshFor + staleIfError), it is served only if loadUser throws.
wrap does the same and returns just the value. Call forget(key) after a write that makes the cached value wrong, and settled() in tests or on shutdown to wait for background refreshes. To take the windows from the upstream's Cache-Control header, use fromCacheControl instead of fixed (example).
Every entry stores its own windows, in milliseconds from when it was written:
| Age of the entry | State | What a read does |
|---|---|---|
up to freshFor |
fresh |
Serves it. The action does not run. |
up to freshFor + staleWhileRevalidate |
stale |
Serves it now and refreshes in the background, one refresh per key. |
up to freshFor + staleIfError |
retained |
Calls the action and waits. Serves the old value only if the action throws. |
| past both, or nothing stored | miss |
Calls the action. If it throws, your error is rethrown unchanged. |
How retention and failed refreshes are handled is in Design and scope.
fromCacheControl reads Cache-Control off anything shaped like a response; fetching, serialising and storing are yours.put.wrap.clear() empties the whole store. If several caches share one store, it clears all of them, whatever their namespace.MemoryStore is per process. Two processes with their own MemoryStore do not see each other's entries.get counts as a miss and a failed set skips the write; both are reported only through onEvent.Repletes are not a species of insect, and the logo isn't really accurate. Repletes are a caste of ants that hang from the nest roof as living food storage for the colony. Only about 20 of the thousands of ant species have them.