@basaltkit/cache 1.1.0 → 1.2.1

package/README.md

@@ -1,3 +1,9 @@
+<p align="center">
+  <a href="https://basaltkit-docs.pages.dev">
+    <img src="https://basaltkit-docs.pages.dev/social-card.png" alt="Basalt" width="440">
+  </a>
+</p>
+
 # @basaltkit/cache
 
 Basalt's cache layer: stores the results of slow operations (database queries, external API calls, heavy computations) so they can be returned instantly next time. You need this module when your application repeats the same work over and over and you want to make it faster and cheaper.
@@ -95,6 +101,27 @@ const plans = await cache.remember('plans', '1h', async () => {
 })
 ```
 
+### Stale-while-revalidate (serve fast, refresh in the background)
+
+For values that are expensive to build but tolerate being *slightly* out of date
+(dashboards, feeds, pricing pages), pass `{ ttl, staleFor }` instead of a plain
+TTL. The value is **fresh** for `ttl`; for a further `staleFor` window a read gets
+the **stale** value **instantly** while a single background revalidation refreshes
+it. Only after `ttl + staleFor` does a read block on the factory again:
+
+```ts
+const feed = await cache.remember('feed', { ttl: '1m', staleFor: '10m' }, () => buildFeed())
+//  0–1m   → fresh, served from cache
+//  1–11m  → stale value returned immediately; ONE background refresh runs
+//  > 11m  → hard-expired; the next read blocks and recomputes
+```
+
+No caller ever waits for a refresh during the stale window, and concurrent stale
+reads trigger only **one** background revalidation (same stampede protection as
+`remember`). If a background refresh throws, the stale value keeps being served
+until it hard-expires — a failing upstream never turns into an error for the user.
+Works with `tags(...)` too: `cache.tags('feed').remember(key, { ttl, staleFor }, fn)`.
+
 ### Deleting entries (`forget` / `flush`)
 
 ```ts
@@ -173,7 +200,7 @@ const cacheB = new Cache(new RedisCacheDriver(redis))
 |---|---|---|
 | `get` | `get<T>(key: string): Promise<T \| undefined>` / `get<T>(key: string, fallback: T): Promise<T>` | Reads a value; returns `undefined` (or the `fallback`) on miss/expiration. |
 | `put` | `put(key: string, value: unknown, ttl?: DurationInput): Promise<void>` | Stores a value, with an optional TTL. |
-| `remember` | `remember<T>(key: string, ttl: DurationInput, factory: () => Promise<T> \| T): Promise<T>` | Returns the cached value or runs the `factory` (only once, even with concurrent calls) and stores the result. |
+| `remember` | `remember<T>(key, ttl: DurationInput, factory): Promise<T>` — or `remember<T>(key, { ttl, staleFor }: SwrOptions, factory)` | Cache-aside with stampede protection. With `{ ttl, staleFor }` it becomes stale-while-revalidate: serves a stale value while refreshing once in the background. |
 | `forget` | `forget(key: string): Promise<boolean>` | Deletes a key; `true` if it existed. |
 | `flush` | `flush(): Promise<void>` | Deletes all keys in the current prefix/scope. |
 | `tags` | `tags(...tags: string[])` | Returns an object with `put`, `remember` and `flush` scoped to the given tags. |

package/dist/driver.d.ts

@@ -0,0 +1,12 @@
+/** Cache driver contract. Every driver passes the same conformance suite. */
+export interface CacheDriver {
+    /** Returns the value, or undefined on miss/expired. */
+    get(key: string): Promise<unknown>;
+    set(key: string, value: unknown, ttlMs?: number, tags?: string[]): Promise<void>;
+    delete(key: string): Promise<boolean>;
+    /** Removes all keys starting with the prefix. */
+    flushPrefix(prefix: string): Promise<void>;
+    /** Removes all keys associated with any of the tags. */
+    flushTags(tags: string[]): Promise<void>;
+    disconnect(): Promise<void>;
+}

package/dist/driver.js

@@ -0,0 +1 @@
+export {};

package/dist/drivers/memory.d.ts

@@ -0,0 +1,10 @@
+import type { CacheDriver } from '../driver.js';
+export declare class MemoryCacheDriver implements CacheDriver {
+    private readonly store;
+    get(key: string): Promise<unknown>;
+    set(key: string, value: unknown, ttlMs?: number, tags?: string[]): Promise<void>;
+    delete(key: string): Promise<boolean>;
+    flushPrefix(prefix: string): Promise<void>;
+    flushTags(tags: string[]): Promise<void>;
+    disconnect(): Promise<void>;
+}

package/dist/drivers/memory.js

@@ -0,0 +1,38 @@
+export class MemoryCacheDriver {
+    store = new Map();
+    async get(key) {
+        const entry = this.store.get(key);
+        if (!entry)
+            return undefined;
+        if (entry.expiresAt !== undefined && Date.now() >= entry.expiresAt) {
+            this.store.delete(key);
+            return undefined;
+        }
+        return entry.value;
+    }
+    async set(key, value, ttlMs, tags = []) {
+        this.store.set(key, {
+            value,
+            ...(ttlMs !== undefined ? { expiresAt: Date.now() + ttlMs } : {}),
+            tags: new Set(tags),
+        });
+    }
+    async delete(key) {
+        return this.store.delete(key);
+    }
+    async flushPrefix(prefix) {
+        for (const key of this.store.keys()) {
+            if (key.startsWith(prefix))
+                this.store.delete(key);
+        }
+    }
+    async flushTags(tags) {
+        for (const [key, entry] of this.store) {
+            if (tags.some((tag) => entry.tags.has(tag)))
+                this.store.delete(key);
+        }
+    }
+    async disconnect() {
+        this.store.clear();
+    }
+}

package/dist/drivers/redis.d.ts

@@ -0,0 +1,13 @@
+import { Redis } from 'ioredis';
+import type { CacheDriver } from '../driver.js';
+export declare class RedisCacheDriver implements CacheDriver {
+    private readonly redis;
+    constructor(redis: Redis);
+    static fromUrl(url: string): RedisCacheDriver;
+    get(key: string): Promise<unknown>;
+    set(key: string, value: unknown, ttlMs?: number, tags?: string[]): Promise<void>;
+    delete(key: string): Promise<boolean>;
+    flushPrefix(prefix: string): Promise<void>;
+    flushTags(tags: string[]): Promise<void>;
+    disconnect(): Promise<void>;
+}

package/dist/drivers/redis.js

@@ -0,0 +1,52 @@
+import { Redis } from 'ioredis';
+/** Namespace for tag sets in Redis, outside the value key space. */
+const TAG_PREFIX = '__tags__:';
+export class RedisCacheDriver {
+    redis;
+    constructor(redis) {
+        this.redis = redis;
+    }
+    static fromUrl(url) {
+        return new RedisCacheDriver(new Redis(url));
+    }
+    async get(key) {
+        const raw = await this.redis.get(key);
+        return raw === null ? undefined : JSON.parse(raw);
+    }
+    async set(key, value, ttlMs, tags = []) {
+        const raw = JSON.stringify(value);
+        if (ttlMs !== undefined) {
+            await this.redis.set(key, raw, 'PX', Math.max(1, Math.ceil(ttlMs)));
+        }
+        else {
+            await this.redis.set(key, raw);
+        }
+        for (const tag of tags) {
+            await this.redis.sadd(TAG_PREFIX + tag, key);
+        }
+    }
+    async delete(key) {
+        return (await this.redis.del(key)) > 0;
+    }
+    async flushPrefix(prefix) {
+        let cursor = '0';
+        do {
+            const [next, keys] = await this.redis.scan(cursor, 'MATCH', `${prefix}*`, 'COUNT', 200);
+            cursor = next;
+            if (keys.length > 0)
+                await this.redis.del(...keys);
+        } while (cursor !== '0');
+    }
+    async flushTags(tags) {
+        for (const tag of tags) {
+            const tagKey = TAG_PREFIX + tag;
+            const keys = await this.redis.smembers(tagKey);
+            if (keys.length > 0)
+                await this.redis.del(...keys);
+            await this.redis.del(tagKey);
+        }
+    }
+    async disconnect() {
+        await this.redis.quit();
+    }
+}

package/dist/index.d.ts

@@ -1,46 +1,12 @@
-import * as _basaltkit_core from '@basaltkit/core';
-import { DurationInput, BasaltError } from '@basaltkit/core';
-import { Redis } from 'ioredis';
-
-/** Cache driver contract. Every driver passes the same conformance suite. */
-interface CacheDriver {
-    /** Returns the value, or undefined on miss/expired. */
-    get(key: string): Promise<unknown>;
-    set(key: string, value: unknown, ttlMs?: number, tags?: string[]): Promise<void>;
-    delete(key: string): Promise<boolean>;
-    /** Removes all keys starting with the prefix. */
-    flushPrefix(prefix: string): Promise<void>;
-    /** Removes all keys associated with any of the tags. */
-    flushTags(tags: string[]): Promise<void>;
-    disconnect(): Promise<void>;
-}
-
-declare class MemoryCacheDriver implements CacheDriver {
-    private readonly store;
-    get(key: string): Promise<unknown>;
-    set(key: string, value: unknown, ttlMs?: number, tags?: string[]): Promise<void>;
-    delete(key: string): Promise<boolean>;
-    flushPrefix(prefix: string): Promise<void>;
-    flushTags(tags: string[]): Promise<void>;
-    disconnect(): Promise<void>;
-}
-
-declare class RedisCacheDriver implements CacheDriver {
-    private readonly redis;
-    constructor(redis: Redis);
-    static fromUrl(url: string): RedisCacheDriver;
-    get(key: string): Promise<unknown>;
-    set(key: string, value: unknown, ttlMs?: number, tags?: string[]): Promise<void>;
-    delete(key: string): Promise<boolean>;
-    flushPrefix(prefix: string): Promise<void>;
-    flushTags(tags: string[]): Promise<void>;
-    disconnect(): Promise<void>;
-}
-
-declare class MissingCacheScopeError extends BasaltError {
+import { BasaltError, type DurationInput } from '@basaltkit/core';
+import type { CacheDriver } from './driver.js';
+export type { CacheDriver } from './driver.js';
+export { MemoryCacheDriver } from './drivers/memory.js';
+export { RedisCacheDriver } from './drivers/redis.js';
+export declare class MissingCacheScopeError extends BasaltError {
     constructor(op: string);
 }
-interface CacheOptions {
+export interface CacheOptions {
     /** Root prefix for all keys. Default: 'basalt' */
     prefix?: string;
     /**
@@ -57,13 +23,27 @@ interface CacheOptions {
      * regardless, so a mis-scoped call can't wipe every tenant's cache.
      */
     onMissingScope?: 'global' | 'error';
+    /** Injectable clock (ms) for stale-while-revalidate windows. Default: Date.now. */
+    now?: () => number;
+}
+/** SwrOptions turns `remember` into a stale-while-revalidate read. */
+export interface SwrOptions {
+    /** How long the value stays fresh (served without revalidation). */
+    ttl: DurationInput;
+    /**
+     * Extra window after `ttl` during which a stale value is served immediately
+     * while a single background revalidation refreshes it. After `ttl + staleFor`
+     * the entry is hard-expired and the next read blocks on the factory.
+     */
+    staleFor: DurationInput;
 }
-declare class Cache {
+export declare class Cache {
     private readonly driver;
     private readonly prefix;
     private readonly scope;
     private readonly onMissingScope;
-    /** dedupe of in-flight factories — per-process stampede protection */
+    private readonly now;
+    /** dedupe of in-flight factories — per-process stampede protection (also dedupes SWR revalidation) */
     private readonly pending;
     constructor(driver: CacheDriver, options?: CacheOptions);
     get<T>(key: string): Promise<T | undefined>;
@@ -74,26 +54,29 @@ declare class Cache {
      * for the same key share ONE execution of the factory.
      */
     remember<T>(key: string, ttl: DurationInput, factory: () => Promise<T> | T): Promise<T>;
+    remember<T>(key: string, options: SwrOptions, factory: () => Promise<T> | T): Promise<T>;
     forget(key: string): Promise<boolean>;
     /** Clears only the keys under this prefix/scope — never the entire Redis. */
     flush(): Promise<void>;
     /** Tag-scoped operations: `cache.tags('plans').flush()` invalidates the group. */
     tags(...tags: string[]): {
         put: (key: string, value: unknown, ttl?: DurationInput) => Promise<void>;
-        remember: <T>(key: string, ttl: DurationInput, factory: () => Promise<T> | T) => Promise<T>;
+        remember: <T>(key: string, ttlOrOptions: DurationInput | SwrOptions, factory: () => Promise<T> | T) => Promise<T>;
         flush: () => Promise<void>;
     };
     private rememberWithTags;
+    /** Blocking cache-aside compute with per-key stampede dedupe. */
+    private compute;
+    /** Fire-and-forget SWR refresh: one per key, failures keep serving stale. */
+    private revalidate;
     private root;
     private key;
 }
-declare const CACHE: _basaltkit_core.Token<Cache>;
-interface CachePluginOptions extends CacheOptions {
+export declare const CACHE: import("@basaltkit/core").Token<Cache>;
+export interface CachePluginOptions extends CacheOptions {
     /** 'memory' (default), 'redis' (needs `url`), or a custom `CacheDriver` instance. */
     driver?: 'memory' | 'redis' | CacheDriver;
     /** Required with the 'redis' driver. */
     url?: string;
 }
-declare function cachePlugin(options?: CachePluginOptions): _basaltkit_core.BasaltPlugin<unknown>;
-
-export { CACHE, Cache, type CacheDriver, type CacheOptions, type CachePluginOptions, MemoryCacheDriver, MissingCacheScopeError, RedisCacheDriver, cachePlugin };
+export declare function cachePlugin(options?: CachePluginOptions): import("@basaltkit/core").BasaltPlugin<unknown>;

package/dist/index.js

@@ -1,218 +1,179 @@
-// src/index.ts
-import {
-  BasaltError,
-  createToken,
-  definePlugin,
-  parseDuration,
-  tryCtx
-} from "@basaltkit/core";
-
-// src/drivers/memory.ts
-var MemoryCacheDriver = class {
-  store = /* @__PURE__ */ new Map();
-  async get(key) {
-    const entry = this.store.get(key);
-    if (!entry) return void 0;
-    if (entry.expiresAt !== void 0 && Date.now() >= entry.expiresAt) {
-      this.store.delete(key);
-      return void 0;
+import { BasaltError, createToken, definePlugin, parseDuration, tryCtx, } from '@basaltkit/core';
+import { MemoryCacheDriver } from './drivers/memory.js';
+import { RedisCacheDriver } from './drivers/redis.js';
+export { MemoryCacheDriver } from './drivers/memory.js';
+export { RedisCacheDriver } from './drivers/redis.js';
+export class MissingCacheScopeError extends BasaltError {
+    constructor(op) {
+        super('CACHE_SCOPE_MISSING', `Refusing cache ${op}: a tenant-scoped cache resolved no tenant (ran without a tenant context). Establish a tenant, or use scope:null for a deliberate global cache.`);
     }
-    return entry.value;
-  }
-  async set(key, value, ttlMs, tags = []) {
-    this.store.set(key, {
-      value,
-      ...ttlMs !== void 0 ? { expiresAt: Date.now() + ttlMs } : {},
-      tags: new Set(tags)
-    });
-  }
-  async delete(key) {
-    return this.store.delete(key);
-  }
-  async flushPrefix(prefix) {
-    for (const key of this.store.keys()) {
-      if (key.startsWith(prefix)) this.store.delete(key);
+}
+function isEnvelope(value) {
+    return typeof value === 'object' && value !== null && value.__swr === 1;
+}
+function isSwr(value) {
+    return typeof value === 'object' && value !== null && 'staleFor' in value;
+}
+const defaultScope = () => {
+    const tenant = tryCtx()?.['tenant'];
+    return tenant?.id ? `tenant:${tenant.id}` : undefined;
+};
+export class Cache {
+    driver;
+    prefix;
+    scope;
+    onMissingScope;
+    now;
+    /** dedupe of in-flight factories — per-process stampede protection (also dedupes SWR revalidation) */
+    pending = new Map();
+    constructor(driver, options = {}) {
+        this.driver = driver;
+        this.prefix = options.prefix ?? 'basalt';
+        this.scope = options.scope === undefined ? defaultScope : options.scope;
+        this.onMissingScope = options.onMissingScope ?? 'global';
+        this.now = options.now ?? Date.now;
     }
-  }
-  async flushTags(tags) {
-    for (const [key, entry] of this.store) {
-      if (tags.some((tag) => entry.tags.has(tag))) this.store.delete(key);
+    async get(key, fallback) {
+        const stored = await this.driver.get(this.key(key));
+        const value = isEnvelope(stored) ? stored.v : stored;
+        return value === undefined ? fallback : value;
     }
-  }
-  async disconnect() {
-    this.store.clear();
-  }
-};
-
-// src/drivers/redis.ts
-import { Redis } from "ioredis";
-var TAG_PREFIX = "__tags__:";
-var RedisCacheDriver = class _RedisCacheDriver {
-  constructor(redis) {
-    this.redis = redis;
-  }
-  redis;
-  static fromUrl(url) {
-    return new _RedisCacheDriver(new Redis(url));
-  }
-  async get(key) {
-    const raw = await this.redis.get(key);
-    return raw === null ? void 0 : JSON.parse(raw);
-  }
-  async set(key, value, ttlMs, tags = []) {
-    const raw = JSON.stringify(value);
-    if (ttlMs !== void 0) {
-      await this.redis.set(key, raw, "PX", Math.max(1, Math.ceil(ttlMs)));
-    } else {
-      await this.redis.set(key, raw);
+    async put(key, value, ttl) {
+        await this.driver.set(this.key(key), value, ttl === undefined ? undefined : parseDuration(ttl));
     }
-    for (const tag of tags) {
-      await this.redis.sadd(TAG_PREFIX + tag, key);
+    async remember(key, ttlOrOptions, factory) {
+        return this.rememberWithTags(key, ttlOrOptions, factory, []);
     }
-  }
-  async delete(key) {
-    return await this.redis.del(key) > 0;
-  }
-  async flushPrefix(prefix) {
-    let cursor = "0";
-    do {
-      const [next, keys] = await this.redis.scan(cursor, "MATCH", `${prefix}*`, "COUNT", 200);
-      cursor = next;
-      if (keys.length > 0) await this.redis.del(...keys);
-    } while (cursor !== "0");
-  }
-  async flushTags(tags) {
-    for (const tag of tags) {
-      const tagKey = TAG_PREFIX + tag;
-      const keys = await this.redis.smembers(tagKey);
-      if (keys.length > 0) await this.redis.del(...keys);
-      await this.redis.del(tagKey);
+    async forget(key) {
+        return this.driver.delete(this.key(key));
     }
-  }
-  async disconnect() {
-    await this.redis.quit();
-  }
-};
-
-// src/index.ts
-var MissingCacheScopeError = class extends BasaltError {
-  constructor(op) {
-    super(
-      "CACHE_SCOPE_MISSING",
-      `Refusing cache ${op}: a tenant-scoped cache resolved no tenant (ran without a tenant context). Establish a tenant, or use scope:null for a deliberate global cache.`
-    );
-  }
-};
-var defaultScope = () => {
-  const tenant = tryCtx()?.["tenant"];
-  return tenant?.id ? `tenant:${tenant.id}` : void 0;
-};
-var Cache = class {
-  constructor(driver, options = {}) {
-    this.driver = driver;
-    this.prefix = options.prefix ?? "basalt";
-    this.scope = options.scope === void 0 ? defaultScope : options.scope;
-    this.onMissingScope = options.onMissingScope ?? "global";
-  }
-  driver;
-  prefix;
-  scope;
-  onMissingScope;
-  /** dedupe of in-flight factories — per-process stampede protection */
-  pending = /* @__PURE__ */ new Map();
-  async get(key, fallback) {
-    const value = await this.driver.get(this.key(key));
-    return value === void 0 ? fallback : value;
-  }
-  async put(key, value, ttl) {
-    await this.driver.set(
-      this.key(key),
-      value,
-      ttl === void 0 ? void 0 : parseDuration(ttl)
-    );
-  }
-  /**
-   * One-line cache-aside, with stampede protection: concurrent calls
-   * for the same key share ONE execution of the factory.
-   */
-  async remember(key, ttl, factory) {
-    return this.rememberWithTags(key, ttl, factory, []);
-  }
-  async forget(key) {
-    return this.driver.delete(this.key(key));
-  }
-  /** Clears only the keys under this prefix/scope — never the entire Redis. */
-  async flush() {
-    if (this.scope !== null && this.scope() === void 0) throw new MissingCacheScopeError("flush");
-    await this.driver.flushPrefix(this.root());
-  }
-  /** Tag-scoped operations: `cache.tags('plans').flush()` invalidates the group. */
-  tags(...tags) {
-    const scopedTags = tags.map((tag) => `${this.root()}${tag}`);
-    return {
-      put: async (key, value, ttl) => {
-        await this.driver.set(
-          this.key(key),
-          value,
-          ttl === void 0 ? void 0 : parseDuration(ttl),
-          scopedTags
-        );
-      },
-      remember: (key, ttl, factory) => this.rememberWithTags(key, ttl, factory, scopedTags),
-      flush: async () => {
-        await this.driver.flushTags(scopedTags);
-      }
-    };
-  }
-  async rememberWithTags(key, ttl, factory, tags) {
-    const fullKey = this.key(key);
-    const cached = await this.driver.get(fullKey);
-    if (cached !== void 0) return cached;
-    const inFlight = this.pending.get(fullKey);
-    if (inFlight) return inFlight;
-    const computation = (async () => {
-      try {
-        const value = await factory();
-        await this.driver.set(fullKey, value, parseDuration(ttl), tags);
-        return value;
-      } finally {
-        this.pending.delete(fullKey);
-      }
-    })();
-    this.pending.set(fullKey, computation);
-    return computation;
-  }
-  root() {
-    if (this.scope === null) return `${this.prefix}:`;
-    const scope = this.scope();
-    if (scope === void 0 && this.onMissingScope === "error") throw new MissingCacheScopeError("operation");
-    return scope ? `${this.prefix}:${scope}:` : `${this.prefix}:`;
-  }
-  key(key) {
-    return this.root() + key;
-  }
-};
-var CACHE = createToken("cache");
-function cachePlugin(options = {}) {
-  let driver;
-  return definePlugin({
-    name: "basalt:cache",
-    register({ container }) {
-      container.singleton(CACHE, () => {
-        driver = typeof options.driver === "object" ? options.driver : options.driver === "redis" ? RedisCacheDriver.fromUrl(options.url) : new MemoryCacheDriver();
-        return new Cache(driver, options);
-      });
-    },
-    async shutdown() {
-      await driver?.disconnect();
+    /** Clears only the keys under this prefix/scope — never the entire Redis. */
+    async flush() {
+        // Always fail closed: a whole-namespace wipe with an unresolved tenant scope
+        // would delete EVERY tenant's cache. `scope:null` (deliberate global) is fine.
+        if (this.scope !== null && this.scope() === undefined)
+            throw new MissingCacheScopeError('flush');
+        await this.driver.flushPrefix(this.root());
+    }
+    /** Tag-scoped operations: `cache.tags('plans').flush()` invalidates the group. */
+    tags(...tags) {
+        const scopedTags = tags.map((tag) => `${this.root()}${tag}`);
+        return {
+            put: async (key, value, ttl) => {
+                await this.driver.set(this.key(key), value, ttl === undefined ? undefined : parseDuration(ttl), scopedTags);
+            },
+            remember: (key, ttlOrOptions, factory) => this.rememberWithTags(key, ttlOrOptions, factory, scopedTags),
+            flush: async () => {
+                await this.driver.flushTags(scopedTags);
+            },
+        };
+    }
+    async rememberWithTags(key, ttlOrOptions, factory, tags) {
+        const fullKey = this.key(key);
+        const stored = await this.driver.get(fullKey);
+        // Plain hard-TTL remember (no staleFor): unchanged cache-aside with raw values.
+        if (!isSwr(ttlOrOptions)) {
+            const cached = isEnvelope(stored) ? stored.v : stored;
+            if (cached !== undefined)
+                return cached;
+            return this.compute(fullKey, () => factory(), (value) => this.driver.set(fullKey, value, parseDuration(ttlOrOptions), tags));
+        }
+        // Stale-while-revalidate path.
+        const ttlMs = parseDuration(ttlOrOptions.ttl);
+        const staleMs = parseDuration(ttlOrOptions.staleFor);
+        const store = (value) => {
+            const now = this.now();
+            const envelope = {
+                __swr: 1,
+                v: value,
+                freshUntil: now + ttlMs,
+                staleUntil: now + ttlMs + staleMs,
+            };
+            // Driver TTL is the hard window; Cache-layer windows gate fresh/stale/expired.
+            return this.driver.set(fullKey, envelope, ttlMs + staleMs, tags);
+        };
+        if (isEnvelope(stored)) {
+            const now = this.now();
+            if (now < stored.freshUntil)
+                return stored.v;
+            if (now < stored.staleUntil) {
+                // Serve stale immediately; refresh once in the background.
+                this.revalidate(fullKey, () => factory(), store);
+                return stored.v;
+            }
+            // Hard-expired → fall through to a blocking recompute.
+        }
+        else if (stored !== undefined) {
+            // A raw value written by put()/plain remember(): treat as fresh, no windows.
+            return stored;
+        }
+        return this.compute(fullKey, () => factory(), store);
+    }
+    /** Blocking cache-aside compute with per-key stampede dedupe. */
+    compute(fullKey, factory, store) {
+        const inFlight = this.pending.get(fullKey);
+        if (inFlight)
+            return inFlight;
+        const computation = (async () => {
+            try {
+                const value = await factory();
+                await store(value);
+                return value;
+            }
+            finally {
+                this.pending.delete(fullKey);
+            }
+        })();
+        this.pending.set(fullKey, computation);
+        return computation;
+    }
+    /** Fire-and-forget SWR refresh: one per key, failures keep serving stale. */
+    revalidate(fullKey, factory, store) {
+        if (this.pending.has(fullKey))
+            return;
+        const computation = (async () => {
+            try {
+                const value = await factory();
+                await store(value);
+            }
+            finally {
+                this.pending.delete(fullKey);
+            }
+        })();
+        this.pending.set(fullKey, computation);
+        // Never surface a background error as an unhandled rejection.
+        void computation.catch(() => undefined);
+    }
+    root() {
+        if (this.scope === null)
+            return `${this.prefix}:`; // deliberate global cache
+        const scope = this.scope();
+        if (scope === undefined && this.onMissingScope === 'error')
+            throw new MissingCacheScopeError('operation');
+        return scope ? `${this.prefix}:${scope}:` : `${this.prefix}:`;
+    }
+    key(key) {
+        return this.root() + key;
     }
-  });
 }
-export {
-  CACHE,
-  Cache,
-  MemoryCacheDriver,
-  MissingCacheScopeError,
-  RedisCacheDriver,
-  cachePlugin
-};
+export const CACHE = createToken('cache');
+export function cachePlugin(options = {}) {
+    let driver;
+    return definePlugin({
+        name: 'basalt:cache',
+        register({ container }) {
+            container.singleton(CACHE, () => {
+                driver =
+                    typeof options.driver === 'object'
+                        ? options.driver
+                        : options.driver === 'redis'
+                            ? RedisCacheDriver.fromUrl(options.url)
+                            : new MemoryCacheDriver();
+                return new Cache(driver, options);
+            });
+        },
+        async shutdown() {
+            await driver?.disconnect();
+        },
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@basaltkit/cache",
-  "version": "1.1.0",
+  "version": "1.2.1",
   "description": "Basalt cache layer: Redis and Memory drivers, tags, TTL, stampede protection and automatic per-tenant isolation.",
   "license": "MIT",
   "type": "module",
@@ -14,14 +14,13 @@
     "dist"
   ],
   "dependencies": {
-    "ioredis": "^5.6.0",
-    "@basaltkit/core": "^1.0.0"
+    "ioredis": "^6.0.0",
+    "@basaltkit/core": "^1.1.2"
   },
   "devDependencies": {
-    "@types/node": "^22.15.0",
-    "tsup": "^8.4.0",
-    "typescript": "^5.8.0",
-    "vitest": "^3.1.0",
+    "@types/node": "^26.3.0",
+    "typescript": "^7.0.2",
+    "vitest": "^4.1.11",
     "@basaltkit/tsconfig": "^0.24.0"
   },
   "publishConfig": {
@@ -29,11 +28,11 @@
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/Zebedeu/basalt.git",
+    "url": "git+https://github.com/basaltkit/basalt.git",
     "directory": "packages/cache"
   },
-  "homepage": "https://github.com/Zebedeu/basalt/tree/main/packages/cache#readme",
-  "bugs": "https://github.com/Zebedeu/basalt/issues",
+  "homepage": "https://github.com/basaltkit/basalt/tree/main/packages/cache#readme",
+  "bugs": "https://github.com/basaltkit/basalt/issues",
   "keywords": [
     "basalt",
     "typescript",
@@ -41,7 +40,7 @@
     "redis"
   ],
   "scripts": {
-    "build": "tsup src/index.ts --format esm --dts --clean",
+    "build": "tsc -p tsconfig.build.json",
     "test": "vitest run",
     "typecheck": "tsc --noEmit"
   }