cacheable 1.8.0 → 1.8.1

package/dist/index.cjs

@@ -249,6 +249,10 @@ var CacheableMemory = class {
   // Turned off by default
   _interval = 0;
   // Turned off by default
+  /**
+   * @constructor
+   * @param {CacheableMemoryOptions} [options] - The options for the CacheableMemory
+   */
   constructor(options) {
     if (options?.ttl) {
       this.setTtl(options.ttl);
@@ -264,40 +268,89 @@ var CacheableMemory = class {
     }
     this.startIntervalCheck();
   }
+  /**
+   * Gets the time-to-live
+   * @returns {number|string|undefined} - The time-to-live in miliseconds or a human-readable format. If undefined, it will not have a time-to-live.
+   */
   get ttl() {
     return this._ttl;
   }
+  /**
+   * Sets the time-to-live
+   * @param {number|string|undefined} value - The time-to-live in miliseconds or a human-readable format (example '1s' = 1 second, '1h' = 1 hour). If undefined, it will not have a time-to-live.
+   */
   set ttl(value) {
     this.setTtl(value);
   }
+  /**
+   * Gets whether to use clone
+   * @returns {boolean} - If true, it will clone the value before returning it. If false, it will return the value directly. Default is true.
+   */
   get useClone() {
     return this._useClone;
   }
+  /**
+   * Sets whether to use clone
+   * @param {boolean} value - If true, it will clone the value before returning it. If false, it will return the value directly. Default is true.
+   */
   set useClone(value) {
     this._useClone = value;
   }
+  /**
+   * Gets the size of the LRU cache
+   * @returns {number} - The size of the LRU cache. If set to 0, it will not use LRU cache. Default is 0.
+   */
   get lruSize() {
     return this._lruSize;
   }
+  /**
+   * Sets the size of the LRU cache
+   * @param {number} value - The size of the LRU cache. If set to 0, it will not use LRU cache. Default is 0.
+   */
   set lruSize(value) {
     this._lruSize = value;
     this.lruResize();
   }
+  /**
+   * Gets the check interval
+   * @returns {number} - The interval to check for expired items. If set to 0, it will not check for expired items. Default is 0.
+   */
   get checkInterval() {
     return this._checkInterval;
   }
+  /**
+   * Sets the check interval
+   * @param {number} value - The interval to check for expired items. If set to 0, it will not check for expired items. Default is 0.
+   */
   set checkInterval(value) {
     this._checkInterval = value;
   }
+  /**
+   * Gets the size of the cache
+   * @returns {number} - The size of the cache
+   */
   get size() {
     return this._hash0.size + this._hash1.size + this._hash2.size + this._hash3.size + this._hash4.size + this._hash5.size + this._hash6.size + this._hash7.size + this._hash8.size + this._hash9.size;
   }
+  /**
+   * Gets the keys
+   * @returns {IterableIterator<string>} - The keys
+   */
   get keys() {
     return this.concatStores().keys();
   }
+  /**
+   * Gets the items
+   * @returns {IterableIterator<CacheableStoreItem>} - The items
+   */
   get items() {
     return this.concatStores().values();
   }
+  /**
+   * Gets the value of the key
+   * @param {string} key - The key to get the value
+   * @returns {T | undefined} - The value of the key
+   */
   get(key) {
     const store = this.getStore(key);
     const item = store.get(key);
@@ -314,6 +367,11 @@ var CacheableMemory = class {
     }
     return this.clone(item.value);
   }
+  /**
+   * Gets the values of the keys
+   * @param {string[]} keys - The keys to get the values
+   * @returns {T[]} - The values of the keys
+   */
   getMany(keys) {
     const result = new Array();
     for (const key of keys) {
@@ -321,6 +379,11 @@ var CacheableMemory = class {
     }
     return result;
   }
+  /**
+   * Gets the raw value of the key
+   * @param {string} key - The key to get the value
+   * @returns {CacheableStoreItem | undefined} - The raw value of the key
+   */
   getRaw(key) {
     const store = this.getStore(key);
     const item = store.get(key);
@@ -334,6 +397,11 @@ var CacheableMemory = class {
     this.lruMoveToFront(key);
     return item;
   }
+  /**
+   * Gets the raw values of the keys
+   * @param {string[]} keys - The keys to get the values
+   * @returns {CacheableStoreItem[]} - The raw values of the keys
+   */
   getManyRaw(keys) {
     const result = new Array();
     for (const key of keys) {
@@ -341,6 +409,14 @@ var CacheableMemory = class {
     }
     return result;
   }
+  /**
+   * Sets the value of the key
+   * @param {string} key - The key to set the value
+   * @param {any} value - The value to set
+   * @param {number|string} [ttl] - Time to Live - If you set a number it is miliseconds, if you set a string it is a human-readable.
+   * If you set undefined, it will use the default time-to-live. If both are undefined then it will not have a time-to-live.
+   * @returns {void}
+   */
   set(key, value, ttl) {
     const store = this.getStore(key);
     let expires;
@@ -371,15 +447,43 @@ var CacheableMemory = class {
       expires
     });
   }
+  /**
+   * Sets the values of the keys
+   * @param {CacheableItem[]} items - The items to set
+   * @returns {void}
+   */
   setMany(items) {
     for (const item of items) {
       this.set(item.key, item.value, item.ttl);
     }
   }
+  /**
+   * Checks if the key exists
+   * @param {string} key - The key to check
+   * @returns {boolean} - If true, the key exists. If false, the key does not exist.
+   */
   has(key) {
     const item = this.get(key);
     return Boolean(item);
   }
+  /**
+   * @function hasMany
+   * @param {string[]} keys - The keys to check
+   * @returns {boolean[]} - If true, the key exists. If false, the key does not exist.
+   */
+  hasMany(keys) {
+    const result = new Array();
+    for (const key of keys) {
+      const item = this.get(key);
+      result.push(Boolean(item));
+    }
+    return result;
+  }
+  /**
+   * Take will get the key and delete the entry from cache
+   * @param {string} key - The key to take
+   * @returns {T | undefined} - The value of the key
+   */
   take(key) {
     const item = this.get(key);
     if (!item) {
@@ -388,6 +492,11 @@ var CacheableMemory = class {
     this.delete(key);
     return item;
   }
+  /**
+   * TakeMany will get the keys and delete the entries from cache
+   * @param {string[]} keys - The keys to take
+   * @returns {T[]} - The values of the keys
+   */
   takeMany(keys) {
     const result = new Array();
     for (const key of keys) {
@@ -395,15 +504,29 @@ var CacheableMemory = class {
     }
     return result;
   }
+  /**
+   * Delete the key
+   * @param {string} key - The key to delete
+   * @returns {void}
+   */
   delete(key) {
     const store = this.getStore(key);
     store.delete(key);
   }
+  /**
+   * Delete the keys
+   * @param {string[]} keys - The keys to delete
+   * @returns {void}
+   */
   deleteMany(keys) {
     for (const key of keys) {
       this.delete(key);
     }
   }
+  /**
+   * Clear the cache
+   * @returns {void}
+   */
   clear() {
     this._hash0.clear();
     this._hash1.clear();
@@ -417,6 +540,11 @@ var CacheableMemory = class {
     this._hash9.clear();
     this._hashCache.clear();
   }
+  /**
+   * Hash the key. this is used to determine which store to use (internal use)
+   * @param {string} key - The key to hash
+   * @returns {number} - The hash number
+   */
   hashKey(key) {
     const cacheHashNumber = this._hashCache.get(key);
     if (cacheHashNumber) {
@@ -431,6 +559,11 @@ var CacheableMemory = class {
     this._hashCache.set(key, result);
     return result;
   }
+  /**
+   * Get the store based on the key (internal use)
+   * @param {string} key - The key to get the store
+   * @returns {Map<string, any>} - The store
+   */
   getStore(key) {
     const hashKey = this.hashKey(key);
     switch (hashKey) {
@@ -466,24 +599,43 @@ var CacheableMemory = class {
       }
     }
   }
+  /**
+   * Clone the value. This is for internal use
+   * @param {any} value - The value to clone
+   * @returns {any} - The cloned value
+   */
   clone(value) {
     if (this.isPrimitive(value)) {
       return value;
     }
     return structuredClone(value);
   }
+  /**
+   * Add to the front of the LRU cache. This is for internal use
+   * @param {string} key - The key to add to the front
+   * @returns {void}
+   */
   lruAddToFront(key) {
     if (this._lruSize === 0) {
       return;
     }
     this._lru.addToFront(key);
   }
+  /**
+   * Move to the front of the LRU cache. This is for internal use
+   * @param {string} key - The key to move to the front
+   * @returns {void}
+   */
   lruMoveToFront(key) {
     if (this._lruSize === 0) {
       return;
     }
     this._lru.moveToFront(key);
   }
+  /**
+   * Resize the LRU cache. This is for internal use
+   * @returns {void}
+   */
   lruResize() {
     if (this._lruSize === 0) {
       return;
@@ -496,6 +648,10 @@ var CacheableMemory = class {
       }
     }
   }
+  /**
+   * Check for expiration. This is for internal use
+   * @returns {void}
+   */
   checkExpiration() {
     const stores = this.concatStores();
     for (const item of stores.values()) {
@@ -504,6 +660,10 @@ var CacheableMemory = class {
       }
     }
   }
+  /**
+   * Start the interval check. This is for internal use
+   * @returns {void}
+   */
   startIntervalCheck() {
     if (this._checkInterval > 0) {
       this._interval = setInterval(() => {
@@ -511,6 +671,10 @@ var CacheableMemory = class {
       }, this._checkInterval);
     }
   }
+  /**
+   * Stop the interval check. This is for internal use
+   * @returns {void}
+   */
   stopIntervalCheck() {
     if (this._interval) {
       clearInterval(this._interval);
@@ -518,9 +682,21 @@ var CacheableMemory = class {
     this._interval = 0;
     this._checkInterval = 0;
   }
+  /**
+   * Hash the object. This is for internal use
+   * @param {any} object - The object to hash
+   * @param {string} [algorithm='sha256'] - The algorithm to hash
+   * @returns {string} - The hashed string
+   */
   hash(object, algorithm = "sha256") {
     return hash(object, algorithm);
   }
+  /**
+   * Wrap the function for caching
+   * @param {Function} function_ - The function to wrap
+   * @param {Object} [options] - The options to wrap
+   * @returns {Function} - The wrapped function
+   */
   wrap(function_, options = {}) {
     const wrapOptions = {
       ttl: options.ttl,
@@ -623,36 +799,78 @@ var CacheableStats = class {
       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;
   }
@@ -804,6 +1022,10 @@ var Cacheable = class extends import_hookified.Hookified {
   _nonBlocking = false;
   _ttl;
   _stats = new CacheableStats({ enabled: false });
+  /**
+   * Creates a new cacheable instance
+   * @param {CacheableOptions} [options] The options for the cacheable instance
+   */
   constructor(options) {
     super();
     if (options?.primary) {
@@ -822,39 +1044,126 @@ var Cacheable = class extends import_hookified.Hookified {
       this.setTtl(options.ttl);
     }
   }
+  /**
+   * The statistics for the cacheable instance
+   * @returns {CacheableStats} The statistics for the cacheable instance
+   */
   get stats() {
     return this._stats;
   }
+  /**
+   * The primary store for the cacheable instance
+   * @returns {Keyv} The primary store for the cacheable instance
+   */
   get primary() {
     return this._primary;
   }
+  /**
+   * Sets the primary store for the cacheable instance
+   * @param {Keyv} primary The primary store for the cacheable instance
+   */
   set primary(primary) {
     this._primary = primary;
   }
+  /**
+   * The secondary store for the cacheable instance
+   * @returns {Keyv | undefined} The secondary store for the cacheable instance
+   */
   get secondary() {
     return this._secondary;
   }
+  /**
+   * Sets the secondary store for the cacheable instance. If it is set to undefined then the secondary store is disabled.
+   * @param {Keyv | undefined} secondary The secondary store for the cacheable instance
+   * @returns {void}
+   */
   set secondary(secondary) {
     this._secondary = secondary;
   }
+  /**
+   * Gets whether the secondary store is non-blocking mode. It is set to false by default.
+   * If it is set to true then the secondary store will not block the primary store.
+   *
+   * [Learn more about non-blocking mode](https://cacheable.org/docs/cacheable/#non-blocking-operations).
+   *
+   * @returns {boolean} Whether the cacheable instance is non-blocking
+   */
   get nonBlocking() {
     return this._nonBlocking;
   }
+  /**
+   * Sets whether the secondary store is non-blocking mode. It is set to false by default.
+   * If it is set to true then the secondary store will not block the primary store.
+   *
+   * [Learn more about non-blocking mode](https://cacheable.org/docs/cacheable/#non-blocking-operations).
+   *
+   * @param {boolean} nonBlocking Whether the cacheable instance is non-blocking
+   * @returns {void}
+   */
   set nonBlocking(nonBlocking) {
     this._nonBlocking = nonBlocking;
   }
+  /**
+   * The time-to-live for the cacheable instance and will be used as the default value.
+   * can be a number in milliseconds or a human-readable format such as `1s` for 1 second or `1h` for 1 hour
+   * or undefined if there is no time-to-live.
+   *
+   * [Learn more about time-to-live](https://cacheable.org/docs/cacheable/#shorthand-for-time-to-live-ttl).
+   *
+   * @returns {number | string | undefined} The time-to-live for the cacheable instance in milliseconds, human-readable format or undefined
+   * @example
+   * ```typescript
+   * const cacheable = new Cacheable({ ttl: '1h' });
+   * console.log(cacheable.ttl); // 1h
+   * ```
+   */
   get ttl() {
     return this._ttl;
   }
+  /**
+   * Sets the time-to-live for the cacheable instance and will be used as the default value.
+   * If you set a number it is miliseconds, if you set a string it is a human-readable
+   * format such as `1s` for 1 second or `1h` for 1 hour. Setting undefined means that
+   * there is no time-to-live.
+   *
+   * [Learn more about time-to-live](https://cacheable.org/docs/cacheable/#shorthand-for-time-to-live-ttl).
+   *
+   * @param {number | string | undefined} ttl The time-to-live for the cacheable instance
+   * @example
+   * ```typescript
+   * const cacheable = new Cacheable();
+   * cacheable.ttl = '1h'; // Set the time-to-live to 1 hour
+   * ```
+   * or setting the time-to-live in milliseconds
+   * ```typescript
+   * const cacheable = new Cacheable();
+   * cacheable.ttl = 3600000; // Set the time-to-live to 1 hour
+   * ```
+   */
   set ttl(ttl) {
     this.setTtl(ttl);
   }
+  /**
+   * Sets the primary store for the cacheable instance
+   * @param {Keyv | KeyvStoreAdapter} primary The primary store for the cacheable instance
+   * @returns {void}
+   */
   setPrimary(primary) {
     this._primary = primary instanceof import_keyv.Keyv ? primary : new import_keyv.Keyv(primary);
   }
+  /**
+   * Sets the secondary store for the cacheable instance. If it is set to undefined then the secondary store is disabled.
+   * @param {Keyv | KeyvStoreAdapter} secondary The secondary store for the cacheable instance
+   * @returns {void}
+   */
   setSecondary(secondary) {
     this._secondary = secondary instanceof import_keyv.Keyv ? secondary : new import_keyv.Keyv(secondary);
   }
+  /**
+   * Gets the value of the key. If the key does not exist in the primary store then it will check the secondary store.
+   * @param {string} key The key to get the value of
+   * @returns {Promise<T | undefined>} The value of the key or undefined if the key does not exist
+   */
   async get(key) {
     let result;
     try {
@@ -881,6 +1190,11 @@ var Cacheable = class extends import_hookified.Hookified {
     }
     return result;
   }
+  /**
+   * Gets the values of the keys. If the key does not exist in the primary store then it will check the secondary store.
+   * @param {string[]} keys The keys to get the values of
+   * @returns {Promise<Array<T | undefined>>} The values of the keys or undefined if the key does not exist
+   */
   async getMany(keys) {
     let result = [];
     try {
@@ -918,6 +1232,15 @@ var Cacheable = class extends import_hookified.Hookified {
     }
     return result;
   }
+  /**
+   * Sets the value of the key. If the secondary store is set then it will also set the value in the secondary store.
+   * @param {string} key the key to set the value of
+   * @param {T} value The value to set
+   * @param {number | string} [ttl] Time to Live - If you set a number it is miliseconds, if you set a string it is a human-readable
+   * format such as `1s` for 1 second or `1h` for 1 hour. Setting undefined means that it will use the default time-to-live. If both are
+   * undefined then it will not have a time-to-live.
+   * @returns {boolean} Whether the value was set
+   */
   async set(key, value, ttl) {
     let result = false;
     const finalTtl = shorthandToMilliseconds(ttl ?? this._ttl);
@@ -947,6 +1270,11 @@ var Cacheable = class extends import_hookified.Hookified {
     }
     return result;
   }
+  /**
+   * Sets the values of the keys. If the secondary store is set then it will also set the values in the secondary store.
+   * @param {CacheableItem[]} items The items to set
+   * @returns {boolean} Whether the values were set
+   */
   async setMany(items) {
     let result = false;
     try {
@@ -972,16 +1300,31 @@ var Cacheable = class extends import_hookified.Hookified {
     }
     return result;
   }
+  /**
+   * Takes the value of the key and deletes the key. If the key does not exist then it will return undefined.
+   * @param {string} key The key to take the value of
+   * @returns {Promise<T | undefined>} The value of the key or undefined if the key does not exist
+   */
   async take(key) {
     const result = await this.get(key);
     await this.delete(key);
     return result;
   }
+  /**
+   * Takes the values of the keys and deletes the keys. If the key does not exist then it will return undefined.
+   * @param {string[]} keys The keys to take the values of
+   * @returns {Promise<Array<T | undefined>>} The values of the keys or undefined if the key does not exist
+   */
   async takeMany(keys) {
     const result = await this.getMany(keys);
     await this.deleteMany(keys);
     return result;
   }
+  /**
+   * Checks if the key exists in the primary store. If it does not exist then it will check the secondary store.
+   * @param {string} key The key to check
+   * @returns {Promise<boolean>} Whether the key exists
+   */
   async has(key) {
     const promises = [];
     promises.push(this._primary.has(key));
@@ -996,6 +1339,11 @@ var Cacheable = class extends import_hookified.Hookified {
     }
     return false;
   }
+  /**
+   * Checks if the keys exist in the primary store. If it does not exist then it will check the secondary store.
+   * @param {string[]} keys The keys to check
+   * @returns {Promise<boolean[]>} Whether the keys exist
+   */
   async hasMany(keys) {
     const result = await this.hasManyKeyv(this._primary, keys);
     const missingKeys = [];
@@ -1014,6 +1362,11 @@ var Cacheable = class extends import_hookified.Hookified {
     }
     return result;
   }
+  /**
+   * Deletes the key from the primary store. If the secondary store is set then it will also delete the key from the secondary store.
+   * @param {string} key The key to delete
+   * @returns {Promise<boolean>} Whether the key was deleted
+   */
   async delete(key) {
     let result = false;
     const promises = [];
@@ -1038,6 +1391,11 @@ var Cacheable = class extends import_hookified.Hookified {
     }
     return result;
   }
+  /**
+   * Deletes the keys from the primary store. If the secondary store is set then it will also delete the keys from the secondary store.
+   * @param {string[]} keys The keys to delete
+   * @returns {Promise<boolean>} Whether the keys were deleted
+   */
   async deleteMany(keys) {
     if (this.stats.enabled) {
       const statResult = await this._primary.get(keys);
@@ -1058,6 +1416,10 @@ var Cacheable = class extends import_hookified.Hookified {
     }
     return result;
   }
+  /**
+   * Clears the primary store. If the secondary store is set then it will also clear the secondary store.
+   * @returns {Promise<void>}
+   */
   async clear() {
     const promises = [];
     promises.push(this._primary.clear());
@@ -1070,6 +1432,10 @@ var Cacheable = class extends import_hookified.Hookified {
       this._stats.incrementClears();
     }
   }
+  /**
+   * Disconnects the primary store. If the secondary store is set then it will also disconnect the secondary store.
+   * @returns {Promise<void>}
+   */
   async disconnect() {
     const promises = [];
     promises.push(this._primary.disconnect());
@@ -1078,6 +1444,14 @@ var Cacheable = class extends import_hookified.Hookified {
     }
     await (this._nonBlocking ? Promise.race(promises) : Promise.all(promises));
   }
+  /**
+   * Wraps a function with caching
+   *
+   * [Learn more about wrapping functions](https://cacheable.org/docs/cacheable/#wrap--memoization-for-sync-and-async-functions).
+   * @param {Function} function_ The function to wrap
+   * @param {WrapOptions} [options] The options for the wrap function
+   * @returns {Function} The wrapped function
+   */
   wrap(function_, options = {}) {
     const wrapOptions = {
       ttl: options.ttl,
@@ -1086,6 +1460,12 @@ var Cacheable = class extends import_hookified.Hookified {
     };
     return wrap(function_, wrapOptions);
   }
+  /**
+   * Will hash an object using the specified algorithm. The default algorithm is 'sha256'.
+   * @param {any} object the object to hash
+   * @param {string} algorithm the hash algorithm to use. The default is 'sha256'
+   * @returns {string} the hash of the object
+   */
   hash(object, algorithm = "sha256") {
     return hash(object, algorithm);
   }