cacheable 1.7.1 → 1.8.0

package/README.md

@@ -36,6 +36,7 @@
 * [Cacheable Statistics (Instance Only)](#cacheable-statistics-instance-only)
 * [API](#api)
 * [CacheableMemory - In-Memory Cache](#cacheablememory---in-memory-cache)
+* [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)
 
@@ -218,12 +219,13 @@ _This does not enable statistics for your layer 2 cache as that is a distributed
 * `delete(key)`: Deletes a value from the cache.
 * `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, options)`: Wraps a function in a cache. (coming soon)
+* `wrap(function, WrapOptions)`: Wraps an `async` function in a cache.
 * `disconnect()`: Disconnects from the cache stores.
 * `onHook(hook, callback)`: Sets a hook.
 * `removeHook(hook)`: Removes a hook.
 * `on(event, callback)`: Listens for an event.
 * `removeListener(event, callback)`: Removes a listener.
+* `hash(object: any, algorithm = 'sha256'): string`: Hashes an object with the algorithm. Default is `sha256`.
 * `primary`: The primary store for the cache (layer 1) defaults to in-memory by Keyv.
 * `secondary`: The secondary store for the cache (layer 2) usually a persistent cache by Keyv.
 * `nonBlocking`: If the secondary store is non-blocking. Default is `false`.
@@ -271,6 +273,7 @@ By default we use lazy expiration deletion which means on `get` and `getMany` ty
 * `deleteMany([keys])`: Deletes multiple values from the cache.
 * `take(key)`: Takes a value from the cache and deletes it.
 * `takeMany([keys])`: Takes multiple values from the cache and deletes them.
+* `wrap(function, WrapSyncOptions)`: Wraps a `sync` function in a cache.
 * `clear()`: Clears the cache.
 * `size()`: The number of keys in the cache.
 * `keys()`: The keys in the cache.
@@ -278,7 +281,35 @@ By default we use lazy expiration deletion which means on `get` and `getMany` ty
 * `checkExpired()`: Checks for expired keys in the cache. This is used by the `checkInterval` property.
 * `startIntervalCheck()`: Starts the interval check for expired keys if `checkInterval` is above 0 ms.
 * `stopIntervalCheck()`: Stops the interval check for expired keys.
+* `hash(object: any, algorithm = 'sha256'): string`: Hashes an object with the algorithm. Default is `sha256`.
 
+## 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:
+
+```javascript
+import { Cacheable } from 'cacheable';
+const asyncFunction = async (value: number) => {
+  return value * 2;
+};
+
+const cache = new Cacheable();
+const wrappedFunction = cache.wrap(asyncFunction, { ttl: '1h' });
+```
+
+In this example we are wrapping an `async` function in a cache with a `ttl` of `1 hour`. This will cache the result of the function for `1 hour` and then expire the value. You can also wrap a `sync` function in a cache:
+
+```javascript
+import { CacheableMemory } from 'cacheable';
+const syncFunction = (value: number) => {
+  return value * 2;
+};
+
+const cache = new CacheableMemory();
+const wrappedFunction = cache.wrap(syncFunction, { ttl: '1h' });
+```
+
+In this example we are wrapping a `sync` function in a cache with a `ttl` of `1 hour`. This will cache the result of the function for `1 hour` and then expire the value.
 
 ## How to Contribute
 

package/dist/index.cjs

@@ -1,7 +1,9 @@
 "use strict";
+var __create = Object.create;
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
 var __export = (target, all) => {
   for (var name in all)
@@ -15,6 +17,14 @@ var __copyProps = (to, from, except, desc) => {
   }
   return to;
 };
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
 // src/index.ts
@@ -25,9 +35,13 @@ __export(src_exports, {
   CacheableHooks: () => CacheableHooks,
   CacheableMemory: () => CacheableMemory,
   CacheableStats: () => CacheableStats,
+  Keyv: () => import_keyv2.Keyv,
   KeyvCacheableMemory: () => KeyvCacheableMemory,
+  KeyvHooks: () => import_keyv2.KeyvHooks,
   shorthandToMilliseconds: () => shorthandToMilliseconds,
-  shorthandToTime: () => shorthandToTime
+  shorthandToTime: () => shorthandToTime,
+  wrap: () => wrap,
+  wrapSync: () => wrapSync
 });
 module.exports = __toCommonJS(src_exports);
 var import_keyv = require("keyv");
@@ -100,6 +114,32 @@ var shorthandToTime = (shorthand, fromDate) => {
   return fromDate.getTime() + milliseconds;
 };
 
+// src/wrap.ts
+function wrapSync(function_, options) {
+  const { ttl, key, cache } = options;
+  return function(...arguments_) {
+    const cacheKey = key ?? cache.hash(arguments_);
+    let value = cache.get(cacheKey);
+    if (value === void 0) {
+      value = function_(...arguments_);
+      cache.set(cacheKey, value, ttl);
+    }
+    return value;
+  };
+}
+function wrap(function_, options) {
+  const { ttl, key, cache } = options;
+  return async function(...arguments_) {
+    const cacheKey = key ?? cache.hash(arguments_);
+    let value = await cache.get(cacheKey);
+    if (value === void 0) {
+      value = await function_(...arguments_);
+      await cache.set(cacheKey, value, ttl);
+    }
+    return value;
+  };
+}
+
 // src/memory-lru.ts
 var ListNode = class {
   // eslint-disable-next-line @typescript-eslint/parameter-properties
@@ -173,6 +213,18 @@ var DoublyLinkedList = class {
   }
 };
 
+// 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");
+}
+
 // src/memory.ts
 var CacheableMemory = class {
   _hashCache = /* @__PURE__ */ new Map();
@@ -370,12 +422,12 @@ var CacheableMemory = class {
     if (cacheHashNumber) {
       return cacheHashNumber;
     }
-    let hash = 0;
+    let hash2 = 0;
     const primeMultiplier = 31;
     for (let i = 0; i < key.length; i++) {
-      hash = hash * primeMultiplier + key.charCodeAt(i);
+      hash2 = hash2 * primeMultiplier + key.charCodeAt(i);
     }
-    const result = Math.abs(hash) % 10;
+    const result = Math.abs(hash2) % 10;
     this._hashCache.set(key, result);
     return result;
   }
@@ -466,6 +518,17 @@ var CacheableMemory = class {
     this._interval = 0;
     this._checkInterval = 0;
   }
+  hash(object, algorithm = "sha256") {
+    return hash(object, algorithm);
+  }
+  wrap(function_, options = {}) {
+    const wrapOptions = {
+      ttl: options.ttl,
+      key: options.key,
+      cache: this
+    };
+    return wrapSync(function_, wrapOptions);
+  }
   isPrimitive(value) {
     const result = false;
     if (value === null || value === void 0) {
@@ -719,6 +782,7 @@ var CacheableStats = class {
 };
 
 // src/index.ts
+var import_keyv2 = require("keyv");
 var CacheableHooks = /* @__PURE__ */ ((CacheableHooks2) => {
   CacheableHooks2["BEFORE_SET"] = "BEFORE_SET";
   CacheableHooks2["AFTER_SET"] = "AFTER_SET";
@@ -1014,6 +1078,17 @@ var Cacheable = class extends import_hookified.Hookified {
     }
     await (this._nonBlocking ? Promise.race(promises) : Promise.all(promises));
   }
+  wrap(function_, options = {}) {
+    const wrapOptions = {
+      ttl: options.ttl,
+      key: options.key,
+      cache: this
+    };
+    return wrap(function_, wrapOptions);
+  }
+  hash(object, algorithm = "sha256") {
+    return hash(object, algorithm);
+  }
   async deleteManyKeyv(keyv, keys) {
     const promises = [];
     for (const key of keys) {
@@ -1055,7 +1130,11 @@ var Cacheable = class extends import_hookified.Hookified {
   CacheableHooks,
   CacheableMemory,
   CacheableStats,
+  Keyv,
   KeyvCacheableMemory,
+  KeyvHooks,
   shorthandToMilliseconds,
-  shorthandToTime
+  shorthandToTime,
+  wrap,
+  wrapSync
 });

package/dist/index.d.cts

@@ -1,4 +1,5 @@
 import { KeyvStoreAdapter, StoredData, Keyv } from 'keyv';
+export { Keyv, KeyvHooks, KeyvOptions, KeyvStoreAdapter } from 'keyv';
 import { Hookified } from 'hookified';
 
 type CacheableOptions$1 = {
@@ -93,8 +94,8 @@ declare class CacheableMemory {
     get size(): number;
     get keys(): IterableIterator<string>;
     get items(): IterableIterator<CacheableStoreItem>;
-    get<T>(key: string): any;
-    getMany<T>(keys: string[]): any[];
+    get<T>(key: string): T | undefined;
+    getMany<T>(keys: string[]): T[];
     getRaw(key: string): CacheableStoreItem | undefined;
     getManyRaw(keys: string[]): Array<CacheableStoreItem | undefined>;
     set(key: string, value: any, ttl?: number | string): void;
@@ -114,6 +115,11 @@ declare class CacheableMemory {
     checkExpiration(): void;
     startIntervalCheck(): void;
     stopIntervalCheck(): void;
+    hash(object: any, algorithm?: string): string;
+    wrap<T>(function_: (...arguments_: any[]) => T, options?: {
+        ttl?: number;
+        key?: string;
+    }): (...arguments_: any[]) => T;
     private isPrimitive;
     private concatStores;
     private setTtl;
@@ -142,6 +148,20 @@ declare class KeyvCacheableMemory implements KeyvStoreAdapter {
 declare const shorthandToMilliseconds: (shorthand?: string | number) => number | undefined;
 declare const shorthandToTime: (shorthand?: string | number, fromDate?: Date) => number;
 
+type WrapOptions = {
+    ttl?: number | string;
+    key?: string;
+    cache: Cacheable;
+};
+type WrapSyncOptions = {
+    ttl?: number | string;
+    key?: string;
+    cache: CacheableMemory;
+};
+type AnyFunction = (...arguments_: any[]) => any;
+declare function wrapSync<T>(function_: AnyFunction, options: WrapSyncOptions): AnyFunction;
+declare function wrap<T>(function_: AnyFunction, options: WrapOptions): AnyFunction;
+
 declare enum CacheableHooks {
     BEFORE_SET = "BEFORE_SET",
     AFTER_SET = "AFTER_SET",
@@ -182,7 +202,7 @@ declare class Cacheable extends Hookified {
     setSecondary(secondary: Keyv | KeyvStoreAdapter): void;
     get<T>(key: string): Promise<T | undefined>;
     getMany<T>(keys: string[]): Promise<Array<T | undefined>>;
-    set<T>(key: string, value: T, ttl?: number): Promise<boolean>;
+    set<T>(key: string, value: T, ttl?: number | string): Promise<boolean>;
     setMany(items: CacheableItem[]): Promise<boolean>;
     take<T>(key: string): Promise<T | undefined>;
     takeMany<T>(keys: string[]): Promise<Array<T | undefined>>;
@@ -192,10 +212,15 @@ declare class Cacheable extends Hookified {
     deleteMany(keys: string[]): Promise<boolean>;
     clear(): Promise<void>;
     disconnect(): Promise<void>;
+    wrap<T>(function_: (...arguments_: any[]) => T, options?: {
+        ttl?: number;
+        key?: string;
+    }): (...arguments_: any[]) => T;
+    hash(object: any, algorithm?: string): string;
     private deleteManyKeyv;
     private setManyKeyv;
     private hasManyKeyv;
     private setTtl;
 }
 
-export { Cacheable, CacheableEvents, CacheableHooks, type CacheableItem, CacheableMemory, type CacheableOptions, CacheableStats, KeyvCacheableMemory, shorthandToMilliseconds, shorthandToTime };
+export { Cacheable, CacheableEvents, CacheableHooks, type CacheableItem, CacheableMemory, type CacheableOptions, CacheableStats, KeyvCacheableMemory, type WrapOptions, type WrapSyncOptions, shorthandToMilliseconds, shorthandToTime, wrap, wrapSync };

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 import { KeyvStoreAdapter, StoredData, Keyv } from 'keyv';
+export { Keyv, KeyvHooks, KeyvOptions, KeyvStoreAdapter } from 'keyv';
 import { Hookified } from 'hookified';
 
 type CacheableOptions$1 = {
@@ -93,8 +94,8 @@ declare class CacheableMemory {
     get size(): number;
     get keys(): IterableIterator<string>;
     get items(): IterableIterator<CacheableStoreItem>;
-    get<T>(key: string): any;
-    getMany<T>(keys: string[]): any[];
+    get<T>(key: string): T | undefined;
+    getMany<T>(keys: string[]): T[];
     getRaw(key: string): CacheableStoreItem | undefined;
     getManyRaw(keys: string[]): Array<CacheableStoreItem | undefined>;
     set(key: string, value: any, ttl?: number | string): void;
@@ -114,6 +115,11 @@ declare class CacheableMemory {
     checkExpiration(): void;
     startIntervalCheck(): void;
     stopIntervalCheck(): void;
+    hash(object: any, algorithm?: string): string;
+    wrap<T>(function_: (...arguments_: any[]) => T, options?: {
+        ttl?: number;
+        key?: string;
+    }): (...arguments_: any[]) => T;
     private isPrimitive;
     private concatStores;
     private setTtl;
@@ -142,6 +148,20 @@ declare class KeyvCacheableMemory implements KeyvStoreAdapter {
 declare const shorthandToMilliseconds: (shorthand?: string | number) => number | undefined;
 declare const shorthandToTime: (shorthand?: string | number, fromDate?: Date) => number;
 
+type WrapOptions = {
+    ttl?: number | string;
+    key?: string;
+    cache: Cacheable;
+};
+type WrapSyncOptions = {
+    ttl?: number | string;
+    key?: string;
+    cache: CacheableMemory;
+};
+type AnyFunction = (...arguments_: any[]) => any;
+declare function wrapSync<T>(function_: AnyFunction, options: WrapSyncOptions): AnyFunction;
+declare function wrap<T>(function_: AnyFunction, options: WrapOptions): AnyFunction;
+
 declare enum CacheableHooks {
     BEFORE_SET = "BEFORE_SET",
     AFTER_SET = "AFTER_SET",
@@ -182,7 +202,7 @@ declare class Cacheable extends Hookified {
     setSecondary(secondary: Keyv | KeyvStoreAdapter): void;
     get<T>(key: string): Promise<T | undefined>;
     getMany<T>(keys: string[]): Promise<Array<T | undefined>>;
-    set<T>(key: string, value: T, ttl?: number): Promise<boolean>;
+    set<T>(key: string, value: T, ttl?: number | string): Promise<boolean>;
     setMany(items: CacheableItem[]): Promise<boolean>;
     take<T>(key: string): Promise<T | undefined>;
     takeMany<T>(keys: string[]): Promise<Array<T | undefined>>;
@@ -192,10 +212,15 @@ declare class Cacheable extends Hookified {
     deleteMany(keys: string[]): Promise<boolean>;
     clear(): Promise<void>;
     disconnect(): Promise<void>;
+    wrap<T>(function_: (...arguments_: any[]) => T, options?: {
+        ttl?: number;
+        key?: string;
+    }): (...arguments_: any[]) => T;
+    hash(object: any, algorithm?: string): string;
     private deleteManyKeyv;
     private setManyKeyv;
     private hasManyKeyv;
     private setTtl;
 }
 
-export { Cacheable, CacheableEvents, CacheableHooks, type CacheableItem, CacheableMemory, type CacheableOptions, CacheableStats, KeyvCacheableMemory, shorthandToMilliseconds, shorthandToTime };
+export { Cacheable, CacheableEvents, CacheableHooks, type CacheableItem, CacheableMemory, type CacheableOptions, CacheableStats, KeyvCacheableMemory, type WrapOptions, type WrapSyncOptions, shorthandToMilliseconds, shorthandToTime, wrap, wrapSync };

package/dist/index.js

@@ -69,6 +69,32 @@ var shorthandToTime = (shorthand, fromDate) => {
   return fromDate.getTime() + milliseconds;
 };
 
+// src/wrap.ts
+function wrapSync(function_, options) {
+  const { ttl, key, cache } = options;
+  return function(...arguments_) {
+    const cacheKey = key ?? cache.hash(arguments_);
+    let value = cache.get(cacheKey);
+    if (value === void 0) {
+      value = function_(...arguments_);
+      cache.set(cacheKey, value, ttl);
+    }
+    return value;
+  };
+}
+function wrap(function_, options) {
+  const { ttl, key, cache } = options;
+  return async function(...arguments_) {
+    const cacheKey = key ?? cache.hash(arguments_);
+    let value = await cache.get(cacheKey);
+    if (value === void 0) {
+      value = await function_(...arguments_);
+      await cache.set(cacheKey, value, ttl);
+    }
+    return value;
+  };
+}
+
 // src/memory-lru.ts
 var ListNode = class {
   // eslint-disable-next-line @typescript-eslint/parameter-properties
@@ -142,6 +168,18 @@ var DoublyLinkedList = class {
   }
 };
 
+// src/hash.ts
+import * as crypto from "node:crypto";
+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");
+}
+
 // src/memory.ts
 var CacheableMemory = class {
   _hashCache = /* @__PURE__ */ new Map();
@@ -339,12 +377,12 @@ var CacheableMemory = class {
     if (cacheHashNumber) {
       return cacheHashNumber;
     }
-    let hash = 0;
+    let hash2 = 0;
     const primeMultiplier = 31;
     for (let i = 0; i < key.length; i++) {
-      hash = hash * primeMultiplier + key.charCodeAt(i);
+      hash2 = hash2 * primeMultiplier + key.charCodeAt(i);
     }
-    const result = Math.abs(hash) % 10;
+    const result = Math.abs(hash2) % 10;
     this._hashCache.set(key, result);
     return result;
   }
@@ -435,6 +473,17 @@ var CacheableMemory = class {
     this._interval = 0;
     this._checkInterval = 0;
   }
+  hash(object, algorithm = "sha256") {
+    return hash(object, algorithm);
+  }
+  wrap(function_, options = {}) {
+    const wrapOptions = {
+      ttl: options.ttl,
+      key: options.key,
+      cache: this
+    };
+    return wrapSync(function_, wrapOptions);
+  }
   isPrimitive(value) {
     const result = false;
     if (value === null || value === void 0) {
@@ -688,6 +737,10 @@ var CacheableStats = class {
 };
 
 // src/index.ts
+import {
+  KeyvHooks,
+  Keyv as Keyv2
+} from "keyv";
 var CacheableHooks = /* @__PURE__ */ ((CacheableHooks2) => {
   CacheableHooks2["BEFORE_SET"] = "BEFORE_SET";
   CacheableHooks2["AFTER_SET"] = "AFTER_SET";
@@ -983,6 +1036,17 @@ var Cacheable = class extends Hookified {
     }
     await (this._nonBlocking ? Promise.race(promises) : Promise.all(promises));
   }
+  wrap(function_, options = {}) {
+    const wrapOptions = {
+      ttl: options.ttl,
+      key: options.key,
+      cache: this
+    };
+    return wrap(function_, wrapOptions);
+  }
+  hash(object, algorithm = "sha256") {
+    return hash(object, algorithm);
+  }
   async deleteManyKeyv(keyv, keys) {
     const promises = [];
     for (const key of keys) {
@@ -1023,7 +1087,11 @@ export {
   CacheableHooks,
   CacheableMemory,
   CacheableStats,
+  Keyv2 as Keyv,
   KeyvCacheableMemory,
+  KeyvHooks,
   shorthandToMilliseconds,
-  shorthandToTime
+  shorthandToTime,
+  wrap,
+  wrapSync
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cacheable",
-  "version": "1.7.1",
+  "version": "1.8.0",
   "description": "Simple Caching Engine using Keyv",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -18,7 +18,7 @@
   "private": false,
   "devDependencies": {
     "@keyv/redis": "^3.0.1",
-    "@types/node": "^22.6.1",
+    "@types/node": "^22.7.4",
     "@vitest/coverage-v8": "^2.1.1",
     "lru-cache": "^11.0.1",
     "rimraf": "^6.0.1",