cacheable 1.7.1 → 1.8.1

package/dist/index.d.cts

@@ -1,4 +1,5 @@
 import { KeyvStoreAdapter, StoredData, Keyv } from 'keyv';
+export { Keyv, KeyvHooks, KeyvOptions, KeyvStoreAdapter } from 'keyv';
 import { Hookified } from 'hookified';
 
 type CacheableOptions$1 = {
@@ -16,16 +17,58 @@ declare class CacheableStats {
     private _count;
     private _enabled;
     constructor(options?: CacheableOptions$1);
+    /**
+     * @returns {boolean} - Whether the stats are enabled
+     */
     get enabled(): boolean;
+    /**
+     * @param {boolean} enabled - Whether to enable the stats
+     */
     set enabled(enabled: boolean);
+    /**
+     * @returns {number} - The number of hits
+     * @readonly
+     */
     get hits(): number;
+    /**
+     * @returns {number} - The number of misses
+     * @readonly
+     */
     get misses(): number;
+    /**
+     * @returns {number} - The number of gets
+     * @readonly
+     */
     get gets(): number;
+    /**
+     * @returns {number} - The number of sets
+     * @readonly
+     */
     get sets(): number;
+    /**
+     * @returns {number} - The number of deletes
+     * @readonly
+     */
     get deletes(): number;
+    /**
+     * @returns {number} - The number of clears
+     * @readonly
+     */
     get clears(): number;
+    /**
+     * @returns {number} - The vsize (value size) of the cache instance
+     * @readonly
+     */
     get vsize(): number;
+    /**
+     * @returns {number} - The ksize (key size) of the cache instance
+     * @readonly
+     */
     get ksize(): number;
+    /**
+     * @returns {number} - The count of the cache instance
+     * @readonly
+     */
     get count(): number;
     incrementHits(): void;
     incrementMisses(): void;
@@ -46,6 +89,15 @@ declare class CacheableStats {
     resetStoreValues(): void;
 }
 
+/**
+ * CacheableItem
+ * @typedef {Object} CacheableItem
+ * @property {string} key - The key of the cacheable item
+ * @property {any} value - The value of the cacheable item
+ * @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.
+ */
 type CacheableItem = {
     key: string;
     value: any;
@@ -57,6 +109,15 @@ type CacheableStoreItem = {
     expires?: 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} [checkInterval] - The interval to check for expired items. If set to 0, it will not check for expired items. Default is 0.
+ */
 type CacheableMemoryOptions = {
     ttl?: number | string;
     useClone?: boolean;
@@ -81,39 +142,213 @@ declare class CacheableMemory {
     private _lruSize;
     private _checkInterval;
     private _interval;
+    /**
+     * @constructor
+     * @param {CacheableMemoryOptions} [options] - The options for the CacheableMemory
+     */
     constructor(options?: CacheableMemoryOptions);
+    /**
+     * 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(): number | string | undefined;
+    /**
+     * 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: number | string | undefined);
+    /**
+     * 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(): boolean;
+    /**
+     * 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: 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.
+     */
     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.
+     */
     set lruSize(value: number);
+    /**
+     * 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(): number;
+    /**
+     * 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: number);
+    /**
+     * Gets the size of the cache
+     * @returns {number} - The size of the cache
+     */
     get size(): number;
+    /**
+     * Gets the keys
+     * @returns {IterableIterator<string>} - The keys
+     */
     get keys(): IterableIterator<string>;
+    /**
+     * Gets the items
+     * @returns {IterableIterator<CacheableStoreItem>} - The items
+     */
     get items(): IterableIterator<CacheableStoreItem>;
-    get<T>(key: string): any;
-    getMany<T>(keys: string[]): any[];
+    /**
+     * Gets the value of the key
+     * @param {string} key - The key to get the value
+     * @returns {T | undefined} - The value of the key
+     */
+    get<T>(key: string): T | undefined;
+    /**
+     * Gets the values of the keys
+     * @param {string[]} keys - The keys to get the values
+     * @returns {T[]} - The values of the keys
+     */
+    getMany<T>(keys: string[]): T[];
+    /**
+     * 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: string): CacheableStoreItem | undefined;
+    /**
+     * 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: string[]): Array<CacheableStoreItem | undefined>;
+    /**
+     * 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: string, value: any, ttl?: number | string): void;
+    /**
+     * Sets the values of the keys
+     * @param {CacheableItem[]} items - The items to set
+     * @returns {void}
+     */
     setMany(items: CacheableItem[]): void;
+    /**
+     * 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: string): boolean;
-    take<T>(key: string): any;
-    takeMany<T>(keys: string[]): any[];
+    /**
+     * @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: string[]): boolean[];
+    /**
+     * 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<T>(key: string): T | undefined;
+    /**
+     * 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<T>(keys: string[]): T[];
+    /**
+     * Delete the key
+     * @param {string} key - The key to delete
+     * @returns {void}
+     */
     delete(key: string): void;
+    /**
+     * Delete the keys
+     * @param {string[]} keys - The keys to delete
+     * @returns {void}
+     */
     deleteMany(keys: string[]): void;
+    /**
+     * Clear the cache
+     * @returns {void}
+     */
     clear(): void;
+    /**
+     * 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: string): number;
+    /**
+     * 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: string): Map<string, any>;
+    /**
+     * Clone the value. This is for internal use
+     * @param {any} value - The value to clone
+     * @returns {any} - The cloned value
+     */
     clone(value: any): any;
+    /**
+     * 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: string): void;
+    /**
+     * 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: string): void;
+    /**
+     * Resize the LRU cache. This is for internal use
+     * @returns {void}
+     */
     lruResize(): void;
+    /**
+     * Check for expiration. This is for internal use
+     * @returns {void}
+     */
     checkExpiration(): void;
+    /**
+     * Start the interval check. This is for internal use
+     * @returns {void}
+     */
     startIntervalCheck(): void;
+    /**
+     * Stop the interval check. This is for internal use
+     * @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
+     * @param {Object} [options] - The options to wrap
+     * @returns {Function} - The wrapped function
+     */
+    wrap<T>(function_: (...arguments_: any[]) => T, options?: {
+        ttl?: number;
+        key?: string;
+    }): (...arguments_: any[]) => T;
     private isPrimitive;
     private concatStores;
     private setTtl;
@@ -142,6 +377,20 @@ declare class KeyvCacheableMemory implements KeyvStoreAdapter {
 declare const shorthandToMilliseconds: (shorthand?: string | number) => number | undefined;
 declare const shorthandToTime: (shorthand?: string | number, fromDate?: Date) => number;
 
+type WrapOptions = {
+    ttl?: number | string;
+    key?: string;
+    cache: Cacheable;
+};
+type WrapSyncOptions = {
+    ttl?: number | string;
+    key?: string;
+    cache: CacheableMemory;
+};
+type AnyFunction = (...arguments_: any[]) => any;
+declare function wrapSync<T>(function_: AnyFunction, options: WrapSyncOptions): AnyFunction;
+declare function wrap<T>(function_: AnyFunction, options: WrapOptions): AnyFunction;
+
 declare enum CacheableHooks {
     BEFORE_SET = "BEFORE_SET",
     AFTER_SET = "AFTER_SET",
@@ -168,34 +417,201 @@ declare class Cacheable extends Hookified {
     private _nonBlocking;
     private _ttl?;
     private readonly _stats;
+    /**
+     * Creates a new cacheable instance
+     * @param {CacheableOptions} [options] The options for the cacheable instance
+     */
     constructor(options?: CacheableOptions);
+    /**
+     * The statistics for the cacheable instance
+     * @returns {CacheableStats} The statistics for the cacheable instance
+     */
     get stats(): CacheableStats;
+    /**
+     * The primary store for the cacheable instance
+     * @returns {Keyv} The primary store for the cacheable instance
+     */
     get primary(): Keyv;
+    /**
+     * Sets the primary store for the cacheable instance
+     * @param {Keyv} primary The primary store for the cacheable instance
+     */
     set primary(primary: Keyv);
+    /**
+     * The secondary store for the cacheable instance
+     * @returns {Keyv | undefined} The secondary store for the cacheable instance
+     */
     get secondary(): Keyv | undefined;
+    /**
+     * 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: Keyv | undefined);
+    /**
+     * 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(): boolean;
+    /**
+     * 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: boolean);
+    /**
+     * 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(): number | string | undefined;
+    /**
+     * 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: number | string | undefined);
+    /**
+     * Sets the primary store for the cacheable instance
+     * @param {Keyv | KeyvStoreAdapter} primary The primary store for the cacheable instance
+     * @returns {void}
+     */
     setPrimary(primary: Keyv | KeyvStoreAdapter): void;
+    /**
+     * 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: Keyv | KeyvStoreAdapter): void;
+    /**
+     * 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
+     */
     get<T>(key: string): Promise<T | undefined>;
+    /**
+     * 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
+     */
     getMany<T>(keys: string[]): Promise<Array<T | undefined>>;
-    set<T>(key: string, value: T, ttl?: number): Promise<boolean>;
+    /**
+     * 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
+     */
+    set<T>(key: string, value: T, ttl?: number | string): Promise<boolean>;
+    /**
+     * 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
+     */
     setMany(items: CacheableItem[]): Promise<boolean>;
+    /**
+     * 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
+     */
     take<T>(key: string): Promise<T | undefined>;
+    /**
+     * 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
+     */
     takeMany<T>(keys: string[]): Promise<Array<T | undefined>>;
+    /**
+     * 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
+     */
     has(key: string): Promise<boolean>;
+    /**
+     * 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
+     */
     hasMany(keys: string[]): Promise<boolean[]>;
+    /**
+     * 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
+     */
     delete(key: string): Promise<boolean>;
+    /**
+     * 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
+     */
     deleteMany(keys: string[]): Promise<boolean>;
+    /**
+     * Clears the primary store. If the secondary store is set then it will also clear the secondary store.
+     * @returns {Promise<void>}
+     */
     clear(): Promise<void>;
+    /**
+     * Disconnects the primary store. If the secondary store is set then it will also disconnect the secondary store.
+     * @returns {Promise<void>}
+     */
     disconnect(): Promise<void>;
+    /**
+     * 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<T>(function_: (...arguments_: any[]) => T, options?: {
+        ttl?: number;
+        key?: string;
+    }): (...arguments_: any[]) => T;
+    /**
+     * 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: any, algorithm?: string): string;
     private deleteManyKeyv;
     private setManyKeyv;
     private hasManyKeyv;
     private setTtl;
 }
 
-export { Cacheable, CacheableEvents, CacheableHooks, type CacheableItem, CacheableMemory, type CacheableOptions, CacheableStats, KeyvCacheableMemory, shorthandToMilliseconds, shorthandToTime };
+export { Cacheable, CacheableEvents, CacheableHooks, type CacheableItem, CacheableMemory, type CacheableOptions, CacheableStats, KeyvCacheableMemory, type WrapOptions, type WrapSyncOptions, shorthandToMilliseconds, shorthandToTime, wrap, wrapSync };