repletes - v1.1.0
    Preparing search index...

    repletes - v1.1.0

    Repletes

    repletes logo

    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.

    • HTTP caching. fromCacheControl reads Cache-Control off anything shaped like a response; fetching, serialising and storing are yours.
    • Retries, deadlines, rate limits and single-flight. Use Firefly, inside the action, so a cache hit never uses a retry or rate-limit slot.
    • Describing the HTTP API the action calls. Use Aphid.
    • Writing values into the cache directly. There is no put.
    • Default windows. There are none; you pick them per kind of data.
    • Key hashing or normalisation. Do it before wrap.
    • Concurrent misses on the same key each call the action. Only background refreshes are deduplicated.
    • 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.
    • Store errors do not fail a read. A failed get counts as a miss and a failed set skips the write; both are reported only through onEvent.

    ISC

    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.