cacheable 1.10.2 → 1.10.4

package/README.md

@@ -51,7 +51,7 @@
 
 # Getting Started
 
-`cacheable` is primarily used as an extension to you caching engine with a robust storage backend [Keyv](https://keyv.org), Memonization (Wrap), Hooks, Events, and Statistics.
+`cacheable` is primarily used as an extension to your caching engine with a robust storage backend [Keyv](https://keyv.org), Memoization (Wrap), Hooks, Events, and Statistics.
 
 ```bash
 npm install cacheable

package/dist/index.cjs

@@ -46,8 +46,118 @@ __export(index_exports, {
   wrapSync: () => wrapSync
 });
 module.exports = __toCommonJS(index_exports);
-var import_keyv2 = require("keyv");
 var import_hookified2 = require("hookified");
+var import_keyv2 = require("keyv");
+
+// src/hash.ts
+var crypto = __toESM(require("crypto"), 1);
+function hash(object, 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);
+  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/keyv-memory.ts
+var import_keyv = require("keyv");
+
+// src/memory.ts
+var import_hookified = require("hookified");
+
+// src/memory-lru.ts
+var ListNode = class {
+  value;
+  prev = void 0;
+  next = void 0;
+  constructor(value) {
+    this.value = value;
+  }
+};
+var DoublyLinkedList = class {
+  head = void 0;
+  tail = void 0;
+  nodesMap = /* @__PURE__ */ new Map();
+  // Add a new node to the front (most recently used)
+  addToFront(value) {
+    const newNode = new ListNode(value);
+    if (this.head) {
+      newNode.next = this.head;
+      this.head.prev = newNode;
+      this.head = newNode;
+    } else {
+      this.head = this.tail = newNode;
+    }
+    this.nodesMap.set(value, newNode);
+  }
+  // Move an existing node to the front (most recently used)
+  moveToFront(value) {
+    const node = this.nodesMap.get(value);
+    if (!node || this.head === node) {
+      return;
+    }
+    if (node.prev) {
+      node.prev.next = node.next;
+    }
+    if (node.next) {
+      node.next.prev = node.prev;
+    }
+    if (node === this.tail) {
+      this.tail = node.prev;
+    }
+    node.prev = void 0;
+    node.next = this.head;
+    if (this.head) {
+      this.head.prev = node;
+    }
+    this.head = node;
+    this.tail ??= node;
+  }
+  // Get the oldest node (tail)
+  getOldest() {
+    return this.tail ? this.tail.value : void 0;
+  }
+  // Remove the oldest node (tail)
+  removeOldest() {
+    if (!this.tail) {
+      return void 0;
+    }
+    const oldValue = this.tail.value;
+    if (this.tail.prev) {
+      this.tail = this.tail.prev;
+      this.tail.next = void 0;
+    } else {
+      this.head = this.tail = void 0;
+    }
+    this.nodesMap.delete(oldValue);
+    return oldValue;
+  }
+  get size() {
+    return this.nodesMap.size;
+  }
+};
 
 // src/shorthand-time.ts
 var shorthandToMilliseconds = (shorthand) => {
@@ -62,7 +172,9 @@ var shorthandToMilliseconds = (shorthand) => {
     if (Number.isNaN(Number(shorthand))) {
       const match = /^([\d.]+)\s*(ms|s|m|h|hr|d)$/i.exec(shorthand);
       if (!match) {
-        throw new Error(`Unsupported time format: "${shorthand}". Use 'ms', 's', 'm', 'h', 'hr', or 'd'.`);
+        throw new Error(
+          `Unsupported time format: "${shorthand}". Use 'ms', 's', 'm', 'h', 'hr', or 'd'.`
+        );
       }
       const [, value, unit] = match;
       const numericValue = Number.parseFloat(value);
@@ -114,44 +226,6 @@ var shorthandToTime = (shorthand, fromDate) => {
   return fromDate.getTime() + milliseconds;
 };
 
-// src/keyv-memory.ts
-var import_keyv = require("keyv");
-
-// src/memory.ts
-var import_hookified = require("hookified");
-
-// src/hash.ts
-var crypto = __toESM(require("crypto"), 1);
-function hash(object, 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);
-  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();
 function hasKey(key) {
@@ -210,7 +284,7 @@ async function coalesceAsync(key, fnc) {
 // src/wrap.ts
 function wrapSync(function_, options) {
   const { ttl, keyPrefix, cache } = options;
-  return function(...arguments_) {
+  return (...arguments_) => {
     let cacheKey = createWrapKey(function_, arguments_, keyPrefix);
     if (options.createKey) {
       cacheKey = options.createKey(function_, arguments_, options);
@@ -256,12 +330,16 @@ async function getOrSet(key, function_, options) {
 }
 function wrap(function_, options) {
   const { keyPrefix, cache } = options;
-  return async function(...arguments_) {
+  return async (...arguments_) => {
     let cacheKey = createWrapKey(function_, arguments_, keyPrefix);
     if (options.createKey) {
       cacheKey = options.createKey(function_, arguments_, options);
     }
-    return cache.getOrSet(cacheKey, async () => function_(...arguments_), options);
+    return cache.getOrSet(
+      cacheKey,
+      async () => function_(...arguments_),
+      options
+    );
   };
 }
 function createWrapKey(function_, arguments_, keyPrefix) {
@@ -271,79 +349,6 @@ function createWrapKey(function_, arguments_, keyPrefix) {
   return `${keyPrefix}::${function_.name}::${hash(arguments_)}`;
 }
 
-// src/memory-lru.ts
-var ListNode = class {
-  // eslint-disable-next-line @typescript-eslint/parameter-properties
-  value;
-  prev = void 0;
-  next = void 0;
-  constructor(value) {
-    this.value = value;
-  }
-};
-var DoublyLinkedList = class {
-  head = void 0;
-  tail = void 0;
-  nodesMap = /* @__PURE__ */ new Map();
-  // Add a new node to the front (most recently used)
-  addToFront(value) {
-    const newNode = new ListNode(value);
-    if (this.head) {
-      newNode.next = this.head;
-      this.head.prev = newNode;
-      this.head = newNode;
-    } else {
-      this.head = this.tail = newNode;
-    }
-    this.nodesMap.set(value, newNode);
-  }
-  // Move an existing node to the front (most recently used)
-  moveToFront(value) {
-    const node = this.nodesMap.get(value);
-    if (!node || this.head === node) {
-      return;
-    }
-    if (node.prev) {
-      node.prev.next = node.next;
-    }
-    if (node.next) {
-      node.next.prev = node.prev;
-    }
-    if (node === this.tail) {
-      this.tail = node.prev;
-    }
-    node.prev = void 0;
-    node.next = this.head;
-    if (this.head) {
-      this.head.prev = node;
-    }
-    this.head = node;
-    this.tail ??= node;
-  }
-  // Get the oldest node (tail)
-  getOldest() {
-    return this.tail ? this.tail.value : void 0;
-  }
-  // Remove the oldest node (tail)
-  removeOldest() {
-    if (!this.tail) {
-      return void 0;
-    }
-    const oldValue = this.tail.value;
-    if (this.tail.prev) {
-      this.tail = this.tail.prev;
-      this.tail.next = void 0;
-    } else {
-      this.head = this.tail = void 0;
-    }
-    this.nodesMap.delete(oldValue);
-    return oldValue;
-  }
-  get size() {
-    return this.nodesMap.size;
-  }
-};
-
 // src/memory.ts
 var defaultStoreHashSize = 16;
 var maximumMapSize = 16777216;
@@ -352,7 +357,10 @@ var CacheableMemory = class extends import_hookified.Hookified {
   _storeHashSize = defaultStoreHashSize;
   _storeHashAlgorithm = "djb2Hash" /* djb2Hash */;
   // Default is djb2Hash
-  _store = Array.from({ length: this._storeHashSize }, () => /* @__PURE__ */ new Map());
+  _store = Array.from(
+    { length: this._storeHashSize },
+    () => /* @__PURE__ */ new Map()
+  );
   _ttl;
   // Turned off by default
   _useClone = true;
@@ -380,7 +388,12 @@ var CacheableMemory = class extends import_hookified.Hookified {
     }
     if (options?.lruSize) {
       if (options.lruSize > maximumMapSize) {
-        this.emit("error", new Error(`LRU size cannot be larger than ${maximumMapSize} due to Map limitations.`));
+        this.emit(
+          "error",
+          new Error(
+            `LRU size cannot be larger than ${maximumMapSize} due to Map limitations.`
+          )
+        );
       } else {
         this._lruSize = options.lruSize;
       }
@@ -391,7 +404,10 @@ var CacheableMemory = class extends import_hookified.Hookified {
     if (options?.storeHashAlgorithm) {
       this._storeHashAlgorithm = options.storeHashAlgorithm;
     }
-    this._store = Array.from({ length: this._storeHashSize }, () => /* @__PURE__ */ new Map());
+    this._store = Array.from(
+      { length: this._storeHashSize },
+      () => /* @__PURE__ */ new Map()
+    );
     this.startIntervalCheck();
   }
   /**
@@ -435,7 +451,12 @@ var CacheableMemory = class extends import_hookified.Hookified {
    */
   set lruSize(value) {
     if (value > maximumMapSize) {
-      this.emit("error", new Error(`LRU size cannot be larger than ${maximumMapSize} due to Map limitations.`));
+      this.emit(
+        "error",
+        new Error(
+          `LRU size cannot be larger than ${maximumMapSize} due to Map limitations.`
+        )
+      );
       return;
     }
     this._lruSize = value;
@@ -486,7 +507,10 @@ var CacheableMemory = class extends import_hookified.Hookified {
       return;
     }
     this._storeHashSize = value;
-    this._store = Array.from({ length: this._storeHashSize }, () => /* @__PURE__ */ new Map());
+    this._store = Array.from(
+      { length: this._storeHashSize },
+      () => /* @__PURE__ */ new Map()
+    );
   }
   /**
    * Gets the store hash algorithm
@@ -507,7 +531,7 @@ var CacheableMemory = class extends import_hookified.Hookified {
    * @returns {IterableIterator<string>} - The keys
    */
   get keys() {
-    const keys = new Array();
+    const keys = [];
     for (const store of this._store) {
       for (const key of store.keys()) {
         const item = store.get(key);
@@ -525,7 +549,7 @@ var CacheableMemory = class extends import_hookified.Hookified {
    * @returns {IterableIterator<CacheableStoreItem>} - The items
    */
   get items() {
-    const items = new Array();
+    const items = [];
     for (const store of this._store) {
       for (const item of store.values()) {
         if (this.hasExpired(item)) {
@@ -571,7 +595,7 @@ var CacheableMemory = class extends import_hookified.Hookified {
    * @returns {T[]} - The values of the keys
    */
   getMany(keys) {
-    const result = new Array();
+    const result = [];
     for (const key of keys) {
       result.push(this.get(key));
     }
@@ -601,7 +625,7 @@ var CacheableMemory = class extends import_hookified.Hookified {
    * @returns {CacheableStoreItem[]} - The raw values of the keys
    */
   getManyRaw(keys) {
-    const result = new Array();
+    const result = [];
     for (const key of keys) {
       result.push(this.getRaw(key));
     }
@@ -652,10 +676,7 @@ var CacheableMemory = class extends import_hookified.Hookified {
       }
     }
     const item = { key, value, expires };
-    store.set(
-      key,
-      item
-    );
+    store.set(key, item);
   }
   /**
    * Sets the values of the keys
@@ -682,7 +703,7 @@ var CacheableMemory = class extends import_hookified.Hookified {
    * @returns {boolean[]} - If true, the key exists. If false, the key does not exist.
    */
   hasMany(keys) {
-    const result = new Array();
+    const result = [];
     for (const key of keys) {
       const item = this.get(key);
       result.push(Boolean(item));
@@ -708,7 +729,7 @@ var CacheableMemory = class extends import_hookified.Hookified {
    * @returns {T[]} - The values of the keys
    */
   takeMany(keys) {
-    const result = new Array();
+    const result = [];
     for (const key of keys) {
       result.push(this.take(key));
     }
@@ -738,7 +759,10 @@ var CacheableMemory = class extends import_hookified.Hookified {
    * @returns {void}
    */
   clear() {
-    this._store = Array.from({ length: this._storeHashSize }, () => /* @__PURE__ */ new Map());
+    this._store = Array.from(
+      { length: this._storeHashSize },
+      () => /* @__PURE__ */ new Map()
+    );
     this._lru = new DoublyLinkedList();
   }
   /**
@@ -1110,28 +1134,24 @@ var CacheableStats = class {
     }
     this._clears++;
   }
-  // eslint-disable-next-line @typescript-eslint/naming-convention
   incrementVSize(value) {
     if (!this._enabled) {
       return;
     }
     this._vsize += this.roughSizeOfObject(value);
   }
-  // eslint-disable-next-line @typescript-eslint/naming-convention
   decreaseVSize(value) {
     if (!this._enabled) {
       return;
     }
     this._vsize -= this.roughSizeOfObject(value);
   }
-  // eslint-disable-next-line @typescript-eslint/naming-convention
   incrementKSize(key) {
     if (!this._enabled) {
       return;
     }
     this._ksize += this.roughSizeOfString(key);
   }
-  // eslint-disable-next-line @typescript-eslint/naming-convention
   decreaseKSize(key) {
     if (!this._enabled) {
       return;
@@ -1450,11 +1470,26 @@ var Cacheable = class extends import_hookified2.Hookified {
       this.emit("error" /* ERROR */, error);
     });
   }
+  // biome-ignore lint/suspicious/noExplicitAny: type format
   isKeyvInstance(keyv) {
     if (keyv instanceof import_keyv2.Keyv) {
       return true;
     }
-    const keyvMethods = ["generateIterator", "get", "getMany", "set", "setMany", "delete", "deleteMany", "has", "hasMany", "clear", "disconnect", "serialize", "deserialize"];
+    const keyvMethods = [
+      "generateIterator",
+      "get",
+      "getMany",
+      "set",
+      "setMany",
+      "delete",
+      "deleteMany",
+      "has",
+      "hasMany",
+      "clear",
+      "disconnect",
+      "serialize",
+      "deserialize"
+    ];
     return keyvMethods.every((method) => typeof keyv[method] === "function");
   }
   getNameSpace() {
@@ -1478,7 +1513,10 @@ var Cacheable = class extends import_hookified2.Hookified {
           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.hook(
+            "BEFORE_SECONDARY_SETS_PRIMARY" /* BEFORE_SECONDARY_SETS_PRIMARY */,
+            setItem
+          );
           await this._primary.set(setItem.key, setItem.value, setItem.ttl);
         }
       }
@@ -1520,7 +1558,10 @@ var Cacheable = class extends import_hookified2.Hookified {
             }
             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.hook(
+              "BEFORE_SECONDARY_SETS_PRIMARY" /* BEFORE_SECONDARY_SETS_PRIMARY */,
+              setItem
+            );
             await this._primary.set(setItem.key, setItem.value, setItem.ttl);
           }
         }
@@ -1662,7 +1703,7 @@ var Cacheable = class extends import_hookified2.Hookified {
     }
     if (missingKeys.length > 0 && this._secondary) {
       const secondary = await this.hasManyKeyv(this._secondary, keys);
-      for (const [i, key] of keys.entries()) {
+      for (const [i, _key] of keys.entries()) {
         if (!result[i] && secondary[i]) {
           result[i] = secondary[i];
         }
@@ -1760,6 +1801,7 @@ var Cacheable = class extends import_hookified2.Hookified {
    * @param {WrapOptions} [options] The options for the wrap function
    * @returns {Function} The wrapped function
    */
+  // biome-ignore lint/suspicious/noExplicitAny: type format
   wrap(function_, options) {
     const wrapOptions = {
       ttl: options?.ttl ?? this._ttl,
@@ -1795,6 +1837,7 @@ var Cacheable = class extends import_hookified2.Hookified {
    * @param {string} algorithm the hash algorithm to use. The default is 'sha256'
    * @returns {string} the hash of the object
    */
+  // biome-ignore lint/suspicious/noExplicitAny: type format
   hash(object, algorithm = "sha256") {
     return hash(object, algorithm);
   }
@@ -1806,7 +1849,7 @@ var Cacheable = class extends import_hookified2.Hookified {
     return result;
   }
   async getManySecondaryRawResults(keys) {
-    let result = new Array();
+    let result = [];
     if (this._secondary) {
       result = await this._secondary.get(keys, { raw: true });
     }

package/dist/index.d.cts

@@ -1,6 +1,26 @@
-import { KeyvStoreAdapter, StoredData, Keyv, StoredDataRaw } from 'keyv';
-export { Keyv, KeyvHooks, KeyvOptions, KeyvStoreAdapter } from 'keyv';
 import { Hookified } from 'hookified';
+import { Keyv, KeyvStoreAdapter, StoredData, StoredDataRaw } from 'keyv';
+export { Keyv, KeyvHooks, KeyvOptions, KeyvStoreAdapter } from 'keyv';
+
+/**
+ * CacheableItem
+ * @typedef {Object} CacheableItem
+ * @property {string} key - The key of the cacheable item
+ * @property {any} value - The value of the cacheable item
+ * @property {number|string} [ttl] - Time to Live - If you set a number it is miliseconds, if you set a string it is a human-readable
+ * format such as `1s` for 1 second or `1h` for 1 hour. Setting undefined means that it will use the default time-to-live. If both are
+ * undefined then it will not have a time-to-live.
+ */
+type CacheableItem = {
+    key: string;
+    value: any;
+    ttl?: number | string;
+};
+type CacheableStoreItem = {
+    key: string;
+    value: any;
+    expires?: number;
+};
 
 type CacheableOptions$1 = {
     enabled?: boolean;
@@ -89,26 +109,6 @@ declare class CacheableStats {
     resetStoreValues(): void;
 }
 
-/**
- * CacheableItem
- * @typedef {Object} CacheableItem
- * @property {string} key - The key of the cacheable item
- * @property {any} value - The value of the cacheable item
- * @property {number|string} [ttl] - Time to Live - If you set a number it is miliseconds, if you set a string it is a human-readable
- * format such as `1s` for 1 second or `1h` for 1 hour. Setting undefined means that it will use the default time-to-live. If both are
- * undefined then it will not have a time-to-live.
- */
-type CacheableItem = {
-    key: string;
-    value: any;
-    ttl?: number | string;
-};
-type CacheableStoreItem = {
-    key: string;
-    value: any;
-    expires?: number;
-};
-
 type GetOrSetKey = string | ((options?: GetOrSetOptions) => string);
 type GetOrSetFunctionOptions = {
     ttl?: number | string;
@@ -144,7 +144,7 @@ declare enum StoreHashAlgorithm {
     MD5 = "md5",
     djb2Hash = "djb2Hash"
 }
-type StoreHashAlgorithmFunction = ((key: string, storeHashSize: number) => number);
+type StoreHashAlgorithmFunction = (key: string, storeHashSize: number) => number;
 /**
  * @typedef {Object} CacheableMemoryOptions
  * @property {number|string} [ttl] - Time to Live - If you set a number it is miliseconds, if you set a string it is a human-readable
@@ -623,19 +623,19 @@ declare class Cacheable extends Hookified {
     isKeyvInstance(keyv: any): boolean;
     getNameSpace(): string | undefined;
     /**
-   * Retrieves an entry from the cache, with an optional “raw” mode.
-   *
-   * Checks the primary store first; if not found and a secondary store is configured,
-   * it will fetch from the secondary, repopulate the primary, and return the result.
-   *
-   * @typeParam T - The expected type of the stored value.
-   * @param {string} key - The cache key to retrieve.
-   * @param {{ raw?: boolean }} [opts] - Options for retrieval.
-   * @param {boolean} [opts.raw=false] - If `true`, returns the full raw data object
-   *                                      (`StoredDataRaw<T>`); otherwise returns just the value.
-   * @returns {Promise<T | StoredDataRaw<T> | undefined>}
-   *   A promise that resolves to the cached value (or raw data) if found, or `undefined`.
-   */
+     * Retrieves an entry from the cache, with an optional “raw” mode.
+     *
+     * Checks the primary store first; if not found and a secondary store is configured,
+     * it will fetch from the secondary, repopulate the primary, and return the result.
+     *
+     * @typeParam T - The expected type of the stored value.
+     * @param {string} key - The cache key to retrieve.
+     * @param {{ raw?: boolean }} [opts] - Options for retrieval.
+     * @param {boolean} [opts.raw=false] - If `true`, returns the full raw data object
+     *                                      (`StoredDataRaw<T>`); otherwise returns just the value.
+     * @returns {Promise<T | StoredDataRaw<T> | undefined>}
+     *   A promise that resolves to the cached value (or raw data) if found, or `undefined`.
+     */
     get<T>(key: string, options?: {
         raw?: false;
     }): Promise<T | undefined>;
@@ -643,20 +643,20 @@ declare class Cacheable extends Hookified {
         raw: true;
     }): Promise<StoredDataRaw<T>>;
     /**
-   * Retrieves multiple entries from the cache.
-   * Checks the primary store for each key; if a key is missing and a secondary store is configured,
-   * it will fetch from the secondary store, repopulate the primary store, and return the results.
-   *
-   * @typeParam T - The expected type of the stored values.
-   * @param {string[]} keys - The cache keys to retrieve.
-   * @param {{ raw?: boolean }} [options] - Options for retrieval.
-   * @param {boolean} [options.raw=false] - When `true`, returns an array of raw data objects (`StoredDataRaw<T>`);
-   *                                        when `false`, returns an array of unwrapped values (`T`) or `undefined` for misses.
-   * @returns {Promise<Array<T | undefined>> | Promise<Array<StoredDataRaw<T>>>}
-   *   A promise that resolves to:
-   *   - `Array<T | undefined>` if `raw` is `false` (default).
-   *   - `Array<StoredDataRaw<T>>` if `raw` is `true`.
-   */
+     * Retrieves multiple entries from the cache.
+     * Checks the primary store for each key; if a key is missing and a secondary store is configured,
+     * it will fetch from the secondary store, repopulate the primary store, and return the results.
+     *
+     * @typeParam T - The expected type of the stored values.
+     * @param {string[]} keys - The cache keys to retrieve.
+     * @param {{ raw?: boolean }} [options] - Options for retrieval.
+     * @param {boolean} [options.raw=false] - When `true`, returns an array of raw data objects (`StoredDataRaw<T>`);
+     *                                        when `false`, returns an array of unwrapped values (`T`) or `undefined` for misses.
+     * @returns {Promise<Array<T | undefined>> | Promise<Array<StoredDataRaw<T>>>}
+     *   A promise that resolves to:
+     *   - `Array<T | undefined>` if `raw` is `false` (default).
+     *   - `Array<StoredDataRaw<T>>` if `raw` is `true`.
+     */
     getMany<T>(keys: string[], options?: {
         raw?: false;
     }): Promise<Array<T | undefined>>;