cacheable 1.8.3 → 1.8.4

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:
 

package/dist/index.cjs

@@ -126,6 +126,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;
@@ -142,11 +197,18 @@ function wrapSync(function_, options) {
 function wrap(function_, options) {
   const { ttl, keyPrefix, cache } = options;
   return async function(...arguments_) {
-    const cacheKey = createWrapKey(function_, arguments_, keyPrefix);
-    let value = await cache.get(cacheKey);
-    if (value === void 0) {
-      value = await function_(...arguments_);
-      await cache.set(cacheKey, value, ttl);
+    let value;
+    try {
+      const cacheKey = createWrapKey(function_, arguments_, keyPrefix);
+      value = await cache.get(cacheKey);
+      if (value === void 0) {
+        value = await coalesceAsync(cacheKey, async () => {
+          const result = await function_(...arguments_);
+          await cache.set(cacheKey, result, ttl);
+          return result;
+        });
+      }
+    } catch {
     }
     return value;
   };

package/dist/index.d.cts

@@ -635,4 +635,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

@@ -635,4 +635,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

@@ -81,6 +81,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;
@@ -97,11 +152,18 @@ function wrapSync(function_, options) {
 function wrap(function_, options) {
   const { ttl, keyPrefix, cache } = options;
   return async function(...arguments_) {
-    const cacheKey = createWrapKey(function_, arguments_, keyPrefix);
-    let value = await cache.get(cacheKey);
-    if (value === void 0) {
-      value = await function_(...arguments_);
-      await cache.set(cacheKey, value, ttl);
+    let value;
+    try {
+      const cacheKey = createWrapKey(function_, arguments_, keyPrefix);
+      value = await cache.get(cacheKey);
+      if (value === void 0) {
+        value = await coalesceAsync(cacheKey, async () => {
+          const result = await function_(...arguments_);
+          await cache.set(cacheKey, result, ttl);
+          return result;
+        });
+      }
+    } catch {
     }
     return value;
   };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cacheable",
-  "version": "1.8.3",
+  "version": "1.8.4",
   "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",