@nifrajs/cache 1.1.0

package/README.md

@@ -0,0 +1,54 @@
+# @nifrajs/cache
+
+Typed KV cache for nifra — **TTL**, **stale-while-revalidate**, **tag invalidation**, and **single-flight
+stampede protection** on a **pluggable store** (in-memory by default; bring CF KV / Redis for a shared
+cache). **Dependency-free**; runs on Bun/Node/Deno/Workers.
+
+```ts
+import { createCache } from "@nifrajs/cache"
+
+const cache = createCache({ defaultTtlMs: 30_000 })
+
+// Cache-aside in a loader — one DB hit per key per TTL, even under a stampede:
+export async function loader({ params }) {
+  const user = await cache.wrap(
+    `user:${params.id}`,
+    () => db.users.find(params.id),
+    { ttlMs: 30_000, swrMs: 60_000, tags: [`user:${params.id}`] },
+  )
+  return { user }
+}
+
+// On write, drop everything tagged for that user:
+await cache.invalidateTag(`user:${id}`)
+```
+
+## Semantics
+
+- **`wrap(key, loader, opts)`** — returns the cached value, or runs `loader`, stores, and returns it.
+  - **Fresh** (`now < staleAt`): the cached value, no loader call.
+  - **Stale-but-live** (`staleAt ≤ now < expiresAt`, i.e. within `swrMs`): the stale value is returned
+    **immediately** while a **background** refresh runs (deduped). Latency stays flat; data self-heals.
+  - **Miss/expired**: awaits `loader`. Concurrent misses for the same key share **one** call (no stampede).
+  - A throwing `loader` is **not** cached (and in the background path goes to `onError`, never rejects the caller).
+- **`set` / `get` / `has` / `delete`**, **`invalidateTag(tag)`**, **`clear()`**.
+- TTL: `ttlMs` (→ stale) + optional `swrMs` (→ served-stale window) + optional `tags`.
+
+## Stores
+
+The default `MemoryCache` is in-process with lazy expiry, a tag index, and an optional LRU cap
+(`new MemoryCache({ maxEntries: 10_000 })`). For a cache shared across instances, implement `CacheStore`
+(`get` / `set` / `delete` / `invalidateTag` / `clear`) over CF KV, Redis, etc.:
+
+```ts
+const cache = createCache({ store: new RedisCacheStore(redis) })
+```
+
+On **Cloudflare Workers** the in-memory cache is per-isolate and short-lived — back it with **CF KV** (or
+the Cache API) via a `CacheStore` for anything that should survive across requests/instances.
+
+## API
+
+- `createCache(options?)` → `Cache` — `{ store?, defaultTtlMs?, now?, onError? }`.
+- `cache.wrap(key, loader, { ttlMs?, swrMs?, tags? })` · `get` · `has` · `set` · `delete` · `invalidateTag` · `clear`.
+- `MemoryCache({ maxEntries?, now? })` — the default store; implement `CacheStore` for your own.

package/dist/cache.d.ts

@@ -0,0 +1,4 @@
+import type { Cache, CacheOptions } from "./types.js";
+/** Create a cache over the given (or a fresh in-memory) store. */
+export declare function createCache(options?: CacheOptions): Cache;
+//# sourceMappingURL=cache.d.ts.map

package/dist/cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../src/cache.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,KAAK,EAAE,YAAY,EAAuC,MAAM,YAAY,CAAA;AAE1F,kEAAkE;AAClE,wBAAgB,WAAW,CAAC,OAAO,GAAE,YAAiB,GAAG,KAAK,CAiF7D"}

package/dist/cache.js

@@ -0,0 +1,84 @@
+/**
+ * The cache facade — typed get/set/wrap over a {@link CacheStore}, with TTL, stale-while-revalidate, and
+ * single-flight stampede protection. Mirrors the other nifra primitives: a factory, an injectable clock,
+ * and error isolation (a background revalidation that throws goes to `onError`, never rejects the caller).
+ *
+ *   import { createCache } from "@nifrajs/cache"
+ *
+ *   const cache = createCache({ defaultTtlMs: 30_000 })
+ *   // Cache-aside in a loader — one DB hit per 30s per key, stampede-safe:
+ *   const user = await cache.wrap(`user:${id}`, () => db.user(id), { ttlMs: 30_000, swrMs: 60_000, tags: [`user:${id}`] })
+ *   await cache.invalidateTag(`user:${id}`) // on write
+ */
+import { MemoryCache } from "./memory-cache.js";
+/** Create a cache over the given (or a fresh in-memory) store. */
+export function createCache(options = {}) {
+    const defaultTtlMs = options.defaultTtlMs ?? 60_000;
+    const now = options.now ?? (() => Date.now());
+    // The default store must share the facade's clock, or test-injected timestamps look instantly expired.
+    const store = options.store ?? new MemoryCache({ now });
+    const onError = options.onError ??
+        ((error, key) => console.error(`[nifra/cache] revalidate ${JSON.stringify(key)} failed:`, error));
+    // Single-flight: concurrent loads for the same key share one promise (miss stampede + SWR dedup).
+    const inflight = new Map();
+    async function get(key) {
+        const entry = await store.get(key);
+        return entry === undefined ? undefined : entry.value;
+    }
+    async function has(key) {
+        return (await store.get(key)) !== undefined;
+    }
+    async function set(key, value, opts = {}) {
+        const ttlMs = opts.ttlMs ?? defaultTtlMs;
+        const swrMs = Math.max(0, opts.swrMs ?? 0);
+        const t = now();
+        await store.set(key, { value, staleAt: t + ttlMs, expiresAt: t + ttlMs + swrMs }, opts.tags ?? []);
+    }
+    function load(key, loader, opts) {
+        const existing = inflight.get(key);
+        if (existing !== undefined)
+            return existing;
+        const p = (async () => {
+            const value = await loader();
+            await set(key, value, opts);
+            return value;
+        })().finally(() => {
+            if (inflight.get(key) === p)
+                inflight.delete(key);
+        });
+        inflight.set(key, p);
+        return p;
+    }
+    function revalidate(key, loader, opts) {
+        if (inflight.has(key))
+            return; // a refresh is already running
+        void load(key, loader, opts).catch((error) => {
+            try {
+                onError(error, key);
+            }
+            catch {
+                /* a throwing onError must not surface */
+            }
+        });
+    }
+    async function wrap(key, loader, opts = {}) {
+        const entry = await store.get(key);
+        if (entry !== undefined) {
+            if (now() < entry.staleAt)
+                return entry.value; // fresh hit
+            revalidate(key, loader, opts); // stale-but-live → serve stale, refresh in background
+            return entry.value;
+        }
+        return (await load(key, loader, opts)); // miss → load (single-flight)
+    }
+    return {
+        get,
+        has,
+        set,
+        wrap,
+        delete: (key) => Promise.resolve(store.delete(key)),
+        invalidateTag: (tag) => Promise.resolve(store.invalidateTag(tag)),
+        clear: () => Promise.resolve(store.clear()),
+    };
+}
+//# sourceMappingURL=cache.js.map

package/dist/cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.js","sourceRoot":"","sources":["../src/cache.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * @nifrajs/cache — a typed KV cache for nifra: TTL, stale-while-revalidate, tag invalidation, and
+ * single-flight stampede protection, on a pluggable store (in-memory by default; bring CF KV / Redis for
+ * a shared cache). Dependency-free; runs on Bun/Node/Deno/Workers.
+ *
+ *   import { createCache } from "@nifrajs/cache"
+ *   const cache = createCache()
+ *   const data = await cache.wrap("key", () => expensive(), { ttlMs: 60_000 })
+ */
+export { createCache } from "./cache.js";
+export { MemoryCache, type MemoryCacheOptions } from "./memory-cache.js";
+export type { Cache, CacheOptions, CacheStore, SetOptions, StoredEntry, WrapOptions, } from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AACxC,OAAO,EAAE,WAAW,EAAE,KAAK,kBAAkB,EAAE,MAAM,mBAAmB,CAAA;AACxE,YAAY,EACV,KAAK,EACL,YAAY,EACZ,UAAU,EACV,UAAU,EACV,WAAW,EACX,WAAW,GACZ,MAAM,YAAY,CAAA"}

package/dist/index.js

@@ -0,0 +1,12 @@
+/**
+ * @nifrajs/cache — a typed KV cache for nifra: TTL, stale-while-revalidate, tag invalidation, and
+ * single-flight stampede protection, on a pluggable store (in-memory by default; bring CF KV / Redis for
+ * a shared cache). Dependency-free; runs on Bun/Node/Deno/Workers.
+ *
+ *   import { createCache } from "@nifrajs/cache"
+ *   const cache = createCache()
+ *   const data = await cache.wrap("key", () => expensive(), { ttlMs: 60_000 })
+ */
+export { createCache } from "./cache.js";
+export { MemoryCache } from "./memory-cache.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AACxC,OAAO,EAAE,WAAW,EAA2B,MAAM,mBAAmB,CAAA"}

package/dist/memory-cache.d.ts

@@ -0,0 +1,29 @@
+/**
+ * In-process {@link CacheStore} — a Map with lazy expiry, a tag index for group invalidation, and an
+ * optional LRU cap. Correct for a single instance; for a cache shared across instances/workers, implement
+ * `CacheStore` over CF KV / Redis. Not persisted (a restart empties it).
+ */
+import type { CacheStore, StoredEntry } from "./types.js";
+export interface MemoryCacheOptions {
+    /** Evict the least-recently-used entry once the count exceeds this. `0` (default) = unbounded. */
+    readonly maxEntries?: number;
+    /** Injectable clock (tests). Default `() => Date.now()`. */
+    readonly now?: () => number;
+}
+export declare class MemoryCache implements CacheStore {
+    private readonly rows;
+    private readonly tagIndex;
+    private readonly maxEntries;
+    private readonly now;
+    constructor(options?: MemoryCacheOptions);
+    get(key: string): StoredEntry | undefined;
+    set(key: string, entry: StoredEntry, tags: readonly string[]): void;
+    delete(key: string): void;
+    invalidateTag(tag: string): void;
+    clear(): void;
+    /** Live entry count (for observability/tests). */
+    size(): number;
+    /** Remove a key and unlink it from every tag set it belonged to. */
+    private evict;
+}
+//# sourceMappingURL=memory-cache.d.ts.map

package/dist/memory-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-cache.d.ts","sourceRoot":"","sources":["../src/memory-cache.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AASzD,MAAM,WAAW,kBAAkB;IACjC,kGAAkG;IAClG,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAA;IAC5B,4DAA4D;IAC5D,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAA;CAC5B;AAED,qBAAa,WAAY,YAAW,UAAU;IAE5C,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAyB;IAC9C,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAiC;IAC1D,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAQ;IACnC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAc;gBAEtB,OAAO,GAAE,kBAAuB;IAK5C,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS;IAazC,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,WAAW,EAAE,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,IAAI;IAsBnE,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAIzB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAMhC,KAAK,IAAI,IAAI;IAKb,kDAAkD;IAClD,IAAI,IAAI,MAAM;IAId,oEAAoE;IACpE,OAAO,CAAC,KAAK;CAYd"}

package/dist/memory-cache.js

@@ -0,0 +1,80 @@
+export class MemoryCache {
+    // Map iteration is insertion-ordered, so the first key is the LRU victim; `get`/`set` re-insert to touch.
+    rows = new Map();
+    tagIndex = new Map();
+    maxEntries;
+    now;
+    constructor(options = {}) {
+        this.maxEntries = options.maxEntries ?? 0;
+        this.now = options.now ?? (() => Date.now());
+    }
+    get(key) {
+        const row = this.rows.get(key);
+        if (row === undefined)
+            return undefined;
+        if (this.now() >= row.expiresAt) {
+            this.evict(key);
+            return undefined;
+        }
+        // LRU touch.
+        this.rows.delete(key);
+        this.rows.set(key, row);
+        return { value: row.value, expiresAt: row.expiresAt, staleAt: row.staleAt };
+    }
+    set(key, entry, tags) {
+        this.evict(key); // clear any prior tag links before overwriting
+        this.rows.set(key, {
+            value: entry.value,
+            expiresAt: entry.expiresAt,
+            staleAt: entry.staleAt,
+            tags,
+        });
+        for (const tag of tags) {
+            let set = this.tagIndex.get(tag);
+            if (set === undefined) {
+                set = new Set();
+                this.tagIndex.set(tag, set);
+            }
+            set.add(key);
+        }
+        if (this.maxEntries > 0 && this.rows.size > this.maxEntries) {
+            const oldest = this.rows.keys().next().value;
+            if (oldest !== undefined)
+                this.evict(oldest);
+        }
+    }
+    delete(key) {
+        this.evict(key);
+    }
+    invalidateTag(tag) {
+        const keys = this.tagIndex.get(tag);
+        if (keys === undefined)
+            return;
+        for (const key of [...keys])
+            this.evict(key);
+    }
+    clear() {
+        this.rows.clear();
+        this.tagIndex.clear();
+    }
+    /** Live entry count (for observability/tests). */
+    size() {
+        return this.rows.size;
+    }
+    /** Remove a key and unlink it from every tag set it belonged to. */
+    evict(key) {
+        const row = this.rows.get(key);
+        if (row === undefined)
+            return;
+        this.rows.delete(key);
+        for (const tag of row.tags) {
+            const set = this.tagIndex.get(tag);
+            if (set !== undefined) {
+                set.delete(key);
+                if (set.size === 0)
+                    this.tagIndex.delete(tag);
+            }
+        }
+    }
+}
+//# sourceMappingURL=memory-cache.js.map

package/dist/memory-cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-cache.js","sourceRoot":"","sources":["../src/memory-cache.ts"],"names":[],"mappings":"AAqBA,MAAM,OAAO,WAAW;IACtB,0GAA0G;IACzF,IAAI,GAAG,IAAI,GAAG,EAAe,CAAA;IAC7B,QAAQ,GAAG,IAAI,GAAG,EAAuB,CAAA;IACzC,UAAU,CAAQ;IAClB,GAAG,CAAc;IAElC,YAAY,UAA8B,EAAE;QAC1C,IAAI,CAAC,UAAU,GAAG,OAAO,CAAC,UAAU,IAAI,CAAC,CAAA;QACzC,IAAI,CAAC,GAAG,GAAG,OAAO,CAAC,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,CAAA;IAC9C,CAAC;IAED,GAAG,CAAC,GAAW;QACb,MAAM,GAAG,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;QAC9B,IAAI,GAAG,KAAK,SAAS;YAAE,OAAO,SAAS,CAAA;QACvC,IAAI,IAAI,CAAC,GAAG,EAAE,IAAI,GAAG,CAAC,SAAS,EAAE,CAAC;YAChC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAA;YACf,OAAO,SAAS,CAAA;QAClB,CAAC;QACD,aAAa;QACb,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,CAAA;QACrB,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,GAAG,CAAC,CAAA;QACvB,OAAO,EAAE,KAAK,EAAE,GAAG,CAAC,KAAK,EAAE,SAAS,EAAE,GAAG,CAAC,SAAS,EAAE,OAAO,EAAE,GAAG,CAAC,OAAO,EAAE,CAAA;IAC7E,CAAC;IAED,GAAG,CAAC,GAAW,EAAE,KAAkB,EAAE,IAAuB;QAC1D,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAA,CAAC,+CAA+C;QAC/D,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE;YACjB,KAAK,EAAE,KAAK,CAAC,KAAK;YAClB,SAAS,EAAE,KAAK,CAAC,SAAS;YAC1B,OAAO,EAAE,KAAK,CAAC,OAAO;YACtB,IAAI;SACL,CAAC,CAAA;QACF,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;YACvB,IAAI,GAAG,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;YAChC,IAAI,GAAG,KAAK,SAAS,EAAE,CAAC;gBACtB,GAAG,GAAG,IAAI,GAAG,EAAE,CAAA;gBACf,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,GAAG,EAAE,GAAG,CAAC,CAAA;YAC7B,CAAC;YACD,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;QACd,CAAC;QACD,IAAI,IAAI,CAAC,UAAU,GAAG,CAAC,IAAI,IAAI,CAAC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,UAAU,EAAE,CAAC;YAC5D,MAAM,MAAM,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,CAAA;YAC5C,IAAI,MAAM,KAAK,SAAS;gBAAE,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,CAAA;QAC9C,CAAC;IACH,CAAC;IAED,MAAM,CAAC,GAAW;QAChB,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAA;IACjB,CAAC;IAED,aAAa,CAAC,GAAW;QACvB,MAAM,IAAI,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;QACnC,IAAI,IAAI,KAAK,SAAS;YAAE,OAAM;QAC9B,KAAK,MAAM,GAAG,IAAI,CAAC,GAAG,IAAI,CAAC;YAAE,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAA;IAC9C,CAAC;IAED,KAAK;QACH,IAAI,CAAC,IAAI,CAAC,KAAK,EAAE,CAAA;QACjB,IAAI,CAAC,QAAQ,CAAC,KAAK,EAAE,CAAA;IACvB,CAAC;IAED,kDAAkD;IAClD,IAAI;QACF,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,CAAA;IACvB,CAAC;IAED,oEAAoE;IAC5D,KAAK,CAAC,GAAW;QACvB,MAAM,GAAG,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;QAC9B,IAAI,GAAG,KAAK,SAAS;YAAE,OAAM;QAC7B,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,CAAA;QACrB,KAAK,MAAM,GAAG,IAAI,GAAG,CAAC,IAAI,EAAE,CAAC;YAC3B,MAAM,GAAG,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;YAClC,IAAI,GAAG,KAAK,SAAS,EAAE,CAAC;gBACtB,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAA;gBACf,IAAI,GAAG,CAAC,IAAI,KAAK,CAAC;oBAAE,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,GAAG,CAAC,CAAA;YAC/C,CAAC;QACH,CAAC;IACH,CAAC;CACF"}

package/dist/types.d.ts

@@ -0,0 +1,67 @@
+/**
+ * @nifrajs/cache — types for the typed KV cache.
+ *
+ * The facade ({@link Cache}) is typed + owns TTL/SWR/stampede logic; the {@link CacheStore} is a raw
+ * key→entry adapter (memory by default; bring CF KV / Redis for shared or durable caching). Dependency-free.
+ */
+/** A cached entry as the store holds it. */
+export interface StoredEntry {
+    readonly value: unknown;
+    /** Epoch-ms after which the entry is gone — a miss. */
+    readonly expiresAt: number;
+    /** Epoch-ms after which the entry is stale: still served during the SWR window while a refresh runs.
+     * Equal to `expiresAt` when there's no stale-while-revalidate window. */
+    readonly staleAt: number;
+}
+/**
+ * Raw key→entry storage. The default {@link MemoryCache} is in-process; implement this over CF KV /
+ * Redis / etc. for a cache shared across instances. All methods may be sync or async — the cache awaits them.
+ */
+export interface CacheStore {
+    /** The live entry for `key`, or `undefined` if missing or hard-expired (`now >= expiresAt`). */
+    get(key: string): StoredEntry | undefined | Promise<StoredEntry | undefined>;
+    /** Store `entry` under `key`, indexed by `tags` for {@link CacheStore.invalidateTag}. */
+    set(key: string, entry: StoredEntry, tags: readonly string[]): void | Promise<void>;
+    delete(key: string): void | Promise<void>;
+    /** Drop every entry carrying `tag`. */
+    invalidateTag(tag: string): void | Promise<void>;
+    clear(): void | Promise<void>;
+}
+export interface SetOptions {
+    /** Time-to-live (ms) before the value goes stale. Default: the cache's `defaultTtlMs`. */
+    readonly ttlMs?: number;
+    /** Extra ms past TTL during which the stale value is served while a background refresh runs. Default 0. */
+    readonly swrMs?: number;
+    /** Tags for group invalidation via `invalidateTag`. */
+    readonly tags?: readonly string[];
+}
+export type WrapOptions = SetOptions;
+export interface CacheOptions {
+    /** Storage adapter. Default: a fresh {@link MemoryCache}. */
+    readonly store?: CacheStore;
+    /** Default TTL (ms) for `set`/`wrap` when none is given. Default 60_000. */
+    readonly defaultTtlMs?: number;
+    /** Injectable clock (tests). Default `() => Date.now()`. */
+    readonly now?: () => number;
+    /** Called when a background SWR revalidation throws. Default: `console.error`. */
+    readonly onError?: (error: unknown, key: string) => void;
+}
+export interface Cache {
+    /** The cached value for `key`, or `undefined` if missing/expired. Pass `T` for the value type. */
+    get<T = unknown>(key: string): Promise<T | undefined>;
+    /** Whether a live (non-expired) entry exists. */
+    has(key: string): Promise<boolean>;
+    /** Store `value` under `key`. */
+    set<T>(key: string, value: T, options?: SetOptions): Promise<void>;
+    delete(key: string): Promise<void>;
+    /** Drop every entry tagged `tag`. */
+    invalidateTag(tag: string): Promise<void>;
+    clear(): Promise<void>;
+    /**
+     * Cache-aside: return the cached value, or run `loader`, store the result, and return it. Stampede-safe
+     * (concurrent misses for one key share a single `loader` call) and SWR-aware (a stale-but-live value is
+     * returned immediately while a deduped background refresh runs). A throwing `loader` is NOT cached.
+     */
+    wrap<T>(key: string, loader: () => T, options?: WrapOptions): Promise<Awaited<T>>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,4CAA4C;AAC5C,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAA;IACvB,uDAAuD;IACvD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B;6EACyE;IACzE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CACzB;AAED;;;GAGG;AACH,MAAM,WAAW,UAAU;IACzB,gGAAgG;IAChG,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS,GAAG,OAAO,CAAC,WAAW,GAAG,SAAS,CAAC,CAAA;IAC5E,yFAAyF;IACzF,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,WAAW,EAAE,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACnF,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACzC,uCAAuC;IACvC,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAChD,KAAK,IAAI,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CAC9B;AAED,MAAM,WAAW,UAAU;IACzB,0FAA0F;IAC1F,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;IACvB,2GAA2G;IAC3G,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;IACvB,uDAAuD;IACvD,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;CAClC;AAED,MAAM,MAAM,WAAW,GAAG,UAAU,CAAA;AAEpC,MAAM,WAAW,YAAY;IAC3B,6DAA6D;IAC7D,QAAQ,CAAC,KAAK,CAAC,EAAE,UAAU,CAAA;IAC3B,4EAA4E;IAC5E,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAA;IAC9B,4DAA4D;IAC5D,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAA;IAC3B,kFAAkF;IAClF,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,KAAK,IAAI,CAAA;CACzD;AAED,MAAM,WAAW,KAAK;IACpB,kGAAkG;IAClG,GAAG,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC,CAAA;IACrD,iDAAiD;IACjD,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;IAClC,iCAAiC;IACjC,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,OAAO,CAAC,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAClE,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAClC,qCAAqC;IACrC,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACzC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;IACtB;;;;OAIG;IACH,IAAI,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAA;CAClF"}

package/dist/types.js

@@ -0,0 +1,8 @@
+/**
+ * @nifrajs/cache — types for the typed KV cache.
+ *
+ * The facade ({@link Cache}) is typed + owns TTL/SWR/stampede logic; the {@link CacheStore} is a raw
+ * key→entry adapter (memory by default; bring CF KV / Redis for shared or durable caching). Dependency-free.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG"}

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@nifrajs/cache",
+  "version": "1.1.0",
+  "description": "Typed KV cache for nifra — TTL, stale-while-revalidate, tag invalidation, and single-flight stampede protection on a pluggable store (in-memory default; bring CF KV / Redis). Dependency-free, runs on Bun/Node/Deno/Workers.",
+  "keywords": [
+    "bun",
+    "typescript",
+    "nifra",
+    "web-framework",
+    "full-stack",
+    "edge",
+    "ssr"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "bun": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json && bun run ../../scripts/fix-dts.ts dist"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nifrajs/nifra.git",
+    "directory": "packages/cache"
+  },
+  "bugs": {
+    "url": "https://github.com/nifrajs/nifra/issues"
+  },
+  "homepage": "https://github.com/nifrajs/nifra#readme"
+}

package/src/cache.ts

@@ -0,0 +1,98 @@
+/**
+ * The cache facade — typed get/set/wrap over a {@link CacheStore}, with TTL, stale-while-revalidate, and
+ * single-flight stampede protection. Mirrors the other nifra primitives: a factory, an injectable clock,
+ * and error isolation (a background revalidation that throws goes to `onError`, never rejects the caller).
+ *
+ *   import { createCache } from "@nifrajs/cache"
+ *
+ *   const cache = createCache({ defaultTtlMs: 30_000 })
+ *   // Cache-aside in a loader — one DB hit per 30s per key, stampede-safe:
+ *   const user = await cache.wrap(`user:${id}`, () => db.user(id), { ttlMs: 30_000, swrMs: 60_000, tags: [`user:${id}`] })
+ *   await cache.invalidateTag(`user:${id}`) // on write
+ */
+import { MemoryCache } from "./memory-cache.ts"
+import type { Cache, CacheOptions, CacheStore, SetOptions, WrapOptions } from "./types.ts"
+
+/** Create a cache over the given (or a fresh in-memory) store. */
+export function createCache(options: CacheOptions = {}): Cache {
+  const defaultTtlMs = options.defaultTtlMs ?? 60_000
+  const now = options.now ?? (() => Date.now())
+  // The default store must share the facade's clock, or test-injected timestamps look instantly expired.
+  const store: CacheStore = options.store ?? new MemoryCache({ now })
+  const onError =
+    options.onError ??
+    ((error, key) =>
+      console.error(`[nifra/cache] revalidate ${JSON.stringify(key)} failed:`, error))
+
+  // Single-flight: concurrent loads for the same key share one promise (miss stampede + SWR dedup).
+  const inflight = new Map<string, Promise<unknown>>()
+
+  async function get<T = unknown>(key: string): Promise<T | undefined> {
+    const entry = await store.get(key)
+    return entry === undefined ? undefined : (entry.value as T)
+  }
+
+  async function has(key: string): Promise<boolean> {
+    return (await store.get(key)) !== undefined
+  }
+
+  async function set<T>(key: string, value: T, opts: SetOptions = {}): Promise<void> {
+    const ttlMs = opts.ttlMs ?? defaultTtlMs
+    const swrMs = Math.max(0, opts.swrMs ?? 0)
+    const t = now()
+    await store.set(
+      key,
+      { value, staleAt: t + ttlMs, expiresAt: t + ttlMs + swrMs },
+      opts.tags ?? [],
+    )
+  }
+
+  function load(key: string, loader: () => unknown, opts: WrapOptions): Promise<unknown> {
+    const existing = inflight.get(key)
+    if (existing !== undefined) return existing
+    const p = (async () => {
+      const value = await loader()
+      await set(key, value, opts)
+      return value
+    })().finally(() => {
+      if (inflight.get(key) === p) inflight.delete(key)
+    })
+    inflight.set(key, p)
+    return p
+  }
+
+  function revalidate(key: string, loader: () => unknown, opts: WrapOptions): void {
+    if (inflight.has(key)) return // a refresh is already running
+    void load(key, loader, opts).catch((error) => {
+      try {
+        onError(error, key)
+      } catch {
+        /* a throwing onError must not surface */
+      }
+    })
+  }
+
+  async function wrap<T>(
+    key: string,
+    loader: () => T,
+    opts: WrapOptions = {},
+  ): Promise<Awaited<T>> {
+    const entry = await store.get(key)
+    if (entry !== undefined) {
+      if (now() < entry.staleAt) return entry.value as Awaited<T> // fresh hit
+      revalidate(key, loader as () => unknown, opts) // stale-but-live → serve stale, refresh in background
+      return entry.value as Awaited<T>
+    }
+    return (await load(key, loader as () => unknown, opts)) as Awaited<T> // miss → load (single-flight)
+  }
+
+  return {
+    get,
+    has,
+    set,
+    wrap,
+    delete: (key) => Promise.resolve(store.delete(key)),
+    invalidateTag: (tag) => Promise.resolve(store.invalidateTag(tag)),
+    clear: () => Promise.resolve(store.clear()),
+  }
+}

package/src/index.ts

@@ -0,0 +1,20 @@
+/**
+ * @nifrajs/cache — a typed KV cache for nifra: TTL, stale-while-revalidate, tag invalidation, and
+ * single-flight stampede protection, on a pluggable store (in-memory by default; bring CF KV / Redis for
+ * a shared cache). Dependency-free; runs on Bun/Node/Deno/Workers.
+ *
+ *   import { createCache } from "@nifrajs/cache"
+ *   const cache = createCache()
+ *   const data = await cache.wrap("key", () => expensive(), { ttlMs: 60_000 })
+ */
+
+export { createCache } from "./cache.ts"
+export { MemoryCache, type MemoryCacheOptions } from "./memory-cache.ts"
+export type {
+  Cache,
+  CacheOptions,
+  CacheStore,
+  SetOptions,
+  StoredEntry,
+  WrapOptions,
+} from "./types.ts"

package/src/memory-cache.ts

@@ -0,0 +1,102 @@
+/**
+ * In-process {@link CacheStore} — a Map with lazy expiry, a tag index for group invalidation, and an
+ * optional LRU cap. Correct for a single instance; for a cache shared across instances/workers, implement
+ * `CacheStore` over CF KV / Redis. Not persisted (a restart empties it).
+ */
+import type { CacheStore, StoredEntry } from "./types.ts"
+
+interface Row {
+  value: unknown
+  expiresAt: number
+  staleAt: number
+  tags: readonly string[]
+}
+
+export interface MemoryCacheOptions {
+  /** Evict the least-recently-used entry once the count exceeds this. `0` (default) = unbounded. */
+  readonly maxEntries?: number
+  /** Injectable clock (tests). Default `() => Date.now()`. */
+  readonly now?: () => number
+}
+
+export class MemoryCache implements CacheStore {
+  // Map iteration is insertion-ordered, so the first key is the LRU victim; `get`/`set` re-insert to touch.
+  private readonly rows = new Map<string, Row>()
+  private readonly tagIndex = new Map<string, Set<string>>()
+  private readonly maxEntries: number
+  private readonly now: () => number
+
+  constructor(options: MemoryCacheOptions = {}) {
+    this.maxEntries = options.maxEntries ?? 0
+    this.now = options.now ?? (() => Date.now())
+  }
+
+  get(key: string): StoredEntry | undefined {
+    const row = this.rows.get(key)
+    if (row === undefined) return undefined
+    if (this.now() >= row.expiresAt) {
+      this.evict(key)
+      return undefined
+    }
+    // LRU touch.
+    this.rows.delete(key)
+    this.rows.set(key, row)
+    return { value: row.value, expiresAt: row.expiresAt, staleAt: row.staleAt }
+  }
+
+  set(key: string, entry: StoredEntry, tags: readonly string[]): void {
+    this.evict(key) // clear any prior tag links before overwriting
+    this.rows.set(key, {
+      value: entry.value,
+      expiresAt: entry.expiresAt,
+      staleAt: entry.staleAt,
+      tags,
+    })
+    for (const tag of tags) {
+      let set = this.tagIndex.get(tag)
+      if (set === undefined) {
+        set = new Set()
+        this.tagIndex.set(tag, set)
+      }
+      set.add(key)
+    }
+    if (this.maxEntries > 0 && this.rows.size > this.maxEntries) {
+      const oldest = this.rows.keys().next().value
+      if (oldest !== undefined) this.evict(oldest)
+    }
+  }
+
+  delete(key: string): void {
+    this.evict(key)
+  }
+
+  invalidateTag(tag: string): void {
+    const keys = this.tagIndex.get(tag)
+    if (keys === undefined) return
+    for (const key of [...keys]) this.evict(key)
+  }
+
+  clear(): void {
+    this.rows.clear()
+    this.tagIndex.clear()
+  }
+
+  /** Live entry count (for observability/tests). */
+  size(): number {
+    return this.rows.size
+  }
+
+  /** Remove a key and unlink it from every tag set it belonged to. */
+  private evict(key: string): void {
+    const row = this.rows.get(key)
+    if (row === undefined) return
+    this.rows.delete(key)
+    for (const tag of row.tags) {
+      const set = this.tagIndex.get(tag)
+      if (set !== undefined) {
+        set.delete(key)
+        if (set.size === 0) this.tagIndex.delete(tag)
+      }
+    }
+  }
+}

package/src/types.ts

@@ -0,0 +1,72 @@
+/**
+ * @nifrajs/cache — types for the typed KV cache.
+ *
+ * The facade ({@link Cache}) is typed + owns TTL/SWR/stampede logic; the {@link CacheStore} is a raw
+ * key→entry adapter (memory by default; bring CF KV / Redis for shared or durable caching). Dependency-free.
+ */
+
+/** A cached entry as the store holds it. */
+export interface StoredEntry {
+  readonly value: unknown
+  /** Epoch-ms after which the entry is gone — a miss. */
+  readonly expiresAt: number
+  /** Epoch-ms after which the entry is stale: still served during the SWR window while a refresh runs.
+   * Equal to `expiresAt` when there's no stale-while-revalidate window. */
+  readonly staleAt: number
+}
+
+/**
+ * Raw key→entry storage. The default {@link MemoryCache} is in-process; implement this over CF KV /
+ * Redis / etc. for a cache shared across instances. All methods may be sync or async — the cache awaits them.
+ */
+export interface CacheStore {
+  /** The live entry for `key`, or `undefined` if missing or hard-expired (`now >= expiresAt`). */
+  get(key: string): StoredEntry | undefined | Promise<StoredEntry | undefined>
+  /** Store `entry` under `key`, indexed by `tags` for {@link CacheStore.invalidateTag}. */
+  set(key: string, entry: StoredEntry, tags: readonly string[]): void | Promise<void>
+  delete(key: string): void | Promise<void>
+  /** Drop every entry carrying `tag`. */
+  invalidateTag(tag: string): void | Promise<void>
+  clear(): void | Promise<void>
+}
+
+export interface SetOptions {
+  /** Time-to-live (ms) before the value goes stale. Default: the cache's `defaultTtlMs`. */
+  readonly ttlMs?: number
+  /** Extra ms past TTL during which the stale value is served while a background refresh runs. Default 0. */
+  readonly swrMs?: number
+  /** Tags for group invalidation via `invalidateTag`. */
+  readonly tags?: readonly string[]
+}
+
+export type WrapOptions = SetOptions
+
+export interface CacheOptions {
+  /** Storage adapter. Default: a fresh {@link MemoryCache}. */
+  readonly store?: CacheStore
+  /** Default TTL (ms) for `set`/`wrap` when none is given. Default 60_000. */
+  readonly defaultTtlMs?: number
+  /** Injectable clock (tests). Default `() => Date.now()`. */
+  readonly now?: () => number
+  /** Called when a background SWR revalidation throws. Default: `console.error`. */
+  readonly onError?: (error: unknown, key: string) => void
+}
+
+export interface Cache {
+  /** The cached value for `key`, or `undefined` if missing/expired. Pass `T` for the value type. */
+  get<T = unknown>(key: string): Promise<T | undefined>
+  /** Whether a live (non-expired) entry exists. */
+  has(key: string): Promise<boolean>
+  /** Store `value` under `key`. */
+  set<T>(key: string, value: T, options?: SetOptions): Promise<void>
+  delete(key: string): Promise<void>
+  /** Drop every entry tagged `tag`. */
+  invalidateTag(tag: string): Promise<void>
+  clear(): Promise<void>
+  /**
+   * Cache-aside: return the cached value, or run `loader`, store the result, and return it. Stampede-safe
+   * (concurrent misses for one key share a single `loader` call) and SWR-aware (a stale-but-live value is
+   * returned immediately while a deduped background refresh runs). A throwing `loader` is NOT cached.
+   */
+  wrap<T>(key: string, loader: () => T, options?: WrapOptions): Promise<Awaited<T>>
+}