cacheable 1.8.10 → 1.10.0

package/dist/index.js

@@ -78,7 +78,7 @@ import {
 import { Hookified } from "hookified";
 
 // src/hash.ts
-import * as crypto from "node:crypto";
+import * as crypto from "crypto";
 function hash(object, algorithm = "sha256") {
   const objectString = JSON.stringify(object);
   if (!crypto.getHashes().includes(algorithm)) {
@@ -88,6 +88,26 @@ function hash(object, algorithm = "sha256") {
   hasher.update(objectString);
   return hasher.digest("hex");
 }
+function hashToNumber(object, min = 0, max = 10, algorithm = "sha256") {
+  const objectString = JSON.stringify(object);
+  if (!crypto.getHashes().includes(algorithm)) {
+    throw new Error(`Unsupported hash algorithm: '${algorithm}'`);
+  }
+  const hasher = crypto.createHash(algorithm);
+  hasher.update(objectString);
+  const hashHex = hasher.digest("hex");
+  const hashNumber = Number.parseInt(hashHex, 16);
+  const range = max - min + 1;
+  return min + hashNumber % range;
+}
+function djb2Hash(string_, min = 0, max = 10) {
+  let hash2 = 5381;
+  for (let i = 0; i < string_.length; i++) {
+    hash2 = hash2 * 33 ^ string_.charCodeAt(i);
+  }
+  const range = max - min + 1;
+  return min + Math.abs(hash2) % range;
+}
 
 // src/coalesce-async.ts
 var callbacks = /* @__PURE__ */ new Map();
@@ -164,29 +184,31 @@ function wrapSync(function_, options) {
     return value;
   };
 }
+async function getOrSet(key, function_, options) {
+  let value = await options.cache.get(key);
+  if (value === void 0) {
+    const cacheId = options.cacheId ?? "default";
+    const coalesceKey = `${cacheId}::${key}`;
+    value = await coalesceAsync(coalesceKey, async () => {
+      try {
+        const result = await function_();
+        await options.cache.set(key, result, options.ttl);
+        return result;
+      } catch (error) {
+        options.cache.emit("error", error);
+        if (options.cacheErrors) {
+          await options.cache.set(key, error, options.ttl);
+        }
+      }
+    });
+  }
+  return value;
+}
 function wrap(function_, options) {
-  const { ttl, keyPrefix, cache } = options;
+  const { keyPrefix, cache } = options;
   return async function(...arguments_) {
-    let value;
     const cacheKey = createWrapKey(function_, arguments_, keyPrefix);
-    value = await cache.get(cacheKey);
-    if (value === void 0) {
-      const cacheId = options.cacheId ?? "default";
-      const coalesceKey = `${cacheId}::${cacheKey}`;
-      value = await coalesceAsync(coalesceKey, 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;
+    return cache.getOrSet(cacheKey, async () => function_(...arguments_), options);
   };
 }
 function createWrapKey(function_, arguments_, keyPrefix) {
@@ -270,19 +292,14 @@ var DoublyLinkedList = class {
 };
 
 // src/memory.ts
+var defaultStoreHashSize = 16;
+var maximumMapSize = 16777216;
 var CacheableMemory = class extends Hookified {
   _lru = new DoublyLinkedList();
-  _hashCache = /* @__PURE__ */ new Map();
-  _hash0 = /* @__PURE__ */ new Map();
-  _hash1 = /* @__PURE__ */ new Map();
-  _hash2 = /* @__PURE__ */ new Map();
-  _hash3 = /* @__PURE__ */ new Map();
-  _hash4 = /* @__PURE__ */ new Map();
-  _hash5 = /* @__PURE__ */ new Map();
-  _hash6 = /* @__PURE__ */ new Map();
-  _hash7 = /* @__PURE__ */ new Map();
-  _hash8 = /* @__PURE__ */ new Map();
-  _hash9 = /* @__PURE__ */ new Map();
+  _storeHashSize = defaultStoreHashSize;
+  _storeHashAlgorithm = "djb2Hash" /* djb2Hash */;
+  // Default is djb2Hash
+  _store = Array.from({ length: this._storeHashSize }, () => /* @__PURE__ */ new Map());
   _ttl;
   // Turned off by default
   _useClone = true;
@@ -305,12 +322,23 @@ var CacheableMemory = class extends Hookified {
     if (options?.useClone !== void 0) {
       this._useClone = options.useClone;
     }
+    if (options?.storeHashSize && options.storeHashSize > 0) {
+      this._storeHashSize = options.storeHashSize;
+    }
     if (options?.lruSize) {
-      this._lruSize = options.lruSize;
+      if (options.lruSize > maximumMapSize) {
+        this.emit("error", new Error(`LRU size cannot be larger than ${maximumMapSize} due to Map limitations.`));
+      } else {
+        this._lruSize = options.lruSize;
+      }
     }
     if (options?.checkInterval) {
       this._checkInterval = options.checkInterval;
     }
+    if (options?.storeHashAlgorithm) {
+      this._storeHashAlgorithm = options.storeHashAlgorithm;
+    }
+    this._store = Array.from({ length: this._storeHashSize }, () => /* @__PURE__ */ new Map());
     this.startIntervalCheck();
   }
   /**
@@ -343,17 +371,25 @@ var CacheableMemory = class extends Hookified {
   }
   /**
    * Gets the size of the LRU cache
-   * @returns {number} - The size of the LRU cache. If set to 0, it will not use LRU cache. Default is 0.
+   * @returns {number} - The size of the LRU cache. If set to 0, it will not use LRU cache. Default is 0. If you are using LRU then the limit is based on Map() size 17mm.
    */
   get lruSize() {
     return this._lruSize;
   }
   /**
    * Sets the size of the LRU cache
-   * @param {number} value - The size of the LRU cache. If set to 0, it will not use LRU cache. Default is 0.
+   * @param {number} value - The size of the LRU cache. If set to 0, it will not use LRU cache. Default is 0. If you are using LRU then the limit is based on Map() size 17mm.
    */
   set lruSize(value) {
+    if (value > maximumMapSize) {
+      this.emit("error", new Error(`LRU size cannot be larger than ${maximumMapSize} due to Map limitations.`));
+      return;
+    }
     this._lruSize = value;
+    if (this._lruSize === 0) {
+      this._lru = new DoublyLinkedList();
+      return;
+    }
     this.lruResize();
   }
   /**
@@ -375,21 +411,85 @@ var CacheableMemory = class extends Hookified {
    * @returns {number} - The size of the cache
    */
   get size() {
-    return this._hash0.size + this._hash1.size + this._hash2.size + this._hash3.size + this._hash4.size + this._hash5.size + this._hash6.size + this._hash7.size + this._hash8.size + this._hash9.size;
+    let size = 0;
+    for (const store of this._store) {
+      size += store.size;
+    }
+    return size;
+  }
+  /**
+   * Gets the number of hash stores
+   * @returns {number} - The number of hash stores
+   */
+  get storeHashSize() {
+    return this._storeHashSize;
+  }
+  /**
+   * Sets the number of hash stores. This will recreate the store and all data will be cleared
+   * @param {number} value - The number of hash stores
+   */
+  set storeHashSize(value) {
+    if (value === this._storeHashSize) {
+      return;
+    }
+    this._storeHashSize = value;
+    this._store = Array.from({ length: this._storeHashSize }, () => /* @__PURE__ */ new Map());
+  }
+  /**
+   * Gets the store hash algorithm
+   * @returns {StoreHashAlgorithm | StoreHashAlgorithmFunction} - The store hash algorithm
+   */
+  get storeHashAlgorithm() {
+    return this._storeHashAlgorithm;
+  }
+  /**
+   * Sets the store hash algorithm. This will recreate the store and all data will be cleared
+   * @param {StoreHashAlgorithm | StoreHashAlgorithmFunction} value - The store hash algorithm
+   */
+  set storeHashAlgorithm(value) {
+    this._storeHashAlgorithm = value;
   }
   /**
    * Gets the keys
    * @returns {IterableIterator<string>} - The keys
    */
   get keys() {
-    return this.concatStores().keys();
+    const keys = new Array();
+    for (const store of this._store) {
+      for (const key of store.keys()) {
+        const item = store.get(key);
+        if (item && this.hasExpired(item)) {
+          store.delete(key);
+          continue;
+        }
+        keys.push(key);
+      }
+    }
+    return keys.values();
   }
   /**
    * Gets the items
    * @returns {IterableIterator<CacheableStoreItem>} - The items
    */
   get items() {
-    return this.concatStores().values();
+    const items = new Array();
+    for (const store of this._store) {
+      for (const item of store.values()) {
+        if (this.hasExpired(item)) {
+          store.delete(item.key);
+          continue;
+        }
+        items.push(item);
+      }
+    }
+    return items.values();
+  }
+  /**
+   * Gets the store
+   * @returns {Array<Map<string, CacheableStoreItem>>} - The store
+   */
+  get store() {
+    return this._store;
   }
   /**
    * Gets the value of the key
@@ -402,7 +502,7 @@ var CacheableMemory = class extends Hookified {
     if (!item) {
       return void 0;
     }
-    if (item.expires && item.expires && Date.now() > item.expires) {
+    if (item.expires && Date.now() > item.expires) {
       store.delete(key);
       return void 0;
     }
@@ -585,17 +685,7 @@ var CacheableMemory = class extends Hookified {
    * @returns {void}
    */
   clear() {
-    this._hash0.clear();
-    this._hash1.clear();
-    this._hash2.clear();
-    this._hash3.clear();
-    this._hash4.clear();
-    this._hash5.clear();
-    this._hash6.clear();
-    this._hash7.clear();
-    this._hash8.clear();
-    this._hash9.clear();
-    this._hashCache.clear();
+    this._store = Array.from({ length: this._storeHashSize }, () => /* @__PURE__ */ new Map());
     this._lru = new DoublyLinkedList();
   }
   /**
@@ -604,66 +694,27 @@ var CacheableMemory = class extends Hookified {
    * @returns {CacheableHashStore} - The store
    */
   getStore(key) {
-    const hash2 = this.hashKey(key);
-    return this.getStoreFromHash(hash2);
+    const hash2 = this.getKeyStoreHash(key);
+    this._store[hash2] ||= /* @__PURE__ */ new Map();
+    return this._store[hash2];
   }
   /**
-   * Get the store based on the hash (internal use)
-   * @param {number} hash
-   * @returns {Map<string, CacheableStoreItem>}
+   * Hash the key for which store to go to (internal use)
+   * @param {string} key - The key to hash
+   * Available algorithms are: SHA256, SHA1, MD5, and djb2Hash.
+   * @returns {number} - The hashed key as a number
    */
-  getStoreFromHash(hash2) {
-    switch (hash2) {
-      case 1: {
-        return this._hash1;
-      }
-      case 2: {
-        return this._hash2;
-      }
-      case 3: {
-        return this._hash3;
-      }
-      case 4: {
-        return this._hash4;
-      }
-      case 5: {
-        return this._hash5;
-      }
-      case 6: {
-        return this._hash6;
-      }
-      case 7: {
-        return this._hash7;
-      }
-      case 8: {
-        return this._hash8;
-      }
-      case 9: {
-        return this._hash9;
-      }
-      default: {
-        return this._hash0;
-      }
+  getKeyStoreHash(key) {
+    if (this._store.length === 1) {
+      return 0;
     }
-  }
-  /**
-   * Hash the key (internal use)
-   * @param key
-   * @returns {number} from 0 to 9
-   */
-  hashKey(key) {
-    const cacheHashNumber = this._hashCache.get(key);
-    if (cacheHashNumber) {
-      return cacheHashNumber;
+    if (this._storeHashAlgorithm === "djb2Hash" /* djb2Hash */) {
+      return djb2Hash(key, 0, this._storeHashSize);
     }
-    let hash2 = 0;
-    const primeMultiplier = 31;
-    for (let i = 0; i < key.length; i++) {
-      hash2 = hash2 * primeMultiplier + key.charCodeAt(i);
+    if (typeof this._storeHashAlgorithm === "function") {
+      return this._storeHashAlgorithm(key, this._storeHashSize);
     }
-    const result = Math.abs(hash2) % 10;
-    this._hashCache.set(key, result);
-    return result;
+    return hashToNumber(key, 0, this._storeHashSize, this._storeHashAlgorithm);
   }
   /**
    * Clone the value. This is for internal use
@@ -699,13 +750,10 @@ var CacheableMemory = class extends Hookified {
     this._lru.moveToFront(key);
   }
   /**
-   * Resize the LRU cache. This is for internal use
+   * Resize the LRU cache. This is for internal use.
    * @returns {void}
    */
   lruResize() {
-    if (this._lruSize === 0) {
-      return;
-    }
     while (this._lru.size > this._lruSize) {
       const oldestKey = this._lru.getOldest();
       if (oldestKey) {
@@ -719,10 +767,11 @@ var CacheableMemory = class extends Hookified {
    * @returns {void}
    */
   checkExpiration() {
-    const stores = this.concatStores();
-    for (const item of stores.values()) {
-      if (item.expires && Date.now() > item.expires) {
-        this.delete(item.key);
+    for (const store of this._store) {
+      for (const item of store.values()) {
+        if (item.expires && Date.now() > item.expires) {
+          store.delete(item.key);
+        }
       }
     }
   }
@@ -751,15 +800,6 @@ var CacheableMemory = class extends Hookified {
     this._interval = 0;
     this._checkInterval = 0;
   }
-  /**
-   * Hash the object. This is for internal use
-   * @param {any} object - The object to hash
-   * @param {string} [algorithm='sha256'] - The algorithm to hash
-   * @returns {string} - The hashed string
-   */
-  hash(object, algorithm = "sha256") {
-    return hash(object, algorithm);
-  }
   /**
    * Wrap the function for caching
    * @param {Function} function_ - The function to wrap
@@ -784,9 +824,6 @@ var CacheableMemory = class extends Hookified {
     }
     return result;
   }
-  concatStores() {
-    return new Map([...this._hash0, ...this._hash1, ...this._hash2, ...this._hash3, ...this._hash4, ...this._hash5, ...this._hash6, ...this._hash7, ...this._hash8, ...this._hash9]);
-  }
   setTtl(ttl) {
     if (typeof ttl === "string" || ttl === void 0) {
       this._ttl = ttl;
@@ -796,6 +833,12 @@ var CacheableMemory = class extends Hookified {
       this._ttl = void 0;
     }
   }
+  hasExpired(item) {
+    if (item.expires && Date.now() > item.expires) {
+      return true;
+    }
+    return false;
+  }
 };
 
 // src/keyv-memory.ts
@@ -1103,6 +1146,35 @@ var CacheableStats = class {
   }
 };
 
+// src/ttl.ts
+function getTtlFromExpires(expires) {
+  if (expires === void 0 || expires === null) {
+    return void 0;
+  }
+  const now = Date.now();
+  if (expires < now) {
+    return void 0;
+  }
+  return expires - now;
+}
+function getCascadingTtl(cacheableTtl, primaryTtl, secondaryTtl) {
+  return secondaryTtl ?? primaryTtl ?? shorthandToMilliseconds(cacheableTtl);
+}
+function calculateTtlFromExpiration(ttl, expires) {
+  const ttlFromExpires = getTtlFromExpires(expires);
+  const expiresFromTtl = ttl ? Date.now() + ttl : void 0;
+  if (ttlFromExpires === void 0) {
+    return ttl;
+  }
+  if (expiresFromTtl === void 0) {
+    return ttlFromExpires;
+  }
+  if (expires > expiresFromTtl) {
+    return ttl;
+  }
+  return ttlFromExpires;
+}
+
 // src/index.ts
 import {
   KeyvHooks,
@@ -1117,6 +1189,7 @@ var CacheableHooks = /* @__PURE__ */ ((CacheableHooks2) => {
   CacheableHooks2["AFTER_GET"] = "AFTER_GET";
   CacheableHooks2["BEFORE_GET_MANY"] = "BEFORE_GET_MANY";
   CacheableHooks2["AFTER_GET_MANY"] = "AFTER_GET_MANY";
+  CacheableHooks2["BEFORE_SECONDARY_SETS_PRIMARY"] = "BEFORE_SECONDARY_SETS_PRIMARY";
   return CacheableHooks2;
 })(CacheableHooks || {});
 var CacheableEvents = /* @__PURE__ */ ((CacheableEvents2) => {
@@ -1325,37 +1398,26 @@ var Cacheable = class extends Hookified2 {
     }
     return this._namespace;
   }
-  /**
-   * Gets the value of the key. If the key does not exist in the primary store then it will check the secondary store.
-   * @param {string} key The key to get the value of
-   * @returns {Promise<T | undefined>} The value of the key or undefined if the key does not exist
-   */
-  async get(key) {
+  async get(key, options = {}) {
     let result;
+    const { raw = false } = options;
     try {
       await this.hook("BEFORE_GET" /* BEFORE_GET */, key);
-      result = await this._primary.get(key);
+      result = await this._primary.get(key, { raw: true });
+      let ttl;
       if (!result && this._secondary) {
-        const rawResult = await this._secondary.get(key, { raw: true });
-        if (rawResult) {
-          result = rawResult.value;
-          let finalTtl;
-          let expired = false;
-          if (rawResult.expires) {
-            const now = Date.now();
-            finalTtl = rawResult.expires - now;
-            if (finalTtl <= 0) {
-              expired = true;
-            }
-          }
-          if (expired) {
-            result = void 0;
-          } else {
-            await this._primary.set(key, result, finalTtl);
-          }
+        const secondaryResult = await this.getSecondaryRawResults(key);
+        if (secondaryResult?.value) {
+          result = secondaryResult;
+          const cascadeTtl = getCascadingTtl(this._ttl, this._primary.ttl);
+          const expires = secondaryResult.expires ?? void 0;
+          ttl = calculateTtlFromExpiration(cascadeTtl, expires);
+          const setItem = { key, value: result.value, ttl };
+          await this.hook("BEFORE_SECONDARY_SETS_PRIMARY" /* BEFORE_SECONDARY_SETS_PRIMARY */, setItem);
+          await this._primary.set(setItem.key, setItem.value, setItem.ttl);
         }
       }
-      await this.hook("AFTER_GET" /* AFTER_GET */, { key, result });
+      await this.hook("AFTER_GET" /* AFTER_GET */, { key, result, ttl });
     } catch (error) {
       this.emit("error" /* ERROR */, error);
     }
@@ -1367,18 +1429,14 @@ var Cacheable = class extends Hookified2 {
       }
       this.stats.incrementGets();
     }
-    return result;
+    return raw ? result : result?.value;
   }
-  /**
-   * Gets the values of the keys. If the key does not exist in the primary store then it will check the secondary store.
-   * @param {string[]} keys The keys to get the values of
-   * @returns {Promise<Array<T | undefined>>} The values of the keys or undefined if the key does not exist
-   */
-  async getMany(keys) {
+  async getMany(keys, options = {}) {
     let result = [];
+    const { raw = false } = options;
     try {
       await this.hook("BEFORE_GET_MANY" /* BEFORE_GET_MANY */, keys);
-      result = await this._primary.get(keys);
+      result = await this._primary.get(keys, { raw: true });
       if (this._secondary) {
         const missingKeys = [];
         for (const [i, key] of keys.entries()) {
@@ -1386,12 +1444,16 @@ var Cacheable = class extends Hookified2 {
             missingKeys.push(key);
           }
         }
-        const secondaryResult = await this._secondary.get(missingKeys);
-        for (const [i, key] of keys.entries()) {
-          if (!result[i] && secondaryResult[i]) {
-            result[i] = secondaryResult[i];
-            const finalTtl = shorthandToMilliseconds(this._ttl);
-            await this._primary.set(key, secondaryResult[i], finalTtl);
+        const secondaryResults = await this.getManySecondaryRawResults(missingKeys);
+        for await (const [i, key] of keys.entries()) {
+          if (!result[i] && secondaryResults[i]) {
+            result[i] = secondaryResults[i];
+            const cascadeTtl = getCascadingTtl(this._ttl, this._primary.ttl);
+            const expires = secondaryResults[i].expires;
+            const ttl = calculateTtlFromExpiration(cascadeTtl, expires);
+            const setItem = { key, value: result[i].value, ttl };
+            await this.hook("BEFORE_SECONDARY_SETS_PRIMARY" /* BEFORE_SECONDARY_SETS_PRIMARY */, setItem);
+            await this._primary.set(setItem.key, setItem.value, setItem.ttl);
           }
         }
       }
@@ -1409,7 +1471,7 @@ var Cacheable = class extends Hookified2 {
       }
       this.stats.incrementGets();
     }
-    return result;
+    return raw ? result : result.map((item) => item?.value);
   }
   /**
    * Sets the value of the key. If the secondary store is set then it will also set the value in the secondary store.
@@ -1639,6 +1701,24 @@ var Cacheable = class extends Hookified2 {
     };
     return wrap(function_, wrapOptions);
   }
+  /**
+   * Retrieves the value associated with the given key from the cache. If the key is not found,
+   * invokes the provided function to calculate the value, stores it in the cache, and then returns it.
+   *
+   * @param {string} key - The key to retrieve or set in the cache.
+   * @param {() => Promise<T>} function_ - The asynchronous function that computes the value to be cached if the key does not exist.
+   * @param {WrapFunctionOptions} [options] - Optional settings for caching, such as the time to live (TTL) or whether to cache errors.
+   * @return {Promise<T | undefined>} - A promise that resolves to the cached or newly computed value, or undefined if an error occurs and caching is not configured for errors.
+   */
+  async getOrSet(key, function_, options) {
+    const getOrSetOptions = {
+      cache: this,
+      cacheId: this._cacheId,
+      ttl: options?.ttl ?? this._ttl,
+      cacheErrors: options?.cacheErrors
+    };
+    return getOrSet(key, function_, getOrSetOptions);
+  }
   /**
    * Will hash an object using the specified algorithm. The default algorithm is 'sha256'.
    * @param {any} object the object to hash
@@ -1648,6 +1728,20 @@ var Cacheable = class extends Hookified2 {
   hash(object, algorithm = "sha256") {
     return hash(object, algorithm);
   }
+  async getSecondaryRawResults(key) {
+    let result;
+    if (this._secondary) {
+      result = await this._secondary.get(key, { raw: true });
+    }
+    return result;
+  }
+  async getManySecondaryRawResults(keys) {
+    let result = new Array();
+    if (this._secondary) {
+      result = await this._secondary.get(keys, { raw: true });
+    }
+    return result;
+  }
   async deleteManyKeyv(keyv, keys) {
     const promises = [];
     for (const key of keys) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cacheable",
-  "version": "1.8.10",
+  "version": "1.10.0",
   "description": "High Performance Layer 1 / Layer 2 Caching with Keyv Storage",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -21,20 +21,20 @@
   "license": "MIT",
   "private": false,
   "devDependencies": {
-    "@faker-js/faker": "^9.6.0",
-    "@keyv/redis": "^4.3.2",
-    "@types/node": "^22.14.0",
-    "@vitest/coverage-v8": "^3.1.1",
+    "@faker-js/faker": "^9.7.0",
+    "@keyv/redis": "^4.4.0",
+    "@types/node": "^22.15.3",
+    "@vitest/coverage-v8": "^3.1.3",
     "lru-cache": "^11.1.0",
     "rimraf": "^6.0.1",
     "tsup": "^8.4.0",
-    "typescript": "^5.8.2",
-    "vitest": "^3.1.1",
+    "typescript": "^5.8.3",
+    "vitest": "^3.1.3",
     "xo": "^0.60.0"
   },
   "dependencies": {
-    "hookified": "^1.8.1",
-    "keyv": "^5.3.2"
+    "hookified": "^1.8.2",
+    "keyv": "^5.3.3"
   },
   "keywords": [
     "cacheable",