cacheable 1.8.3 → 1.8.5

package/README.md

@@ -17,7 +17,7 @@
 * Scalable and trusted storage engine by Keyv
 * Memory Caching with LRU and Expiration `CacheableMemory`
 * Resilient to failures with try/catch and offline
-* Wrap / Memoization for Sync and Async Functions
+* Wrap / Memoization for Sync and Async Functions with Stampede Protection
 * Hooks and Events to extend functionality
 * Shorthand for ttl in milliseconds `(1m = 60000) (1h = 3600000) (1d = 86400000)`
 * Non-blocking operations for layer 2 caching
@@ -310,6 +310,30 @@ const wrappedFunction = cache.wrap(asyncFunction, options);
 console.log(await wrappedFunction(2)); // 4
 console.log(await wrappedFunction(2)); // 4 from cache
 ```
+With `Cacheable` we have also included stampede protection so that a `Promise` based call will only be called once if multiple requests of the same are executed at the same time. Here is an example of how to test for stampede protection:
+  
+```javascript
+import { Cacheable } from 'cacheable';
+const asyncFunction = async (value: number) => {
+  return value;
+};
+
+const cache = new Cacheable();
+const options = {
+  ttl: '1h', // 1 hour
+  keyPrefix: 'p1', // key prefix. This is used if you have multiple functions and need to set a unique prefix.
+}
+
+const wrappedFunction = cache.wrap(asyncFunction, options);
+const promises = [];
+for (let i = 0; i < 10; i++) {
+  promises.push(wrappedFunction(i));
+}
+
+const results = await Promise.all(promises); // all results should be the same
+
+console.log(results); // [0, 0, 0, 0, 0, 0, 0, 0, 0, 0]
+```
 
 In this example we are wrapping an `async` function in a cache with a `ttl` of `1 hour`. This will cache the result of the function for `1 hour` and then expire the value. You can also wrap a `sync` function in a cache:
 
@@ -323,11 +347,24 @@ const cache = new CacheableMemory();
 const wrappedFunction = cache.wrap(syncFunction, { ttl: '1h', key: 'syncFunction' });
 console.log(wrappedFunction(2)); // 4
 console.log(wrappedFunction(2)); // 4 from cache
-console.log(cache.get('syncFunction')); // 4
 ```
 
 In this example we are wrapping a `sync` function in a cache with a `ttl` of `1 hour`. This will cache the result of the function for `1 hour` and then expire the value. You can also set the `key` property in the `wrap()` options to set a custom key for the cache.
 
+When an error occurs in the function it will not cache the value and will return the error. This is useful if you want to cache the results of a function but not cache the error. If you want it to cache the error you can set the `cacheError` property to `true` in the `wrap()` options. This is disabled by default.
+
+```javascript
+import { CacheableMemory } from 'cacheable';
+const syncFunction = (value: number) => {
+  throw new Error('error');
+};
+
+const cache = new CacheableMemory();
+const wrappedFunction = cache.wrap(syncFunction, { ttl: '1h', key: 'syncFunction', cacheError: true });
+console.log(wrappedFunction()); // error
+console.log(wrappedFunction()); // error from cache
+```
+
 # Keyv Storage Adapter - KeyvCacheableMemory
 
 `cacheable` comes with a built-in storage adapter for Keyv called `KeyvCacheableMemory`. This takes `CacheableMemory` and creates a storage adapter for Keyv. This is useful if you want to use `CacheableMemory` as a storage adapter for Keyv. Here is an example of how to use `KeyvCacheableMemory`:

package/dist/index.cjs

@@ -45,7 +45,7 @@ __export(src_exports, {
 });
 module.exports = __toCommonJS(src_exports);
 var import_keyv = require("keyv");
-var import_hookified = require("hookified");
+var import_hookified2 = require("hookified");
 
 // src/shorthand-time.ts
 var shorthandToMilliseconds = (shorthand) => {
@@ -114,6 +114,9 @@ var shorthandToTime = (shorthand, fromDate) => {
   return fromDate.getTime() + milliseconds;
 };
 
+// src/memory.ts
+var import_hookified = require("hookified");
+
 // src/hash.ts
 var crypto = __toESM(require("crypto"), 1);
 function hash(object, algorithm = "sha256") {
@@ -126,6 +129,61 @@ function hash(object, algorithm = "sha256") {
   return hasher.digest("hex");
 }
 
+// src/coalesce-async.ts
+var callbacks = /* @__PURE__ */ new Map();
+function hasKey(key) {
+  return callbacks.has(key);
+}
+function addKey(key) {
+  callbacks.set(key, []);
+}
+function removeKey(key) {
+  callbacks.delete(key);
+}
+function addCallbackToKey(key, callback) {
+  const stash = getCallbacksByKey(key);
+  stash.push(callback);
+  callbacks.set(key, stash);
+}
+function getCallbacksByKey(key) {
+  return callbacks.get(key) ?? [];
+}
+async function enqueue(key) {
+  return new Promise((resolve, reject) => {
+    const callback = { resolve, reject };
+    addCallbackToKey(key, callback);
+  });
+}
+function dequeue(key) {
+  const stash = getCallbacksByKey(key);
+  removeKey(key);
+  return stash;
+}
+function coalesce(options) {
+  const { key, error, result } = options;
+  for (const callback of dequeue(key)) {
+    if (error) {
+      callback.reject(error);
+    } else {
+      callback.resolve(result);
+    }
+  }
+}
+async function coalesceAsync(key, fnc) {
+  if (!hasKey(key)) {
+    addKey(key);
+    try {
+      const result = await Promise.resolve(fnc());
+      coalesce({ key, result });
+      return result;
+    } catch (error) {
+      coalesce({ key, error });
+      throw error;
+    }
+  }
+  return enqueue(key);
+}
+
 // src/wrap.ts
 function wrapSync(function_, options) {
   const { ttl, keyPrefix, cache } = options;
@@ -133,8 +191,15 @@ function wrapSync(function_, options) {
     const cacheKey = createWrapKey(function_, arguments_, keyPrefix);
     let value = cache.get(cacheKey);
     if (value === void 0) {
-      value = function_(...arguments_);
-      cache.set(cacheKey, value, ttl);
+      try {
+        value = function_(...arguments_);
+        cache.set(cacheKey, value, ttl);
+      } catch (error) {
+        cache.emit("error", error);
+        if (options.cacheErrors) {
+          cache.set(cacheKey, error, ttl);
+        }
+      }
     }
     return value;
   };
@@ -142,11 +207,22 @@ function wrapSync(function_, options) {
 function wrap(function_, options) {
   const { ttl, keyPrefix, cache } = options;
   return async function(...arguments_) {
+    let value;
     const cacheKey = createWrapKey(function_, arguments_, keyPrefix);
-    let value = await cache.get(cacheKey);
+    value = await cache.get(cacheKey);
     if (value === void 0) {
-      value = await function_(...arguments_);
-      await cache.set(cacheKey, value, ttl);
+      value = await coalesceAsync(cacheKey, async () => {
+        try {
+          const result = await function_(...arguments_);
+          await cache.set(cacheKey, result, ttl);
+          return result;
+        } catch (error) {
+          cache.emit("error", error);
+          if (options.cacheErrors) {
+            await cache.set(cacheKey, error, ttl);
+          }
+        }
+      });
     }
     return value;
   };
@@ -232,7 +308,7 @@ var DoublyLinkedList = class {
 };
 
 // src/memory.ts
-var CacheableMemory = class {
+var CacheableMemory = class extends import_hookified.Hookified {
   _lru = new DoublyLinkedList();
   _hashCache = /* @__PURE__ */ new Map();
   _hash0 = /* @__PURE__ */ new Map();
@@ -260,6 +336,7 @@ var CacheableMemory = class {
    * @param {CacheableMemoryOptions} [options] - The options for the CacheableMemory
    */
   constructor(options) {
+    super();
     if (options?.ttl) {
       this.setTtl(options.ttl);
     }
@@ -805,6 +882,7 @@ var KeyvCacheableMemory = class {
     return this.getStore(this._namespace).has(key);
   }
   on(event, listener) {
+    this.getStore(this._namespace).on(event, listener);
     return this;
   }
   getStore(namespace) {
@@ -1052,7 +1130,7 @@ var CacheableEvents = /* @__PURE__ */ ((CacheableEvents2) => {
   CacheableEvents2["ERROR"] = "error";
   return CacheableEvents2;
 })(CacheableEvents || {});
-var Cacheable = class extends import_hookified.Hookified {
+var Cacheable = class extends import_hookified2.Hookified {
   _primary = new import_keyv.Keyv({ store: new KeyvCacheableMemory() });
   _secondary;
   _nonBlocking = false;
@@ -1213,6 +1291,9 @@ var Cacheable = class extends import_hookified.Hookified {
    */
   setPrimary(primary) {
     this._primary = primary instanceof import_keyv.Keyv ? primary : new import_keyv.Keyv(primary);
+    this._primary.on("error", (error) => {
+      this.emit("error" /* ERROR */, error);
+    });
   }
   /**
    * Sets the secondary store for the cacheable instance. If it is set to undefined then the secondary store is disabled.
@@ -1221,6 +1302,9 @@ var Cacheable = class extends import_hookified.Hookified {
    */
   setSecondary(secondary) {
     this._secondary = secondary instanceof import_keyv.Keyv ? secondary : new import_keyv.Keyv(secondary);
+    this._secondary.on("error", (error) => {
+      this.emit("error" /* ERROR */, error);
+    });
   }
   getNameSpace() {
     if (typeof this._namespace === "function") {

package/dist/index.d.cts

@@ -112,6 +112,7 @@ type CacheableStoreItem = {
 type WrapFunctionOptions = {
     ttl?: number | string;
     keyPrefix?: string;
+    cacheErrors?: boolean;
 };
 type WrapOptions = WrapFunctionOptions & {
     cache: Cacheable;
@@ -138,7 +139,7 @@ type CacheableMemoryOptions = {
     lruSize?: number;
     checkInterval?: number;
 };
-declare class CacheableMemory {
+declare class CacheableMemory extends Hookified {
     private _lru;
     private readonly _hashCache;
     private readonly _hash0;
@@ -635,4 +636,4 @@ declare class Cacheable extends Hookified {
     private setTtl;
 }
 
-export { Cacheable, CacheableEvents, CacheableHooks, type CacheableItem, CacheableMemory, type CacheableOptions, CacheableStats, KeyvCacheableMemory, type WrapOptions, type WrapSyncOptions, shorthandToMilliseconds, shorthandToTime, wrap, wrapSync };
+export { Cacheable, CacheableEvents, CacheableHooks, type CacheableItem, CacheableMemory, type CacheableMemoryOptions, type CacheableOptions, CacheableStats, KeyvCacheableMemory, type WrapOptions, type WrapSyncOptions, shorthandToMilliseconds, shorthandToTime, wrap, wrapSync };

package/dist/index.d.ts

@@ -112,6 +112,7 @@ type CacheableStoreItem = {
 type WrapFunctionOptions = {
     ttl?: number | string;
     keyPrefix?: string;
+    cacheErrors?: boolean;
 };
 type WrapOptions = WrapFunctionOptions & {
     cache: Cacheable;
@@ -138,7 +139,7 @@ type CacheableMemoryOptions = {
     lruSize?: number;
     checkInterval?: number;
 };
-declare class CacheableMemory {
+declare class CacheableMemory extends Hookified {
     private _lru;
     private readonly _hashCache;
     private readonly _hash0;
@@ -635,4 +636,4 @@ declare class Cacheable extends Hookified {
     private setTtl;
 }
 
-export { Cacheable, CacheableEvents, CacheableHooks, type CacheableItem, CacheableMemory, type CacheableOptions, CacheableStats, KeyvCacheableMemory, type WrapOptions, type WrapSyncOptions, shorthandToMilliseconds, shorthandToTime, wrap, wrapSync };
+export { Cacheable, CacheableEvents, CacheableHooks, type CacheableItem, CacheableMemory, type CacheableMemoryOptions, type CacheableOptions, CacheableStats, KeyvCacheableMemory, type WrapOptions, type WrapSyncOptions, shorthandToMilliseconds, shorthandToTime, wrap, wrapSync };

package/dist/index.js

@@ -1,6 +1,6 @@
 // src/index.ts
 import { Keyv } from "keyv";
-import { Hookified } from "hookified";
+import { Hookified as Hookified2 } from "hookified";
 
 // src/shorthand-time.ts
 var shorthandToMilliseconds = (shorthand) => {
@@ -69,6 +69,9 @@ var shorthandToTime = (shorthand, fromDate) => {
   return fromDate.getTime() + milliseconds;
 };
 
+// src/memory.ts
+import { Hookified } from "hookified";
+
 // src/hash.ts
 import * as crypto from "node:crypto";
 function hash(object, algorithm = "sha256") {
@@ -81,6 +84,61 @@ function hash(object, algorithm = "sha256") {
   return hasher.digest("hex");
 }
 
+// src/coalesce-async.ts
+var callbacks = /* @__PURE__ */ new Map();
+function hasKey(key) {
+  return callbacks.has(key);
+}
+function addKey(key) {
+  callbacks.set(key, []);
+}
+function removeKey(key) {
+  callbacks.delete(key);
+}
+function addCallbackToKey(key, callback) {
+  const stash = getCallbacksByKey(key);
+  stash.push(callback);
+  callbacks.set(key, stash);
+}
+function getCallbacksByKey(key) {
+  return callbacks.get(key) ?? [];
+}
+async function enqueue(key) {
+  return new Promise((resolve, reject) => {
+    const callback = { resolve, reject };
+    addCallbackToKey(key, callback);
+  });
+}
+function dequeue(key) {
+  const stash = getCallbacksByKey(key);
+  removeKey(key);
+  return stash;
+}
+function coalesce(options) {
+  const { key, error, result } = options;
+  for (const callback of dequeue(key)) {
+    if (error) {
+      callback.reject(error);
+    } else {
+      callback.resolve(result);
+    }
+  }
+}
+async function coalesceAsync(key, fnc) {
+  if (!hasKey(key)) {
+    addKey(key);
+    try {
+      const result = await Promise.resolve(fnc());
+      coalesce({ key, result });
+      return result;
+    } catch (error) {
+      coalesce({ key, error });
+      throw error;
+    }
+  }
+  return enqueue(key);
+}
+
 // src/wrap.ts
 function wrapSync(function_, options) {
   const { ttl, keyPrefix, cache } = options;
@@ -88,8 +146,15 @@ function wrapSync(function_, options) {
     const cacheKey = createWrapKey(function_, arguments_, keyPrefix);
     let value = cache.get(cacheKey);
     if (value === void 0) {
-      value = function_(...arguments_);
-      cache.set(cacheKey, value, ttl);
+      try {
+        value = function_(...arguments_);
+        cache.set(cacheKey, value, ttl);
+      } catch (error) {
+        cache.emit("error", error);
+        if (options.cacheErrors) {
+          cache.set(cacheKey, error, ttl);
+        }
+      }
     }
     return value;
   };
@@ -97,11 +162,22 @@ function wrapSync(function_, options) {
 function wrap(function_, options) {
   const { ttl, keyPrefix, cache } = options;
   return async function(...arguments_) {
+    let value;
     const cacheKey = createWrapKey(function_, arguments_, keyPrefix);
-    let value = await cache.get(cacheKey);
+    value = await cache.get(cacheKey);
     if (value === void 0) {
-      value = await function_(...arguments_);
-      await cache.set(cacheKey, value, ttl);
+      value = await coalesceAsync(cacheKey, async () => {
+        try {
+          const result = await function_(...arguments_);
+          await cache.set(cacheKey, result, ttl);
+          return result;
+        } catch (error) {
+          cache.emit("error", error);
+          if (options.cacheErrors) {
+            await cache.set(cacheKey, error, ttl);
+          }
+        }
+      });
     }
     return value;
   };
@@ -187,7 +263,7 @@ var DoublyLinkedList = class {
 };
 
 // src/memory.ts
-var CacheableMemory = class {
+var CacheableMemory = class extends Hookified {
   _lru = new DoublyLinkedList();
   _hashCache = /* @__PURE__ */ new Map();
   _hash0 = /* @__PURE__ */ new Map();
@@ -215,6 +291,7 @@ var CacheableMemory = class {
    * @param {CacheableMemoryOptions} [options] - The options for the CacheableMemory
    */
   constructor(options) {
+    super();
     if (options?.ttl) {
       this.setTtl(options.ttl);
     }
@@ -760,6 +837,7 @@ var KeyvCacheableMemory = class {
     return this.getStore(this._namespace).has(key);
   }
   on(event, listener) {
+    this.getStore(this._namespace).on(event, listener);
     return this;
   }
   getStore(namespace) {
@@ -1010,7 +1088,7 @@ var CacheableEvents = /* @__PURE__ */ ((CacheableEvents2) => {
   CacheableEvents2["ERROR"] = "error";
   return CacheableEvents2;
 })(CacheableEvents || {});
-var Cacheable = class extends Hookified {
+var Cacheable = class extends Hookified2 {
   _primary = new Keyv({ store: new KeyvCacheableMemory() });
   _secondary;
   _nonBlocking = false;
@@ -1171,6 +1249,9 @@ var Cacheable = class extends Hookified {
    */
   setPrimary(primary) {
     this._primary = primary instanceof Keyv ? primary : new Keyv(primary);
+    this._primary.on("error", (error) => {
+      this.emit("error" /* ERROR */, error);
+    });
   }
   /**
    * Sets the secondary store for the cacheable instance. If it is set to undefined then the secondary store is disabled.
@@ -1179,6 +1260,9 @@ var Cacheable = class extends Hookified {
    */
   setSecondary(secondary) {
     this._secondary = secondary instanceof Keyv ? secondary : new Keyv(secondary);
+    this._secondary.on("error", (error) => {
+      this.emit("error" /* ERROR */, error);
+    });
   }
   getNameSpace() {
     if (typeof this._namespace === "function") {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cacheable",
-  "version": "1.8.3",
+  "version": "1.8.5",
   "description": "Simple Caching Engine using Keyv",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -22,9 +22,9 @@
   "private": false,
   "devDependencies": {
     "@keyv/redis": "^3.0.1",
-    "@types/node": "^22.8.4",
+    "@types/node": "^22.9.0",
     "@vitest/coverage-v8": "^2.1.4",
-    "lru-cache": "^11.0.1",
+    "lru-cache": "^11.0.2",
     "rimraf": "^6.0.1",
     "tsup": "^8.3.5",
     "typescript": "^5.6.3",
@@ -33,7 +33,7 @@
   },
   "dependencies": {
     "hookified": "^1.5.0",
-    "keyv": "^5.1.2"
+    "keyv": "^5.2.1"
   },
   "keywords": [
     "cacheable",