cacheable 1.9.0 → 1.10.1

package/dist/index.d.cts

@@ -109,9 +109,21 @@ type CacheableStoreItem = {
     expires?: number;
 };
 
+type GetOrSetKey = string | ((options?: GetOrSetOptions) => string);
+type GetOrSetFunctionOptions = {
+    ttl?: number | string;
+    cacheErrors?: boolean;
+    throwErrors?: boolean;
+};
+type GetOrSetOptions = GetOrSetFunctionOptions & {
+    cacheId?: string;
+    cache: Cacheable;
+};
+type CreateWrapKey = (function_: AnyFunction, arguments_: any[], options?: WrapFunctionOptions) => string;
 type WrapFunctionOptions = {
     ttl?: number | string;
     keyPrefix?: string;
+    createKey?: CreateWrapKey;
     cacheErrors?: boolean;
     cacheId?: string;
 };
@@ -123,22 +135,33 @@ type WrapSyncOptions = WrapFunctionOptions & {
 };
 type AnyFunction = (...arguments_: any[]) => any;
 declare function wrapSync<T>(function_: AnyFunction, options: WrapSyncOptions): AnyFunction;
+declare function getOrSet<T>(key: GetOrSetKey, function_: () => Promise<T>, options: GetOrSetOptions): Promise<T | undefined>;
 declare function wrap<T>(function_: AnyFunction, options: WrapOptions): AnyFunction;
 
+declare enum StoreHashAlgorithm {
+    SHA256 = "sha256",
+    SHA1 = "sha1",
+    MD5 = "md5",
+    djb2Hash = "djb2Hash"
+}
+type StoreHashAlgorithmFunction = ((key: string, storeHashSize: number) => number);
 /**
  * @typedef {Object} CacheableMemoryOptions
  * @property {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.
  * @property {boolean} [useClone] - If true, it will clone the value before returning it. If false, it will return the value directly. Default is true.
- * @property {number} [lruSize] - The size of the LRU cache. If set to 0, it will not use LRU cache. Default is 0.
+ * @property {number} [lruSize] - The size of the LRU cache. If set to 0, it will not use LRU cache. Default is 0. If you are using LRU then the limit is based on Map() size 17mm.
  * @property {number} [checkInterval] - The interval to check for expired items. If set to 0, it will not check for expired items. Default is 0.
+ * @property {number} [storeHashSize] - The number of how many Map stores we have for the hash. Default is 10.
  */
 type CacheableMemoryOptions = {
     ttl?: number | string;
     useClone?: boolean;
     lruSize?: number;
     checkInterval?: number;
+    storeHashSize?: number;
+    storeHashAlgorithm?: StoreHashAlgorithm | ((key: string, storeHashSize: number) => number);
 };
 type SetOptions = {
     ttl?: number | string;
@@ -146,17 +169,9 @@ type SetOptions = {
 };
 declare class CacheableMemory extends Hookified {
     private _lru;
-    private readonly _hashCache;
-    private readonly _hash0;
-    private readonly _hash1;
-    private readonly _hash2;
-    private readonly _hash3;
-    private readonly _hash4;
-    private readonly _hash5;
-    private readonly _hash6;
-    private readonly _hash7;
-    private readonly _hash8;
-    private readonly _hash9;
+    private _storeHashSize;
+    private _storeHashAlgorithm;
+    private _store;
     private _ttl;
     private _useClone;
     private _lruSize;
@@ -189,12 +204,12 @@ declare class CacheableMemory extends Hookified {
     set useClone(value: boolean);
     /**
      * 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.
+     * @returns {number} - The size of the LRU cache. If set to 0, it will not use LRU cache. Default is 0. If you are using LRU then the limit is based on Map() size 17mm.
      */
     get lruSize(): number;
     /**
      * 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.
+     * @param {number} value - The size of the LRU cache. If set to 0, it will not use LRU cache. Default is 0. If you are using LRU then the limit is based on Map() size 17mm.
      */
     set lruSize(value: number);
     /**
@@ -212,6 +227,26 @@ declare class CacheableMemory extends Hookified {
      * @returns {number} - The size of the cache
      */
     get size(): number;
+    /**
+     * Gets the number of hash stores
+     * @returns {number} - The number of hash stores
+     */
+    get storeHashSize(): number;
+    /**
+     * Sets the number of hash stores. This will recreate the store and all data will be cleared
+     * @param {number} value - The number of hash stores
+     */
+    set storeHashSize(value: number);
+    /**
+     * Gets the store hash algorithm
+     * @returns {StoreHashAlgorithm | StoreHashAlgorithmFunction} - The store hash algorithm
+     */
+    get storeHashAlgorithm(): StoreHashAlgorithm | StoreHashAlgorithmFunction;
+    /**
+     * Sets the store hash algorithm. This will recreate the store and all data will be cleared
+     * @param {StoreHashAlgorithm | StoreHashAlgorithmFunction} value - The store hash algorithm
+     */
+    set storeHashAlgorithm(value: StoreHashAlgorithm | StoreHashAlgorithmFunction);
     /**
      * Gets the keys
      * @returns {IterableIterator<string>} - The keys
@@ -222,6 +257,11 @@ declare class CacheableMemory extends Hookified {
      * @returns {IterableIterator<CacheableStoreItem>} - The items
      */
     get items(): IterableIterator<CacheableStoreItem>;
+    /**
+     * Gets the store
+     * @returns {Array<Map<string, CacheableStoreItem>>} - The store
+     */
+    get store(): Array<Map<string, CacheableStoreItem>>;
     /**
      * Gets the value of the key
      * @param {string} key - The key to get the value
@@ -310,17 +350,12 @@ declare class CacheableMemory extends Hookified {
      */
     getStore(key: string): Map<string, CacheableStoreItem>;
     /**
-     * Get the store based on the hash (internal use)
-     * @param {number} hash
-     * @returns {Map<string, CacheableStoreItem>}
-     */
-    getStoreFromHash(hash: number): Map<string, CacheableStoreItem>;
-    /**
-     * Hash the key (internal use)
-     * @param key
-     * @returns {number} from 0 to 9
+     * Hash the key for which store to go to (internal use)
+     * @param {string} key - The key to hash
+     * Available algorithms are: SHA256, SHA1, MD5, and djb2Hash.
+     * @returns {number} - The hashed key as a number
      */
-    hashKey(key: string): number;
+    getKeyStoreHash(key: string): number;
     /**
      * Clone the value. This is for internal use
      * @param {any} value - The value to clone
@@ -340,7 +375,7 @@ declare class CacheableMemory extends Hookified {
      */
     lruMoveToFront(key: string): void;
     /**
-     * Resize the LRU cache. This is for internal use
+     * Resize the LRU cache. This is for internal use.
      * @returns {void}
      */
     lruResize(): void;
@@ -359,13 +394,6 @@ declare class CacheableMemory extends Hookified {
      * @returns {void}
      */
     stopIntervalCheck(): void;
-    /**
-     * 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: any, algorithm?: string): string;
     /**
      * Wrap the function for caching
      * @param {Function} function_ - The function to wrap
@@ -374,8 +402,8 @@ declare class CacheableMemory extends Hookified {
      */
     wrap<T, Arguments extends any[]>(function_: (...arguments_: Arguments) => T, options?: WrapFunctionOptions): (...arguments_: Arguments) => T;
     private isPrimitive;
-    private concatStores;
     private setTtl;
+    private hasExpired;
 }
 
 type KeyvCacheableMemoryOptions = CacheableMemoryOptions & {
@@ -592,6 +620,7 @@ declare class Cacheable extends Hookified {
      * @returns {void}
      */
     setSecondary(secondary: Keyv | KeyvStoreAdapter): void;
+    isKeyvInstance(keyv: any): boolean;
     getNameSpace(): string | undefined;
     /**
    * Retrieves an entry from the cache, with an optional “raw” mode.
@@ -704,6 +733,17 @@ declare class Cacheable extends Hookified {
      * @returns {Function} The wrapped function
      */
     wrap<T, Arguments extends any[]>(function_: (...arguments_: Arguments) => T, options?: WrapFunctionOptions): (...arguments_: Arguments) => T;
+    /**
+     * Retrieves the value associated with the given key from the cache. If the key is not found,
+     * invokes the provided function to calculate the value, stores it in the cache, and then returns it.
+     *
+     * @param {GetOrSetKey} key - The key to retrieve or set in the cache. This can also be a function that returns a string key.
+     * If a function is provided, it will be called with the cache options to generate the key.
+     * @param {() => Promise<T>} function_ - The asynchronous function that computes the value to be cached if the key does not exist.
+     * @param {GetOrSetFunctionOptions} [options] - Optional settings for caching, such as the time to live (TTL) or whether to cache errors.
+     * @return {Promise<T | undefined>} - A promise that resolves to the cached or newly computed value, or undefined if an error occurs and caching is not configured for errors.
+     */
+    getOrSet<T>(key: GetOrSetKey, function_: () => Promise<T>, options?: GetOrSetFunctionOptions): Promise<T | undefined>;
     /**
      * Will hash an object using the specified algorithm. The default algorithm is 'sha256'.
      * @param {any} object the object to hash
@@ -719,4 +759,4 @@ declare class Cacheable extends Hookified {
     private setTtl;
 }
 
-export { Cacheable, CacheableEvents, CacheableHooks, type CacheableItem, CacheableMemory, type CacheableMemoryOptions, type CacheableOptions, CacheableStats, KeyvCacheableMemory, type WrapOptions, type WrapSyncOptions, createKeyv, shorthandToMilliseconds, shorthandToTime, wrap, wrapSync };
+export { Cacheable, CacheableEvents, CacheableHooks, type CacheableItem, CacheableMemory, type CacheableMemoryOptions, type CacheableOptions, CacheableStats, type GetOrSetFunctionOptions, type GetOrSetKey, type GetOrSetOptions, KeyvCacheableMemory, type WrapOptions, type WrapSyncOptions, createKeyv, getOrSet, shorthandToMilliseconds, shorthandToTime, wrap, wrapSync };

package/dist/index.d.ts

@@ -109,9 +109,21 @@ type CacheableStoreItem = {
     expires?: number;
 };
 
+type GetOrSetKey = string | ((options?: GetOrSetOptions) => string);
+type GetOrSetFunctionOptions = {
+    ttl?: number | string;
+    cacheErrors?: boolean;
+    throwErrors?: boolean;
+};
+type GetOrSetOptions = GetOrSetFunctionOptions & {
+    cacheId?: string;
+    cache: Cacheable;
+};
+type CreateWrapKey = (function_: AnyFunction, arguments_: any[], options?: WrapFunctionOptions) => string;
 type WrapFunctionOptions = {
     ttl?: number | string;
     keyPrefix?: string;
+    createKey?: CreateWrapKey;
     cacheErrors?: boolean;
     cacheId?: string;
 };
@@ -123,22 +135,33 @@ type WrapSyncOptions = WrapFunctionOptions & {
 };
 type AnyFunction = (...arguments_: any[]) => any;
 declare function wrapSync<T>(function_: AnyFunction, options: WrapSyncOptions): AnyFunction;
+declare function getOrSet<T>(key: GetOrSetKey, function_: () => Promise<T>, options: GetOrSetOptions): Promise<T | undefined>;
 declare function wrap<T>(function_: AnyFunction, options: WrapOptions): AnyFunction;
 
+declare enum StoreHashAlgorithm {
+    SHA256 = "sha256",
+    SHA1 = "sha1",
+    MD5 = "md5",
+    djb2Hash = "djb2Hash"
+}
+type StoreHashAlgorithmFunction = ((key: string, storeHashSize: number) => number);
 /**
  * @typedef {Object} CacheableMemoryOptions
  * @property {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.
  * @property {boolean} [useClone] - If true, it will clone the value before returning it. If false, it will return the value directly. Default is true.
- * @property {number} [lruSize] - The size of the LRU cache. If set to 0, it will not use LRU cache. Default is 0.
+ * @property {number} [lruSize] - The size of the LRU cache. If set to 0, it will not use LRU cache. Default is 0. If you are using LRU then the limit is based on Map() size 17mm.
  * @property {number} [checkInterval] - The interval to check for expired items. If set to 0, it will not check for expired items. Default is 0.
+ * @property {number} [storeHashSize] - The number of how many Map stores we have for the hash. Default is 10.
  */
 type CacheableMemoryOptions = {
     ttl?: number | string;
     useClone?: boolean;
     lruSize?: number;
     checkInterval?: number;
+    storeHashSize?: number;
+    storeHashAlgorithm?: StoreHashAlgorithm | ((key: string, storeHashSize: number) => number);
 };
 type SetOptions = {
     ttl?: number | string;
@@ -146,17 +169,9 @@ type SetOptions = {
 };
 declare class CacheableMemory extends Hookified {
     private _lru;
-    private readonly _hashCache;
-    private readonly _hash0;
-    private readonly _hash1;
-    private readonly _hash2;
-    private readonly _hash3;
-    private readonly _hash4;
-    private readonly _hash5;
-    private readonly _hash6;
-    private readonly _hash7;
-    private readonly _hash8;
-    private readonly _hash9;
+    private _storeHashSize;
+    private _storeHashAlgorithm;
+    private _store;
     private _ttl;
     private _useClone;
     private _lruSize;
@@ -189,12 +204,12 @@ declare class CacheableMemory extends Hookified {
     set useClone(value: boolean);
     /**
      * 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.
+     * @returns {number} - The size of the LRU cache. If set to 0, it will not use LRU cache. Default is 0. If you are using LRU then the limit is based on Map() size 17mm.
      */
     get lruSize(): number;
     /**
      * 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.
+     * @param {number} value - The size of the LRU cache. If set to 0, it will not use LRU cache. Default is 0. If you are using LRU then the limit is based on Map() size 17mm.
      */
     set lruSize(value: number);
     /**
@@ -212,6 +227,26 @@ declare class CacheableMemory extends Hookified {
      * @returns {number} - The size of the cache
      */
     get size(): number;
+    /**
+     * Gets the number of hash stores
+     * @returns {number} - The number of hash stores
+     */
+    get storeHashSize(): number;
+    /**
+     * Sets the number of hash stores. This will recreate the store and all data will be cleared
+     * @param {number} value - The number of hash stores
+     */
+    set storeHashSize(value: number);
+    /**
+     * Gets the store hash algorithm
+     * @returns {StoreHashAlgorithm | StoreHashAlgorithmFunction} - The store hash algorithm
+     */
+    get storeHashAlgorithm(): StoreHashAlgorithm | StoreHashAlgorithmFunction;
+    /**
+     * Sets the store hash algorithm. This will recreate the store and all data will be cleared
+     * @param {StoreHashAlgorithm | StoreHashAlgorithmFunction} value - The store hash algorithm
+     */
+    set storeHashAlgorithm(value: StoreHashAlgorithm | StoreHashAlgorithmFunction);
     /**
      * Gets the keys
      * @returns {IterableIterator<string>} - The keys
@@ -222,6 +257,11 @@ declare class CacheableMemory extends Hookified {
      * @returns {IterableIterator<CacheableStoreItem>} - The items
      */
     get items(): IterableIterator<CacheableStoreItem>;
+    /**
+     * Gets the store
+     * @returns {Array<Map<string, CacheableStoreItem>>} - The store
+     */
+    get store(): Array<Map<string, CacheableStoreItem>>;
     /**
      * Gets the value of the key
      * @param {string} key - The key to get the value
@@ -310,17 +350,12 @@ declare class CacheableMemory extends Hookified {
      */
     getStore(key: string): Map<string, CacheableStoreItem>;
     /**
-     * Get the store based on the hash (internal use)
-     * @param {number} hash
-     * @returns {Map<string, CacheableStoreItem>}
-     */
-    getStoreFromHash(hash: number): Map<string, CacheableStoreItem>;
-    /**
-     * Hash the key (internal use)
-     * @param key
-     * @returns {number} from 0 to 9
+     * Hash the key for which store to go to (internal use)
+     * @param {string} key - The key to hash
+     * Available algorithms are: SHA256, SHA1, MD5, and djb2Hash.
+     * @returns {number} - The hashed key as a number
      */
-    hashKey(key: string): number;
+    getKeyStoreHash(key: string): number;
     /**
      * Clone the value. This is for internal use
      * @param {any} value - The value to clone
@@ -340,7 +375,7 @@ declare class CacheableMemory extends Hookified {
      */
     lruMoveToFront(key: string): void;
     /**
-     * Resize the LRU cache. This is for internal use
+     * Resize the LRU cache. This is for internal use.
      * @returns {void}
      */
     lruResize(): void;
@@ -359,13 +394,6 @@ declare class CacheableMemory extends Hookified {
      * @returns {void}
      */
     stopIntervalCheck(): void;
-    /**
-     * 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: any, algorithm?: string): string;
     /**
      * Wrap the function for caching
      * @param {Function} function_ - The function to wrap
@@ -374,8 +402,8 @@ declare class CacheableMemory extends Hookified {
      */
     wrap<T, Arguments extends any[]>(function_: (...arguments_: Arguments) => T, options?: WrapFunctionOptions): (...arguments_: Arguments) => T;
     private isPrimitive;
-    private concatStores;
     private setTtl;
+    private hasExpired;
 }
 
 type KeyvCacheableMemoryOptions = CacheableMemoryOptions & {
@@ -592,6 +620,7 @@ declare class Cacheable extends Hookified {
      * @returns {void}
      */
     setSecondary(secondary: Keyv | KeyvStoreAdapter): void;
+    isKeyvInstance(keyv: any): boolean;
     getNameSpace(): string | undefined;
     /**
    * Retrieves an entry from the cache, with an optional “raw” mode.
@@ -704,6 +733,17 @@ declare class Cacheable extends Hookified {
      * @returns {Function} The wrapped function
      */
     wrap<T, Arguments extends any[]>(function_: (...arguments_: Arguments) => T, options?: WrapFunctionOptions): (...arguments_: Arguments) => T;
+    /**
+     * Retrieves the value associated with the given key from the cache. If the key is not found,
+     * invokes the provided function to calculate the value, stores it in the cache, and then returns it.
+     *
+     * @param {GetOrSetKey} key - The key to retrieve or set in the cache. This can also be a function that returns a string key.
+     * If a function is provided, it will be called with the cache options to generate the key.
+     * @param {() => Promise<T>} function_ - The asynchronous function that computes the value to be cached if the key does not exist.
+     * @param {GetOrSetFunctionOptions} [options] - Optional settings for caching, such as the time to live (TTL) or whether to cache errors.
+     * @return {Promise<T | undefined>} - A promise that resolves to the cached or newly computed value, or undefined if an error occurs and caching is not configured for errors.
+     */
+    getOrSet<T>(key: GetOrSetKey, function_: () => Promise<T>, options?: GetOrSetFunctionOptions): Promise<T | undefined>;
     /**
      * Will hash an object using the specified algorithm. The default algorithm is 'sha256'.
      * @param {any} object the object to hash
@@ -719,4 +759,4 @@ declare class Cacheable extends Hookified {
     private setTtl;
 }
 
-export { Cacheable, CacheableEvents, CacheableHooks, type CacheableItem, CacheableMemory, type CacheableMemoryOptions, type CacheableOptions, CacheableStats, KeyvCacheableMemory, type WrapOptions, type WrapSyncOptions, createKeyv, shorthandToMilliseconds, shorthandToTime, wrap, wrapSync };
+export { Cacheable, CacheableEvents, CacheableHooks, type CacheableItem, CacheableMemory, type CacheableMemoryOptions, type CacheableOptions, CacheableStats, type GetOrSetFunctionOptions, type GetOrSetKey, type GetOrSetOptions, KeyvCacheableMemory, type WrapOptions, type WrapSyncOptions, createKeyv, getOrSet, shorthandToMilliseconds, shorthandToTime, wrap, wrapSync };