@basaltkit/cache 1.4.0 → 1.4.1

package/README.md

@@ -244,6 +244,12 @@ 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.
 
+`flush()` follows the same gate. It wipes a whole prefix, so in a multi-tenant app an unresolved
+scope must fail closed — otherwise one mis-scoped call clears every tenant's cache. Without
+tenancy, the prefix *is* this app's own cache and clearing it is exactly what `flush()` means, so
+it proceeds. An explicit `onMissingScope: 'error'` keeps `flush()` fail-closed either way, and
+`scope: null` (a deliberate global cache) may always flush its namespace.
+
 ```ts
 // Multi-tenant: this now throws instead of poisoning the shared namespace.
 cachePlugin({ driver: 'redis', url })   // + tenancyPlugin() registered  → onMissingScope: 'error'

package/dist/index.d.ts

@@ -19,8 +19,9 @@ export interface CacheOptions {
      * 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.
+     * {@link MissingCacheScopeError}) on read/write. In a multi-tenant app (or
+     * with an explicit `'error'`), `flush()` fails closed too, 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. */
@@ -39,13 +40,25 @@ export interface SwrOptions {
 }
 export declare class Cache {
     private readonly driver;
+    /**
+     * Whether the host app registered `@basaltkit/tenancy`. `cachePlugin` wires
+     * this to the container's `'tenancy:active'` metadata marker — a signal,
+     * not an import. Defaults to `false` (single-tenant).
+     */
+    private readonly tenancyActive;
     private readonly prefix;
     private readonly scope;
     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);
+    constructor(driver: CacheDriver, options?: CacheOptions, 
+    /**
+     * Whether the host app registered `@basaltkit/tenancy`. `cachePlugin` wires
+     * this to the container's `'tenancy:active'` metadata marker — a signal,
+     * not an import. Defaults to `false` (single-tenant).
+     */
+    tenancyActive?: () => boolean);
     get<T>(key: string): Promise<T | undefined>;
     get<T>(key: string, fallback: T): Promise<T>;
     put(key: string, value: unknown, ttl?: DurationInput): Promise<void>;

package/dist/index.js

@@ -42,14 +42,22 @@ const defaultScope = () => {
 };
 export class Cache {
     driver;
+    tenancyActive;
     prefix;
     scope;
     onMissingScope;
     now;
     /** dedupe of in-flight factories — per-process stampede protection (also dedupes SWR revalidation) */
     pending = new Map();
-    constructor(driver, options = {}) {
+    constructor(driver, options = {}, 
+    /**
+     * Whether the host app registered `@basaltkit/tenancy`. `cachePlugin` wires
+     * this to the container's `'tenancy:active'` metadata marker — a signal,
+     * not an import. Defaults to `false` (single-tenant).
+     */
+    tenancyActive = () => false) {
         this.driver = driver;
+        this.tenancyActive = tenancyActive;
         this.prefix = options.prefix ?? 'basalt';
         this.scope = options.scope === undefined ? defaultScope : options.scope;
         this.onMissingScope = options.onMissingScope ?? 'global';
@@ -71,10 +79,15 @@ export class Cache {
     }
     /** 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)
+        // Fail closed where a wipe could cross a boundary: with tenancy registered
+        // (or an explicit onMissingScope:'error'), an unresolved scope would delete
+        // EVERY tenant's cache. In a single-tenant app the whole prefix IS this
+        // app's cache, which is exactly what flush() means — so it proceeds.
+        // `scope:null` (deliberate global) is fine either way.
+        const failClosed = this.tenancyActive() || this.onMissingScope === 'error';
+        if (failClosed && 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. */
@@ -198,11 +211,11 @@ export function cachePlugin(options = {}) {
                 // with no resolvable tenant scope throws instead of silently sharing
                 // one global namespace across tenants. Single-tenant apps (no tenancy)
                 // are untouched, and an explicit `onMissingScope`/custom `scope` wins.
-                const tenancyActive = ensureMetadata(container).get('tenancy:active').length > 0;
-                const resolved = options.onMissingScope === undefined && options.scope === undefined && tenancyActive
+                const tenancyActive = () => ensureMetadata(container).get('tenancy:active').length > 0;
+                const resolved = options.onMissingScope === undefined && options.scope === undefined && tenancyActive()
                     ? { ...options, onMissingScope: 'error' }
                     : options;
-                return new Cache(driver, resolved);
+                return new Cache(driver, resolved, tenancyActive);
             });
         },
         async shutdown() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@basaltkit/cache",
-  "version": "1.4.0",
+  "version": "1.4.1",
   "engines": {
     "node": ">=22.5.0"
   },