@basaltkit/cache 1.1.0 → 1.2.0

package/README.md

@@ -95,6 +95,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 +194,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/index.d.ts

@@ -57,13 +57,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. */
+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 {
     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,16 +88,21 @@ 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;
 }
@@ -96,4 +115,4 @@ interface CachePluginOptions extends CacheOptions {
 }
 declare function cachePlugin(options?: CachePluginOptions): _basaltkit_core.BasaltPlugin<unknown>;
 
-export { CACHE, Cache, type CacheDriver, type CacheOptions, type CachePluginOptions, MemoryCacheDriver, MissingCacheScopeError, RedisCacheDriver, cachePlugin };
+export { CACHE, Cache, type CacheDriver, type CacheOptions, type CachePluginOptions, MemoryCacheDriver, MissingCacheScopeError, RedisCacheDriver, type SwrOptions, cachePlugin };

package/dist/index.js

@@ -103,6 +103,12 @@ var MissingCacheScopeError = class extends BasaltError {
     );
   }
 };
+function isEnvelope(value) {
+  return typeof value === "object" && value !== null && value.__swr === 1;
+}
+function isSwr(value) {
+  return typeof value === "object" && value !== null && "staleFor" in value;
+}
 var defaultScope = () => {
   const tenant = tryCtx()?.["tenant"];
   return tenant?.id ? `tenant:${tenant.id}` : void 0;
@@ -113,15 +119,18 @@ var Cache = class {
     this.prefix = options.prefix ?? "basalt";
     this.scope = options.scope === void 0 ? defaultScope : options.scope;
     this.onMissingScope = options.onMissingScope ?? "global";
+    this.now = options.now ?? Date.now;
   }
   driver;
   prefix;
   scope;
   onMissingScope;
-  /** dedupe of in-flight factories — per-process stampede protection */
+  now;
+  /** dedupe of in-flight factories — per-process stampede protection (also dedupes SWR revalidation) */
   pending = /* @__PURE__ */ new Map();
   async get(key, fallback) {
-    const value = await this.driver.get(this.key(key));
+    const stored = await this.driver.get(this.key(key));
+    const value = isEnvelope(stored) ? stored.v : stored;
     return value === void 0 ? fallback : value;
   }
   async put(key, value, ttl) {
@@ -131,12 +140,8 @@ var Cache = class {
       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 remember(key, ttlOrOptions, factory) {
+    return this.rememberWithTags(key, ttlOrOptions, factory, []);
   }
   async forget(key) {
     return this.driver.delete(this.key(key));
@@ -158,22 +163,56 @@ var Cache = class {
           scopedTags
         );
       },
-      remember: (key, ttl, factory) => this.rememberWithTags(key, ttl, factory, scopedTags),
+      remember: (key, ttlOrOptions, factory) => this.rememberWithTags(key, ttlOrOptions, factory, scopedTags),
       flush: async () => {
         await this.driver.flushTags(scopedTags);
       }
     };
   }
-  async rememberWithTags(key, ttl, factory, tags) {
+  async rememberWithTags(key, ttlOrOptions, factory, tags) {
     const fullKey = this.key(key);
-    const cached = await this.driver.get(fullKey);
-    if (cached !== void 0) return cached;
+    const stored = await this.driver.get(fullKey);
+    if (!isSwr(ttlOrOptions)) {
+      const cached = isEnvelope(stored) ? stored.v : stored;
+      if (cached !== void 0) return cached;
+      return this.compute(
+        fullKey,
+        () => factory(),
+        (value) => this.driver.set(fullKey, value, parseDuration(ttlOrOptions), tags)
+      );
+    }
+    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
+      };
+      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) {
+        this.revalidate(fullKey, () => factory(), store);
+        return stored.v;
+      }
+    } else if (stored !== void 0) {
+      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 this.driver.set(fullKey, value, parseDuration(ttl), tags);
+        await store(value);
         return value;
       } finally {
         this.pending.delete(fullKey);
@@ -182,6 +221,20 @@ var Cache = class {
     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);
+    void computation.catch(() => void 0);
+  }
   root() {
     if (this.scope === null) return `${this.prefix}:`;
     const scope = this.scope();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@basaltkit/cache",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Basalt cache layer: Redis and Memory drivers, tags, TTL, stampede protection and automatic per-tenant isolation.",
   "license": "MIT",
   "type": "module",