cacheable 1.10.0 → 1.10.2

package/README.md

@@ -32,6 +32,7 @@
 * [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)
+* [Non-Blocking with @keyv/redis](#non-blocking-with-keyvredis)
 * [CacheSync - Distributed Updates](#cachesync---distributed-updates)
 * [Cacheable Options](#cacheable-options)
 * [Cacheable Statistics (Instance Only)](#cacheable-statistics-instance-only)
@@ -44,6 +45,7 @@
 * [CacheableMemory - API](#cacheablememory---api)
 * [Keyv Storage Adapter - KeyvCacheableMemory](#keyv-storage-adapter---keyvcacheablememory)
 * [Wrap / Memoization for Sync and Async Functions](#wrap--memoization-for-sync-and-async-functions)
+* [Get Or Set Memoization Function](#get-or-set-memoization-function)
 * [How to Contribute](#how-to-contribute)
 * [License and Copyright](#license-and-copyright)
 
@@ -255,6 +257,29 @@ raws.forEach((entry, idx) => {
 
 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.
 
+# Non-Blocking with @keyv/redis
+
+`@keyv/redis` is one of the most popular storage adapters used with `cacheable`. It provides a Redis-backed cache store that can be used as a secondary store. It is a bit complicated to setup as by default it causes hangs and blocking with its default configuration. To get past this you will need to configure the following:
+
+Construct your own Redis client via the `createClient()` method from `@keyv/redis` with the following options:
+* Set `disableOfflineQueue` to `true`
+* Set `socket.reconnectStrategy` to `false`
+In the KeyvRedis options:
+* Set `throwOnConnectError` to `false`
+In the Cacheable options:
+* Set `nonBlocking` to `true`
+
+We have also build a function to help with this called `createKeyvNonBlocking` inside the `@keyv/redis` package after version `4.6.0`. Here is an example of how to use it:
+
+```javascript
+import { Cacheable } from 'cacheable';
+import { createKeyvNonBlocking } from '@keyv/redis';
+
+const secondary = createKeyvNonBlocking('redis://user:pass@localhost:6379');
+
+const cache = new Cacheable({ secondary, nonBlocking: true });
+```
+
 # GetOrSet
 
 The `getOrSet` method provides a convenient way to implement the cache-aside pattern. It attempts to retrieve a value
@@ -355,7 +380,7 @@ _This does not enable statistics for your layer 2 cache as that is a distributed
 * `deleteMany([keys])`: Deletes multiple values from the cache.
 * `clear()`: Clears the cache stores. Be careful with this as it will clear both layer 1 and layer 2.
 * `wrap(function, WrapOptions)`: Wraps an `async` function in a cache.
-* `getOrSet(key, valueFunction, ttl?)`: Gets a value from cache or sets it if not found using the provided function.
+* `getOrSet(GetOrSetKey, valueFunction, GetOrSetFunctionOptions)`: Gets a value from cache or sets it if not found using the provided function.
 * `disconnect()`: Disconnects from the cache stores.
 * `onHook(hook, callback)`: Sets a hook.
 * `removeHook(hook)`: Removes a hook.
@@ -614,6 +639,67 @@ console.log(wrappedFunction()); // error
 console.log(wrappedFunction()); // error from cache
 ```
 
+If you would like to generate your own key for the wrapped function you can set the `createKey` property in the `wrap()` options. This is useful if you want to generate a key based on the arguments of the function or any other criteria.
+
+```javascript
+  const cache = new Cacheable();
+  const options: WrapOptions = {
+    cache,
+    keyPrefix: 'test',
+    createKey: (function_, arguments_, options: WrapOptions) => `customKey:${options?.keyPrefix}:${arguments_[0]}`,
+  };
+
+  const wrapped = wrap((argument: string) => `Result for ${argument}`, options);
+
+  const result1 = await wrapped('arg1');
+  const result2 = await wrapped('arg1'); // Should hit the cache
+
+  console.log(result1); // Result for arg1
+  console.log(result2); // Result for arg1 (from cache)
+```
+
+We will pass in the `function` that is being wrapped, the `arguments` passed to the function, and the `options` used to wrap the function. You can then use these to generate a custom key for the cache.
+
+# Get Or Set Memoization Function
+
+The `getOrSet` method provides a convenient way to implement the cache-aside pattern. It attempts to retrieve a value from cache, and if not found, calls the provided function to compute the value and store it in cache before returning it. Here are the options:
+
+```typescript
+export type GetOrSetFunctionOptions = {
+	ttl?: number | string;
+	cacheErrors?: boolean;
+	throwErrors?: boolean;
+};
+```
+
+Here is an example of how to use the `getOrSet` method:
+
+```javascript
+import { Cacheable } from 'cacheable';
+const cache = new Cacheable();
+// Use getOrSet to fetch user data
+const function_ = async () => Math.random() * 100;
+const value = await cache.getOrSet('randomValue', function_, { ttl: '1h' });
+console.log(value); // e.g. 42.123456789
+```
+
+You can also use a function to compute the key for the function:
+
+```javascript
+import { Cacheable, GetOrSetOptions } from 'cacheable';
+const cache = new Cacheable();
+
+// Function to generate a key based on options
+const generateKey = (options?: GetOrSetOptions) => {
+  return `custom_key_:${options?.cacheId || 'default'}`;
+};
+
+const function_ = async () => Math.random() * 100;
+const value = await cache.getOrSet(generateKey(), function_, { ttl: '1h' });
+```
+
+
+
 # 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

@@ -39,6 +39,7 @@ __export(index_exports, {
   KeyvCacheableMemory: () => KeyvCacheableMemory,
   KeyvHooks: () => import_keyv3.KeyvHooks,
   createKeyv: () => createKeyv,
+  getOrSet: () => getOrSet,
   shorthandToMilliseconds: () => shorthandToMilliseconds,
   shorthandToTime: () => shorthandToTime,
   wrap: () => wrap,
@@ -61,9 +62,7 @@ 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);
@@ -107,7 +106,7 @@ var shorthandToMilliseconds = (shorthand) => {
   return milliseconds;
 };
 var shorthandToTime = (shorthand, fromDate) => {
-  fromDate ||= /* @__PURE__ */ new Date();
+  fromDate ??= /* @__PURE__ */ new Date();
   const milliseconds = shorthandToMilliseconds(shorthand);
   if (milliseconds === void 0) {
     return fromDate.getTime();
@@ -212,7 +211,10 @@ async function coalesceAsync(key, fnc) {
 function wrapSync(function_, options) {
   const { ttl, keyPrefix, cache } = options;
   return function(...arguments_) {
-    const cacheKey = createWrapKey(function_, arguments_, keyPrefix);
+    let cacheKey = createWrapKey(function_, arguments_, keyPrefix);
+    if (options.createKey) {
+      cacheKey = options.createKey(function_, arguments_, options);
+    }
     let value = cache.get(cacheKey);
     if (value === void 0) {
       try {
@@ -229,19 +231,23 @@ function wrapSync(function_, options) {
   };
 }
 async function getOrSet(key, function_, options) {
-  let value = await options.cache.get(key);
+  const keyString = typeof key === "function" ? key(options) : key;
+  let value = await options.cache.get(keyString);
   if (value === void 0) {
     const cacheId = options.cacheId ?? "default";
-    const coalesceKey = `${cacheId}::${key}`;
+    const coalesceKey = `${cacheId}::${keyString}`;
     value = await coalesceAsync(coalesceKey, async () => {
       try {
         const result = await function_();
-        await options.cache.set(key, result, options.ttl);
+        await options.cache.set(keyString, result, options.ttl);
         return result;
       } catch (error) {
         options.cache.emit("error", error);
         if (options.cacheErrors) {
-          await options.cache.set(key, error, options.ttl);
+          await options.cache.set(keyString, error, options.ttl);
+        }
+        if (options.throwErrors) {
+          throw error;
         }
       }
     });
@@ -251,7 +257,10 @@ async function getOrSet(key, function_, options) {
 function wrap(function_, options) {
   const { keyPrefix, cache } = options;
   return async function(...arguments_) {
-    const cacheKey = createWrapKey(function_, arguments_, keyPrefix);
+    let cacheKey = createWrapKey(function_, arguments_, keyPrefix);
+    if (options.createKey) {
+      cacheKey = options.createKey(function_, arguments_, options);
+    }
     return cache.getOrSet(cacheKey, async () => function_(...arguments_), options);
   };
 }
@@ -309,7 +318,7 @@ var DoublyLinkedList = class {
       this.head.prev = node;
     }
     this.head = node;
-    this.tail ||= node;
+    this.tail ??= node;
   }
   // Get the oldest node (tail)
   getOldest() {
@@ -1417,7 +1426,11 @@ var Cacheable = class extends import_hookified2.Hookified {
    * @returns {void}
    */
   setPrimary(primary) {
-    this._primary = primary instanceof import_keyv2.Keyv ? primary : new import_keyv2.Keyv(primary);
+    if (this.isKeyvInstance(primary)) {
+      this._primary = primary;
+    } else {
+      this._primary = new import_keyv2.Keyv(primary);
+    }
     this._primary.on("error", (error) => {
       this.emit("error" /* ERROR */, error);
     });
@@ -1428,11 +1441,22 @@ var Cacheable = class extends import_hookified2.Hookified {
    * @returns {void}
    */
   setSecondary(secondary) {
-    this._secondary = secondary instanceof import_keyv2.Keyv ? secondary : new import_keyv2.Keyv(secondary);
+    if (this.isKeyvInstance(secondary)) {
+      this._secondary = secondary;
+    } else {
+      this._secondary = new import_keyv2.Keyv(secondary);
+    }
     this._secondary.on("error", (error) => {
       this.emit("error" /* ERROR */, error);
     });
   }
+  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"];
+    return keyvMethods.every((method) => typeof keyv[method] === "function");
+  }
   getNameSpace() {
     if (typeof this._namespace === "function") {
       return this._namespace();
@@ -1490,7 +1514,10 @@ var Cacheable = class extends import_hookified2.Hookified {
           if (!result[i] && secondaryResults[i]) {
             result[i] = secondaryResults[i];
             const cascadeTtl = getCascadingTtl(this._ttl, this._primary.ttl);
-            const expires = secondaryResults[i].expires;
+            let { expires } = secondaryResults[i];
+            if (expires === null) {
+              expires = void 0;
+            }
             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);
@@ -1746,9 +1773,10 @@ var Cacheable = class extends import_hookified2.Hookified {
    * 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 {GetOrSetKey} key - The key to retrieve or set in the cache. This can also be a function that returns a string key.
+   * If a function is provided, it will be called with the cache options to generate the key.
    * @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.
+   * @param {GetOrSetFunctionOptions} [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) {
@@ -1756,7 +1784,8 @@ var Cacheable = class extends import_hookified2.Hookified {
       cache: this,
       cacheId: this._cacheId,
       ttl: options?.ttl ?? this._ttl,
-      cacheErrors: options?.cacheErrors
+      cacheErrors: options?.cacheErrors,
+      throwErrors: options?.throwErrors
     };
     return getOrSet(key, function_, getOrSetOptions);
   }
@@ -1828,6 +1857,7 @@ var Cacheable = class extends import_hookified2.Hookified {
   KeyvCacheableMemory,
   KeyvHooks,
   createKeyv,
+  getOrSet,
   shorthandToMilliseconds,
   shorthandToTime,
   wrap,

package/dist/index.d.cts

@@ -109,13 +109,21 @@ type CacheableStoreItem = {
     expires?: number;
 };
 
+type GetOrSetKey = string | ((options?: GetOrSetOptions) => string);
 type GetOrSetFunctionOptions = {
     ttl?: number | string;
     cacheErrors?: boolean;
+    throwErrors?: boolean;
 };
+type GetOrSetOptions = GetOrSetFunctionOptions & {
+    cacheId?: string;
+    cache: Cacheable;
+};
+type CreateWrapKey = (function_: AnyFunction, arguments_: any[], options?: WrapFunctionOptions) => string;
 type WrapFunctionOptions = {
     ttl?: number | string;
     keyPrefix?: string;
+    createKey?: CreateWrapKey;
     cacheErrors?: boolean;
     cacheId?: string;
 };
@@ -127,6 +135,7 @@ type WrapSyncOptions = WrapFunctionOptions & {
 };
 type AnyFunction = (...arguments_: any[]) => any;
 declare function wrapSync<T>(function_: AnyFunction, options: WrapSyncOptions): AnyFunction;
+declare function getOrSet<T>(key: GetOrSetKey, function_: () => Promise<T>, options: GetOrSetOptions): Promise<T | undefined>;
 declare function wrap<T>(function_: AnyFunction, options: WrapOptions): AnyFunction;
 
 declare enum StoreHashAlgorithm {
@@ -611,6 +620,7 @@ declare class Cacheable extends Hookified {
      * @returns {void}
      */
     setSecondary(secondary: Keyv | KeyvStoreAdapter): void;
+    isKeyvInstance(keyv: any): boolean;
     getNameSpace(): string | undefined;
     /**
    * Retrieves an entry from the cache, with an optional “raw” mode.
@@ -727,12 +737,13 @@ declare class Cacheable extends Hookified {
      * 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 {GetOrSetKey} key - The key to retrieve or set in the cache. This can also be a function that returns a string key.
+     * If a function is provided, it will be called with the cache options to generate the key.
      * @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.
+     * @param {GetOrSetFunctionOptions} [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.
      */
-    getOrSet<T>(key: string, function_: () => Promise<T>, options?: GetOrSetFunctionOptions): Promise<T | undefined>;
+    getOrSet<T>(key: GetOrSetKey, function_: () => Promise<T>, options?: GetOrSetFunctionOptions): Promise<T | undefined>;
     /**
      * Will hash an object using the specified algorithm. The default algorithm is 'sha256'.
      * @param {any} object the object to hash
@@ -748,4 +759,4 @@ declare class Cacheable extends Hookified {
     private setTtl;
 }
 
-export { Cacheable, CacheableEvents, CacheableHooks, type CacheableItem, CacheableMemory, type CacheableMemoryOptions, type CacheableOptions, CacheableStats, KeyvCacheableMemory, type WrapOptions, type WrapSyncOptions, createKeyv, shorthandToMilliseconds, shorthandToTime, wrap, wrapSync };
+export { Cacheable, CacheableEvents, CacheableHooks, type CacheableItem, CacheableMemory, type CacheableMemoryOptions, type CacheableOptions, CacheableStats, type GetOrSetFunctionOptions, type GetOrSetKey, type GetOrSetOptions, KeyvCacheableMemory, type WrapOptions, type WrapSyncOptions, createKeyv, getOrSet, shorthandToMilliseconds, shorthandToTime, wrap, wrapSync };

package/dist/index.d.ts

@@ -109,13 +109,21 @@ type CacheableStoreItem = {
     expires?: number;
 };
 
+type GetOrSetKey = string | ((options?: GetOrSetOptions) => string);
 type GetOrSetFunctionOptions = {
     ttl?: number | string;
     cacheErrors?: boolean;
+    throwErrors?: boolean;
 };
+type GetOrSetOptions = GetOrSetFunctionOptions & {
+    cacheId?: string;
+    cache: Cacheable;
+};
+type CreateWrapKey = (function_: AnyFunction, arguments_: any[], options?: WrapFunctionOptions) => string;
 type WrapFunctionOptions = {
     ttl?: number | string;
     keyPrefix?: string;
+    createKey?: CreateWrapKey;
     cacheErrors?: boolean;
     cacheId?: string;
 };
@@ -127,6 +135,7 @@ type WrapSyncOptions = WrapFunctionOptions & {
 };
 type AnyFunction = (...arguments_: any[]) => any;
 declare function wrapSync<T>(function_: AnyFunction, options: WrapSyncOptions): AnyFunction;
+declare function getOrSet<T>(key: GetOrSetKey, function_: () => Promise<T>, options: GetOrSetOptions): Promise<T | undefined>;
 declare function wrap<T>(function_: AnyFunction, options: WrapOptions): AnyFunction;
 
 declare enum StoreHashAlgorithm {
@@ -611,6 +620,7 @@ declare class Cacheable extends Hookified {
      * @returns {void}
      */
     setSecondary(secondary: Keyv | KeyvStoreAdapter): void;
+    isKeyvInstance(keyv: any): boolean;
     getNameSpace(): string | undefined;
     /**
    * Retrieves an entry from the cache, with an optional “raw” mode.
@@ -727,12 +737,13 @@ declare class Cacheable extends Hookified {
      * 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 {GetOrSetKey} key - The key to retrieve or set in the cache. This can also be a function that returns a string key.
+     * If a function is provided, it will be called with the cache options to generate the key.
      * @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.
+     * @param {GetOrSetFunctionOptions} [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.
      */
-    getOrSet<T>(key: string, function_: () => Promise<T>, options?: GetOrSetFunctionOptions): Promise<T | undefined>;
+    getOrSet<T>(key: GetOrSetKey, function_: () => Promise<T>, options?: GetOrSetFunctionOptions): Promise<T | undefined>;
     /**
      * Will hash an object using the specified algorithm. The default algorithm is 'sha256'.
      * @param {any} object the object to hash
@@ -748,4 +759,4 @@ declare class Cacheable extends Hookified {
     private setTtl;
 }
 
-export { Cacheable, CacheableEvents, CacheableHooks, type CacheableItem, CacheableMemory, type CacheableMemoryOptions, type CacheableOptions, CacheableStats, KeyvCacheableMemory, type WrapOptions, type WrapSyncOptions, createKeyv, shorthandToMilliseconds, shorthandToTime, wrap, wrapSync };
+export { Cacheable, CacheableEvents, CacheableHooks, type CacheableItem, CacheableMemory, type CacheableMemoryOptions, type CacheableOptions, CacheableStats, type GetOrSetFunctionOptions, type GetOrSetKey, type GetOrSetOptions, KeyvCacheableMemory, type WrapOptions, type WrapSyncOptions, createKeyv, getOrSet, shorthandToMilliseconds, shorthandToTime, wrap, wrapSync };

package/dist/index.js

@@ -15,9 +15,7 @@ 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);
@@ -61,7 +59,7 @@ var shorthandToMilliseconds = (shorthand) => {
   return milliseconds;
 };
 var shorthandToTime = (shorthand, fromDate) => {
-  fromDate ||= /* @__PURE__ */ new Date();
+  fromDate ??= /* @__PURE__ */ new Date();
   const milliseconds = shorthandToMilliseconds(shorthand);
   if (milliseconds === void 0) {
     return fromDate.getTime();
@@ -168,7 +166,10 @@ async function coalesceAsync(key, fnc) {
 function wrapSync(function_, options) {
   const { ttl, keyPrefix, cache } = options;
   return function(...arguments_) {
-    const cacheKey = createWrapKey(function_, arguments_, keyPrefix);
+    let cacheKey = createWrapKey(function_, arguments_, keyPrefix);
+    if (options.createKey) {
+      cacheKey = options.createKey(function_, arguments_, options);
+    }
     let value = cache.get(cacheKey);
     if (value === void 0) {
       try {
@@ -185,19 +186,23 @@ function wrapSync(function_, options) {
   };
 }
 async function getOrSet(key, function_, options) {
-  let value = await options.cache.get(key);
+  const keyString = typeof key === "function" ? key(options) : key;
+  let value = await options.cache.get(keyString);
   if (value === void 0) {
     const cacheId = options.cacheId ?? "default";
-    const coalesceKey = `${cacheId}::${key}`;
+    const coalesceKey = `${cacheId}::${keyString}`;
     value = await coalesceAsync(coalesceKey, async () => {
       try {
         const result = await function_();
-        await options.cache.set(key, result, options.ttl);
+        await options.cache.set(keyString, result, options.ttl);
         return result;
       } catch (error) {
         options.cache.emit("error", error);
         if (options.cacheErrors) {
-          await options.cache.set(key, error, options.ttl);
+          await options.cache.set(keyString, error, options.ttl);
+        }
+        if (options.throwErrors) {
+          throw error;
         }
       }
     });
@@ -207,7 +212,10 @@ async function getOrSet(key, function_, options) {
 function wrap(function_, options) {
   const { keyPrefix, cache } = options;
   return async function(...arguments_) {
-    const cacheKey = createWrapKey(function_, arguments_, keyPrefix);
+    let cacheKey = createWrapKey(function_, arguments_, keyPrefix);
+    if (options.createKey) {
+      cacheKey = options.createKey(function_, arguments_, options);
+    }
     return cache.getOrSet(cacheKey, async () => function_(...arguments_), options);
   };
 }
@@ -265,7 +273,7 @@ var DoublyLinkedList = class {
       this.head.prev = node;
     }
     this.head = node;
-    this.tail ||= node;
+    this.tail ??= node;
   }
   // Get the oldest node (tail)
   getOldest() {
@@ -1376,7 +1384,11 @@ var Cacheable = class extends Hookified2 {
    * @returns {void}
    */
   setPrimary(primary) {
-    this._primary = primary instanceof Keyv2 ? primary : new Keyv2(primary);
+    if (this.isKeyvInstance(primary)) {
+      this._primary = primary;
+    } else {
+      this._primary = new Keyv2(primary);
+    }
     this._primary.on("error", (error) => {
       this.emit("error" /* ERROR */, error);
     });
@@ -1387,11 +1399,22 @@ var Cacheable = class extends Hookified2 {
    * @returns {void}
    */
   setSecondary(secondary) {
-    this._secondary = secondary instanceof Keyv2 ? secondary : new Keyv2(secondary);
+    if (this.isKeyvInstance(secondary)) {
+      this._secondary = secondary;
+    } else {
+      this._secondary = new Keyv2(secondary);
+    }
     this._secondary.on("error", (error) => {
       this.emit("error" /* ERROR */, error);
     });
   }
+  isKeyvInstance(keyv) {
+    if (keyv instanceof Keyv2) {
+      return true;
+    }
+    const keyvMethods = ["generateIterator", "get", "getMany", "set", "setMany", "delete", "deleteMany", "has", "hasMany", "clear", "disconnect", "serialize", "deserialize"];
+    return keyvMethods.every((method) => typeof keyv[method] === "function");
+  }
   getNameSpace() {
     if (typeof this._namespace === "function") {
       return this._namespace();
@@ -1449,7 +1472,10 @@ var Cacheable = class extends Hookified2 {
           if (!result[i] && secondaryResults[i]) {
             result[i] = secondaryResults[i];
             const cascadeTtl = getCascadingTtl(this._ttl, this._primary.ttl);
-            const expires = secondaryResults[i].expires;
+            let { expires } = secondaryResults[i];
+            if (expires === null) {
+              expires = void 0;
+            }
             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);
@@ -1705,9 +1731,10 @@ var Cacheable = class extends Hookified2 {
    * 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 {GetOrSetKey} key - The key to retrieve or set in the cache. This can also be a function that returns a string key.
+   * If a function is provided, it will be called with the cache options to generate the key.
    * @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.
+   * @param {GetOrSetFunctionOptions} [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) {
@@ -1715,7 +1742,8 @@ var Cacheable = class extends Hookified2 {
       cache: this,
       cacheId: this._cacheId,
       ttl: options?.ttl ?? this._ttl,
-      cacheErrors: options?.cacheErrors
+      cacheErrors: options?.cacheErrors,
+      throwErrors: options?.throwErrors
     };
     return getOrSet(key, function_, getOrSetOptions);
   }
@@ -1786,6 +1814,7 @@ export {
   KeyvCacheableMemory,
   KeyvHooks,
   createKeyv,
+  getOrSet,
   shorthandToMilliseconds,
   shorthandToTime,
   wrap,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cacheable",
-  "version": "1.10.0",
+  "version": "1.10.2",
   "description": "High Performance Layer 1 / Layer 2 Caching with Keyv Storage",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -21,20 +21,22 @@
   "license": "MIT",
   "private": false,
   "devDependencies": {
-    "@faker-js/faker": "^9.7.0",
-    "@keyv/redis": "^4.4.0",
-    "@types/node": "^22.15.3",
-    "@vitest/coverage-v8": "^3.1.3",
+    "@faker-js/faker": "^9.8.0",
+    "@keyv/redis": "^4.5.0",
+    "@keyv/valkey": "^1.0.6",
+    "@types/eslint": "^9.6.1",
+    "@types/node": "^24.0.7",
+    "@vitest/coverage-v8": "^3.2.4",
     "lru-cache": "^11.1.0",
     "rimraf": "^6.0.1",
-    "tsup": "^8.4.0",
+    "tsup": "^8.5.0",
     "typescript": "^5.8.3",
-    "vitest": "^3.1.3",
-    "xo": "^0.60.0"
+    "vitest": "^3.2.4",
+    "xo": "^1.1.1"
   },
   "dependencies": {
-    "hookified": "^1.8.2",
-    "keyv": "^5.3.3"
+    "hookified": "^1.10.0",
+    "keyv": "^5.3.4"
   },
   "keywords": [
     "cacheable",
@@ -70,7 +72,7 @@
     "build": "rimraf ./dist && tsup src/index.ts --format cjs,esm --dts --clean",
     "prepublish": "pnpm build",
     "test": "xo --fix && vitest run --coverage",
-    "test:ci": "xo && vitest run",
+    "test:ci": "xo && vitest run --coverage",
     "clean": "rimraf ./dist ./coverage ./node_modules"
   }
 }