repletes - v1.1.0
    Preparing search index...

    API guide

    Everything is exported from the package root. All durations are milliseconds, measured against the clock the Cache was constructed with.

    store and freshness are required. Everything else is optional.

    Option Description
    store Where entries live. See Stores.
    freshness Decides whether a completed value is stored, and with which windows. See Freshness.
    namespace Prefixed onto every key as namespace:.
    version Prefixed after the namespace. Bump it to orphan every entry written in an old shape.
    now The clock. Defaults to Date.now. Swap it in tests.
    onEvent Receives every event. A listener that throws is ignored.

    Construct one cache per kind of value and share it. Keep it outside your retry and rate-limit layers, so that only a miss turns into a call.

    Returns the value. On a miss, an error thrown by action is rethrown as it was, never wrapped. If the entry is inside its staleIfError window, the old value is served instead.

    The same as wrap, but returns { value, state, age }. state is fresh, stale, retained or miss; age is the served entry's age, and 0 when the action produced the value.

    An action receives whatever the store still holds for the key, in any state, or undefined if it holds nothing. Use it to revalidate, for example by sending the old ETag.

    await cache.wrap(key, async (previous) => {
    const headers = previous ? { "If-None-Match": previous.value.etag } : {};
    return fetchItem(key, headers);
    });

    A key is a non-empty string, or any method that takes one throws invalid-key. The namespace and version are prefixed; nothing else is done to it. If your key comes from hashing a request body, await the hash before calling wrap.

    Method What it does
    peek(key) Reads the store without calling an action or starting a refresh. Returns { value, state, age }, or undefined if nothing readable is stored.
    forget(key) Deletes one key. Deciding when a write has made a cached read wrong is up to you.
    clear() Empties the whole store, including entries from other caches sharing it. Throws clear-unsupported if the store has no clear.
    settled() Resolves when no background refresh is running. For tests and shutdown.

    A freshness policy is a function (value: T) => Windows | undefined. Returning undefined skips the write. Every window must be a finite number >= 0, or Repletes throws invalid-windows.

    The same windows for every value.

    fixed({ freshFor: 30_000, staleWhileRevalidate: 60_000, staleIfError: 300_000 });
    

    Takes the windows from the value's Cache-Control header. The value must look like { headers, status? }, where headers is either an object with get(name) (a Headers) or an array of [name, value] pairs. Store the pairs, because a Headers object does not survive serialisation.

    import { Cache, MemoryStore, fromCacheControl } from "repletes";

    interface Page {
    status: number;
    headers: [string, string][];
    body: string;
    }

    const pages = new Cache<Page>({
    store: new MemoryStore({ maxEntries: 500 }),
    freshness: fromCacheControl({
    fallback: { freshFor: 10_000, staleWhileRevalidate: 30_000, staleIfError: 60_000 },
    }),
    });

    const page = await pages.wrap(url, async () => {
    const res = await fetch(url);
    return { status: res.status, headers: [...res.headers], body: await res.text() };
    });

    It reads no-store, no-cache, private, max-age, s-maxage, stale-while-revalidate and stale-if-error, and ignores the rest of RFC 9111. It skips the write for no-store, for private when shared is true, and for any status storable rejects. no-cache stores the value with freshFor: 0 and staleWhileRevalidate: 0, so every read revalidates; it is served stale only if the response itself carries stale-if-error, never from your defaults.

    Option Description
    fallback Required. The windows used for anything the header does not set.
    shared Default true: prefer s-maxage and refuse private. Set false for a per-user cache.
    staleWhileRevalidate Used instead of fallback.staleWhileRevalidate when the header has none.
    staleIfError Used instead of fallback.staleIfError when the header has none.
    storable (status) => boolean. Default: 2xx only.
    new MemoryStore({ maxEntries: 1_000 });
    

    An in-process Map. maxEntries is required; past it, the least recently used entry is evicted. Entries past their retention are dropped when read. size reports how many entries it holds. It takes an optional now clock for expiry.

    Implement Store<T>. Every method is async, so a networked store fits the same interface. clear is optional.

    import type { Entry, Store } from "repletes";

    class RedisStore<T> implements Store<T> {
    async get(key: string): Promise<Entry<T> | undefined> { /* ... */ }
    async set(key: string, entry: Entry<T>, retainFor: number): Promise<void> { /* ... */ }
    async delete(key: string): Promise<void> { /* ... */ }
    async clear(): Promise<void> { /* optional */ }
    }

    retainFor is a hint for when the entry can be thrown away, for example a Redis PX. Repletes checks the windows again when it reads, so a store that keeps entries longer is still correct.

    A store that throws never fails a call; see Known quirks. The error is reported as a store-error event.

    The Codec<T, Wire> type (encode and decode) is exported so out-of-process stores agree on one serialisation shape. Repletes does not call it.

    onEvent receives one of these objects. Each read that returns a value emits exactly one hit or one miss.

    type Emitted when Extra fields
    hit A value was served from the store state, age
    miss The action produced the value
    write An entry was stored retainFor
    skip The freshness policy declined the write
    refresh A background refresh finished ok
    served-stale A retained value was served because the action threw age
    action-error The action threw, anywhere error, background
    store-error A store call threw operation, error

    action-error fires on a miss, under a retained entry, and behind a stale read, so the upstream failure rate is a single count. background is true for the refresh case.

    Repletes throws only for caller mistakes, as a RepletesError (which extends TypeError). Match on code:

    code Cause
    invalid-windows A window is negative, infinite or not a number.
    invalid-key The key is not a non-empty string.
    invalid-capacity maxEntries is not a positive integer.
    clear-unsupported clear() was called on a store without clear.

    The function behind every read. Given an entry (or undefined) and a timestamp, it returns the state with the value and age. It does no I/O, so you can reuse it if you build your own layer. A storedAt in the future is treated as age 0.