cacheable 1.8.2 → 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;
   };
@@ -713,8 +775,8 @@ var CacheableMemory = class {
    */
   wrap(function_, options) {
     const wrapOptions = {
-      ttl: options.ttl,
-      keyPrefix: options.keyPrefix,
+      ttl: options?.ttl ?? this._ttl,
+      keyPrefix: options?.keyPrefix,
       cache: this
     };
     return wrapSync(function_, wrapOptions);
@@ -1522,8 +1584,8 @@ var Cacheable = class extends import_hookified.Hookified {
    */
   wrap(function_, options) {
     const wrapOptions = {
-      ttl: options.ttl,
-      keyPrefix: options.keyPrefix,
+      ttl: options?.ttl ?? this._ttl,
+      keyPrefix: options?.keyPrefix,
       cache: this
     };
     return wrap(function_, wrapOptions);

package/dist/index.d.cts

@@ -109,20 +109,16 @@ type CacheableStoreItem = {
     expires?: number;
 };
 
-type WrapOptions = {
+type WrapFunctionOptions = {
     ttl?: number | string;
     keyPrefix?: string;
+};
+type WrapOptions = WrapFunctionOptions & {
     cache: Cacheable;
 };
-type WrapSyncOptions = {
-    ttl?: number | string;
-    keyPrefix?: string;
+type WrapSyncOptions = WrapFunctionOptions & {
     cache: CacheableMemory;
 };
-type WrapFunctionOptions = {
-    ttl?: number | string;
-    keyPrefix: string;
-};
 type AnyFunction = (...arguments_: any[]) => any;
 declare function wrapSync<T>(function_: AnyFunction, options: WrapSyncOptions): AnyFunction;
 declare function wrap<T>(function_: AnyFunction, options: WrapOptions): AnyFunction;
@@ -369,7 +365,7 @@ declare class CacheableMemory {
      * @param {Object} [options] - The options to wrap
      * @returns {Function} - The wrapped function
      */
-    wrap<T>(function_: (...arguments_: any[]) => T, options: WrapFunctionOptions): (...arguments_: any[]) => T;
+    wrap<T>(function_: (...arguments_: any[]) => T, options?: WrapFunctionOptions): (...arguments_: any[]) => T;
     private isPrimitive;
     private concatStores;
     private setTtl;
@@ -625,7 +621,7 @@ declare class Cacheable extends Hookified {
      * @param {WrapOptions} [options] The options for the wrap function
      * @returns {Function} The wrapped function
      */
-    wrap<T>(function_: (...arguments_: any[]) => T, options: WrapFunctionOptions): (...arguments_: any[]) => T;
+    wrap<T>(function_: (...arguments_: any[]) => T, options?: WrapFunctionOptions): (...arguments_: any[]) => T;
     /**
      * Will hash an object using the specified algorithm. The default algorithm is 'sha256'.
      * @param {any} object the object to hash
@@ -639,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

@@ -109,20 +109,16 @@ type CacheableStoreItem = {
     expires?: number;
 };
 
-type WrapOptions = {
+type WrapFunctionOptions = {
     ttl?: number | string;
     keyPrefix?: string;
+};
+type WrapOptions = WrapFunctionOptions & {
     cache: Cacheable;
 };
-type WrapSyncOptions = {
-    ttl?: number | string;
-    keyPrefix?: string;
+type WrapSyncOptions = WrapFunctionOptions & {
     cache: CacheableMemory;
 };
-type WrapFunctionOptions = {
-    ttl?: number | string;
-    keyPrefix: string;
-};
 type AnyFunction = (...arguments_: any[]) => any;
 declare function wrapSync<T>(function_: AnyFunction, options: WrapSyncOptions): AnyFunction;
 declare function wrap<T>(function_: AnyFunction, options: WrapOptions): AnyFunction;
@@ -369,7 +365,7 @@ declare class CacheableMemory {
      * @param {Object} [options] - The options to wrap
      * @returns {Function} - The wrapped function
      */
-    wrap<T>(function_: (...arguments_: any[]) => T, options: WrapFunctionOptions): (...arguments_: any[]) => T;
+    wrap<T>(function_: (...arguments_: any[]) => T, options?: WrapFunctionOptions): (...arguments_: any[]) => T;
     private isPrimitive;
     private concatStores;
     private setTtl;
@@ -625,7 +621,7 @@ declare class Cacheable extends Hookified {
      * @param {WrapOptions} [options] The options for the wrap function
      * @returns {Function} The wrapped function
      */
-    wrap<T>(function_: (...arguments_: any[]) => T, options: WrapFunctionOptions): (...arguments_: any[]) => T;
+    wrap<T>(function_: (...arguments_: any[]) => T, options?: WrapFunctionOptions): (...arguments_: any[]) => T;
     /**
      * Will hash an object using the specified algorithm. The default algorithm is 'sha256'.
      * @param {any} object the object to hash
@@ -639,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;
   };
@@ -668,8 +730,8 @@ var CacheableMemory = class {
    */
   wrap(function_, options) {
     const wrapOptions = {
-      ttl: options.ttl,
-      keyPrefix: options.keyPrefix,
+      ttl: options?.ttl ?? this._ttl,
+      keyPrefix: options?.keyPrefix,
       cache: this
     };
     return wrapSync(function_, wrapOptions);
@@ -1480,8 +1542,8 @@ var Cacheable = class extends Hookified {
    */
   wrap(function_, options) {
     const wrapOptions = {
-      ttl: options.ttl,
-      keyPrefix: options.keyPrefix,
+      ttl: options?.ttl ?? this._ttl,
+      keyPrefix: options?.keyPrefix,
       cache: this
     };
     return wrap(function_, wrapOptions);

package/package.json

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