@cacheable/node-cache 1.4.0 → 1.4.2

package/README.md

@@ -6,8 +6,9 @@
 
 [![codecov](https://codecov.io/gh/jaredwray/cacheable/graph/badge.svg?token=lWZ9OBQ7GM)](https://codecov.io/gh/jaredwray/cacheable)
 [![tests](https://github.com/jaredwray/cacheable/actions/workflows/tests.yml/badge.svg)](https://github.com/jaredwray/cacheable/actions/workflows/tests.yml)
-[![npm](https://img.shields.io/npm/dm/cacheable.svg)](https://www.npmjs.com/package/cacheable)
-[![npm](https://img.shields.io/npm/v/cacheable)](https://www.npmjs.com/package/cacheable)
+[![npm](https://img.shields.io/npm/dm/@cacheable/node-cache.svg)](https://www.npmjs.com/package/@cacheable/node-cache)
+[![npm](https://img.shields.io/npm/v/@cacheable/node-cache)](https://www.npmjs.com/package/@cacheable/node-cache)
+[![license](https://img.shields.io/github/license/jaredwray/cacheable)](https://github.com/jaredwray/cacheable/blob/main/LICENSE)
 
 `@cacheable/node-cache` is compatible with the [node-cache](https://www.npmjs.com/package/node-cache) package with regular maintenance and additional functionality (async/await and storage adapters). The only thing not implemented is the `enableLegacyCallbacks` option and functions. If you need them we are happy to take a PR to add them.
 
@@ -18,7 +19,7 @@
 
 Note: `NodeCache` is ready and available for use. `NodeCacheStore` is in progress and will be available soon. Please do not use it until it is released.
 
-## Table of Contents
+# Table of Contents
 * [Getting Started](#getting-started)
 * [Basic Usage](#basic-usage)
 * [Advanced Usage](#advanced-usage)
@@ -27,13 +28,13 @@ Note: `NodeCache` is ready and available for use. `NodeCacheStore` is in progres
 * [How to Contribute](#how-to-contribute)
 * [License and Copyright](#license-and-copyright)
 
-## Getting Started
+# Getting Started
 
 ```bash
 npm install @cacheable/node-cache --save
 ```
 
-## Basic Usage
+# Basic Usage
 
 ```javascript
 import {NodeCache} from '@cacheable/node-cache';
@@ -43,7 +44,7 @@ cache.set('foo', 'bar');
 cache.get('foo'); // 'bar'
 ```
 
-## Advanced Usage
+# Advanced Usage
 
 ```javascript
 import {NodeStorageCache} from '@cacheable/node-cache';
@@ -61,7 +62,7 @@ await cache.get('foo'); // 'bar'
 cache.getStats(); // {hits: 1, misses: 1, keys: 1, ksize: 2, vsize: 3}
 ```
 
-## NodeCacheStore
+# NodeCacheStore
 
 The `NodeCacheStore` is a class that extends the `NodeCache` and adds the ability to use storage adapters. This is based on the `cacheable` engine and allows you to do layer 1 and layer 2 caching. The storage adapters are based on the [Keyv](https://keyv.org) package. This allows you to use any of the storage adapters that are available.
 
@@ -73,7 +74,7 @@ cache.set('foo', 'bar');
 cache.get('foo'); // 'bar'
 ```
 
-### NodeCacheStoreOptions
+## NodeCacheStoreOptions
 
 When initializing the cache you can pass in the options below:
 
@@ -94,7 +95,7 @@ cache.set('foo', 'bar', '1h'); // 1 hour
 cache.set('longfoo', 'bar', '1d'); // 1 day
 ```
 
-### Node Cache Store API
+## Node Cache Store API
 
 * `set(key: string | number, value: any, ttl?: number): Promise<boolean>` - Set a key value pair with an optional ttl (in milliseconds). Will return true on success. If the ttl is not set it will default to 0 (no ttl)
 * `mset(data: Array<NodeCacheItem>): Promise<boolean>` - Set multiple key value pairs at once
@@ -112,9 +113,9 @@ cache.set('longfoo', 'bar', '1d'); // 1 day
 * `secondary`: `Keyv` - The secondary storage adapter
 * `maxKeys`: `number` - If this is set it will throw and error if you try to set more keys than the max
 
-## API
+# API
 
-### `constructor(options?: NodeCacheOptions)`
+## `constructor(options?: NodeCacheOptions)`
 
 Create a new cache instance. You can pass in options to set the configuration:
 
@@ -143,7 +144,7 @@ cache.on('expired', (key, value) => {
 });
 ```
 
-### `.set(key: string | number, value: any, ttl?: number): boolean`
+## `.set(key: string | number, value: any, ttl?: number): boolean`
 
 Set a key value pair with an optional ttl (in seconds). Will return true on success. If the ttl is not set it will default to 0 (no ttl).
 
@@ -151,7 +152,7 @@ Set a key value pair with an optional ttl (in seconds). Will return true on succ
 cache.set('foo', 'bar', 10); // true
 ```
 
-### `.mset(data: Array<NodeCacheItem>): boolean`
+## `.mset(data: Array<NodeCacheItem>): boolean`
 
 Set multiple key value pairs at once. This will take an array of objects with the key, value, and optional ttl.
 
@@ -169,7 +170,7 @@ export type NodeCacheItem = {
 };
 ```
 
-### `.get(key: string | number): any`
+## `.get(key: string | number): any`
 
 Get a value from the cache by key. If the key does not exist it will return `undefined`.
 
@@ -177,7 +178,7 @@ Get a value from the cache by key. If the key does not exist it will return `und
 cache.get('foo'); // 'bar'
 ```
 
-### `mget(keys: Array<string | number>): Record<string, unknown>`
+## `mget(keys: Array<string | number>): Record<string, unknown>`
 
 Get multiple values from the cache by keys. This will return an object with the keys and values.
 
@@ -189,7 +190,7 @@ cache.set('my2', obj2);
 cache.mget(['my', 'my2']); // { my: { my: 'value', my2: 'value2' }, my2: { special: 'value3', life: 'value4' } }
 ```
 
-### `take(key: string | number): any`
+## `take(key: string | number): any`
 
 Get a value from the cache by key and delete it. If the key does not exist it will return `undefined`.
 
@@ -199,7 +200,7 @@ cache.take('foo'); // 'bar'
 cache.get('foo'); // undefined
 ```
 
-### `del(key: string | number | Array<string | number>): number`
+## `del(key: string | number | Array<string | number>): number`
 
 Delete a key from the cache. Will return the number of deleted entries and never fail. You can also pass in an array of keys to delete multiple keys. All examples assume that you have initialized the cache like `const cache = new NodeCache();`.
 
@@ -213,7 +214,7 @@ passing in an array of keys:
 cache.del(['foo', 'bar']); // true
 ```
 
-### `.mdel(keys: Array<string | number>): number`
+## `.mdel(keys: Array<string | number>): number`
 
 Delete multiple keys from the cache. Will return the number of deleted entries and never fail.
 
@@ -221,7 +222,7 @@ Delete multiple keys from the cache. Will return the number of deleted entries a
 cache.mdel(['foo', 'bar']); // true
 ```
 
-### `.ttl(key: string | number, ttl?: number): boolean`
+## `.ttl(key: string | number, ttl?: number): boolean`
 
 Redefine the ttl of a key. Returns true if the key has been found and changed. Otherwise returns false. If the ttl-argument isn't passed the default-TTL will be used.
 
@@ -229,7 +230,7 @@ Redefine the ttl of a key. Returns true if the key has been found and changed. O
 cache.ttl('foo', 10); // true
 ```
 
-### `getTtl(key: string | number): number | undefined`
+## `getTtl(key: string | number): number | undefined`
 
 Get the ttl expiration from `Date.now()` of a key. If the key does not exist it will return `undefined`.
 
@@ -237,7 +238,7 @@ Get the ttl expiration from `Date.now()` of a key. If the key does not exist it
 cache.getTtl('foo'); // 1725993344859
 ```
 
-### `has(key: string | number): boolean`
+## `has(key: string | number): boolean`
 
 Check if a key exists in the cache.
 
@@ -246,7 +247,7 @@ cache.set('foo', 'bar');
 cache.has('foo'); // true
 ```
 
-### `keys(): Array<string>`
+## `keys(): Array<string>`
 
 Get all keys from the cache.
 
@@ -254,7 +255,7 @@ Get all keys from the cache.
 cache.keys(); // ['foo', 'bar']
 ```
 
-### `getStats(): NodeCacheStats`
+## `getStats(): NodeCacheStats`
 
 Get the stats of the cache.
 
@@ -262,7 +263,7 @@ Get the stats of the cache.
 cache.getStats(); // {hits: 1, misses: 1, keys: 1, ksize: 2, vsize: 3}
 ```
 
-### `flushAll(): void`
+## `flushAll(): void`
 
 Flush the cache. Will remove all keys and reset the stats.
 
@@ -272,7 +273,7 @@ cache.keys(); // []
 cache.getStats(); // {hits: 0, misses: 0, keys: 0, ksize: 0, vsize: 0}
 ```
 
-### `flushStats(): void`
+## `flushStats(): void`
 
 Flush the stats. Will reset the stats but keep the keys.
 
@@ -283,7 +284,7 @@ cache.getStats(); // {hits: 0, misses: 0, keys: 0, ksize: 0, vsize: 0}
 cache.keys(); // ['foo']
 ```
 
-### `close(): void`
+## `close(): void`
 
 this will stop the interval that is running for the `checkperiod` and `deleteOnExpire` options.
 
@@ -291,7 +292,7 @@ this will stop the interval that is running for the `checkperiod` and `deleteOnE
 cache.close();
 ```
 
-### `on(event: string, callback: Function): void`
+## `on(event: string, callback: Function): void`
 
 Listen to events. Here are the events that you can listen to:
 * `set` - when a key is set and it will pass in the `key` and `value`.
@@ -306,9 +307,9 @@ cache.on('set', (key, value) => {
 });
 ```
 
-## How to Contribute
+# How to Contribute
 
 You can contribute by forking the repo and submitting a pull request. Please make sure to add tests and update the documentation. To learn more about how to contribute go to our main README [https://github.com/jaredwray/cacheable](https://github.com/jaredwray/cacheable). This will talk about how to `Open a Pull Request`, `Ask a Question`, or `Post an Issue`.
 
-## License and Copyright
+# License and Copyright
 [MIT © Jared Wray](./LICENSE)

package/dist/index.cjs

@@ -60,36 +60,87 @@ var NodeCacheStore = class {
       }
     }
   }
+  /**
+   * Cacheable instance.
+   * @returns {Cacheable}
+   * @readonly
+   */
   get cache() {
     return this._cache;
   }
+  /**
+   * Time to live in milliseconds.
+   * @returns {number | string | undefined}
+   * @readonly
+   */
   get ttl() {
     return this._cache.ttl;
   }
+  /**
+   * Time to live in milliseconds.
+   * @param {number | string | undefined} ttl
+   */
   set ttl(ttl) {
     this._cache.ttl = ttl;
   }
+  /**
+   * Primary cache store.
+   * @returns {Keyv}
+   * @readonly
+   */
   get primary() {
     return this._cache.primary;
   }
+  /**
+   * Primary cache store.
+   * @param {Keyv} primary
+   */
   set primary(primary) {
     this._cache.primary = primary;
   }
+  /**
+   * Secondary cache store. Learn more about the secondary cache store in the
+   * [cacheable](https://github.com/jaredwray/cacheable/tree/main/packages/cacheable#storage-tiering-and-caching) documentation.
+   * @returns {Keyv | undefined}
+   */
   get secondary() {
     return this._cache.secondary;
   }
+  /**
+   * Secondary cache store. Learn more about the secondary cache store in the
+   * [cacheable](https://github.com/jaredwray/cacheable/tree/main/packages/cacheable#storage-tiering-and-caching) documentation.
+   * @param {Keyv | undefined} secondary
+   */
   set secondary(secondary) {
     this._cache.secondary = secondary;
   }
+  /**
+   * Maximum number of keys to store in the cache. if this is set to a value greater than 0,
+   * the cache will keep track of the number of keys and will not store more than the specified number of keys.
+   * @returns {number}
+   * @readonly
+   */
   get maxKeys() {
     return this._maxKeys;
   }
+  /**
+   * Maximum number of keys to store in the cache. if this is set to a value greater than 0,
+   * the cache will keep track of the number of keys and will not store more than the specified number of keys.
+   * @param {number} maxKeys
+   */
   set maxKeys(maxKeys) {
     this._maxKeys = maxKeys;
     if (this._maxKeys > 0) {
       this._cache.stats.enabled = true;
     }
   }
+  /**
+   * Set a key/value pair in the cache.
+   * @param {string | number} key
+   * @param {any} value
+   * @param {number} [ttl]
+   * @returns {boolean}
+   */
   async set(key, value, ttl) {
     if (this._maxKeys > 0) {
       if (this._cache.stats.count >= this._maxKeys) {
@@ -99,6 +150,11 @@ var NodeCacheStore = class {
     await this._cache.set(key.toString(), value, ttl);
     return true;
   }
+  /**
+   * Set multiple key/value pairs in the cache.
+   * @param {NodeCacheItem[]} list
+   * @returns {void}
+   */
   async mset(list) {
     const items = new Array();
     for (const item of list) {
@@ -106,9 +162,19 @@ var NodeCacheStore = class {
     }
     await this._cache.setMany(items);
   }
+  /**
+   * Get a value from the cache.
+   * @param {string | number} key
+   * @returns {any | undefined}
+   */
   async get(key) {
     return this._cache.get(key.toString());
   }
+  /**
+   * Get multiple values from the cache.
+   * @param {Array<string | number>} keys
+   * @returns {Record<string, any | undefined>}
+   */
   async mget(keys) {
     const result = {};
     for (const key of keys) {
@@ -116,15 +182,34 @@ var NodeCacheStore = class {
     }
     return result;
   }
+  /**
+   * Delete a key from the cache.
+   * @param {string | number} key
+   * @returns {boolean}
+   */
   async del(key) {
     return this._cache.delete(key.toString());
   }
+  /**
+   * Delete multiple keys from the cache.
+   * @param {Array<string | number>} keys
+   * @returns {boolean}
+   */
   async mdel(keys) {
     return this._cache.deleteMany(keys.map((key) => key.toString()));
   }
+  /**
+   * Clear the cache.
+   * @returns {void}
+   */
   async clear() {
     return this._cache.clear();
   }
+  /**
+   * Check if a key exists in the cache.
+   * @param {string | number} key
+   * @returns {boolean}
+   */
   async setTtl(key, ttl) {
     const item = await this._cache.get(key.toString());
     if (item) {
@@ -133,9 +218,18 @@ var NodeCacheStore = class {
     }
     return false;
   }
+  /**
+   * Check if a key exists in the cache. If it does exist it will get the value and delete the item from the cache.
+   * @param {string | number} key
+   * @returns {any | undefined}
+   */
   async take(key) {
     return this._cache.take(key.toString());
   }
+  /**
+   * Disconnect from the cache.
+   * @returns {void}
+   */
   async disconnect() {
     await this._cache.disconnect();
   }
@@ -169,7 +263,13 @@ var NodeCache = class extends import_eventemitter3.default {
     }
     this.startInterval();
   }
-  // Sets a key value pair. It is possible to define a ttl (in seconds). Returns true on success.
+  /**
+   * Sets a key value pair. It is possible to define a ttl (in seconds). Returns true on success.
+   * @param {string | number} key - it will convert the key to a string
+   * @param {any} value
+   * @param {number} [ttl] - this is in seconds and undefined will use the default ttl
+   * @returns {boolean}
+   */
   set(key, value, ttl) {
     if (typeof key !== "string" && typeof key !== "number") {
       throw this.createError("The key argument has to be of type `string` or `number`. Found: `__key`" /* EKEYTYPE */, key);
@@ -196,7 +296,11 @@ var NodeCache = class extends import_eventemitter3.default {
     this._stats.setCount(this.store.size);
     return true;
   }
-  // Sets multiple key val pairs. It is possible to define a ttl (seconds). Returns true on success.
+  /**
+   * Sets multiple key val pairs. It is possible to define a ttl (seconds). Returns true on success.
+   * @param {NodeCacheItem[]} data an array of key value pairs with optional ttl
+   * @returns {boolean}
+   */
   mset(data) {
     if (!Array.isArray(data)) {
       throw this.createError("The keys argument has to be an array." /* EKEYSTYPE */);
@@ -206,7 +310,11 @@ var NodeCache = class extends import_eventemitter3.default {
     }
     return true;
   }
-  // Gets a saved value from the cache. Returns a undefined if not found or expired. If the value was found it returns the value.
+  /**
+   * Gets a saved value from the cache. Returns a undefined if not found or expired. If the value was found it returns the value.
+   * @param {string | number} key if the key is a number it will convert it to a string
+   * @returns {T} the value or undefined
+   */
   get(key) {
     const result = this.store.get(this.formatKey(key));
     if (result) {
@@ -234,10 +342,12 @@ var NodeCache = class extends import_eventemitter3.default {
     this._stats.incrementMisses();
     return void 0;
   }
-  /*
-  	Gets multiple saved values from the cache. Returns an empty object {} if not found or expired.
-  	If the value was found it returns an object with the key value pair.
-  */
+  /**
+   * Gets multiple saved values from the cache. Returns an empty object {} if not found or expired.
+   * If the value was found it returns an object with the key value pair.
+   * @param {Array<string | number} keys an array of keys
+   * @returns {Record<string, unknown>} an object with the key as a property and the value as the value
+   */
   mget(keys) {
     const result = {};
     for (const key of keys) {
@@ -248,11 +358,12 @@ var NodeCache = class extends import_eventemitter3.default {
     }
     return result;
   }
-  /*
-  	Get the cached value and remove the key from the cache.
-  	Equivalent to calling get(key) + del(key).
-  	Useful for implementing single use mechanism such as OTP, where once a value is read it will become obsolete.
-  */
+  /**
+   * Get the cached value and remove the key from the cache. Equivalent to calling get(key) + del(key).
+   * Useful for implementing single use mechanism such as OTP, where once a value is read it will become obsolete.
+   * @param {string | number} key
+   * @returns {T | undefined} the value or undefined
+   */
   take(key) {
     const result = this.get(key);
     if (result) {
@@ -264,7 +375,11 @@ var NodeCache = class extends import_eventemitter3.default {
     }
     return void 0;
   }
-  // Delete a key. Returns the number of deleted entries. A delete will never fail.
+  /**
+   * Delete a key. Returns the number of deleted entries. A delete will never fail.
+   * @param {string | number | Array<string | number>} key if the key is a number it will convert it to a string. if an array is passed it will delete all keys in the array.
+   * @returns {number} if it was successful it will return the count that was deleted
+   */
   del(key) {
     if (Array.isArray(key)) {
       return this.mdel(key);
@@ -281,7 +396,11 @@ var NodeCache = class extends import_eventemitter3.default {
     }
     return 0;
   }
-  // Delete all keys in Array that exist. Returns the number of deleted entries.
+  /**
+   * Delete all keys in Array that exist. Returns the number of deleted entries.
+   * @param {Array<string | number>} keys an array of keys
+   * @returns {number} the count of deleted keys
+   */
   mdel(keys) {
     let result = 0;
     for (const key of keys) {
@@ -289,8 +408,13 @@ var NodeCache = class extends import_eventemitter3.default {
     }
     return result;
   }
-  // Redefine the ttl of a key. Returns true if the key has been found and changed.
-  // Otherwise returns false. If the ttl-argument isn't passed the default-TTL will be used.
+  /**
+   * Redefine the ttl of a key. Returns true if the key has been found and changed.
+   * Otherwise returns false. If the ttl-argument isn't passed the default-TTL will be used.
+   * @param {string | number} key if the key is a number it will convert it to a string
+   * @param {number} [ttl] the ttl in seconds
+   * @returns {boolean} true if the key has been found and changed. Otherwise returns false.
+   */
   ttl(key, ttl) {
     const result = this.store.get(this.formatKey(key));
     if (result) {
@@ -301,13 +425,12 @@ var NodeCache = class extends import_eventemitter3.default {
     }
     return false;
   }
-  /*
-  		Receive the ttl of a key. You will get:
-  
-  		undefined if the key does not exist
-  		0 if this key has no ttl
-  		a timestamp in ms representing the time at which the key will expire
-  	*/
+  /**
+   * Receive the ttl of a key.
+   * @param {string | number} key if the key is a number it will convert it to a string
+   * @returns {number | undefined} 0 if this key has no ttl, undefined if this key is not in the cache,
+   * a timestamp in ms representing the time at which this key will expire
+   */
   getTtl(key) {
     const result = this.store.get(this.formatKey(key));
     if (result) {
@@ -318,10 +441,10 @@ var NodeCache = class extends import_eventemitter3.default {
     }
     return void 0;
   }
-  /*
-  	Returns an array of all existing keys.
-  	[ "all", "my", "keys", "foo", "bar" ]
-  */
+  /**
+   * Returns an array of all existing keys. [ "all", "my", "keys", "foo", "bar" ]
+   * @returns {string[]} an array of all keys
+   */
   keys() {
     const result = [];
     for (const key of this.store.keys()) {
@@ -329,11 +452,18 @@ var NodeCache = class extends import_eventemitter3.default {
     }
     return result;
   }
-  // Returns boolean indicating if the key is cached.
+  /**
+   * Returns boolean indicating if the key is cached.
+   * @param {string | number} key if the key is a number it will convert it to a string
+   * @returns {boolean} true if the key is cached
+   */
   has(key) {
     return this.store.has(this.formatKey(key));
   }
-  // Gets the stats of the cache.
+  /**
+   * Gets the stats of the cache
+   * @returns {NodeCacheStats} the stats of the cache
+   */
   getStats() {
     const stats = {
       keys: this._stats.count,
@@ -344,22 +474,34 @@ var NodeCache = class extends import_eventemitter3.default {
     };
     return stats;
   }
-  // Flush the whole data.
+  /**
+   * Flush the whole data.
+   * @returns {void}
+   */
   flushAll() {
     this.store.clear();
     this.flushStats();
     this.emit("flush");
   }
-  // Flush the stats
+  /**
+   * Flush the stats.
+   * @returns {void}
+   */
   flushStats() {
     this._stats = new import_cacheable2.CacheableStats({ enabled: true });
     this.emit("flush_stats");
   }
-  // Close the cache. This will clear the interval timeout which is set on check period option.
+  /**
+   * Close the cache. This will clear the interval timeout which is set on check period option.
+   * @returns {void}
+   */
   close() {
     this.stopInterval();
   }
-  // Get the interval id
+  /**
+   * Get the interval id
+   * @returns {number | NodeJS.Timeout} the interval id
+   */
   getIntervalId() {
     return this.intervalId;
   }