@basaltkit/cache 1.0.0 → 1.1.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/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,19 +37,32 @@ 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';
 }
 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 pending;
     constructor(driver: CacheDriver, options?: CacheOptions);
@@ -83,4 +96,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, cachePlugin };

package/dist/index.js

@@ -1,5 +1,6 @@
 // src/index.ts
 import {
+  BasaltError,
   createToken,
   definePlugin,
   parseDuration,
@@ -94,6 +95,14 @@ 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.`
+    );
+  }
+};
 var defaultScope = () => {
   const tenant = tryCtx()?.["tenant"];
   return tenant?.id ? `tenant:${tenant.id}` : void 0;
@@ -103,10 +112,12 @@ 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";
   }
   driver;
   prefix;
   scope;
+  onMissingScope;
   /** dedupe of in-flight factories — per-process stampede protection */
   pending = /* @__PURE__ */ new Map();
   async get(key, fallback) {
@@ -132,6 +143,7 @@ var Cache = class {
   }
   /** 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. */
@@ -171,7 +183,9 @@ var Cache = class {
     return computation;
   }
   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 +212,7 @@ export {
   CACHE,
   Cache,
   MemoryCacheDriver,
+  MissingCacheScopeError,
   RedisCacheDriver,
   cachePlugin
 };

package/package.json

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