@basaltkit/cache 1.3.0 → 1.4.0

package/README.md

@@ -207,28 +207,112 @@ const cacheB = new Cache(new RedisCacheDriver(redis))
 
 #### `CacheOptions`
 
-| Option | Type | Required? | Default | Description |
-|---|---|---|---|---|
-| `prefix` | `string` | No | `'basalt'` | Root prefix for all keys. |
-| `scope` | `(() => string \| undefined) \| null` | No | reads `ctx().tenant.id` → `tenant:<id>` | Dynamic prefix segment, resolved on each operation. `null` disables tenant isolation. |
-| `onMissingScope` | `'global' \| 'error'` | No | `'error'` when `tenancyPlugin` is registered, else `'global'` | What an operation does when the scope resolves to `undefined` (e.g. a background job outside request context). In multi-tenant apps the default fails CLOSED (`MissingCacheScopeError`) instead of silently sharing one namespace across tenants; single-tenant apps keep the global namespace. Explicit values always win. |
+| Option | Type | Default | Purpose |
+|---|---|---|---|
+| `prefix` | `string` | `'basalt'` | Root prefix for all keys. Change it when two apps share one Redis, so each owns its own key space and `flush()` can't cross the boundary. |
+| `scope` | `(() => string \| undefined) \| null` | reads `ctx().tenant.id` → `tenant:<id>` | Dynamic prefix segment, resolved on **every** operation. Pass `null` for a deliberate global cache; pass your own function to scope by something other than tenant (region, API version). |
+| `onMissingScope` | `'global' \| 'error'` | `'error'` when tenancy is active, else `'global'` — see below | What a read/write does when `scope()` resolves `undefined`. `'global'` shares one namespace; `'error'` throws `MissingCacheScopeError`. |
+| `now` | `() => number` | `Date.now` | Injectable clock (ms) for the stale-while-revalidate windows. For tests. |
+
+A value of `undefined` is a real cached value, not a miss: `remember()` with a factory that returns `undefined` computes it **once** and serves the cached `undefined` afterwards. `get()` still reports its `fallback` for such an entry, because `get` cannot distinguish "cached undefined" from "absent".
+
+`SwrOptions` (the object form of `remember`'s second argument):
+
+| Field | Type | Purpose |
+|---|---|---|
+| `ttl` | `DurationInput` | How long the value stays **fresh** — served with no revalidation. |
+| `staleFor` | `DurationInput` | Extra window after `ttl` in which a stale value is served instantly while one background revalidation runs. After `ttl + staleFor` the entry is hard-expired and the next read blocks on the factory. The driver TTL is set to `ttl + staleFor`. |
+
+#### `onMissingScope` and the `tenancy:active` interaction
+
+The `Cache` class on its own defaults `onMissingScope` to `'global'`. `cachePlugin` **overrides
+that to `'error'`** when three things hold at once:
+
+1. `@basaltkit/tenancy` is registered — it adds a `tenancy:active` marker to the container's
+   metadata at register time, and the cache plugin checks for it;
+2. you did not pass `onMissingScope`; **and**
+3. you did not pass a custom `scope`.
+
+Any explicit `onMissingScope` or `scope` wins — the upgrade only fills a gap you left blank.
+
+The reasoning: in a multi-tenant app, a cache operation that resolves no tenant is a bug almost
+every time (a queue worker, a cron task, a startup hook — code running outside a request). Under
+`'global'` it doesn't fail; it writes a per-tenant value into the shared namespace, where the
+**next tenant reads it**. That is a cross-tenant data leak with no error and no log. Failing
+closed turns it into a stack trace at the call site.
+
+Single-tenant apps are untouched: no tenancy plugin, no marker, so the default stays `'global'`
+and nothing changes.
+
+```ts
+// Multi-tenant: this now throws instead of poisoning the shared namespace.
+cachePlugin({ driver: 'redis', url })   // + tenancyPlugin() registered  → onMissingScope: 'error'
+
+// Deliberate global cache — opt out explicitly, and the scope check never runs.
+cachePlugin({ driver: 'redis', url, scope: null })
+
+// Keep the old permissive behaviour, knowingly.
+cachePlugin({ driver: 'redis', url, onMissingScope: 'global' })
+```
+
+**`flush()` always fails closed**, whatever `onMissingScope` says: if `scope` is not `null` and
+resolves `undefined`, it throws rather than wiping the whole prefix. A mis-scoped `flush()` under
+`'global'` would delete **every tenant's** cache in one call, and no convenience is worth that.
+`scope: null` is exempt — you declared the cache global, so its "everything" is genuinely
+everything you meant.
+
+To flush one tenant, call it inside that tenant's context; to flush the global namespace of a
+tenant-scoped cache, build a second `Cache` with `scope: null`.
 
 ### `cachePlugin(options?: CachePluginOptions)`
 
 Registers `Cache` in the container under the `CACHE` token and disconnects the driver on application `shutdown`.
 
+#### Drivers
+
+**`MemoryCacheDriver`** — the default, and **bounded**: cache keys usually embed ids, slugs or query fingerprints, so unbounded growth on user-influenced keys is an OOM vector. It holds at most `maxEntries` live entries (default **10 000**), evicting already-expired entries first and then the least recently used (`get` counts as a use).
+
+| Option | Type | Default | Purpose |
+|---|---|---|---|
+| `maxEntries` | `number` | `10_000` | Live-entry cap before eviction; `Infinity` disables it. |
+
+It also exposes `size` (live entry count) for diagnostics and tests.
+
+**`RedisCacheDriver`** — values are `JSON.stringify`/`JSON.parse`'d, so store plain data (`Date` comes back as a string; `Map`/class instances do not survive). Two details worth knowing:
+
+- **Prefix flushes are glob-escaped.** The scope segment carries user-controlled data (a tenant id or slug), so `flushPrefix` escapes Redis glob metacharacters (`\ * ? [ ] ^`) before `SCAN MATCH`. Without it, a tenant named `a*` would match — and delete — other tenants' keys.
+- **Tag indexes are sorted sets** under `__tagz__:<tag>`, scored by each member's expiry, plus a reverse index `__tagsof__:<key>`. Expired members are pruned on write and `delete` unregisters the key from its tags, so the index tracks the live key set instead of growing forever. Upgrading from the older plain sets (`__tags__:`) leaves inert orphans — clear them once with `DEL __tags__:*`.
+
 #### `CachePluginOptions` (extends `CacheOptions`)
 
-| Option | Type | Required? | Default | Description |
-|---|---|---|---|---|
-| `driver` | `'memory' \| 'redis'` | No | `'memory'` | Which driver to use. |
-| `url` | `string` | Yes, with `driver: 'redis'` | — | Redis connection URL (e.g. `redis://localhost:6379`). |
-| `prefix`, `scope` | — | No | see `CacheOptions` | Inherited from `CacheOptions`. |
+| Option | Type | Default | Purpose |
+|---|---|---|---|
+| `driver` | `'memory' \| 'redis' \| CacheDriver` | `'memory'` | Built-in driver by name, **or a driver instance** — that is how you plug in [`@basaltkit/cache-tiered`](https://www.npmjs.com/package/@basaltkit/cache-tiered) or your own. An instance is used as-is and `url` is ignored. |
+| `url` | `string` | — | Required with `driver: 'redis'`. Redis connection URL (e.g. `redis://localhost:6379`). |
+| `prefix`, `scope`, `onMissingScope`, `now` | — | see `CacheOptions` | Inherited from `CacheOptions`. |
+
+The plugin registers the `Cache` as a container singleton and `disconnect()`s the driver on
+application `shutdown`.
 
 ### `CACHE`
 
 Dependency injection token: `app.container.get(CACHE)` returns the `Cache` instance.
 
+### Errors
+
+| Error | Code | When |
+|---|---|---|
+| `MissingCacheScopeError` | `CACHE_SCOPE_MISSING` | A tenant-scoped cache resolved no tenant. Raised on a read/write when `onMissingScope: 'error'` (the default once tenancy is registered), and **always** on `flush()` regardless of `onMissingScope`. Extends `BasaltError`. The message names the operation and tells you to establish a tenant or pass `scope: null`. |
+| `DURATION_INVALID` (from `@basaltkit/core`) | `DURATION_INVALID` | A TTL string that `parseDuration` doesn't understand. Accepted forms: a number of ms, or `'500ms'` / `'30s'` / `'5m'` / `'2h'` / `'7d'`. |
+
+There are no other error classes: driver-level faults (a Redis connection error) propagate from
+`ioredis` unchanged.
+
+### Hooks & events
+
+This package emits none. `onMissingScope` is a policy switch, not a callback, and there is no
+hit/miss event bus — measure at the `remember` call site if you need cache metrics.
+
 ### `interface CacheDriver` (Advanced)
 
 Contract that any driver must implement — implement it to create your own storage:
@@ -272,6 +356,12 @@ This is by design: `remember`'s deduplication is **per process** (it uses an in-
 **`flush()` deleted less than I expected.**
 `flush()` only deletes keys under the current prefix + scope (that's the safety guarantee: it never does `FLUSHALL` on Redis). To clear a tenant's keys, call `flush()` inside that tenant's context.
 
+**`CACHE_SCOPE_MISSING` — "Refusing cache operation: a tenant-scoped cache resolved no tenant".**
+Cache code ran outside a tenant context — usually a queue worker, a scheduled task, or a boot hook. Establish the tenant around the call (`runWithContext({ tenant: { id } }, …)`), or, if the value really is global, use a cache built with `scope: null`. Do **not** reach for `onMissingScope: 'global'` to make it go away: that is what makes one tenant's value readable by the next.
+
+**`CACHE_SCOPE_MISSING` on `flush()` even though `onMissingScope` is `'global'`.**
+Deliberate. `flush()` always fails closed, because a mis-scoped whole-namespace wipe would delete every tenant's cache. Only `scope: null` exempts it.
+
 **I configured `driver: 'redis'` and the application fails to boot/use the cache.**
 With `driver: 'redis'`, the `url` option is required. Also verify that the Redis server is reachable at that URL.
 

package/dist/drivers/memory.d.ts

@@ -1,10 +1,28 @@
 import type { CacheDriver } from '../driver.js';
+export interface MemoryCacheDriverOptions {
+    /**
+     * Maximum number of live entries. Past it, expired entries are dropped first,
+     * then the least-recently-used ones. Default 10 000; `Infinity` disables the cap.
+     */
+    maxEntries?: number;
+}
+/**
+ * Bounded in-process cache with LRU eviction. `get` counts as a use, so hot keys
+ * survive; cold ones are evicted first.
+ */
 export declare class MemoryCacheDriver implements CacheDriver {
     private readonly store;
+    private readonly maxEntries;
+    constructor(options?: MemoryCacheDriverOptions);
+    /** Live entry count — useful to assert the bound in tests and diagnostics. */
+    get size(): number;
     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>;
+    private expired;
+    /** Reclaim space: expired entries first (free wins), then least-recently-used. */
+    private evict;
 }

package/dist/drivers/memory.js

@@ -1,21 +1,45 @@
+/**
+ * How many entries the in-process driver holds before it starts evicting.
+ * It is the DEFAULT driver, so it must be bounded: an unbounded map keyed by
+ * user-influenced strings (ids, slugs, query fingerprints) is an OOM vector.
+ * Raise it — or pass `maxEntries: Infinity` — if you deliberately want no cap.
+ */
+const DEFAULT_MAX_ENTRIES = 10_000;
+/**
+ * Bounded in-process cache with LRU eviction. `get` counts as a use, so hot keys
+ * survive; cold ones are evicted first.
+ */
 export class MemoryCacheDriver {
     store = new Map();
+    maxEntries;
+    constructor(options = {}) {
+        this.maxEntries = options.maxEntries ?? DEFAULT_MAX_ENTRIES;
+    }
+    /** Live entry count — useful to assert the bound in tests and diagnostics. */
+    get size() {
+        return this.store.size;
+    }
     async get(key) {
         const entry = this.store.get(key);
         if (!entry)
             return undefined;
-        if (entry.expiresAt !== undefined && Date.now() >= entry.expiresAt) {
+        if (this.expired(entry)) {
             this.store.delete(key);
             return undefined;
         }
+        // Re-insert to move the key to the most-recently-used end of the Map.
+        this.store.delete(key);
+        this.store.set(key, entry);
         return entry.value;
     }
     async set(key, value, ttlMs, tags = []) {
+        this.store.delete(key); // rewrite counts as a use → move to the MRU end
         this.store.set(key, {
             value,
             ...(ttlMs !== undefined ? { expiresAt: Date.now() + ttlMs } : {}),
             tags: new Set(tags),
         });
+        this.evict();
     }
     async delete(key) {
         return this.store.delete(key);
@@ -35,4 +59,23 @@ export class MemoryCacheDriver {
     async disconnect() {
         this.store.clear();
     }
+    expired(entry) {
+        return entry.expiresAt !== undefined && Date.now() >= entry.expiresAt;
+    }
+    /** Reclaim space: expired entries first (free wins), then least-recently-used. */
+    evict() {
+        if (this.store.size <= this.maxEntries)
+            return;
+        for (const [key, entry] of this.store) {
+            if (this.store.size <= this.maxEntries)
+                return;
+            if (this.expired(entry))
+                this.store.delete(key);
+        }
+        for (const key of this.store.keys()) {
+            if (this.store.size <= this.maxEntries)
+                return;
+            this.store.delete(key);
+        }
+    }
 }

package/dist/drivers/redis.d.ts

@@ -1,5 +1,11 @@
 import { Redis } from 'ioredis';
 import type { CacheDriver } from '../driver.js';
+/**
+ * Escapes Redis glob metacharacters so a key segment is matched literally.
+ * Scope segments carry user-controlled data (a tenant id / slug); left raw, a
+ * tenant named `a*` would make `flushPrefix` match — and DELETE — other tenants' keys.
+ */
+export declare function escapeGlob(value: string): string;
 export declare class RedisCacheDriver implements CacheDriver {
     private readonly redis;
     constructor(redis: Redis);

package/dist/drivers/redis.js

@@ -1,6 +1,24 @@
 import { Redis } from 'ioredis';
-/** Namespace for tag sets in Redis, outside the value key space. */
-const TAG_PREFIX = '__tags__:';
+/**
+ * Namespace for tag indexes, outside the value key space. Each tag is a SORTED
+ * SET scoring every member by its expiry timestamp (`+inf` for entries with no
+ * TTL), which lets expired members be pruned in O(log n) — a plain SET grew
+ * forever, since Redis never tells us that a member key has expired.
+ *
+ * NOTE the namespace changed from the pre-1.x `__tags__:` plain sets. Old sets
+ * are inert orphans; clear them once with `DEL __tags__:*` after upgrading.
+ */
+const TAG_PREFIX = '__tagz__:';
+/** Reverse index (key → its tags), so `delete` can unregister the key from its tags. */
+const TAGS_OF_PREFIX = '__tagsof__:';
+/**
+ * Escapes Redis glob metacharacters so a key segment is matched literally.
+ * Scope segments carry user-controlled data (a tenant id / slug); left raw, a
+ * tenant named `a*` would make `flushPrefix` match — and DELETE — other tenants' keys.
+ */
+export function escapeGlob(value) {
+    return value.replace(/[\\*?[\]^]/g, (c) => `\\${c}`);
+}
 export class RedisCacheDriver {
     redis;
     constructor(redis) {
@@ -21,17 +39,36 @@ export class RedisCacheDriver {
         else {
             await this.redis.set(key, raw);
         }
+        if (tags.length === 0)
+            return;
+        const score = ttlMs === undefined ? Number.POSITIVE_INFINITY : Date.now() + ttlMs;
+        const now = Date.now();
         for (const tag of tags) {
-            await this.redis.sadd(TAG_PREFIX + tag, key);
+            const tagKey = TAG_PREFIX + tag;
+            // Drop members that have already expired before adding the new one: the
+            // index stays proportional to the LIVE key set instead of growing forever.
+            await this.redis.zremrangebyscore(tagKey, '-inf', `(${now}`);
+            await this.redis.zadd(tagKey, score === Number.POSITIVE_INFINITY ? '+inf' : String(score), key);
         }
+        const reverseKey = TAGS_OF_PREFIX + key;
+        await this.redis.sadd(reverseKey, ...tags);
+        if (ttlMs !== undefined)
+            await this.redis.pexpire(reverseKey, Math.max(1, Math.ceil(ttlMs)));
     }
     async delete(key) {
+        const reverseKey = TAGS_OF_PREFIX + key;
+        const tags = await this.redis.smembers(reverseKey);
+        for (const tag of tags)
+            await this.redis.zrem(TAG_PREFIX + tag, key);
+        if (tags.length > 0)
+            await this.redis.del(reverseKey);
         return (await this.redis.del(key)) > 0;
     }
     async flushPrefix(prefix) {
+        const pattern = `${escapeGlob(prefix)}*`;
         let cursor = '0';
         do {
-            const [next, keys] = await this.redis.scan(cursor, 'MATCH', `${prefix}*`, 'COUNT', 200);
+            const [next, keys] = await this.redis.scan(cursor, 'MATCH', pattern, 'COUNT', 200);
             cursor = next;
             if (keys.length > 0)
                 await this.redis.del(...keys);
@@ -40,9 +77,11 @@ export class RedisCacheDriver {
     async flushTags(tags) {
         for (const tag of tags) {
             const tagKey = TAG_PREFIX + tag;
-            const keys = await this.redis.smembers(tagKey);
-            if (keys.length > 0)
+            const keys = await this.redis.zrange(tagKey, '0', '-1');
+            if (keys.length > 0) {
                 await this.redis.del(...keys);
+                await this.redis.del(...keys.map((key) => TAGS_OF_PREFIX + key));
+            }
             await this.redis.del(tagKey);
         }
     }

package/dist/index.js

@@ -11,6 +11,28 @@ export class MissingCacheScopeError extends BasaltError {
 function isEnvelope(value) {
     return typeof value === 'object' && value !== null && value.__swr === 1;
 }
+/**
+ * Marker stored in place of a literal `undefined`. Drivers report a miss as
+ * `undefined`, so an undefined VALUE would be indistinguishable from "not cached"
+ * — the factory would rerun on every call (and on Redis, `JSON.stringify(undefined)`
+ * writes the invalid literal `undefined`). Storing the marker makes the hit real.
+ */
+const UNDEFINED_MARKER = { __undefined: 1 };
+function isUndefinedMarker(value) {
+    return (typeof value === 'object' && value !== null && value.__undefined === 1);
+}
+/** Value as written to the driver: `undefined` becomes the marker. */
+function wrap(value) {
+    return value === undefined ? UNDEFINED_MARKER : value;
+}
+/** Value as read back from the driver: markers and SWR envelopes are unwrapped. */
+function unwrap(stored) {
+    if (isEnvelope(stored))
+        return stored.v;
+    if (isUndefinedMarker(stored))
+        return undefined;
+    return stored;
+}
 function isSwr(value) {
     return typeof value === 'object' && value !== null && 'staleFor' in value;
 }
@@ -35,11 +57,11 @@ export class Cache {
     }
     async get(key, fallback) {
         const stored = await this.driver.get(this.key(key));
-        const value = isEnvelope(stored) ? stored.v : stored;
+        const value = unwrap(stored);
         return value === undefined ? fallback : value;
     }
     async put(key, value, ttl) {
-        await this.driver.set(this.key(key), value, ttl === undefined ? undefined : parseDuration(ttl));
+        await this.driver.set(this.key(key), wrap(value), ttl === undefined ? undefined : parseDuration(ttl));
     }
     async remember(key, ttlOrOptions, factory) {
         return this.rememberWithTags(key, ttlOrOptions, factory, []);
@@ -60,7 +82,7 @@ export class Cache {
         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);
+                await this.driver.set(this.key(key), wrap(value), ttl === undefined ? undefined : parseDuration(ttl), scopedTags);
             },
             remember: (key, ttlOrOptions, factory) => this.rememberWithTags(key, ttlOrOptions, factory, scopedTags),
             flush: async () => {
@@ -73,10 +95,12 @@ export class Cache {
         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));
+            // A driver miss is `undefined`; anything else is a hit, INCLUDING a stored
+            // undefined-marker — so a factory that legitimately returns undefined is
+            // cached once instead of rerunning on every call.
+            if (stored !== undefined)
+                return unwrap(stored);
+            return this.compute(fullKey, () => factory(), (value) => this.driver.set(fullKey, wrap(value), parseDuration(ttlOrOptions), tags));
         }
         // Stale-while-revalidate path.
         const ttlMs = parseDuration(ttlOrOptions.ttl);
@@ -105,7 +129,7 @@ export class Cache {
         }
         else if (stored !== undefined) {
             // A raw value written by put()/plain remember(): treat as fresh, no windows.
-            return stored;
+            return unwrap(stored);
         }
         return this.compute(fullKey, () => factory(), store);
     }

package/package.json

@@ -1,9 +1,13 @@
 {
   "name": "@basaltkit/cache",
-  "version": "1.3.0",
+  "version": "1.4.0",
+  "engines": {
+    "node": ">=22.5.0"
+  },
   "description": "Basalt cache layer: Redis and Memory drivers, tags, TTL, stampede protection and automatic per-tenant isolation.",
   "license": "MIT",
   "type": "module",
+  "sideEffects": false,
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -15,7 +19,7 @@
   ],
   "dependencies": {
     "ioredis": "^6.0.0",
-    "@basaltkit/core": "^1.3.0"
+    "@basaltkit/core": "^1.3.1"
   },
   "devDependencies": {
     "@types/node": "^26.3.0",