cacheable 2.2.0 → 2.3.1

package/README.md

@@ -547,6 +547,45 @@ const cache = new Cacheable({
 });
 ```
 
+## Namespace Isolation with Sync
+
+When multiple services share the same Redis instance (or other message provider), you can use namespaces to isolate cache synchronization events between services. This prevents one service's cache updates from affecting another service's cache.
+
+```javascript
+import { Cacheable } from 'cacheable';
+import { RedisMessageProvider } from '@qified/redis';
+
+const provider = new RedisMessageProvider({
+  connection: { host: 'localhost', port: 6379 }
+});
+
+// Service 1 with namespace
+const serviceA = new Cacheable({
+  namespace: 'service-a',
+  sync: { qified: provider }
+});
+
+// Service 2 with different namespace
+const serviceB = new Cacheable({
+  namespace: 'service-b',
+  sync: { qified: provider }
+});
+
+// Set value in service A
+await serviceA.set('config', { timeout: 5000 });
+
+// Service B won't receive this update because it has a different namespace
+const value = await serviceB.get('config'); // undefined
+```
+
+**How Namespace Isolation Works:**
+- Without namespaces, sync events use channel names like `cache:set` and `cache:delete`
+- With namespaces, events are prefixed: `service-a::cache:set`, `service-b::cache:set`
+- Services only subscribe to events matching their namespace, ensuring complete isolation
+- Namespaces can be static strings or functions that return strings
+
+**Note:** The namespace is automatically passed from Cacheable to CacheableSync, so you only need to set it once in the Cacheable options.
+
 ## How Sync Works
 
 1. **SET Operations**: When you call `cache.set()` or `cache.setMany()`, the cache:

package/dist/index.cjs

@@ -78,12 +78,16 @@ var CacheableSyncEvents = /* @__PURE__ */ ((CacheableSyncEvents2) => {
 })(CacheableSyncEvents || {});
 var CacheableSync = class extends import_hookified.Hookified {
   _qified = new import_qified.Qified();
+  _namespace;
+  _storage;
+  _cacheId;
   /**
    * Creates an instance of CacheableSync
    * @param options - Configuration options for CacheableSync
    */
   constructor(options) {
     super(options);
+    this._namespace = options.namespace;
     this._qified = this.createQified(options.qified);
   }
   /**
@@ -100,12 +104,36 @@ var CacheableSync = class extends import_hookified.Hookified {
   set qified(value) {
     this._qified = this.createQified(value);
   }
+  /**
+   * Gets the namespace for sync events
+   * @returns The namespace or undefined if not set
+   */
+  get namespace() {
+    return this._namespace;
+  }
+  /**
+   * Sets the namespace for sync events and resubscribes if needed
+   * @param namespace - The namespace string or function
+   */
+  set namespace(namespace) {
+    if (this._storage && this._cacheId) {
+      const oldSetEvent = this.getPrefixedEvent("cache:set" /* SET */);
+      const oldDeleteEvent = this.getPrefixedEvent("cache:delete" /* DELETE */);
+      void this._qified.unsubscribe(oldSetEvent);
+      void this._qified.unsubscribe(oldDeleteEvent);
+    }
+    this._namespace = namespace;
+    if (this._storage && this._cacheId) {
+      this.subscribe(this._storage, this._cacheId);
+    }
+  }
   /**
    * Publishes a cache event to all the cache instances
    * @param data - The cache item data containing cacheId, key, value, and optional ttl
    */
   async publish(event, data) {
-    await this._qified.publish(event, {
+    const eventName = this.getPrefixedEvent(event);
+    await this._qified.publish(eventName, {
       id: crypto.randomUUID(),
       data
     });
@@ -116,7 +144,11 @@ var CacheableSync = class extends import_hookified.Hookified {
    * @param cacheId - The cache ID to identify this instance
    */
   subscribe(storage, cacheId) {
-    this._qified.subscribe("cache:set" /* SET */, {
+    this._storage = storage;
+    this._cacheId = cacheId;
+    const setEvent = this.getPrefixedEvent("cache:set" /* SET */);
+    const deleteEvent = this.getPrefixedEvent("cache:delete" /* DELETE */);
+    this._qified.subscribe(setEvent, {
       handler: async (message) => {
         const data = message.data;
         if (data.cacheId !== cacheId) {
@@ -124,7 +156,7 @@ var CacheableSync = class extends import_hookified.Hookified {
         }
       }
     });
-    this._qified.subscribe("cache:delete" /* DELETE */, {
+    this._qified.subscribe(deleteEvent, {
       handler: async (message) => {
         const data = message.data;
         if (data.cacheId !== cacheId) {
@@ -145,6 +177,25 @@ var CacheableSync = class extends import_hookified.Hookified {
     const providers = Array.isArray(value) ? value : [value];
     return new import_qified.Qified({ messageProviders: providers });
   }
+  /**
+   * Gets the namespace prefix to use for event names
+   * @returns The resolved namespace string or undefined
+   */
+  getNamespace() {
+    if (typeof this._namespace === "function") {
+      return this._namespace();
+    }
+    return this._namespace;
+  }
+  /**
+   * Prefixes an event name with the namespace if one is set
+   * @param event - The event to prefix
+   * @returns The prefixed event name or the original event
+   */
+  getPrefixedEvent(event) {
+    const ns = this.getNamespace();
+    return ns ? `${ns}::${event}` : event;
+  }
 };
 
 // src/index.ts
@@ -192,7 +243,10 @@ var Cacheable = class extends import_hookified2.Hookified {
       }
     }
     if (options?.sync) {
-      this._sync = options.sync instanceof CacheableSync ? options.sync : new CacheableSync(options.sync);
+      this._sync = options.sync instanceof CacheableSync ? options.sync : new CacheableSync({
+        ...options.sync,
+        namespace: options.namespace
+      });
       this._sync.subscribe(this._primary, this._cacheId);
     }
   }
@@ -214,6 +268,9 @@ var Cacheable = class extends import_hookified2.Hookified {
     if (this._secondary) {
       this._secondary.namespace = this.getNameSpace();
     }
+    if (this._sync) {
+      this._sync.namespace = namespace;
+    }
   }
   /**
    * The statistics for the cacheable instance

package/dist/index.d.cts

@@ -22,6 +22,11 @@ type CacheableSyncOptions = {
      * Qified instance or message provider(s) for synchronization
      */
     qified: Qified | MessageProvider | MessageProvider[];
+    /**
+     * The namespace for sync events. It can be a string or a function that returns a string.
+     * When set, event names will be prefixed with the namespace (e.g., "my-namespace::cache:set")
+     */
+    namespace?: string | (() => string);
 } & HookifiedOptions;
 type CacheableSyncItem = {
     cacheId: string;
@@ -35,6 +40,9 @@ type CacheableSyncItem = {
  */
 declare class CacheableSync extends Hookified {
     private _qified;
+    private _namespace?;
+    private _storage?;
+    private _cacheId?;
     /**
      * Creates an instance of CacheableSync
      * @param options - Configuration options for CacheableSync
@@ -50,6 +58,16 @@ declare class CacheableSync extends Hookified {
      * @param value - Either an existing Qified instance or MessageProvider(s)
      */
     set qified(value: Qified | MessageProvider | MessageProvider[]);
+    /**
+     * Gets the namespace for sync events
+     * @returns The namespace or undefined if not set
+     */
+    get namespace(): string | (() => string) | undefined;
+    /**
+     * Sets the namespace for sync events and resubscribes if needed
+     * @param namespace - The namespace string or function
+     */
+    set namespace(namespace: string | (() => string) | undefined);
     /**
      * Publishes a cache event to all the cache instances
      * @param data - The cache item data containing cacheId, key, value, and optional ttl
@@ -67,6 +85,17 @@ declare class CacheableSync extends Hookified {
      * @returns A Qified instance configured with the provided message provider(s)
      */
     createQified(value: Qified | MessageProvider | MessageProvider[]): Qified;
+    /**
+     * Gets the namespace prefix to use for event names
+     * @returns The resolved namespace string or undefined
+     */
+    private getNamespace;
+    /**
+     * Prefixes an event name with the namespace if one is set
+     * @param event - The event to prefix
+     * @returns The prefixed event name or the original event
+     */
+    private getPrefixedEvent;
 }
 
 type CacheableOptions = {

package/dist/index.d.ts

@@ -22,6 +22,11 @@ type CacheableSyncOptions = {
      * Qified instance or message provider(s) for synchronization
      */
     qified: Qified | MessageProvider | MessageProvider[];
+    /**
+     * The namespace for sync events. It can be a string or a function that returns a string.
+     * When set, event names will be prefixed with the namespace (e.g., "my-namespace::cache:set")
+     */
+    namespace?: string | (() => string);
 } & HookifiedOptions;
 type CacheableSyncItem = {
     cacheId: string;
@@ -35,6 +40,9 @@ type CacheableSyncItem = {
  */
 declare class CacheableSync extends Hookified {
     private _qified;
+    private _namespace?;
+    private _storage?;
+    private _cacheId?;
     /**
      * Creates an instance of CacheableSync
      * @param options - Configuration options for CacheableSync
@@ -50,6 +58,16 @@ declare class CacheableSync extends Hookified {
      * @param value - Either an existing Qified instance or MessageProvider(s)
      */
     set qified(value: Qified | MessageProvider | MessageProvider[]);
+    /**
+     * Gets the namespace for sync events
+     * @returns The namespace or undefined if not set
+     */
+    get namespace(): string | (() => string) | undefined;
+    /**
+     * Sets the namespace for sync events and resubscribes if needed
+     * @param namespace - The namespace string or function
+     */
+    set namespace(namespace: string | (() => string) | undefined);
     /**
      * Publishes a cache event to all the cache instances
      * @param data - The cache item data containing cacheId, key, value, and optional ttl
@@ -67,6 +85,17 @@ declare class CacheableSync extends Hookified {
      * @returns A Qified instance configured with the provided message provider(s)
      */
     createQified(value: Qified | MessageProvider | MessageProvider[]): Qified;
+    /**
+     * Gets the namespace prefix to use for event names
+     * @returns The resolved namespace string or undefined
+     */
+    private getNamespace;
+    /**
+     * Prefixes an event name with the namespace if one is set
+     * @param event - The event to prefix
+     * @returns The prefixed event name or the original event
+     */
+    private getPrefixedEvent;
 }
 
 type CacheableOptions = {

package/dist/index.js

@@ -48,12 +48,16 @@ var CacheableSyncEvents = /* @__PURE__ */ ((CacheableSyncEvents2) => {
 })(CacheableSyncEvents || {});
 var CacheableSync = class extends Hookified {
   _qified = new Qified();
+  _namespace;
+  _storage;
+  _cacheId;
   /**
    * Creates an instance of CacheableSync
    * @param options - Configuration options for CacheableSync
    */
   constructor(options) {
     super(options);
+    this._namespace = options.namespace;
     this._qified = this.createQified(options.qified);
   }
   /**
@@ -70,12 +74,36 @@ var CacheableSync = class extends Hookified {
   set qified(value) {
     this._qified = this.createQified(value);
   }
+  /**
+   * Gets the namespace for sync events
+   * @returns The namespace or undefined if not set
+   */
+  get namespace() {
+    return this._namespace;
+  }
+  /**
+   * Sets the namespace for sync events and resubscribes if needed
+   * @param namespace - The namespace string or function
+   */
+  set namespace(namespace) {
+    if (this._storage && this._cacheId) {
+      const oldSetEvent = this.getPrefixedEvent("cache:set" /* SET */);
+      const oldDeleteEvent = this.getPrefixedEvent("cache:delete" /* DELETE */);
+      void this._qified.unsubscribe(oldSetEvent);
+      void this._qified.unsubscribe(oldDeleteEvent);
+    }
+    this._namespace = namespace;
+    if (this._storage && this._cacheId) {
+      this.subscribe(this._storage, this._cacheId);
+    }
+  }
   /**
    * Publishes a cache event to all the cache instances
    * @param data - The cache item data containing cacheId, key, value, and optional ttl
    */
   async publish(event, data) {
-    await this._qified.publish(event, {
+    const eventName = this.getPrefixedEvent(event);
+    await this._qified.publish(eventName, {
       id: crypto.randomUUID(),
       data
     });
@@ -86,7 +114,11 @@ var CacheableSync = class extends Hookified {
    * @param cacheId - The cache ID to identify this instance
    */
   subscribe(storage, cacheId) {
-    this._qified.subscribe("cache:set" /* SET */, {
+    this._storage = storage;
+    this._cacheId = cacheId;
+    const setEvent = this.getPrefixedEvent("cache:set" /* SET */);
+    const deleteEvent = this.getPrefixedEvent("cache:delete" /* DELETE */);
+    this._qified.subscribe(setEvent, {
       handler: async (message) => {
         const data = message.data;
         if (data.cacheId !== cacheId) {
@@ -94,7 +126,7 @@ var CacheableSync = class extends Hookified {
         }
       }
     });
-    this._qified.subscribe("cache:delete" /* DELETE */, {
+    this._qified.subscribe(deleteEvent, {
       handler: async (message) => {
         const data = message.data;
         if (data.cacheId !== cacheId) {
@@ -115,6 +147,25 @@ var CacheableSync = class extends Hookified {
     const providers = Array.isArray(value) ? value : [value];
     return new Qified({ messageProviders: providers });
   }
+  /**
+   * Gets the namespace prefix to use for event names
+   * @returns The resolved namespace string or undefined
+   */
+  getNamespace() {
+    if (typeof this._namespace === "function") {
+      return this._namespace();
+    }
+    return this._namespace;
+  }
+  /**
+   * Prefixes an event name with the namespace if one is set
+   * @param event - The event to prefix
+   * @returns The prefixed event name or the original event
+   */
+  getPrefixedEvent(event) {
+    const ns = this.getNamespace();
+    return ns ? `${ns}::${event}` : event;
+  }
 };
 
 // src/index.ts
@@ -177,7 +228,10 @@ var Cacheable = class extends Hookified2 {
       }
     }
     if (options?.sync) {
-      this._sync = options.sync instanceof CacheableSync ? options.sync : new CacheableSync(options.sync);
+      this._sync = options.sync instanceof CacheableSync ? options.sync : new CacheableSync({
+        ...options.sync,
+        namespace: options.namespace
+      });
       this._sync.subscribe(this._primary, this._cacheId);
     }
   }
@@ -199,6 +253,9 @@ var Cacheable = class extends Hookified2 {
     if (this._secondary) {
       this._secondary.namespace = this.getNameSpace();
     }
+    if (this._sync) {
+      this._sync.namespace = namespace;
+    }
   }
   /**
    * The statistics for the cacheable instance

package/package.json

@@ -1,15 +1,21 @@
 {
   "name": "cacheable",
-  "version": "2.2.0",
+  "version": "2.3.1",
   "description": "High Performance Layer 1 / Layer 2 Caching with Keyv Storage",
   "type": "module",
-  "main": "./dist/index.cjs",
+  "main": "./dist/index.js",
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "exports": {
     ".": {
-      "require": "./dist/index.cjs",
-      "import": "./dist/index.js"
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
     }
   },
   "repository": {
@@ -21,25 +27,25 @@
   "license": "MIT",
   "private": false,
   "devDependencies": {
-    "@biomejs/biome": "^2.3.5",
+    "@biomejs/biome": "^2.3.8",
     "@faker-js/faker": "^10.1.0",
-    "@keyv/redis": "^5.1.4",
+    "@keyv/redis": "^5.1.5",
     "@keyv/valkey": "^1.0.11",
-    "@qified/redis": "^0.5.2",
-    "@types/node": "^24.10.1",
-    "@vitest/coverage-v8": "^4.0.9",
-    "lru-cache": "^11.2.2",
-    "rimraf": "^6.1.0",
+    "@qified/redis": "^0.5.3",
+    "@types/node": "^25.0.2",
+    "@vitest/coverage-v8": "^4.0.15",
+    "lru-cache": "^11.2.4",
+    "rimraf": "^6.1.2",
     "tsup": "^8.5.1",
     "typescript": "^5.9.3",
-    "vitest": "^4.0.9"
+    "vitest": "^4.0.15"
   },
   "dependencies": {
-    "hookified": "^1.13.0",
-    "keyv": "^5.5.4",
-    "qified": "^0.5.2",
-    "@cacheable/memory": "^2.0.5",
-    "@cacheable/utils": "^2.3.0"
+    "hookified": "^1.14.0",
+    "keyv": "^5.5.5",
+    "qified": "^0.5.3",
+    "@cacheable/memory": "^2.0.6",
+    "@cacheable/utils": "^2.3.2"
   },
   "keywords": [
     "cacheable",