@basaltkit/cache 1.0.0 → 1.2.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 Machize Contributors
+Copyright (c) 2026 Basalt Contributors
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

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

@@ -1,5 +1,5 @@
 import * as _basaltkit_core from '@basaltkit/core';
-import { DurationInput } from '@basaltkit/core';
+import { DurationInput, BasaltError } from '@basaltkit/core';
 import { Redis } from 'ioredis';
 
 /** Cache driver contract. Every driver passes the same conformance suite. */
@@ -37,20 +37,47 @@ declare class RedisCacheDriver implements CacheDriver {
     disconnect(): Promise<void>;
 }
 
+declare class MissingCacheScopeError extends BasaltError {
+    constructor(op: string);
+}
 interface CacheOptions {
     /** Root prefix for all keys. Default: 'basalt' */
     prefix?: string;
     /**
      * Dynamic segment of the prefix, resolved on every operation. The default reads
-     * `ctx().tenant.id` — automatic per-tenant isolation. Pass `null` to disable.
+     * `ctx().tenant.id` — automatic per-tenant isolation. Pass `null` to disable
+     * (a deliberate global cache).
      */
     scope?: (() => string | undefined) | null;
+    /**
+     * What to do when the scope function resolves nothing (no tenant in context):
+     * `'global'` (default) shares one namespace — convenient but a per-tenant value
+     * cached without a tenant leaks to others; `'error'` fails closed (throws
+     * {@link MissingCacheScopeError}) on read/write. `flush()` ALWAYS fails closed
+     * 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;
-    /** dedupe of in-flight factories — per-process stampede protection */
+    private readonly onMissingScope;
+    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>;
@@ -61,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;
 }
@@ -83,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, RedisCacheDriver, cachePlugin };
+export { CACHE, Cache, type CacheDriver, type CacheOptions, type CachePluginOptions, MemoryCacheDriver, MissingCacheScopeError, RedisCacheDriver, type SwrOptions, cachePlugin };

package/dist/index.js

@@ -1,5 +1,6 @@
 // src/index.ts
 import {
+  BasaltError,
   createToken,
   definePlugin,
   parseDuration,
@@ -94,6 +95,20 @@ var RedisCacheDriver = class _RedisCacheDriver {
 };
 
 // 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.`
+    );
+  }
+};
+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;
@@ -103,14 +118,19 @@ var Cache = class {
     this.driver = driver;
     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;
-  /** dedupe of in-flight factories — per-process stampede protection */
+  onMissingScope;
+  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) {
@@ -120,18 +140,15 @@ 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));
   }
   /** 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. */
@@ -146,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);
@@ -170,8 +221,24 @@ 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() {
-    const scope = this.scope?.();
+    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) {
@@ -198,6 +265,7 @@ export {
   CACHE,
   Cache,
   MemoryCacheDriver,
+  MissingCacheScopeError,
   RedisCacheDriver,
   cachePlugin
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@basaltkit/cache",
-  "version": "1.0.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",