@cacheable/utils - npm Package Compare versions

Comparing version 2.1.0 to 2.2.0

dist/index.cjs

@@ -1,1 +0,637 @@
-"use strict";var N=Object.create;var l=Object.defineProperty;var A=Object.getOwnPropertyDescriptor;var H=Object.getOwnPropertyNames;var j=Object.getPrototypeOf,E=Object.prototype.hasOwnProperty;var M=(t,e)=>{for(var r in e)l(t,r,{get:e[r],enumerable:!0})},p=(t,e,r,i)=>{if(e&&typeof e=="object"||typeof e=="function")for(let n of H(e))!E.call(t,n)&&n!==r&&l(t,n,{get:()=>e[n],enumerable:!(i=A(e,n))||i.enumerable});return t};var F=(t,e,r)=>(r=t!=null?N(j(t)):{},p(e||!t||!t.__esModule?l(r,"default",{value:t,enumerable:!0}):r,t)),K=t=>p(l({},"__esModule",{value:!0}),t);var U={};M(U,{HashAlgorithm:()=>b,Stats:()=>m,calculateTtlFromExpiration:()=>C,coalesceAsync:()=>T,getCascadingTtl:()=>P,getTtlFromExpires:()=>d,hash:()=>f,hashToNumber:()=>v,isKeyvInstance:()=>z,isObject:()=>S,lessThan:()=>k,runIfFn:()=>w,shorthandToMilliseconds:()=>u,shorthandToTime:()=>g,sleep:()=>O});module.exports=K(U);var u=t=>{let e;if(t!==void 0){if(typeof t=="number")e=t;else if(typeof t=="string")if(t=t.trim(),Number.isNaN(Number(t))){let r=/^([\d.]+)\s*(ms|s|m|h|hr|d)$/i.exec(t);if(!r)throw new Error(`Unsupported time format: "${t}". Use 'ms', 's', 'm', 'h', 'hr', or 'd'.`);let[,i,n]=r,s=Number.parseFloat(i);switch(n.toLowerCase()){case"ms":{e=s;break}case"s":{e=s*1e3;break}case"m":{e=s*1e3*60;break}case"h":{e=s*1e3*60*60;break}case"hr":{e=s*1e3*60*60;break}case"d":{e=s*1e3*60*60*24;break}default:e=Number(t)}}else e=Number(t);else throw new TypeError("Time must be a string or a number.");return e}},g=(t,e)=>{e??=new Date;let r=u(t);return r===void 0?e.getTime():e.getTime()+r};var a=new Map;function I(t){return a.has(t)}function D(t){a.set(t,[])}function J(t){a.delete(t)}function L(t,e){let r=y(t);r.push(e),a.set(t,r)}function y(t){return a.get(t)??[]}async function $(t){return new Promise((e,r)=>{L(t,{resolve:e,reject:r})})}function V(t){let e=y(t);return J(t),e}function _(t){let{key:e,error:r,result:i}=t;for(let n of V(e))r?n.reject(r):n.resolve(i)}async function T(t,e){if(!I(t)){D(t);try{let r=await Promise.resolve(e());return _({key:t,result:r}),r}catch(r){throw _({key:t,error:r}),r}}return $(t)}var c=F(require("crypto"),1),b=(n=>(n.SHA256="sha256",n.SHA512="sha512",n.MD5="md5",n.DJB2="djb2",n))(b||{});function f(t,e={algorithm:"sha256",serialize:JSON.stringify}){e?.algorithm||(e.algorithm="sha256"),e?.serialize||(e.serialize=JSON.stringify);let r=e.serialize(t);if(e?.algorithm==="djb2")return B(r);if(!c.getHashes().includes(e.algorithm))throw new Error(`Unsupported hash algorithm: '${e?.algorithm}'`);let i=c.createHash(e.algorithm);return i.update(r),i.digest("hex")}function v(t,e={min:0,max:10,algorithm:"sha256",serialize:JSON.stringify}){let r=e?.min??0,i=e?.max??10;if(r>=i)throw new Error(`Invalid range: min (${r}) must be less than max (${i})`);e?.algorithm||(e.algorithm="sha256"),e?.serialize||(e.serialize=JSON.stringify);let n=f(t,e),s=Number.parseInt(n,16),o=i-r+1,h=r+s%o;return h<r?r:h>i?i:h}function B(t){let e=5381;for(let r=0;r<t.length;r++)e=e*33^t.charCodeAt(r);return e.toString()}var x=require("keyv");function z(t){return t==null?!1:t instanceof x.Keyv?!0:["generateIterator","get","getMany","set","setMany","delete","deleteMany","has","hasMany","clear","disconnect","serialize","deserialize"].every(r=>typeof t[r]=="function")}function S(t){return t!==null&&typeof t=="object"&&!Array.isArray(t)}function k(t,e){return typeof t=="number"&&typeof e=="number"?t<e:!1}function w(t,...e){return typeof t=="function"?t(...e):t}var O=async t=>new Promise(e=>setTimeout(e,t));var m=class{_hits=0;_misses=0;_gets=0;_sets=0;_deletes=0;_clears=0;_vsize=0;_ksize=0;_count=0;_enabled=!1;constructor(e){e?.enabled&&(this._enabled=e.enabled)}get enabled(){return this._enabled}set enabled(e){this._enabled=e}get hits(){return this._hits}get misses(){return this._misses}get gets(){return this._gets}get sets(){return this._sets}get deletes(){return this._deletes}get clears(){return this._clears}get vsize(){return this._vsize}get ksize(){return this._ksize}get count(){return this._count}incrementHits(){this._enabled&&this._hits++}incrementMisses(){this._enabled&&this._misses++}incrementGets(){this._enabled&&this._gets++}incrementSets(){this._enabled&&this._sets++}incrementDeletes(){this._enabled&&this._deletes++}incrementClears(){this._enabled&&this._clears++}incrementVSize(e){this._enabled&&(this._vsize+=this.roughSizeOfObject(e))}decreaseVSize(e){this._enabled&&(this._vsize-=this.roughSizeOfObject(e))}incrementKSize(e){this._enabled&&(this._ksize+=this.roughSizeOfString(e))}decreaseKSize(e){this._enabled&&(this._ksize-=this.roughSizeOfString(e))}incrementCount(){this._enabled&&this._count++}decreaseCount(){this._enabled&&this._count--}setCount(e){this._enabled&&(this._count=e)}roughSizeOfString(e){return e.length*2}roughSizeOfObject(e){let r=[],i=[e],n=0;for(;i.length>0;){let s=i.pop();if(typeof s=="boolean")n+=4;else if(typeof s=="string")n+=s.length*2;else if(typeof s=="number")n+=8;else if(typeof s=="object"&&s!==null&&!r.includes(s)){r.push(s);for(let o in s)n+=o.length*2,i.push(s[o])}}return n}reset(){this._hits=0,this._misses=0,this._gets=0,this._sets=0,this._deletes=0,this._clears=0,this._vsize=0,this._ksize=0,this._count=0}resetStoreValues(){this._vsize=0,this._ksize=0,this._count=0}};function d(t){if(t==null)return;let e=Date.now();if(!(t<e))return t-e}function P(t,e,r){return r??e??u(t)}function C(t,e){let r=d(e),i=t?Date.now()+t:void 0;return r===void 0?t:i===void 0?r:e&&e>i?t:r}0&&(module.exports={HashAlgorithm,Stats,calculateTtlFromExpiration,coalesceAsync,getCascadingTtl,getTtlFromExpires,hash,hashToNumber,isKeyvInstance,isObject,lessThan,runIfFn,shorthandToMilliseconds,shorthandToTime,sleep});
+"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)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  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
+var index_exports = {};
+__export(index_exports, {
+  HashAlgorithm: () => HashAlgorithm,
+  Stats: () => Stats,
+  calculateTtlFromExpiration: () => calculateTtlFromExpiration,
+  coalesceAsync: () => coalesceAsync,
+  createWrapKey: () => createWrapKey,
+  getCascadingTtl: () => getCascadingTtl,
+  getOrSet: () => getOrSet,
+  getTtlFromExpires: () => getTtlFromExpires,
+  hash: () => hash,
+  hashToNumber: () => hashToNumber,
+  isKeyvInstance: () => isKeyvInstance,
+  isObject: () => isObject,
+  lessThan: () => lessThan,
+  runIfFn: () => runIfFn,
+  shorthandToMilliseconds: () => shorthandToMilliseconds,
+  shorthandToTime: () => shorthandToTime,
+  sleep: () => sleep,
+  wrap: () => wrap,
+  wrapSync: () => wrapSync
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/shorthand-time.ts
+var shorthandToMilliseconds = (shorthand) => {
+  let milliseconds;
+  if (shorthand === void 0) {
+    return void 0;
+  }
+  if (typeof shorthand === "number") {
+    milliseconds = shorthand;
+  } else {
+    if (typeof shorthand !== "string") {
+      return void 0;
+    }
+    shorthand = shorthand.trim();
+    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'.`
+        );
+      }
+      const [, value, unit] = match;
+      const numericValue = Number.parseFloat(value);
+      const unitLower = unit.toLowerCase();
+      switch (unitLower) {
+        case "ms": {
+          milliseconds = numericValue;
+          break;
+        }
+        case "s": {
+          milliseconds = numericValue * 1e3;
+          break;
+        }
+        case "m": {
+          milliseconds = numericValue * 1e3 * 60;
+          break;
+        }
+        case "h": {
+          milliseconds = numericValue * 1e3 * 60 * 60;
+          break;
+        }
+        case "hr": {
+          milliseconds = numericValue * 1e3 * 60 * 60;
+          break;
+        }
+        case "d": {
+          milliseconds = numericValue * 1e3 * 60 * 60 * 24;
+          break;
+        }
+        /* v8 ignore next -- @preserve */
+        default: {
+          milliseconds = Number(shorthand);
+        }
+      }
+    } else {
+      milliseconds = Number(shorthand);
+    }
+  }
+  return milliseconds;
+};
+var shorthandToTime = (shorthand, fromDate) => {
+  fromDate ??= /* @__PURE__ */ new Date();
+  const milliseconds = shorthandToMilliseconds(shorthand);
+  if (milliseconds === void 0) {
+    return fromDate.getTime();
+  }
+  return fromDate.getTime() + milliseconds;
+};
+
+// src/coalesce-async.ts
+var callbacks = /* @__PURE__ */ new Map();
+function hasKey(key) {
+  return callbacks.has(key);
+}
+function addKey(key) {
+  callbacks.set(key, []);
+}
+function removeKey(key) {
+  callbacks.delete(key);
+}
+function addCallbackToKey(key, callback) {
+  const stash = getCallbacksByKey(key);
+  stash.push(callback);
+  callbacks.set(key, stash);
+}
+function getCallbacksByKey(key) {
+  return callbacks.get(key) ?? [];
+}
+async function enqueue(key) {
+  return new Promise((resolve, reject) => {
+    const callback = { resolve, reject };
+    addCallbackToKey(key, callback);
+  });
+}
+function dequeue(key) {
+  const stash = getCallbacksByKey(key);
+  removeKey(key);
+  return stash;
+}
+function coalesce(options) {
+  const { key, error, result } = options;
+  for (const callback of dequeue(key)) {
+    if (error) {
+      callback.reject(error);
+    } else {
+      callback.resolve(result);
+    }
+  }
+}
+async function coalesceAsync(key, fnc) {
+  if (!hasKey(key)) {
+    addKey(key);
+    try {
+      const result = await Promise.resolve(fnc());
+      coalesce({ key, result });
+      return result;
+    } catch (error) {
+      coalesce({ key, error });
+      throw error;
+    }
+  }
+  return enqueue(key);
+}
+
+// src/hash.ts
+var crypto = __toESM(require("crypto"), 1);
+var HashAlgorithm = /* @__PURE__ */ ((HashAlgorithm2) => {
+  HashAlgorithm2["SHA256"] = "sha256";
+  HashAlgorithm2["SHA512"] = "sha512";
+  HashAlgorithm2["MD5"] = "md5";
+  HashAlgorithm2["DJB2"] = "djb2";
+  return HashAlgorithm2;
+})(HashAlgorithm || {});
+function hash(object, options = {
+  algorithm: "sha256" /* SHA256 */,
+  serialize: JSON.stringify
+}) {
+  if (!options?.algorithm) {
+    options.algorithm = "sha256" /* SHA256 */;
+  }
+  if (!options?.serialize) {
+    options.serialize = JSON.stringify;
+  }
+  const objectString = options.serialize(object);
+  if (options?.algorithm === "djb2" /* DJB2 */) {
+    return djb2Hash(objectString);
+  }
+  if (!crypto.getHashes().includes(options.algorithm)) {
+    throw new Error(`Unsupported hash algorithm: '${options?.algorithm}'`);
+  }
+  const hasher = crypto.createHash(options.algorithm);
+  hasher.update(objectString);
+  return hasher.digest("hex");
+}
+function hashToNumber(object, options = {
+  min: 0,
+  max: 10,
+  algorithm: "sha256" /* SHA256 */,
+  serialize: JSON.stringify
+}) {
+  const min = options?.min ?? 0;
+  const max = options?.max ?? 10;
+  if (min >= max) {
+    throw new Error(
+      `Invalid range: min (${min}) must be less than max (${max})`
+    );
+  }
+  if (!options?.algorithm) {
+    options.algorithm = "sha256" /* SHA256 */;
+  }
+  if (!options?.serialize) {
+    options.serialize = JSON.stringify;
+  }
+  const hashResult = hash(object, options);
+  const hashNumber = Number.parseInt(hashResult, 16);
+  const range = max - min + 1;
+  const result = min + hashNumber % range;
+  if (result < min) {
+    return min;
+  }
+  if (result > max) {
+    return max;
+  }
+  return result;
+}
+function djb2Hash(string_) {
+  let hash2 = 5381;
+  for (let i = 0; i < string_.length; i++) {
+    hash2 = hash2 * 33 ^ string_.charCodeAt(i);
+  }
+  return hash2.toString();
+}
+
+// src/is-keyv-instance.ts
+var import_keyv = require("keyv");
+function isKeyvInstance(keyv) {
+  if (keyv === null || keyv === void 0) {
+    return false;
+  }
+  if (keyv instanceof import_keyv.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");
+}
+
+// src/is-object.ts
+function isObject(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+// src/less-than.ts
+function lessThan(number1, number2) {
+  return typeof number1 === "number" && typeof number2 === "number" ? number1 < number2 : false;
+}
+
+// src/memoize.ts
+function wrapSync(function_, options) {
+  const { ttl, keyPrefix, cache, serialize } = options;
+  return (...arguments_) => {
+    let cacheKey = createWrapKey(function_, arguments_, {
+      keyPrefix,
+      serialize
+    });
+    if (options.createKey) {
+      cacheKey = options.createKey(function_, arguments_, options);
+    }
+    let value = cache.get(cacheKey);
+    if (value === void 0) {
+      try {
+        value = function_(...arguments_);
+        cache.set(cacheKey, value, ttl);
+      } catch (error) {
+        cache.emit("error", error);
+        if (options.cacheErrors) {
+          cache.set(cacheKey, error, ttl);
+        }
+      }
+    }
+    return value;
+  };
+}
+async function getOrSet(key, function_, options) {
+  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}::${keyString}`;
+    value = await coalesceAsync(coalesceKey, async () => {
+      try {
+        const result = await function_();
+        await options.cache.set(keyString, result, options.ttl);
+        return result;
+      } catch (error) {
+        options.cache.emit("error", error);
+        if (options.cacheErrors) {
+          await options.cache.set(keyString, error, options.ttl);
+        }
+        if (options.throwErrors) {
+          throw error;
+        }
+      }
+    });
+  }
+  return value;
+}
+function wrap(function_, options) {
+  const { keyPrefix, serialize } = options;
+  return async (...arguments_) => {
+    let cacheKey = createWrapKey(function_, arguments_, {
+      keyPrefix,
+      serialize
+    });
+    if (options.createKey) {
+      cacheKey = options.createKey(function_, arguments_, options);
+    }
+    return getOrSet(
+      cacheKey,
+      async () => function_(...arguments_),
+      options
+    );
+  };
+}
+function createWrapKey(function_, arguments_, options) {
+  const { keyPrefix, serialize } = options || {};
+  if (!keyPrefix) {
+    return `${function_.name}::${hash(arguments_, { serialize })}`;
+  }
+  return `${keyPrefix}::${function_.name}::${hash(arguments_, { serialize })}`;
+}
+
+// src/run-if-fn.ts
+function runIfFn(valueOrFunction, ...arguments_) {
+  return typeof valueOrFunction === "function" ? valueOrFunction(...arguments_) : valueOrFunction;
+}
+
+// src/sleep.ts
+var sleep = async (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+// src/stats.ts
+var Stats = class {
+  _hits = 0;
+  _misses = 0;
+  _gets = 0;
+  _sets = 0;
+  _deletes = 0;
+  _clears = 0;
+  _vsize = 0;
+  _ksize = 0;
+  _count = 0;
+  _enabled = false;
+  constructor(options) {
+    if (options?.enabled) {
+      this._enabled = options.enabled;
+    }
+  }
+  /**
+   * @returns {boolean} - Whether the stats are enabled
+   */
+  get enabled() {
+    return this._enabled;
+  }
+  /**
+   * @param {boolean} enabled - Whether to enable the stats
+   */
+  set enabled(enabled) {
+    this._enabled = enabled;
+  }
+  /**
+   * @returns {number} - The number of hits
+   * @readonly
+   */
+  get hits() {
+    return this._hits;
+  }
+  /**
+   * @returns {number} - The number of misses
+   * @readonly
+   */
+  get misses() {
+    return this._misses;
+  }
+  /**
+   * @returns {number} - The number of gets
+   * @readonly
+   */
+  get gets() {
+    return this._gets;
+  }
+  /**
+   * @returns {number} - The number of sets
+   * @readonly
+   */
+  get sets() {
+    return this._sets;
+  }
+  /**
+   * @returns {number} - The number of deletes
+   * @readonly
+   */
+  get deletes() {
+    return this._deletes;
+  }
+  /**
+   * @returns {number} - The number of clears
+   * @readonly
+   */
+  get clears() {
+    return this._clears;
+  }
+  /**
+   * @returns {number} - The vsize (value size) of the cache instance
+   * @readonly
+   */
+  get vsize() {
+    return this._vsize;
+  }
+  /**
+   * @returns {number} - The ksize (key size) of the cache instance
+   * @readonly
+   */
+  get ksize() {
+    return this._ksize;
+  }
+  /**
+   * @returns {number} - The count of the cache instance
+   * @readonly
+   */
+  get count() {
+    return this._count;
+  }
+  incrementHits() {
+    if (!this._enabled) {
+      return;
+    }
+    this._hits++;
+  }
+  incrementMisses() {
+    if (!this._enabled) {
+      return;
+    }
+    this._misses++;
+  }
+  incrementGets() {
+    if (!this._enabled) {
+      return;
+    }
+    this._gets++;
+  }
+  incrementSets() {
+    if (!this._enabled) {
+      return;
+    }
+    this._sets++;
+  }
+  incrementDeletes() {
+    if (!this._enabled) {
+      return;
+    }
+    this._deletes++;
+  }
+  incrementClears() {
+    if (!this._enabled) {
+      return;
+    }
+    this._clears++;
+  }
+  incrementVSize(value) {
+    if (!this._enabled) {
+      return;
+    }
+    this._vsize += this.roughSizeOfObject(value);
+  }
+  decreaseVSize(value) {
+    if (!this._enabled) {
+      return;
+    }
+    this._vsize -= this.roughSizeOfObject(value);
+  }
+  incrementKSize(key) {
+    if (!this._enabled) {
+      return;
+    }
+    this._ksize += this.roughSizeOfString(key);
+  }
+  decreaseKSize(key) {
+    if (!this._enabled) {
+      return;
+    }
+    this._ksize -= this.roughSizeOfString(key);
+  }
+  incrementCount() {
+    if (!this._enabled) {
+      return;
+    }
+    this._count++;
+  }
+  decreaseCount() {
+    if (!this._enabled) {
+      return;
+    }
+    this._count--;
+  }
+  setCount(count) {
+    if (!this._enabled) {
+      return;
+    }
+    this._count = count;
+  }
+  roughSizeOfString(value) {
+    return value.length * 2;
+  }
+  roughSizeOfObject(object) {
+    const objectList = [];
+    const stack = [object];
+    let bytes = 0;
+    while (stack.length > 0) {
+      const value = stack.pop();
+      if (typeof value === "boolean") {
+        bytes += 4;
+      } else if (typeof value === "string") {
+        bytes += value.length * 2;
+      } else if (typeof value === "number") {
+        bytes += 8;
+      } else {
+        if (value === null || value === void 0) {
+          bytes += 4;
+          continue;
+        }
+        if (objectList.includes(value)) {
+          continue;
+        }
+        objectList.push(value);
+        for (const key in value) {
+          bytes += key.length * 2;
+          stack.push(value[key]);
+        }
+      }
+    }
+    return bytes;
+  }
+  reset() {
+    this._hits = 0;
+    this._misses = 0;
+    this._gets = 0;
+    this._sets = 0;
+    this._deletes = 0;
+    this._clears = 0;
+    this._vsize = 0;
+    this._ksize = 0;
+    this._count = 0;
+  }
+  resetStoreValues() {
+    this._vsize = 0;
+    this._ksize = 0;
+    this._count = 0;
+  }
+};
+
+// 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 && expires > expiresFromTtl) {
+    return ttl;
+  }
+  return ttlFromExpires;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  HashAlgorithm,
+  Stats,
+  calculateTtlFromExpiration,
+  coalesceAsync,
+  createWrapKey,
+  getCascadingTtl,
+  getOrSet,
+  getTtlFromExpires,
+  hash,
+  hashToNumber,
+  isKeyvInstance,
+  isObject,
+  lessThan,
+  runIfFn,
+  shorthandToMilliseconds,
+  shorthandToTime,
+  sleep,
+  wrap,
+  wrapSync
+});
+/* v8 ignore next -- @preserve */

dist/index.d.cts

@@ -97,2 +97,53 @@ /**
 
+type CacheInstance = {
+    get: (key: string) => Promise<any | undefined>;
+    has: (key: string) => Promise<boolean>;
+    set: (key: string, value: any, ttl?: number | string) => Promise<void>;
+    on: (event: string, listener: (...args: any[]) => void) => void;
+    emit: (event: string, ...args: any[]) => boolean;
+};
+type CacheSyncInstance = {
+    get: (key: string) => any | undefined;
+    has: (key: string) => boolean;
+    set: (key: string, value: any, ttl?: number | string) => void;
+    on: (event: string, listener: (...args: any[]) => void) => void;
+    emit: (event: string, ...args: any[]) => boolean;
+};
+type GetOrSetKey = string | ((options?: GetOrSetOptions) => string);
+type GetOrSetFunctionOptions = {
+    ttl?: number | string;
+    cacheErrors?: boolean;
+    throwErrors?: boolean;
+};
+type GetOrSetOptions = GetOrSetFunctionOptions & {
+    cacheId?: string;
+    cache: CacheInstance;
+};
+type CreateWrapKey = (function_: AnyFunction, arguments_: any[], options?: WrapFunctionOptions) => string;
+type WrapFunctionOptions = {
+    ttl?: number | string;
+    keyPrefix?: string;
+    createKey?: CreateWrapKey;
+    cacheErrors?: boolean;
+    cacheId?: string;
+    serialize?: (object: any) => string;
+};
+type WrapOptions = WrapFunctionOptions & {
+    cache: CacheInstance;
+    serialize?: (object: any) => string;
+};
+type WrapSyncOptions = WrapFunctionOptions & {
+    cache: CacheSyncInstance;
+    serialize?: (object: any) => string;
+};
+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;
+type CreateWrapKeyOptions = {
+    keyPrefix?: string;
+    serialize?: (object: any) => string;
+};
+declare function createWrapKey(function_: AnyFunction, arguments_: any[], options?: CreateWrapKeyOptions): string;
+
 type Function_<P, T> = (...arguments_: P[]) => T;
@@ -213,2 +264,2 @@ declare function runIfFn<T, P>(valueOrFunction: T | Function_<P, T>, ...arguments_: P[]): T;
 
-export { type CacheableItem, type CacheableStoreItem, HashAlgorithm, Stats, type StatsOptions, calculateTtlFromExpiration, coalesceAsync, getCascadingTtl, getTtlFromExpires, hash, hashToNumber, isKeyvInstance, isObject, lessThan, runIfFn, shorthandToMilliseconds, shorthandToTime, sleep };
+export { type AnyFunction, type CacheInstance, type CacheSyncInstance, type CacheableItem, type CacheableStoreItem, type CreateWrapKey, type CreateWrapKeyOptions, type GetOrSetFunctionOptions, type GetOrSetKey, type GetOrSetOptions, HashAlgorithm, Stats, type StatsOptions, type WrapFunctionOptions, type WrapOptions, type WrapSyncOptions, calculateTtlFromExpiration, coalesceAsync, createWrapKey, getCascadingTtl, getOrSet, getTtlFromExpires, hash, hashToNumber, isKeyvInstance, isObject, lessThan, runIfFn, shorthandToMilliseconds, shorthandToTime, sleep, wrap, wrapSync };

dist/index.d.ts

@@ -97,2 +97,53 @@ /**
 
+type CacheInstance = {
+    get: (key: string) => Promise<any | undefined>;
+    has: (key: string) => Promise<boolean>;
+    set: (key: string, value: any, ttl?: number | string) => Promise<void>;
+    on: (event: string, listener: (...args: any[]) => void) => void;
+    emit: (event: string, ...args: any[]) => boolean;
+};
+type CacheSyncInstance = {
+    get: (key: string) => any | undefined;
+    has: (key: string) => boolean;
+    set: (key: string, value: any, ttl?: number | string) => void;
+    on: (event: string, listener: (...args: any[]) => void) => void;
+    emit: (event: string, ...args: any[]) => boolean;
+};
+type GetOrSetKey = string | ((options?: GetOrSetOptions) => string);
+type GetOrSetFunctionOptions = {
+    ttl?: number | string;
+    cacheErrors?: boolean;
+    throwErrors?: boolean;
+};
+type GetOrSetOptions = GetOrSetFunctionOptions & {
+    cacheId?: string;
+    cache: CacheInstance;
+};
+type CreateWrapKey = (function_: AnyFunction, arguments_: any[], options?: WrapFunctionOptions) => string;
+type WrapFunctionOptions = {
+    ttl?: number | string;
+    keyPrefix?: string;
+    createKey?: CreateWrapKey;
+    cacheErrors?: boolean;
+    cacheId?: string;
+    serialize?: (object: any) => string;
+};
+type WrapOptions = WrapFunctionOptions & {
+    cache: CacheInstance;
+    serialize?: (object: any) => string;
+};
+type WrapSyncOptions = WrapFunctionOptions & {
+    cache: CacheSyncInstance;
+    serialize?: (object: any) => string;
+};
+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;
+type CreateWrapKeyOptions = {
+    keyPrefix?: string;
+    serialize?: (object: any) => string;
+};
+declare function createWrapKey(function_: AnyFunction, arguments_: any[], options?: CreateWrapKeyOptions): string;
+
 type Function_<P, T> = (...arguments_: P[]) => T;
@@ -213,2 +264,2 @@ declare function runIfFn<T, P>(valueOrFunction: T | Function_<P, T>, ...arguments_: P[]): T;
 
-export { type CacheableItem, type CacheableStoreItem, HashAlgorithm, Stats, type StatsOptions, calculateTtlFromExpiration, coalesceAsync, getCascadingTtl, getTtlFromExpires, hash, hashToNumber, isKeyvInstance, isObject, lessThan, runIfFn, shorthandToMilliseconds, shorthandToTime, sleep };
+export { type AnyFunction, type CacheInstance, type CacheSyncInstance, type CacheableItem, type CacheableStoreItem, type CreateWrapKey, type CreateWrapKeyOptions, type GetOrSetFunctionOptions, type GetOrSetKey, type GetOrSetOptions, HashAlgorithm, Stats, type StatsOptions, type WrapFunctionOptions, type WrapOptions, type WrapSyncOptions, calculateTtlFromExpiration, coalesceAsync, createWrapKey, getCascadingTtl, getOrSet, getTtlFromExpires, hash, hashToNumber, isKeyvInstance, isObject, lessThan, runIfFn, shorthandToMilliseconds, shorthandToTime, sleep, wrap, wrapSync };

dist/index.js

@@ -1,1 +0,582 @@
-var a=t=>{let e;if(t!==void 0){if(typeof t=="number")e=t;else if(typeof t=="string")if(t=t.trim(),Number.isNaN(Number(t))){let r=/^([\d.]+)\s*(ms|s|m|h|hr|d)$/i.exec(t);if(!r)throw new Error(`Unsupported time format: "${t}". Use 'ms', 's', 'm', 'h', 'hr', or 'd'.`);let[,i,s]=r,n=Number.parseFloat(i);switch(s.toLowerCase()){case"ms":{e=n;break}case"s":{e=n*1e3;break}case"m":{e=n*1e3*60;break}case"h":{e=n*1e3*60*60;break}case"hr":{e=n*1e3*60*60;break}case"d":{e=n*1e3*60*60*24;break}default:e=Number(t)}}else e=Number(t);else throw new TypeError("Time must be a string or a number.");return e}},g=(t,e)=>{e??=new Date;let r=a(t);return r===void 0?e.getTime():e.getTime()+r};var u=new Map;function _(t){return u.has(t)}function y(t){u.set(t,[])}function T(t){u.delete(t)}function v(t,e){let r=b(t);r.push(e),u.set(t,r)}function b(t){return u.get(t)??[]}async function x(t){return new Promise((e,r)=>{v(t,{resolve:e,reject:r})})}function z(t){let e=b(t);return T(t),e}function h(t){let{key:e,error:r,result:i}=t;for(let s of z(e))r?s.reject(r):s.resolve(i)}async function S(t,e){if(!_(t)){y(t);try{let r=await Promise.resolve(e());return h({key:t,result:r}),r}catch(r){throw h({key:t,error:r}),r}}return x(t)}import*as l from"crypto";var f=(s=>(s.SHA256="sha256",s.SHA512="sha512",s.MD5="md5",s.DJB2="djb2",s))(f||{});function d(t,e={algorithm:"sha256",serialize:JSON.stringify}){e?.algorithm||(e.algorithm="sha256"),e?.serialize||(e.serialize=JSON.stringify);let r=e.serialize(t);if(e?.algorithm==="djb2")return w(r);if(!l.getHashes().includes(e.algorithm))throw new Error(`Unsupported hash algorithm: '${e?.algorithm}'`);let i=l.createHash(e.algorithm);return i.update(r),i.digest("hex")}function k(t,e={min:0,max:10,algorithm:"sha256",serialize:JSON.stringify}){let r=e?.min??0,i=e?.max??10;if(r>=i)throw new Error(`Invalid range: min (${r}) must be less than max (${i})`);e?.algorithm||(e.algorithm="sha256"),e?.serialize||(e.serialize=JSON.stringify);let s=d(t,e),n=Number.parseInt(s,16),o=i-r+1,c=r+n%o;return c<r?r:c>i?i:c}function w(t){let e=5381;for(let r=0;r<t.length;r++)e=e*33^t.charCodeAt(r);return e.toString()}import{Keyv as O}from"keyv";function P(t){return t==null?!1:t instanceof O?!0:["generateIterator","get","getMany","set","setMany","delete","deleteMany","has","hasMany","clear","disconnect","serialize","deserialize"].every(r=>typeof t[r]=="function")}function C(t){return t!==null&&typeof t=="object"&&!Array.isArray(t)}function N(t,e){return typeof t=="number"&&typeof e=="number"?t<e:!1}function A(t,...e){return typeof t=="function"?t(...e):t}var H=async t=>new Promise(e=>setTimeout(e,t));var m=class{_hits=0;_misses=0;_gets=0;_sets=0;_deletes=0;_clears=0;_vsize=0;_ksize=0;_count=0;_enabled=!1;constructor(e){e?.enabled&&(this._enabled=e.enabled)}get enabled(){return this._enabled}set enabled(e){this._enabled=e}get hits(){return this._hits}get misses(){return this._misses}get gets(){return this._gets}get sets(){return this._sets}get deletes(){return this._deletes}get clears(){return this._clears}get vsize(){return this._vsize}get ksize(){return this._ksize}get count(){return this._count}incrementHits(){this._enabled&&this._hits++}incrementMisses(){this._enabled&&this._misses++}incrementGets(){this._enabled&&this._gets++}incrementSets(){this._enabled&&this._sets++}incrementDeletes(){this._enabled&&this._deletes++}incrementClears(){this._enabled&&this._clears++}incrementVSize(e){this._enabled&&(this._vsize+=this.roughSizeOfObject(e))}decreaseVSize(e){this._enabled&&(this._vsize-=this.roughSizeOfObject(e))}incrementKSize(e){this._enabled&&(this._ksize+=this.roughSizeOfString(e))}decreaseKSize(e){this._enabled&&(this._ksize-=this.roughSizeOfString(e))}incrementCount(){this._enabled&&this._count++}decreaseCount(){this._enabled&&this._count--}setCount(e){this._enabled&&(this._count=e)}roughSizeOfString(e){return e.length*2}roughSizeOfObject(e){let r=[],i=[e],s=0;for(;i.length>0;){let n=i.pop();if(typeof n=="boolean")s+=4;else if(typeof n=="string")s+=n.length*2;else if(typeof n=="number")s+=8;else if(typeof n=="object"&&n!==null&&!r.includes(n)){r.push(n);for(let o in n)s+=o.length*2,i.push(n[o])}}return s}reset(){this._hits=0,this._misses=0,this._gets=0,this._sets=0,this._deletes=0,this._clears=0,this._vsize=0,this._ksize=0,this._count=0}resetStoreValues(){this._vsize=0,this._ksize=0,this._count=0}};function p(t){if(t==null)return;let e=Date.now();if(!(t<e))return t-e}function j(t,e,r){return r??e??a(t)}function E(t,e){let r=p(e),i=t?Date.now()+t:void 0;return r===void 0?t:i===void 0?r:e&&e>i?t:r}export{f as HashAlgorithm,m as Stats,E as calculateTtlFromExpiration,S as coalesceAsync,j as getCascadingTtl,p as getTtlFromExpires,d as hash,k as hashToNumber,P as isKeyvInstance,C as isObject,N as lessThan,A as runIfFn,a as shorthandToMilliseconds,g as shorthandToTime,H as sleep};
+// src/shorthand-time.ts
+var shorthandToMilliseconds = (shorthand) => {
+  let milliseconds;
+  if (shorthand === void 0) {
+    return void 0;
+  }
+  if (typeof shorthand === "number") {
+    milliseconds = shorthand;
+  } else {
+    if (typeof shorthand !== "string") {
+      return void 0;
+    }
+    shorthand = shorthand.trim();
+    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'.`
+        );
+      }
+      const [, value, unit] = match;
+      const numericValue = Number.parseFloat(value);
+      const unitLower = unit.toLowerCase();
+      switch (unitLower) {
+        case "ms": {
+          milliseconds = numericValue;
+          break;
+        }
+        case "s": {
+          milliseconds = numericValue * 1e3;
+          break;
+        }
+        case "m": {
+          milliseconds = numericValue * 1e3 * 60;
+          break;
+        }
+        case "h": {
+          milliseconds = numericValue * 1e3 * 60 * 60;
+          break;
+        }
+        case "hr": {
+          milliseconds = numericValue * 1e3 * 60 * 60;
+          break;
+        }
+        case "d": {
+          milliseconds = numericValue * 1e3 * 60 * 60 * 24;
+          break;
+        }
+        /* v8 ignore next -- @preserve */
+        default: {
+          milliseconds = Number(shorthand);
+        }
+      }
+    } else {
+      milliseconds = Number(shorthand);
+    }
+  }
+  return milliseconds;
+};
+var shorthandToTime = (shorthand, fromDate) => {
+  fromDate ??= /* @__PURE__ */ new Date();
+  const milliseconds = shorthandToMilliseconds(shorthand);
+  if (milliseconds === void 0) {
+    return fromDate.getTime();
+  }
+  return fromDate.getTime() + milliseconds;
+};
+
+// src/coalesce-async.ts
+var callbacks = /* @__PURE__ */ new Map();
+function hasKey(key) {
+  return callbacks.has(key);
+}
+function addKey(key) {
+  callbacks.set(key, []);
+}
+function removeKey(key) {
+  callbacks.delete(key);
+}
+function addCallbackToKey(key, callback) {
+  const stash = getCallbacksByKey(key);
+  stash.push(callback);
+  callbacks.set(key, stash);
+}
+function getCallbacksByKey(key) {
+  return callbacks.get(key) ?? [];
+}
+async function enqueue(key) {
+  return new Promise((resolve, reject) => {
+    const callback = { resolve, reject };
+    addCallbackToKey(key, callback);
+  });
+}
+function dequeue(key) {
+  const stash = getCallbacksByKey(key);
+  removeKey(key);
+  return stash;
+}
+function coalesce(options) {
+  const { key, error, result } = options;
+  for (const callback of dequeue(key)) {
+    if (error) {
+      callback.reject(error);
+    } else {
+      callback.resolve(result);
+    }
+  }
+}
+async function coalesceAsync(key, fnc) {
+  if (!hasKey(key)) {
+    addKey(key);
+    try {
+      const result = await Promise.resolve(fnc());
+      coalesce({ key, result });
+      return result;
+    } catch (error) {
+      coalesce({ key, error });
+      throw error;
+    }
+  }
+  return enqueue(key);
+}
+
+// src/hash.ts
+import * as crypto from "crypto";
+var HashAlgorithm = /* @__PURE__ */ ((HashAlgorithm2) => {
+  HashAlgorithm2["SHA256"] = "sha256";
+  HashAlgorithm2["SHA512"] = "sha512";
+  HashAlgorithm2["MD5"] = "md5";
+  HashAlgorithm2["DJB2"] = "djb2";
+  return HashAlgorithm2;
+})(HashAlgorithm || {});
+function hash(object, options = {
+  algorithm: "sha256" /* SHA256 */,
+  serialize: JSON.stringify
+}) {
+  if (!options?.algorithm) {
+    options.algorithm = "sha256" /* SHA256 */;
+  }
+  if (!options?.serialize) {
+    options.serialize = JSON.stringify;
+  }
+  const objectString = options.serialize(object);
+  if (options?.algorithm === "djb2" /* DJB2 */) {
+    return djb2Hash(objectString);
+  }
+  if (!crypto.getHashes().includes(options.algorithm)) {
+    throw new Error(`Unsupported hash algorithm: '${options?.algorithm}'`);
+  }
+  const hasher = crypto.createHash(options.algorithm);
+  hasher.update(objectString);
+  return hasher.digest("hex");
+}
+function hashToNumber(object, options = {
+  min: 0,
+  max: 10,
+  algorithm: "sha256" /* SHA256 */,
+  serialize: JSON.stringify
+}) {
+  const min = options?.min ?? 0;
+  const max = options?.max ?? 10;
+  if (min >= max) {
+    throw new Error(
+      `Invalid range: min (${min}) must be less than max (${max})`
+    );
+  }
+  if (!options?.algorithm) {
+    options.algorithm = "sha256" /* SHA256 */;
+  }
+  if (!options?.serialize) {
+    options.serialize = JSON.stringify;
+  }
+  const hashResult = hash(object, options);
+  const hashNumber = Number.parseInt(hashResult, 16);
+  const range = max - min + 1;
+  const result = min + hashNumber % range;
+  if (result < min) {
+    return min;
+  }
+  if (result > max) {
+    return max;
+  }
+  return result;
+}
+function djb2Hash(string_) {
+  let hash2 = 5381;
+  for (let i = 0; i < string_.length; i++) {
+    hash2 = hash2 * 33 ^ string_.charCodeAt(i);
+  }
+  return hash2.toString();
+}
+
+// src/is-keyv-instance.ts
+import { Keyv } from "keyv";
+function isKeyvInstance(keyv) {
+  if (keyv === null || keyv === void 0) {
+    return false;
+  }
+  if (keyv instanceof 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");
+}
+
+// src/is-object.ts
+function isObject(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+// src/less-than.ts
+function lessThan(number1, number2) {
+  return typeof number1 === "number" && typeof number2 === "number" ? number1 < number2 : false;
+}
+
+// src/memoize.ts
+function wrapSync(function_, options) {
+  const { ttl, keyPrefix, cache, serialize } = options;
+  return (...arguments_) => {
+    let cacheKey = createWrapKey(function_, arguments_, {
+      keyPrefix,
+      serialize
+    });
+    if (options.createKey) {
+      cacheKey = options.createKey(function_, arguments_, options);
+    }
+    let value = cache.get(cacheKey);
+    if (value === void 0) {
+      try {
+        value = function_(...arguments_);
+        cache.set(cacheKey, value, ttl);
+      } catch (error) {
+        cache.emit("error", error);
+        if (options.cacheErrors) {
+          cache.set(cacheKey, error, ttl);
+        }
+      }
+    }
+    return value;
+  };
+}
+async function getOrSet(key, function_, options) {
+  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}::${keyString}`;
+    value = await coalesceAsync(coalesceKey, async () => {
+      try {
+        const result = await function_();
+        await options.cache.set(keyString, result, options.ttl);
+        return result;
+      } catch (error) {
+        options.cache.emit("error", error);
+        if (options.cacheErrors) {
+          await options.cache.set(keyString, error, options.ttl);
+        }
+        if (options.throwErrors) {
+          throw error;
+        }
+      }
+    });
+  }
+  return value;
+}
+function wrap(function_, options) {
+  const { keyPrefix, serialize } = options;
+  return async (...arguments_) => {
+    let cacheKey = createWrapKey(function_, arguments_, {
+      keyPrefix,
+      serialize
+    });
+    if (options.createKey) {
+      cacheKey = options.createKey(function_, arguments_, options);
+    }
+    return getOrSet(
+      cacheKey,
+      async () => function_(...arguments_),
+      options
+    );
+  };
+}
+function createWrapKey(function_, arguments_, options) {
+  const { keyPrefix, serialize } = options || {};
+  if (!keyPrefix) {
+    return `${function_.name}::${hash(arguments_, { serialize })}`;
+  }
+  return `${keyPrefix}::${function_.name}::${hash(arguments_, { serialize })}`;
+}
+
+// src/run-if-fn.ts
+function runIfFn(valueOrFunction, ...arguments_) {
+  return typeof valueOrFunction === "function" ? valueOrFunction(...arguments_) : valueOrFunction;
+}
+
+// src/sleep.ts
+var sleep = async (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+// src/stats.ts
+var Stats = class {
+  _hits = 0;
+  _misses = 0;
+  _gets = 0;
+  _sets = 0;
+  _deletes = 0;
+  _clears = 0;
+  _vsize = 0;
+  _ksize = 0;
+  _count = 0;
+  _enabled = false;
+  constructor(options) {
+    if (options?.enabled) {
+      this._enabled = options.enabled;
+    }
+  }
+  /**
+   * @returns {boolean} - Whether the stats are enabled
+   */
+  get enabled() {
+    return this._enabled;
+  }
+  /**
+   * @param {boolean} enabled - Whether to enable the stats
+   */
+  set enabled(enabled) {
+    this._enabled = enabled;
+  }
+  /**
+   * @returns {number} - The number of hits
+   * @readonly
+   */
+  get hits() {
+    return this._hits;
+  }
+  /**
+   * @returns {number} - The number of misses
+   * @readonly
+   */
+  get misses() {
+    return this._misses;
+  }
+  /**
+   * @returns {number} - The number of gets
+   * @readonly
+   */
+  get gets() {
+    return this._gets;
+  }
+  /**
+   * @returns {number} - The number of sets
+   * @readonly
+   */
+  get sets() {
+    return this._sets;
+  }
+  /**
+   * @returns {number} - The number of deletes
+   * @readonly
+   */
+  get deletes() {
+    return this._deletes;
+  }
+  /**
+   * @returns {number} - The number of clears
+   * @readonly
+   */
+  get clears() {
+    return this._clears;
+  }
+  /**
+   * @returns {number} - The vsize (value size) of the cache instance
+   * @readonly
+   */
+  get vsize() {
+    return this._vsize;
+  }
+  /**
+   * @returns {number} - The ksize (key size) of the cache instance
+   * @readonly
+   */
+  get ksize() {
+    return this._ksize;
+  }
+  /**
+   * @returns {number} - The count of the cache instance
+   * @readonly
+   */
+  get count() {
+    return this._count;
+  }
+  incrementHits() {
+    if (!this._enabled) {
+      return;
+    }
+    this._hits++;
+  }
+  incrementMisses() {
+    if (!this._enabled) {
+      return;
+    }
+    this._misses++;
+  }
+  incrementGets() {
+    if (!this._enabled) {
+      return;
+    }
+    this._gets++;
+  }
+  incrementSets() {
+    if (!this._enabled) {
+      return;
+    }
+    this._sets++;
+  }
+  incrementDeletes() {
+    if (!this._enabled) {
+      return;
+    }
+    this._deletes++;
+  }
+  incrementClears() {
+    if (!this._enabled) {
+      return;
+    }
+    this._clears++;
+  }
+  incrementVSize(value) {
+    if (!this._enabled) {
+      return;
+    }
+    this._vsize += this.roughSizeOfObject(value);
+  }
+  decreaseVSize(value) {
+    if (!this._enabled) {
+      return;
+    }
+    this._vsize -= this.roughSizeOfObject(value);
+  }
+  incrementKSize(key) {
+    if (!this._enabled) {
+      return;
+    }
+    this._ksize += this.roughSizeOfString(key);
+  }
+  decreaseKSize(key) {
+    if (!this._enabled) {
+      return;
+    }
+    this._ksize -= this.roughSizeOfString(key);
+  }
+  incrementCount() {
+    if (!this._enabled) {
+      return;
+    }
+    this._count++;
+  }
+  decreaseCount() {
+    if (!this._enabled) {
+      return;
+    }
+    this._count--;
+  }
+  setCount(count) {
+    if (!this._enabled) {
+      return;
+    }
+    this._count = count;
+  }
+  roughSizeOfString(value) {
+    return value.length * 2;
+  }
+  roughSizeOfObject(object) {
+    const objectList = [];
+    const stack = [object];
+    let bytes = 0;
+    while (stack.length > 0) {
+      const value = stack.pop();
+      if (typeof value === "boolean") {
+        bytes += 4;
+      } else if (typeof value === "string") {
+        bytes += value.length * 2;
+      } else if (typeof value === "number") {
+        bytes += 8;
+      } else {
+        if (value === null || value === void 0) {
+          bytes += 4;
+          continue;
+        }
+        if (objectList.includes(value)) {
+          continue;
+        }
+        objectList.push(value);
+        for (const key in value) {
+          bytes += key.length * 2;
+          stack.push(value[key]);
+        }
+      }
+    }
+    return bytes;
+  }
+  reset() {
+    this._hits = 0;
+    this._misses = 0;
+    this._gets = 0;
+    this._sets = 0;
+    this._deletes = 0;
+    this._clears = 0;
+    this._vsize = 0;
+    this._ksize = 0;
+    this._count = 0;
+  }
+  resetStoreValues() {
+    this._vsize = 0;
+    this._ksize = 0;
+    this._count = 0;
+  }
+};
+
+// 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 && expires > expiresFromTtl) {
+    return ttl;
+  }
+  return ttlFromExpires;
+}
+export {
+  HashAlgorithm,
+  Stats,
+  calculateTtlFromExpiration,
+  coalesceAsync,
+  createWrapKey,
+  getCascadingTtl,
+  getOrSet,
+  getTtlFromExpires,
+  hash,
+  hashToNumber,
+  isKeyvInstance,
+  isObject,
+  lessThan,
+  runIfFn,
+  shorthandToMilliseconds,
+  shorthandToTime,
+  sleep,
+  wrap,
+  wrapSync
+};
+/* v8 ignore next -- @preserve */

package.json

 {
   "name": "@cacheable/utils",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "description": "Cacheable Utilities for Caching Libraries",
@@ -24,13 +24,11 @@ "type": "module",
   "devDependencies": {
-    "@biomejs/biome": "^2.2.4",
-    "@faker-js/faker": "^10.0.0",
-    "@keyv/redis": "^5.1.2",
-    "@keyv/valkey": "^1.0.8",
-    "@types/node": "^24.5.2",
-    "@vitest/coverage-v8": "^3.2.4",
+    "@biomejs/biome": "^2.3.0",
+    "@faker-js/faker": "^10.1.0",
+    "@types/node": "^24.9.1",
+    "@vitest/coverage-v8": "^4.0.3",
     "lru-cache": "^11.2.2",
     "rimraf": "^6.0.1",
     "tsup": "^8.5.0",
-    "typescript": "^5.9.2",
-    "vitest": "^3.2.4"
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.3"
   },
@@ -53,3 +51,3 @@ "keywords": [
   "scripts": {
-    "build": "rimraf ./dist && tsup src/index.ts --format cjs,esm --dts --clean --minify",
+    "build": "rimraf ./dist && tsup src/index.ts --format cjs,esm --dts --clean",
     "prepublish": "pnpm build",
@@ -56,0 +54,0 @@ "lint": "biome check --write --error-on-warnings",

README.md

@@ -18,2 +18,3 @@ [<img align="center" src="https://cacheable.org/logo.svg" alt="Cacheable" />](https://github.com/jaredwray/cacheable)
 * Sleep / Delay for Testing and Timing
+* Memoization for wraping or get / set options
 * Time to Live (TTL) Helpers
@@ -33,2 +34,4 @@
 * [Is Object Helper](#is-object-helper)
+* [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)
@@ -39,4 +42,2 @@ * [License and Copyright](#license-and-copyright)
 
-`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
@@ -341,2 +342,137 @@ npm install @cacheable/utils --save
 
+# Wrap / Memoization for Sync and Async Functions
+
+The `@cacheable/utils` package provides two main functions: `wrap` and `wrapSync`. These functions are used to memoize asynchronous and synchronous functions, respectively.
+
+```javascript
+import { Cacheable } from 'cacheable';
+const asyncFunction = async (value: number) => {
+  return Math.random() * value;
+};
+
+const cache = new Cacheable();
+const options = {
+  ttl: '1h', // 1 hour
+  keyPrefix: 'p1', // key prefix. This is used if you have multiple functions and need to set a unique prefix.
+  cache,
+}
+const wrappedFunction = wrap(asyncFunction, options);
+console.log(await wrappedFunction(2)); // 4
+console.log(await wrappedFunction(2)); // 4 from cache
+```
+With `wrap` we have also included stampede protection so that a `Promise` based call will only be called once if multiple requests of the same are executed at the same time. Here is an example of how to test for stampede protection:
+  
+```javascript
+import { Cacheable } from 'cacheable';
+const asyncFunction = async (value: number) => {
+  return value;
+};
+
+const cache = new Cacheable();
+const options = {
+  ttl: '1h', // 1 hour
+  keyPrefix: 'p1', // key prefix. This is used if you have multiple functions and need to set a unique prefix.
+  cache,
+}
+
+const wrappedFunction = wrap(asyncFunction, options);
+const promises = [];
+for (let i = 0; i < 10; i++) {
+  promises.push(wrappedFunction(i));
+}
+
+const results = await Promise.all(promises); // all results should be the same
+
+console.log(results); // [0, 0, 0, 0, 0, 0, 0, 0, 0, 0]
+```
+
+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 = wrap(syncFunction, { ttl: '1h', key: 'syncFunction', cache });
+console.log(wrappedFunction(2)); // 4
+console.log(wrappedFunction(2)); // 4 from cache
+```
+
+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. You can also set the `key` property in the `wrap()` options to set a custom key for the cache.
+
+When an error occurs in the function it will not cache the value and will return the error. This is useful if you want to cache the results of a function but not cache the error. If you want it to cache the error you can set the `cacheError` property to `true` in the `wrap()` options. This is disabled by default.
+
+```javascript
+import { CacheableMemory } from 'cacheable';
+const syncFunction = (value: number) => {
+  throw new Error('error');
+};
+
+const cache = new CacheableMemory();
+const wrappedFunction = wrap(syncFunction, { ttl: '1h', key: 'syncFunction', cacheError: true, cache });
+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 getOrSet('randomValue', function_, { ttl: '1h', cache });
+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 getOrSet(generateKey(), function_, { ttl: '1h', cache });
+```
+
 # How to Contribute
@@ -343,0 +479,0 @@

New alerts

Major refactor

Supply chain risk

Package has recently undergone a major refactor. It may be unstable or indicate significant internal changes. Use caution when updating to versions that include significant changes.

Found 1 instance in 1 package

Fixed alerts

Minified code

Quality

This package contains minified code. This may be harmless in some cases where minified code is included in packaged libraries, however packages on npm should not minify code.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

69066

69.23%

Dev dependency count

9

-18.18%

Lines of code

1450

496.71%

Number of low quality alerts

1

-66.67%

Number of lines in readme file

480

39.53%

Worsened metrics

Number of medium supply chain risk alerts

1

Infinity%

No dependency changes