cacheable 1.8.9 → 1.9.0

package/README.md

@@ -29,6 +29,7 @@
 * [Basic Usage](#basic-usage)
 * [Hooks and Events](#hooks-and-events)
 * [Storage Tiering and Caching](#storage-tiering-and-caching)
+* [TTL Propagation and Storage Tiering](#ttl-propagation-and-storage-tiering)
 * [Shorthand for Time to Live (ttl)](#shorthand-for-time-to-live-ttl)
 * [Non-Blocking Operations](#non-blocking-operations)
 * [CacheSync - Distributed Updates](#cachesync---distributed-updates)
@@ -38,8 +39,8 @@
 * [CacheableMemory - In-Memory Cache](#cacheablememory---in-memory-cache)
 * [CacheableMemory Options](#cacheablememory-options)
 * [CacheableMemory - API](#cacheablememory---api)
-* [Wrap / Memoization for Sync and Async Functions](#wrap--memoization-for-sync-and-async-functions)
 * [Keyv Storage Adapter - KeyvCacheableMemory](#keyv-storage-adapter---keyvcacheablememory)
+* [Wrap / Memoization for Sync and Async Functions](#wrap--memoization-for-sync-and-async-functions)
 * [How to Contribute](#how-to-contribute)
 * [License and Copyright](#license-and-copyright)
 
@@ -98,6 +99,7 @@ The following hooks are available for you to extend the functionality of `cachea
 * `AFTER_GET`: This is called after the `get()` method is called.
 * `BEFORE_GET_MANY`: This is called before the `getMany()` method is called.
 * `AFTER_GET_MANY`: This is called after the `getMany()` method is called.
+* `BEFORE_SECONDARY_SETS_PRIMARY`: This is called when the secondary store sets the value in the primary store.
 
 An example of how to use these hooks:
 
@@ -110,6 +112,19 @@ cacheable.onHook(CacheableHooks.BEFORE_SET, (data) => {
 });
 ```
 
+Here is an example of how to use `BEFORE_SECONDARY_SETS_PRIMARY` hook:
+
+```javascript
+import { Cacheable, CacheableHooks } from 'cacheable';
+import KeyvRedis from '@keyv/redis';
+const secondary = new KeyvRedis('redis://user:pass@localhost:6379');
+const cache = new Cacheable({secondary});
+cache.onHook(CacheableHooks.BEFORE_SECONDARY_SETS_PRIMARY, (data) => {
+  console.log(`before secondary sets primary: ${data.key} ${data.value} ${data.ttl}`);
+});
+```
+This is called when the secondary store sets the value in the primary store. This is useful if you want to do something before the value is set in the primary store such as manipulating the ttl or the value.
+
 # Storage Tiering and Caching
 
 `cacheable` is built as a layer 1 and layer 2 caching engine by default. The purpose is to have your layer 1 be fast and your layer 2 be more persistent. The primary store is the layer 1 cache and the secondary store is the layer 2 cache. By adding the secondary store you are enabling layer 2 caching. By default the operations are blocking but fault tolerant:
@@ -119,6 +134,48 @@ cacheable.onHook(CacheableHooks.BEFORE_SET, (data) => {
 * `Deleting Data`: Deletes the value from the primary store and secondary store at the same time waiting for both to respond.
 * `Clearing Data`: Clears the primary store and secondary store at the same time waiting for both to respond.
 
+When `Getting Data` if the value does not exist in the primary store it will try to get it from the secondary store. If the secondary store returns the value it will set it in the primary store. Because we use [TTL Propagation](#ttl-propagation-and-storage-tiering) the value will be set in the primary store with the TTL of the secondary store unless the time to live (TTL) is greater than the primary store which will then use the TTL of the primary store. An example of this is:
+
+```javascript
+import { Cacheable } from 'cacheable';
+import KeyvRedis from '@keyv/redis';
+const secondary = new KeyvRedis('redis://user:pass@localhost:6379', { ttl: 1000 });
+const cache = new Cacheable({secondary, ttl: 100});
+
+await cache.set('key', 'value'); // sets the value in the primary store with a ttl of 100 ms and secondary store with a ttl of 1000 ms
+
+await sleep(500); // wait for .5 seconds
+
+const value = await cache.get('key'); // gets the value from the secondary store and now sets the value in the primary store with a ttl of 500 ms which is what is left from the secondary store
+```
+
+In this example the primary store has a ttl of `100 ms` and the secondary store has a ttl of `1000 ms`. Because the ttl is greater in the secondary store it will default to setting ttl value in the primary store.
+
+```javascript
+import { Cacheable } from 'cacheable';
+import {Keyv} from 'keyv';
+import KeyvRedis from '@keyv/redis';
+const primary = new Keyv({ ttl: 200 });
+const secondary = new KeyvRedis('redis://user:pass@localhost:6379', { ttl: 1000 });
+const cache = new Cacheable({primary, secondary});
+
+await cache.set('key', 'value'); // sets the value in the primary store with a ttl of 100 ms and secondary store with a ttl of 1000 ms
+
+await sleep(200); // wait for .2 seconds
+
+const value = await cache.get('key'); // gets the value from the secondary store and now sets the value in the primary store with a ttl of 200 ms which is what the primary store is set with
+```
+
+# TTL Propagation and Storage Tiering
+
+Cacheable TTL propagation is a feature that allows you to set a time to live (TTL) for the cache. By default the TTL is set in the following order:
+
+```
+ttl = set at the function ?? storage adapter ttl ?? cacheable ttl
+```
+
+This means that if you set a TTL at the function level it will override the storage adapter TTL and the cacheable TTL. If you do not set a TTL at the function level it will use the storage adapter TTL and then the cacheable TTL. If you do not set a TTL at all it will use the default TTL of `undefined` which is disabled.
+
 # Shorthand for Time to Live (ttl)
 
 By default `Cacheable` and `CacheableMemory` the `ttl` is in milliseconds but you can use shorthand for the time to live. Here are the following shorthand values:
@@ -157,6 +214,40 @@ cache.ttl = -1; // sets the default ttl to 0 which is disabled
 console.log(cache.ttl); // undefined
 ```
 
+## Retrieving raw cache entries
+
+The `get` and `getMany` methods support a `raw` option, which returns the full stored metadata (`StoredDataRaw<T>`) instead of just the value:
+
+```typescript
+import { Cacheable } from 'cacheable';
+
+const cache = new Cacheable();
+
+// store a value
+await cache.set('user:1', { name: 'Alice' });
+
+// default: only the value
+const user = await cache.get<{ name: string }>('user:1');
+console.log(user); // { name: 'Alice' }
+
+// with raw: full record including expiration
+const raw = await cache.get<{ name: string }>('user:1', { raw: true });
+console.log(raw.value);   // { name: 'Alice' }
+console.log(raw.expires); // e.g. 1677628495000 or null
+```
+
+```typescript
+// getMany with raw option
+await cache.set('a', 1);
+await cache.set('b', 2);
+
+const raws = await cache.getMany<number>(['a', 'b'], { raw: true });
+raws.forEach((entry, idx) => {
+  console.log(`key=${['a','b'][idx]}, value=${entry?.value}, expires=${entry?.expires}`);
+});
+```
+
+
 # Non-Blocking Operations
 
 If you want your layer 2 (secondary) store to be non-blocking you can set the `nonBlocking` property to `true` in the options. This will make the secondary store non-blocking and will not wait for the secondary store to respond on `setting data`, `deleting data`, or `clearing data`. This is useful if you want to have a faster response time and not wait for the secondary store to respond.
@@ -215,7 +306,9 @@ _This does not enable statistics for your layer 2 cache as that is a distributed
 * `set(key, value, ttl?)`: Sets a value in the cache.
 * `setMany([{key, value, ttl?}])`: Sets multiple values in the cache.
 * `get(key)`: Gets a value from the cache.
+* `get(key, { raw: true })`: Gets a raw value from the cache.
 * `getMany([keys])`: Gets multiple values from the cache.
+* `getMany([keys], { raw: true })`: Gets multiple raw values from the cache.
 * `has(key)`: Checks if a value exists in the cache.
 * `hasMany([keys])`: Checks if multiple values exist in the cache.
 * `take(key)`: Takes a value from the cache and deletes it.
@@ -289,6 +382,20 @@ By default we use lazy expiration deletion which means on `get` and `getMany` ty
 * `stopIntervalCheck()`: Stops the interval check for expired keys.
 * `hash(object: any, algorithm = 'sha256'): string`: Hashes an object with the algorithm. Default is `sha256`.
 
+# 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`:
+
+```javascript
+import { Keyv } from 'keyv';
+import { KeyvCacheableMemory } from 'cacheable';
+
+const keyv = new Keyv({ store: new KeyvCacheableMemory() });
+await keyv.set('foo', 'bar');
+const value = await keyv.get('foo');
+console.log(value); // bar 
+```
+
 # Wrap / Memoization for Sync and Async Functions
 
 `Cacheable` and `CacheableMemory` has a feature called `wrap` that allows you to wrap a function in a cache. This is useful for memoization and caching the results of a function. You can wrap a `sync` or `async` function in a cache. Here is an example of how to use the `wrap` function:
@@ -363,20 +470,6 @@ 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`:
-
-```javascript
-import { Keyv } from 'keyv';
-import { KeyvCacheableMemory } from 'cacheable';
-
-const keyv = new Keyv({ store: new KeyvCacheableMemory() });
-await keyv.set('foo', 'bar');
-const value = await keyv.get('foo');
-console.log(value); // bar 
-```
-
 # How to Contribute
 
 You can contribute by forking the repo and submitting a pull request. Please make sure to add tests and update the documentation. To learn more about how to contribute go to our main README [https://github.com/jaredwray/cacheable](https://github.com/jaredwray/cacheable). This will talk about how to `Open a Pull Request`, `Ask a Question`, or `Post an Issue`.

package/dist/index.cjs

@@ -613,6 +613,7 @@ var CacheableMemory = class extends import_hookified.Hookified {
   delete(key) {
     const store = this.getStore(key);
     store.delete(key);
+    this._hashCache.delete(key);
   }
   /**
    * Delete the keys
@@ -697,7 +698,7 @@ var CacheableMemory = class extends import_hookified.Hookified {
    */
   hashKey(key) {
     const cacheHashNumber = this._hashCache.get(key);
-    if (cacheHashNumber) {
+    if (typeof cacheHashNumber === "number") {
       return cacheHashNumber;
     }
     let hash2 = 0;
@@ -1147,6 +1148,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
 var import_keyv3 = require("keyv");
 var CacheableHooks = /* @__PURE__ */ ((CacheableHooks2) => {
@@ -1158,6 +1188,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) => {
@@ -1366,25 +1397,26 @@ var Cacheable = class extends import_hookified2.Hookified {
     }
     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;
-          const finalTtl = rawResult.expires ?? void 0;
-          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);
     }
@@ -1396,18 +1428,14 @@ var Cacheable = class extends import_hookified2.Hookified {
       }
       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()) {
@@ -1415,12 +1443,16 @@ var Cacheable = class extends import_hookified2.Hookified {
             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);
           }
         }
       }
@@ -1438,7 +1470,7 @@ var Cacheable = class extends import_hookified2.Hookified {
       }
       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.
@@ -1677,6 +1709,20 @@ var Cacheable = class extends import_hookified2.Hookified {
   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/dist/index.d.cts

@@ -1,4 +1,4 @@
-import { KeyvStoreAdapter, StoredData, Keyv } from 'keyv';
+import { KeyvStoreAdapter, StoredData, Keyv, StoredDataRaw } from 'keyv';
 export { Keyv, KeyvHooks, KeyvOptions, KeyvStoreAdapter } from 'keyv';
 import { Hookified } from 'hookified';
 
@@ -423,7 +423,8 @@ declare enum CacheableHooks {
     BEFORE_GET = "BEFORE_GET",
     AFTER_GET = "AFTER_GET",
     BEFORE_GET_MANY = "BEFORE_GET_MANY",
-    AFTER_GET_MANY = "AFTER_GET_MANY"
+    AFTER_GET_MANY = "AFTER_GET_MANY",
+    BEFORE_SECONDARY_SETS_PRIMARY = "BEFORE_SECONDARY_SETS_PRIMARY"
 }
 declare enum CacheableEvents {
     ERROR = "error"
@@ -593,17 +594,46 @@ declare class Cacheable extends Hookified {
     setSecondary(secondary: Keyv | KeyvStoreAdapter): void;
     getNameSpace(): string | undefined;
     /**
-     * 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
-     */
-    get<T>(key: string): Promise<T | undefined>;
-    /**
-     * 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
-     */
-    getMany<T>(keys: string[]): Promise<Array<T | 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>;
+    get<T>(key: string, options: {
+        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`.
+   */
+    getMany<T>(keys: string[], options?: {
+        raw?: false;
+    }): Promise<Array<T | undefined>>;
+    getMany<T>(keys: string[], options: {
+        raw: true;
+    }): Promise<Array<StoredDataRaw<T>>>;
     /**
      * Sets the value of the key. If the secondary store is set then it will also set the value in the secondary store.
      * @param {string} key the key to set the value of
@@ -681,6 +711,8 @@ declare class Cacheable extends Hookified {
      * @returns {string} the hash of the object
      */
     hash(object: any, algorithm?: string): string;
+    private getSecondaryRawResults;
+    private getManySecondaryRawResults;
     private deleteManyKeyv;
     private setManyKeyv;
     private hasManyKeyv;

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { KeyvStoreAdapter, StoredData, Keyv } from 'keyv';
+import { KeyvStoreAdapter, StoredData, Keyv, StoredDataRaw } from 'keyv';
 export { Keyv, KeyvHooks, KeyvOptions, KeyvStoreAdapter } from 'keyv';
 import { Hookified } from 'hookified';
 
@@ -423,7 +423,8 @@ declare enum CacheableHooks {
     BEFORE_GET = "BEFORE_GET",
     AFTER_GET = "AFTER_GET",
     BEFORE_GET_MANY = "BEFORE_GET_MANY",
-    AFTER_GET_MANY = "AFTER_GET_MANY"
+    AFTER_GET_MANY = "AFTER_GET_MANY",
+    BEFORE_SECONDARY_SETS_PRIMARY = "BEFORE_SECONDARY_SETS_PRIMARY"
 }
 declare enum CacheableEvents {
     ERROR = "error"
@@ -593,17 +594,46 @@ declare class Cacheable extends Hookified {
     setSecondary(secondary: Keyv | KeyvStoreAdapter): void;
     getNameSpace(): string | undefined;
     /**
-     * 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
-     */
-    get<T>(key: string): Promise<T | undefined>;
-    /**
-     * 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
-     */
-    getMany<T>(keys: string[]): Promise<Array<T | 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>;
+    get<T>(key: string, options: {
+        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`.
+   */
+    getMany<T>(keys: string[], options?: {
+        raw?: false;
+    }): Promise<Array<T | undefined>>;
+    getMany<T>(keys: string[], options: {
+        raw: true;
+    }): Promise<Array<StoredDataRaw<T>>>;
     /**
      * Sets the value of the key. If the secondary store is set then it will also set the value in the secondary store.
      * @param {string} key the key to set the value of
@@ -681,6 +711,8 @@ declare class Cacheable extends Hookified {
      * @returns {string} the hash of the object
      */
     hash(object: any, algorithm?: string): string;
+    private getSecondaryRawResults;
+    private getManySecondaryRawResults;
     private deleteManyKeyv;
     private setManyKeyv;
     private hasManyKeyv;

package/dist/index.js

@@ -569,6 +569,7 @@ var CacheableMemory = class extends Hookified {
   delete(key) {
     const store = this.getStore(key);
     store.delete(key);
+    this._hashCache.delete(key);
   }
   /**
    * Delete the keys
@@ -653,7 +654,7 @@ var CacheableMemory = class extends Hookified {
    */
   hashKey(key) {
     const cacheHashNumber = this._hashCache.get(key);
-    if (cacheHashNumber) {
+    if (typeof cacheHashNumber === "number") {
       return cacheHashNumber;
     }
     let hash2 = 0;
@@ -1103,6 +1104,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 +1147,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,25 +1356,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;
-          const finalTtl = rawResult.expires ?? void 0;
-          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);
     }
@@ -1355,18 +1387,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()) {
@@ -1374,12 +1402,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);
           }
         }
       }
@@ -1397,7 +1429,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.
@@ -1636,6 +1668,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.9",
+  "version": "1.9.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.5.1",
-    "@keyv/redis": "^4.3.1",
-    "@types/node": "^22.13.9",
-    "@vitest/coverage-v8": "^3.0.7",
-    "lru-cache": "^11.0.2",
+    "@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.0.7",
+    "typescript": "^5.8.3",
+    "vitest": "^3.1.3",
     "xo": "^0.60.0"
   },
   "dependencies": {
-    "hookified": "^1.7.1",
-    "keyv": "^5.3.1"
+    "hookified": "^1.8.2",
+    "keyv": "^5.3.3"
   },
   "keywords": [
     "cacheable",