cacheable 2.0.3 → 2.1.1

package/README.md

@@ -8,7 +8,7 @@
 [![npm](https://img.shields.io/npm/v/cacheable)](https://www.npmjs.com/package/cacheable)
 [![license](https://img.shields.io/github/license/jaredwray/cacheable)](https://github.com/jaredwray/cacheable/blob/main/LICENSE)
 
-`cacheable` is a high performance layer 1 / layer 2 caching engine that is focused on distributed caching with enterprise features such as `CacheSync` (coming soon). It is built on top of the robust storage engine [Keyv](https://keyv.org) and provides a simple API to cache and retrieve data.
+`cacheable` is a high performance layer 1 / layer 2 caching engine that is focused on distributed caching with enterprise features such as `CacheSync`. It is built on top of the robust storage engine [Keyv](https://keyv.org) and provides a simple API to cache and retrieve data.
 
 * Simple to use with robust API
 * Not bloated with additional modules
@@ -19,7 +19,7 @@
 * Hooks and Events to extend functionality
 * Shorthand for ttl in milliseconds `(1m = 60000) (1h = 3600000) (1d = 86400000)`
 * Non-blocking operations for layer 2 caching
-* Distributed Caching Sync via Pub/Sub (coming soon)
+* **Distributed Caching Sync via Pub/Sub with CacheSync**
 * Comprehensive testing and code coverage
 * ESM and CommonJS support with Typescript
 * Maintained and supported regularly
@@ -34,7 +34,7 @@
 * [Shorthand for Time to Live (ttl)](#shorthand-for-time-to-live-ttl)
 * [Non-Blocking Operations](#non-blocking-operations)
 * [Non-Blocking with @keyv/redis](#non-blocking-with-keyvredis)
-* [CacheSync - Distributed Updates](#cachesync---distributed-updates)
+* [CacheableSync - Distributed Updates](#cacheablesync---distributed-updates)
 * [Cacheable Options](#cacheable-options)
 * [Cacheable Statistics (Instance Only)](#cacheable-statistics-instance-only)
 * [Cacheable - API](#cacheable---api)
@@ -359,17 +359,108 @@ const secondary = new KeyvRedis('redis://user:pass@localhost:6379');
 const cache = new Cacheable({secondary, nonBlocking: true});
 ```
 
-# CacheSync - Distributed Updates
+# CacheableSync - Distributed Updates
 
-`cacheable` has a feature called `CacheSync` that is coming soon. This feature will allow you to have distributed caching with Pub/Sub. This will allow you to have multiple instances of `cacheable` running and when a value is set, deleted, or cleared it will update all instances of `cacheable` with the same value. Current plan is to support the following:
+`cacheable` includes `CacheableSync`, a feature that enables distributed cache synchronization across multiple instances using Pub/Sub messaging via [Qified](https://github.com/jaredwray/qified). When a value is set or deleted in one cache instance, all other connected instances automatically receive and apply the update.
 
-* [AWS SQS](https://aws.amazon.com/sqs)
-* [RabbitMQ](https://www.rabbitmq.com)
-* [Nats](https://nats.io)
-* [Azure Service Bus](https://azure.microsoft.com/en-us/services/service-bus)
-* [Redis Pub/Sub](https://redis.io/topics/pubsub)
+## How It Works
 
-This feature should be live by end of year. 
+`CacheableSync` uses message providers from Qified to broadcast cache operations (SET and DELETE) to all connected cache instances. Each instance subscribes to these events and automatically updates its `primary` (example: in-memory) storage when receiving updates from other instances.
+
+## Supported Message Providers
+
+`Qified` supports multiple providers and you can learn more by going to https://qified.org.
+
+## Basic Usage
+
+```javascript
+import { Cacheable } from 'cacheable';
+import { RedisMessageProvider } from '@qified/redis';
+
+// Create a Redis message provider
+const provider = new RedisMessageProvider({
+  connection: { host: 'localhost', port: 6379 }
+});
+
+// Create cache instances with sync enabled
+const cache1 = new Cacheable({
+  sync: { qified: provider }
+});
+
+const cache2 = new Cacheable({
+  sync: { qified: provider }
+});
+
+// Set a value in cache1
+await cache1.set('key', 'value');
+
+// Note: you might want to sleep for a bit based on the backend.
+
+// The value is automatically synced to cache2
+const value = await cache2.get('key'); // Returns 'value'
+```
+
+## Using Multiple Message Providers
+
+You can use multiple message providers for redundancy:
+
+```javascript
+import { Cacheable } from 'cacheable';
+import { RedisMessageProvider } from '@qified/redis';
+import { NatsMessageProvider } from '@qified/nats';
+
+const redisProvider = new RedisMessageProvider({
+  connection: { host: 'localhost', port: 6379 }
+});
+
+const natsProvider = new NatsMessageProvider({
+  servers: ['nats://localhost:4222']
+});
+
+const cache = new Cacheable({
+  sync: { qified: [redisProvider, natsProvider] }
+});
+```
+
+## Using an Existing Qified Instance
+
+You can also pass a pre-configured Qified instance:
+
+```javascript
+import { Cacheable } from 'cacheable';
+import { Qified } from 'qified';
+import { RedisMessageProvider } from '@qified/redis';
+
+const provider = new RedisMessageProvider({
+  connection: { host: 'localhost', port: 6379 }
+});
+
+const qified = new Qified({ messageProviders: [provider] });
+
+const cache = new Cacheable({
+  sync: { qified }
+});
+```
+
+## How Sync Works
+
+1. **SET Operations**: When you call `cache.set()` or `cache.setMany()`, the cache:
+   - Updates the local primary storage and secondary storage
+   - Publishes a `cache:set` event with the key, value, ttl, and cacheId
+   - Other cache instances receive the event and update their `primary` storage (excluding the originating instance)
+
+2. **DELETE Operations**: When you call `cache.delete()` or `cache.deleteMany()`, the cache:
+   - Removes the key from primary and secondary storage
+   - Publishes a `cache:delete` event with the key and cacheId
+   - Other cache instances receive the event and remove the key from their storage
+
+## Important Notes
+
+* Cache sync only works with the **primary storage layer**. Secondary storage is usually handled by the instance doing the initial work.
+* Each cache instance should have a unique `cacheId` to properly filter sync events. This is setup by default but you can set it if you want.
+* Sync events are **eventually consistent** - there may be a small delay between when a value is set and when it appears in other instances.
+* The sync feature requires a message provider to be running and accessible by all cache instances.
+* Each cache instance has a unique `cacheId`. Events are only applied if they come from a different instance, preventing infinite loops.
 
 # Cacheable Options
 
@@ -381,6 +472,10 @@ The following options are available for you to configure `cacheable`:
 * `stats`: To enable statistics for this instance. Default is `false`.
 * `ttl`: The default time to live for the cache in milliseconds. Default is `undefined` which is disabled.
 * `namespace`: The namespace for the cache. Default is `undefined`.
+* `cacheId`: A unique identifier for this cache instance. Used for sync filtering. Default is a random string.
+* `sync`: Enable distributed cache synchronization. Can be:
+  - `CacheableSync` instance
+  - `CacheableSyncOptions` object with `{ qified: MessageProvider | MessageProvider[] | Qified }`
 
 # Cacheable Statistics (Instance Only)
 

package/dist/index.cjs

@@ -25,6 +25,8 @@ __export(index_exports, {
   CacheableHooks: () => CacheableHooks,
   CacheableMemory: () => import_memory2.CacheableMemory,
   CacheableStats: () => import_utils2.Stats,
+  CacheableSync: () => CacheableSync,
+  CacheableSyncEvents: () => CacheableSyncEvents,
   HashAlgorithm: () => import_utils2.HashAlgorithm,
   Keyv: () => import_keyv2.Keyv,
   KeyvCacheableMemory: () => import_memory2.KeyvCacheableMemory,
@@ -43,7 +45,7 @@ module.exports = __toCommonJS(index_exports);
 var import_memoize = require("@cacheable/memoize");
 var import_memory = require("@cacheable/memory");
 var import_utils = require("@cacheable/utils");
-var import_hookified = require("hookified");
+var import_hookified2 = require("hookified");
 var import_keyv = require("keyv");
 
 // src/enums.ts
@@ -66,12 +68,92 @@ var CacheableEvents = /* @__PURE__ */ ((CacheableEvents2) => {
   return CacheableEvents2;
 })(CacheableEvents || {});
 
+// src/sync.ts
+var import_hookified = require("hookified");
+var import_qified = require("qified");
+var CacheableSyncEvents = /* @__PURE__ */ ((CacheableSyncEvents2) => {
+  CacheableSyncEvents2["ERROR"] = "error";
+  CacheableSyncEvents2["SET"] = "cache:set";
+  CacheableSyncEvents2["DELETE"] = "cache:delete";
+  return CacheableSyncEvents2;
+})(CacheableSyncEvents || {});
+var CacheableSync = class extends import_hookified.Hookified {
+  _qified = new import_qified.Qified();
+  /**
+   * Creates an instance of CacheableSync
+   * @param options - Configuration options for CacheableSync
+   */
+  constructor(options) {
+    super(options);
+    this._qified = this.createQified(options.qified);
+  }
+  /**
+   * Gets the Qified instance used for synchronization
+   * @returns The Qified instance
+   */
+  get qified() {
+    return this._qified;
+  }
+  /**
+   * Sets the Qified instance used for synchronization
+   * @param value - Either an existing Qified instance or MessageProvider(s)
+   */
+  set qified(value) {
+    this._qified = this.createQified(value);
+  }
+  /**
+   * 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, {
+      id: crypto.randomUUID(),
+      data
+    });
+  }
+  /**
+   * Subscribes to sync events and updates the provided storage
+   * @param storage - The Keyv storage instance to update
+   * @param cacheId - The cache ID to identify this instance
+   */
+  subscribe(storage, cacheId) {
+    this._qified.subscribe("cache:set" /* SET */, {
+      handler: async (message) => {
+        const data = message.data;
+        if (data.cacheId !== cacheId) {
+          await storage.set(data.key, data.value, data.ttl);
+        }
+      }
+    });
+    this._qified.subscribe("cache:delete" /* DELETE */, {
+      handler: async (message) => {
+        const data = message.data;
+        if (data.cacheId !== cacheId) {
+          await storage.delete(data.key);
+        }
+      }
+    });
+  }
+  /**
+   * Creates or returns a Qified instance from the provided value
+   * @param value - Either an existing Qified instance or MessageProvider(s)
+   * @returns A Qified instance configured with the provided message provider(s)
+   */
+  createQified(value) {
+    if (value instanceof import_qified.Qified) {
+      return value;
+    }
+    const providers = Array.isArray(value) ? value : [value];
+    return new import_qified.Qified({ messageProviders: providers });
+  }
+};
+
 // src/index.ts
 var import_memoize2 = require("@cacheable/memoize");
 var import_memory2 = require("@cacheable/memory");
 var import_utils2 = require("@cacheable/utils");
 var import_keyv2 = require("keyv");
-var Cacheable = class extends import_hookified.Hookified {
+var Cacheable = class extends import_hookified2.Hookified {
   _primary = (0, import_memory.createKeyv)();
   _secondary;
   _nonBlocking = false;
@@ -79,6 +161,7 @@ var Cacheable = class extends import_hookified.Hookified {
   _stats = new import_utils.Stats({ enabled: false });
   _namespace;
   _cacheId = Math.random().toString(36).slice(2);
+  _sync;
   /**
    * Creates a new cacheable instance
    * @param {CacheableOptions} [options] The options for the cacheable instance
@@ -110,6 +193,10 @@ var Cacheable = class extends import_hookified.Hookified {
         this._secondary.namespace = this.getNameSpace();
       }
     }
+    if (options?.sync) {
+      this._sync = options.sync instanceof CacheableSync ? options.sync : new CacheableSync(options.sync);
+      this._sync.subscribe(this._primary, this._cacheId);
+    }
   }
   /**
    * The namespace for the cacheable instance
@@ -245,13 +332,30 @@ var Cacheable = class extends import_hookified.Hookified {
   set cacheId(cacheId) {
     this._cacheId = cacheId;
   }
+  /**
+   * Gets the sync instance for the cacheable instance
+   * @returns {CacheableSync | undefined} The sync instance for the cacheable instance
+   */
+  get sync() {
+    return this._sync;
+  }
+  /**
+   * Sets the sync instance for the cacheable instance
+   * @param {CacheableSync | undefined} sync The sync instance for the cacheable instance
+   */
+  set sync(sync) {
+    this._sync = sync;
+    if (this._sync) {
+      this._sync.subscribe(this._primary, this._cacheId);
+    }
+  }
   /**
    * Sets the primary store for the cacheable instance
    * @param {Keyv | KeyvStoreAdapter} primary The primary store for the cacheable instance
    * @returns {void}
    */
   setPrimary(primary) {
-    if (this.isKeyvInstance(primary)) {
+    if ((0, import_utils.isKeyvInstance)(primary)) {
       this._primary = primary;
     } else {
       this._primary = new import_keyv.Keyv(primary);
@@ -266,7 +370,7 @@ var Cacheable = class extends import_hookified.Hookified {
    * @returns {void}
    */
   setSecondary(secondary) {
-    if (this.isKeyvInstance(secondary)) {
+    if ((0, import_utils.isKeyvInstance)(secondary)) {
       this._secondary = secondary;
     } else {
       this._secondary = new import_keyv.Keyv(secondary);
@@ -275,28 +379,6 @@ var Cacheable = class extends import_hookified.Hookified {
       this.emit("error" /* ERROR */, error);
     });
   }
-  // biome-ignore lint/suspicious/noExplicitAny: type format
-  isKeyvInstance(keyv) {
-    if (keyv instanceof import_keyv.Keyv) {
-      return true;
-    }
-    const keyvMethods = [
-      "generateIterator",
-      "get",
-      "getMany",
-      "set",
-      "setMany",
-      "delete",
-      "deleteMany",
-      "has",
-      "hasMany",
-      "clear",
-      "disconnect",
-      "serialize",
-      "deserialize"
-    ];
-    return keyvMethods.every((method) => typeof keyv[method] === "function");
-  }
   getNameSpace() {
     if (typeof this._namespace === "function") {
       return this._namespace();
@@ -489,6 +571,14 @@ var Cacheable = class extends import_hookified.Hookified {
         result = results[0];
       }
       await this.hook("AFTER_SET" /* AFTER_SET */, item);
+      if (this._sync && result) {
+        await this._sync.publish("cache:set" /* SET */, {
+          cacheId: this._cacheId,
+          key: item.key,
+          value: item.value,
+          ttl: item.ttl
+        });
+      }
     } catch (error) {
       this.emit("error" /* ERROR */, error);
     }
@@ -520,6 +610,16 @@ var Cacheable = class extends import_hookified.Hookified {
         }
       }
       await this.hook("AFTER_SET_MANY" /* AFTER_SET_MANY */, items);
+      if (this._sync && result) {
+        for (const item of items) {
+          await this._sync.publish("cache:set" /* SET */, {
+            cacheId: this._cacheId,
+            key: item.key,
+            value: item.value,
+            ttl: (0, import_utils.shorthandToMilliseconds)(item.ttl)
+          });
+        }
+      }
     } catch (error) {
       this.emit("error" /* ERROR */, error);
     }
@@ -626,6 +726,12 @@ var Cacheable = class extends import_hookified.Hookified {
       const resultAll = await Promise.all(promises);
       result = resultAll[0];
     }
+    if (this._sync && result) {
+      await this._sync.publish("cache:delete" /* DELETE */, {
+        cacheId: this._cacheId,
+        key
+      });
+    }
     return result;
   }
   /**
@@ -653,6 +759,14 @@ var Cacheable = class extends import_hookified.Hookified {
         await this._secondary.deleteMany(keys);
       }
     }
+    if (this._sync && result) {
+      for (const key of keys) {
+        await this._sync.publish("cache:delete" /* DELETE */, {
+          cacheId: this._cacheId,
+          key
+        });
+      }
+    }
     return result;
   }
   /**
@@ -955,6 +1069,8 @@ var Cacheable = class extends import_hookified.Hookified {
   CacheableHooks,
   CacheableMemory,
   CacheableStats,
+  CacheableSync,
+  CacheableSyncEvents,
   HashAlgorithm,
   Keyv,
   KeyvCacheableMemory,

package/dist/index.d.cts

@@ -2,11 +2,75 @@ import { WrapFunctionOptions, GetOrSetKey, GetOrSetFunctionOptions } from '@cach
 export { GetOrSetFunctionOptions, GetOrSetKey, GetOrSetOptions, WrapOptions, WrapSyncOptions, getOrSet, wrap, wrapSync } from '@cacheable/memoize';
 import { Stats, CacheableItem, HashAlgorithm } from '@cacheable/utils';
 export { CacheableItem, Stats as CacheableStats, HashAlgorithm, calculateTtlFromExpiration, getCascadingTtl, hash, shorthandToMilliseconds, shorthandToTime } from '@cacheable/utils';
-import { Hookified } from 'hookified';
+import { Hookified, HookifiedOptions } from 'hookified';
 import { Keyv, KeyvStoreAdapter, StoredDataRaw } from 'keyv';
 export { Keyv, KeyvHooks, KeyvOptions, KeyvStoreAdapter } from 'keyv';
+import { Qified, MessageProvider } from 'qified';
 export { CacheableMemory, CacheableMemoryOptions, KeyvCacheableMemory, KeyvCacheableMemoryOptions, createKeyv } from '@cacheable/memory';
 
+/**
+ * Events emitted by CacheableSync
+ */
+declare enum CacheableSyncEvents {
+    ERROR = "error",
+    SET = "cache:set",
+    DELETE = "cache:delete"
+}
+/**
+ * Configuration options for CacheableSync
+ */
+type CacheableSyncOptions = {
+    /**
+     * Qified instance or message provider(s) for synchronization
+     */
+    qified: Qified | MessageProvider | MessageProvider[];
+} & HookifiedOptions;
+type CacheableSyncItem = {
+    cacheId: string;
+    key: string;
+    value?: unknown;
+    ttl?: number;
+};
+/**
+ * CacheableSync provides synchronization capabilities for cacheable items
+ * using message providers from Qified
+ */
+declare class CacheableSync extends Hookified {
+    private _qified;
+    /**
+     * Creates an instance of CacheableSync
+     * @param options - Configuration options for CacheableSync
+     */
+    constructor(options: CacheableSyncOptions);
+    /**
+     * Gets the Qified instance used for synchronization
+     * @returns The Qified instance
+     */
+    get qified(): Qified;
+    /**
+     * Sets the Qified instance used for synchronization
+     * @param value - Either an existing Qified instance or MessageProvider(s)
+     */
+    set qified(value: Qified | MessageProvider | MessageProvider[]);
+    /**
+     * Publishes a cache event to all the cache instances
+     * @param data - The cache item data containing cacheId, key, value, and optional ttl
+     */
+    publish(event: CacheableSyncEvents, data: CacheableSyncItem): Promise<void>;
+    /**
+     * Subscribes to sync events and updates the provided storage
+     * @param storage - The Keyv storage instance to update
+     * @param cacheId - The cache ID to identify this instance
+     */
+    subscribe(storage: Keyv, cacheId: string): void;
+    /**
+     * Creates or returns a Qified instance from the provided value
+     * @param value - Either an existing Qified instance or MessageProvider(s)
+     * @returns A Qified instance configured with the provided message provider(s)
+     */
+    createQified(value: Qified | MessageProvider | MessageProvider[]): Qified;
+}
+
 type CacheableOptions = {
     /**
      * The primary store for the cacheable instance
@@ -40,6 +104,10 @@ type CacheableOptions = {
      * If it is not set then it will be a random string that is generated
      */
     cacheId?: string;
+    /**
+     * The sync instance for the cacheable instance to enable synchronization across cache instances
+     */
+    sync?: CacheableSync | CacheableSyncOptions;
 };
 type GetOptions = {
     /**
@@ -74,6 +142,7 @@ declare class Cacheable extends Hookified {
     private readonly _stats;
     private _namespace?;
     private _cacheId;
+    private _sync?;
     /**
      * Creates a new cacheable instance
      * @param {CacheableOptions} [options] The options for the cacheable instance
@@ -183,6 +252,16 @@ declare class Cacheable extends Hookified {
      * @param {string} cacheId The cacheId for the cacheable instance
      */
     set cacheId(cacheId: string);
+    /**
+     * Gets the sync instance for the cacheable instance
+     * @returns {CacheableSync | undefined} The sync instance for the cacheable instance
+     */
+    get sync(): CacheableSync | undefined;
+    /**
+     * Sets the sync instance for the cacheable instance
+     * @param {CacheableSync | undefined} sync The sync instance for the cacheable instance
+     */
+    set sync(sync: CacheableSync | undefined);
     /**
      * Sets the primary store for the cacheable instance
      * @param {Keyv | KeyvStoreAdapter} primary The primary store for the cacheable instance
@@ -195,7 +274,6 @@ declare class Cacheable extends Hookified {
      * @returns {void}
      */
     setSecondary(secondary: Keyv | KeyvStoreAdapter): void;
-    isKeyvInstance(keyv: any): boolean;
     getNameSpace(): string | undefined;
     /**
      * Retrieves an entry from the cache.
@@ -376,4 +454,4 @@ declare class Cacheable extends Hookified {
     private setTtl;
 }
 
-export { Cacheable, CacheableEvents, CacheableHooks, type CacheableOptions };
+export { Cacheable, CacheableEvents, CacheableHooks, type CacheableOptions, CacheableSync, CacheableSyncEvents, type CacheableSyncItem, type CacheableSyncOptions };

package/dist/index.d.ts

@@ -2,11 +2,75 @@ import { WrapFunctionOptions, GetOrSetKey, GetOrSetFunctionOptions } from '@cach
 export { GetOrSetFunctionOptions, GetOrSetKey, GetOrSetOptions, WrapOptions, WrapSyncOptions, getOrSet, wrap, wrapSync } from '@cacheable/memoize';
 import { Stats, CacheableItem, HashAlgorithm } from '@cacheable/utils';
 export { CacheableItem, Stats as CacheableStats, HashAlgorithm, calculateTtlFromExpiration, getCascadingTtl, hash, shorthandToMilliseconds, shorthandToTime } from '@cacheable/utils';
-import { Hookified } from 'hookified';
+import { Hookified, HookifiedOptions } from 'hookified';
 import { Keyv, KeyvStoreAdapter, StoredDataRaw } from 'keyv';
 export { Keyv, KeyvHooks, KeyvOptions, KeyvStoreAdapter } from 'keyv';
+import { Qified, MessageProvider } from 'qified';
 export { CacheableMemory, CacheableMemoryOptions, KeyvCacheableMemory, KeyvCacheableMemoryOptions, createKeyv } from '@cacheable/memory';
 
+/**
+ * Events emitted by CacheableSync
+ */
+declare enum CacheableSyncEvents {
+    ERROR = "error",
+    SET = "cache:set",
+    DELETE = "cache:delete"
+}
+/**
+ * Configuration options for CacheableSync
+ */
+type CacheableSyncOptions = {
+    /**
+     * Qified instance or message provider(s) for synchronization
+     */
+    qified: Qified | MessageProvider | MessageProvider[];
+} & HookifiedOptions;
+type CacheableSyncItem = {
+    cacheId: string;
+    key: string;
+    value?: unknown;
+    ttl?: number;
+};
+/**
+ * CacheableSync provides synchronization capabilities for cacheable items
+ * using message providers from Qified
+ */
+declare class CacheableSync extends Hookified {
+    private _qified;
+    /**
+     * Creates an instance of CacheableSync
+     * @param options - Configuration options for CacheableSync
+     */
+    constructor(options: CacheableSyncOptions);
+    /**
+     * Gets the Qified instance used for synchronization
+     * @returns The Qified instance
+     */
+    get qified(): Qified;
+    /**
+     * Sets the Qified instance used for synchronization
+     * @param value - Either an existing Qified instance or MessageProvider(s)
+     */
+    set qified(value: Qified | MessageProvider | MessageProvider[]);
+    /**
+     * Publishes a cache event to all the cache instances
+     * @param data - The cache item data containing cacheId, key, value, and optional ttl
+     */
+    publish(event: CacheableSyncEvents, data: CacheableSyncItem): Promise<void>;
+    /**
+     * Subscribes to sync events and updates the provided storage
+     * @param storage - The Keyv storage instance to update
+     * @param cacheId - The cache ID to identify this instance
+     */
+    subscribe(storage: Keyv, cacheId: string): void;
+    /**
+     * Creates or returns a Qified instance from the provided value
+     * @param value - Either an existing Qified instance or MessageProvider(s)
+     * @returns A Qified instance configured with the provided message provider(s)
+     */
+    createQified(value: Qified | MessageProvider | MessageProvider[]): Qified;
+}
+
 type CacheableOptions = {
     /**
      * The primary store for the cacheable instance
@@ -40,6 +104,10 @@ type CacheableOptions = {
      * If it is not set then it will be a random string that is generated
      */
     cacheId?: string;
+    /**
+     * The sync instance for the cacheable instance to enable synchronization across cache instances
+     */
+    sync?: CacheableSync | CacheableSyncOptions;
 };
 type GetOptions = {
     /**
@@ -74,6 +142,7 @@ declare class Cacheable extends Hookified {
     private readonly _stats;
     private _namespace?;
     private _cacheId;
+    private _sync?;
     /**
      * Creates a new cacheable instance
      * @param {CacheableOptions} [options] The options for the cacheable instance
@@ -183,6 +252,16 @@ declare class Cacheable extends Hookified {
      * @param {string} cacheId The cacheId for the cacheable instance
      */
     set cacheId(cacheId: string);
+    /**
+     * Gets the sync instance for the cacheable instance
+     * @returns {CacheableSync | undefined} The sync instance for the cacheable instance
+     */
+    get sync(): CacheableSync | undefined;
+    /**
+     * Sets the sync instance for the cacheable instance
+     * @param {CacheableSync | undefined} sync The sync instance for the cacheable instance
+     */
+    set sync(sync: CacheableSync | undefined);
     /**
      * Sets the primary store for the cacheable instance
      * @param {Keyv | KeyvStoreAdapter} primary The primary store for the cacheable instance
@@ -195,7 +274,6 @@ declare class Cacheable extends Hookified {
      * @returns {void}
      */
     setSecondary(secondary: Keyv | KeyvStoreAdapter): void;
-    isKeyvInstance(keyv: any): boolean;
     getNameSpace(): string | undefined;
     /**
      * Retrieves an entry from the cache.
@@ -376,4 +454,4 @@ declare class Cacheable extends Hookified {
     private setTtl;
 }
 
-export { Cacheable, CacheableEvents, CacheableHooks, type CacheableOptions };
+export { Cacheable, CacheableEvents, CacheableHooks, type CacheableOptions, CacheableSync, CacheableSyncEvents, type CacheableSyncItem, type CacheableSyncOptions };

package/dist/index.js

@@ -10,9 +10,10 @@ import {
   getCascadingTtl,
   HashAlgorithm,
   hash,
+  isKeyvInstance,
   shorthandToMilliseconds
 } from "@cacheable/utils";
-import { Hookified } from "hookified";
+import { Hookified as Hookified2 } from "hookified";
 import {
   Keyv
 } from "keyv";
@@ -37,6 +38,86 @@ var CacheableEvents = /* @__PURE__ */ ((CacheableEvents2) => {
   return CacheableEvents2;
 })(CacheableEvents || {});
 
+// src/sync.ts
+import { Hookified } from "hookified";
+import { Qified } from "qified";
+var CacheableSyncEvents = /* @__PURE__ */ ((CacheableSyncEvents2) => {
+  CacheableSyncEvents2["ERROR"] = "error";
+  CacheableSyncEvents2["SET"] = "cache:set";
+  CacheableSyncEvents2["DELETE"] = "cache:delete";
+  return CacheableSyncEvents2;
+})(CacheableSyncEvents || {});
+var CacheableSync = class extends Hookified {
+  _qified = new Qified();
+  /**
+   * Creates an instance of CacheableSync
+   * @param options - Configuration options for CacheableSync
+   */
+  constructor(options) {
+    super(options);
+    this._qified = this.createQified(options.qified);
+  }
+  /**
+   * Gets the Qified instance used for synchronization
+   * @returns The Qified instance
+   */
+  get qified() {
+    return this._qified;
+  }
+  /**
+   * Sets the Qified instance used for synchronization
+   * @param value - Either an existing Qified instance or MessageProvider(s)
+   */
+  set qified(value) {
+    this._qified = this.createQified(value);
+  }
+  /**
+   * 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, {
+      id: crypto.randomUUID(),
+      data
+    });
+  }
+  /**
+   * Subscribes to sync events and updates the provided storage
+   * @param storage - The Keyv storage instance to update
+   * @param cacheId - The cache ID to identify this instance
+   */
+  subscribe(storage, cacheId) {
+    this._qified.subscribe("cache:set" /* SET */, {
+      handler: async (message) => {
+        const data = message.data;
+        if (data.cacheId !== cacheId) {
+          await storage.set(data.key, data.value, data.ttl);
+        }
+      }
+    });
+    this._qified.subscribe("cache:delete" /* DELETE */, {
+      handler: async (message) => {
+        const data = message.data;
+        if (data.cacheId !== cacheId) {
+          await storage.delete(data.key);
+        }
+      }
+    });
+  }
+  /**
+   * Creates or returns a Qified instance from the provided value
+   * @param value - Either an existing Qified instance or MessageProvider(s)
+   * @returns A Qified instance configured with the provided message provider(s)
+   */
+  createQified(value) {
+    if (value instanceof Qified) {
+      return value;
+    }
+    const providers = Array.isArray(value) ? value : [value];
+    return new Qified({ messageProviders: providers });
+  }
+};
+
 // src/index.ts
 import {
   getOrSet as getOrSet2,
@@ -58,7 +139,7 @@ import {
   shorthandToTime
 } from "@cacheable/utils";
 import { Keyv as Keyv2, KeyvHooks } from "keyv";
-var Cacheable = class extends Hookified {
+var Cacheable = class extends Hookified2 {
   _primary = createKeyv();
   _secondary;
   _nonBlocking = false;
@@ -66,6 +147,7 @@ var Cacheable = class extends Hookified {
   _stats = new CacheableStats({ enabled: false });
   _namespace;
   _cacheId = Math.random().toString(36).slice(2);
+  _sync;
   /**
    * Creates a new cacheable instance
    * @param {CacheableOptions} [options] The options for the cacheable instance
@@ -97,6 +179,10 @@ var Cacheable = class extends Hookified {
         this._secondary.namespace = this.getNameSpace();
       }
     }
+    if (options?.sync) {
+      this._sync = options.sync instanceof CacheableSync ? options.sync : new CacheableSync(options.sync);
+      this._sync.subscribe(this._primary, this._cacheId);
+    }
   }
   /**
    * The namespace for the cacheable instance
@@ -232,13 +318,30 @@ var Cacheable = class extends Hookified {
   set cacheId(cacheId) {
     this._cacheId = cacheId;
   }
+  /**
+   * Gets the sync instance for the cacheable instance
+   * @returns {CacheableSync | undefined} The sync instance for the cacheable instance
+   */
+  get sync() {
+    return this._sync;
+  }
+  /**
+   * Sets the sync instance for the cacheable instance
+   * @param {CacheableSync | undefined} sync The sync instance for the cacheable instance
+   */
+  set sync(sync) {
+    this._sync = sync;
+    if (this._sync) {
+      this._sync.subscribe(this._primary, this._cacheId);
+    }
+  }
   /**
    * Sets the primary store for the cacheable instance
    * @param {Keyv | KeyvStoreAdapter} primary The primary store for the cacheable instance
    * @returns {void}
    */
   setPrimary(primary) {
-    if (this.isKeyvInstance(primary)) {
+    if (isKeyvInstance(primary)) {
       this._primary = primary;
     } else {
       this._primary = new Keyv(primary);
@@ -253,7 +356,7 @@ var Cacheable = class extends Hookified {
    * @returns {void}
    */
   setSecondary(secondary) {
-    if (this.isKeyvInstance(secondary)) {
+    if (isKeyvInstance(secondary)) {
       this._secondary = secondary;
     } else {
       this._secondary = new Keyv(secondary);
@@ -262,28 +365,6 @@ var Cacheable = class extends Hookified {
       this.emit("error" /* ERROR */, error);
     });
   }
-  // biome-ignore lint/suspicious/noExplicitAny: type format
-  isKeyvInstance(keyv) {
-    if (keyv instanceof Keyv) {
-      return true;
-    }
-    const keyvMethods = [
-      "generateIterator",
-      "get",
-      "getMany",
-      "set",
-      "setMany",
-      "delete",
-      "deleteMany",
-      "has",
-      "hasMany",
-      "clear",
-      "disconnect",
-      "serialize",
-      "deserialize"
-    ];
-    return keyvMethods.every((method) => typeof keyv[method] === "function");
-  }
   getNameSpace() {
     if (typeof this._namespace === "function") {
       return this._namespace();
@@ -476,6 +557,14 @@ var Cacheable = class extends Hookified {
         result = results[0];
       }
       await this.hook("AFTER_SET" /* AFTER_SET */, item);
+      if (this._sync && result) {
+        await this._sync.publish("cache:set" /* SET */, {
+          cacheId: this._cacheId,
+          key: item.key,
+          value: item.value,
+          ttl: item.ttl
+        });
+      }
     } catch (error) {
       this.emit("error" /* ERROR */, error);
     }
@@ -507,6 +596,16 @@ var Cacheable = class extends Hookified {
         }
       }
       await this.hook("AFTER_SET_MANY" /* AFTER_SET_MANY */, items);
+      if (this._sync && result) {
+        for (const item of items) {
+          await this._sync.publish("cache:set" /* SET */, {
+            cacheId: this._cacheId,
+            key: item.key,
+            value: item.value,
+            ttl: shorthandToMilliseconds(item.ttl)
+          });
+        }
+      }
     } catch (error) {
       this.emit("error" /* ERROR */, error);
     }
@@ -613,6 +712,12 @@ var Cacheable = class extends Hookified {
       const resultAll = await Promise.all(promises);
       result = resultAll[0];
     }
+    if (this._sync && result) {
+      await this._sync.publish("cache:delete" /* DELETE */, {
+        cacheId: this._cacheId,
+        key
+      });
+    }
     return result;
   }
   /**
@@ -640,6 +745,14 @@ var Cacheable = class extends Hookified {
         await this._secondary.deleteMany(keys);
       }
     }
+    if (this._sync && result) {
+      for (const key of keys) {
+        await this._sync.publish("cache:delete" /* DELETE */, {
+          cacheId: this._cacheId,
+          key
+        });
+      }
+    }
     return result;
   }
   /**
@@ -941,6 +1054,8 @@ export {
   CacheableHooks,
   CacheableMemory,
   Stats as CacheableStats,
+  CacheableSync,
+  CacheableSyncEvents,
   HashAlgorithm2 as HashAlgorithm,
   Keyv2 as Keyv,
   KeyvCacheableMemory,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cacheable",
-  "version": "2.0.3",
+  "version": "2.1.1",
   "description": "High Performance Layer 1 / Layer 2 Caching with Keyv Storage",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -21,24 +21,26 @@
   "license": "MIT",
   "private": false,
   "devDependencies": {
-    "@biomejs/biome": "^2.2.4",
-    "@faker-js/faker": "^10.0.0",
-    "@keyv/redis": "^5.1.2",
-    "@keyv/valkey": "^1.0.8",
-    "@types/node": "^24.5.2",
+    "@biomejs/biome": "^2.2.6",
+    "@faker-js/faker": "^10.1.0",
+    "@keyv/redis": "^5.1.3",
+    "@keyv/valkey": "^1.0.10",
+    "@qified/redis": "^0.5.0",
+    "@types/node": "^24.8.1",
     "@vitest/coverage-v8": "^3.2.4",
-    "lru-cache": "^11.2.1",
+    "lru-cache": "^11.2.2",
     "rimraf": "^6.0.1",
     "tsup": "^8.5.0",
-    "typescript": "^5.9.2",
+    "typescript": "^5.9.3",
     "vitest": "^3.2.4"
   },
   "dependencies": {
-    "hookified": "^1.12.1",
+    "hookified": "^1.12.2",
     "keyv": "^5.5.3",
+    "qified": "^0.5.0",
     "@cacheable/memoize": "^2.0.3",
     "@cacheable/memory": "^2.0.3",
-    "@cacheable/utils": "^2.0.3"
+    "@cacheable/utils": "^2.1.0"
   },
   "keywords": [
     "cacheable",