@cacheable/node-cache 1.5.6 → 1.5.7

package/README.md

@@ -13,18 +13,18 @@
 `@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.
 
 * Fully Compatible with `node-cache` using `{NodeCache}`
+* Faster than the original `node-cache` package 🚀
 * Async/Await functionality with `{NodeCacheStore}`
 * Storage Adapters via [Keyv](https://keyv.org) with `{NodeCacheStore}`
 * Maintained and Updated Regularly! 🎉
 
-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
 * [Getting Started](#getting-started)
 * [Basic Usage](#basic-usage)
-* [Advanced Usage](#advanced-usage)
+* [NodeCache Performance](#nodecache-performance)
+* [NodeCache API](#nodecache-api)
 * [NodeCacheStore](#nodecachestore)
-* [API](#api)
+* [NodeCacheStore API](#nodecachestore-api)
 * [How to Contribute](#how-to-contribute)
 * [License and Copyright](#license-and-copyright)
 
@@ -50,7 +50,7 @@ cache.del('foo'); // true
 cache.set('bar', 'baz', '35m'); // 35 minutes using shorthand
 ```
 
-# NodeCache Not Default Export
+The `NodeCache` is not the default export, so you need to import it like this:
 
 ```javascript
 import {NodeCache} from '@cacheable/node-cache';
@@ -60,77 +60,16 @@ cache.set('foo', 'bar');
 cache.get('foo'); // 'bar'
 ```
 
-# Advanced Usage
-
-```javascript
-import {NodeStorageCache} from '@cacheable/node-cache';
-import {Keyv} from 'keyv';
-import {KeyvRedis} from '@keyv/redis';
-
-const storage = new Keyv({store: new KeyvRedis('redis://user:pass@localhost:6379')});
-const cache = new NodeStorageCache(storage);
-
-// with storage you have the same functionality as the NodeCache but will be using async/await
-await cache.set('foo', 'bar');
-await cache.get('foo'); // 'bar'
-
-// if you call getStats() this will now only be for the single instance of the adapter as it is in memory
-cache.getStats(); // {hits: 1, misses: 1, keys: 1, ksize: 2, vsize: 3}
-```
-
-# 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.
-
-```javascript
-import {NodeCacheStore} from '@cacheable/node-cache';
+# NodeCache Performance
 
-const cache = new NodeCacheStore();
-cache.set('foo', 'bar');
-cache.get('foo'); // 'bar'
-```
+The performance is comparable if not faster to the original `node-cache` package, but with additional features and improvements.
 
-## NodeCacheStoreOptions
+|               name                |  summary  |  ops/sec  |  time/op  |  margin  |  samples  |
+|-----------------------------------|:---------:|----------:|----------:|:--------:|----------:|
+|  Cacheable NodeCache - set / get  |    🥇     |     117K  |      9µs  |  ±1.01%  |     111K  |
+|  Node Cache - set / get           |   -4.6%   |     112K  |      9µs  |  ±1.31%  |     106K  |
 
-When initializing the cache you can pass in the options below:
-
-```javascript
-export type NodeCacheStoreOptions = {
-	ttl?: number; // The standard ttl as number in milliseconds for every generated cache element. 0 = unlimited
-	primary?: Keyv; // The primary storage adapter
-	secondary?: Keyv; // The secondary storage adapter
-	maxKeys?: number; // Default is 0 (unlimited). If this is set it will throw and error if you try to set more keys than the max.
-	stats?: boolean; // Default is true, if this is set to false it will not track stats
-};
-```
-
-Note: the `ttl` is now in milliseconds and not seconds like `stdTTL` in `NodeCache`. You can learn more about using shorthand also in the [cacheable documentation](https://github.com/jaredwray/cacheable/blob/main/packages/cacheable/README.md#shorthand-for-time-to-live-ttl). as it is fulling supported. Here is an example:
-
-```javascript
-const cache = new NodeCacheStore({ttl: 60000 }); // 1 minute as it defaults to milliseconds
-cache.set('foo', 'bar', '1h'); // 1 hour
-cache.set('longfoo', 'bar', '1d'); // 1 day
-```
-
-## 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
-* `get<T>(key: string | number): Promise<T>` - Get a value from the cache by key
-* `mget(keys: Array<string | number>): Promise<Record<string, unknown>>` - Get multiple values from the cache by keys
-* `take<T>(key: string | number): Promise<T>` - Get a value from the cache by key and delete it
-* `del(key: string | number): Promise<boolean>` - Delete a key
-* `mdel(keys: Array<string | number>): Promise<boolean>` - Delete multiple keys
-* `clear(): Promise<void>` - Clear the cache
-* `setTtl(key: string | number, ttl: number): Promise<boolean>` - Set the ttl of a key
-* `disconnect(): Promise<void>` - Disconnect the storage adapters
-* `stats`: `NodeCacheStats` - Get the stats of the cache
-* `ttl`: `number` | `string` - The standard ttl as number in seconds for every generated cache element. `< 0` or `undefined` = unlimited
-* `primary`: `Keyv` - The primary storage adapter
-* `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
+# NodeCache API
 
 ## `constructor(options?: NodeCacheOptions)`
 
@@ -161,7 +100,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).
 
@@ -169,7 +108,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.
 
@@ -187,7 +126,7 @@ export type NodeCacheItem = {
 };
 ```
 
-## `.get(key: string | number): any`
+## `get<T>(key: string | number): T | undefined`
 
 Get a value from the cache by key. If the key does not exist it will return `undefined`.
 
@@ -195,7 +134,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<T>(keys: Array<string | number>): Record<string, T | undefined>`
 
 Get multiple values from the cache by keys. This will return an object with the keys and values.
 
@@ -207,7 +146,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<T>(key: string | number): T | undefined`
 
 Get a value from the cache by key and delete it. If the key does not exist it will return `undefined`.
 
@@ -231,7 +170,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.
 
@@ -239,7 +178,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.
 
@@ -264,12 +203,12 @@ cache.set('foo', 'bar');
 cache.has('foo'); // true
 ```
 
-## `keys(): Array<string>`
+## `keys(): string[]`
 
 Get all keys from the cache.
 
 ```javascript
-cache.keys(); // ['foo', 'bar']
+await cache.keys(); // ['foo', 'bar']
 ```
 
 ## `getStats(): NodeCacheStats`
@@ -286,7 +225,7 @@ Flush the cache. Will remove all keys and reset the stats.
 
 ```javascript
 cache.flushAll();
-cache.keys(); // []
+await cache.keys(); // []
 cache.getStats(); // {hits: 0, misses: 0, keys: 0, ksize: 0, vsize: 0}
 ```
 
@@ -295,18 +234,10 @@ cache.getStats(); // {hits: 0, misses: 0, keys: 0, ksize: 0, vsize: 0}
 Flush the stats. Will reset the stats but keep the keys.
 
 ```javascript
-cache.set('foo', 'bar');
+await cache.set('foo', 'bar');
 cache.flushStats();
 cache.getStats(); // {hits: 0, misses: 0, keys: 0, ksize: 0, vsize: 0}
-cache.keys(); // ['foo']
-```
-
-## `close(): void`
-
-this will stop the interval that is running for the `checkperiod` and `deleteOnExpire` options.
-
-```javascript
-cache.close();
+await cache.keys(); // ['foo']
 ```
 
 ## `on(event: string, callback: Function): void`
@@ -324,9 +255,78 @@ cache.on('set', (key, value) => {
 });
 ```
 
+# NodeCacheStore
+
+`NodeCacheStore` has a similar API to `NodeCache` but it is using `async / await` as it uses the `Keyv` storage adapters under the hood. This means that you can use all the storage adapters that are available in `Keyv` and it will work seamlessly with the `NodeCacheStore`. To learn more about the `Keyv` storage adapters you can check out the [Keyv documentation](https://keyv.org).
+
+```javascript
+import {NodeCacheStore} from '@cacheable/node-cache';
+
+const cache = new NodeCacheStore();
+await cache.set('foo', 'bar');
+await cache.get('foo'); // 'bar'
+```
+
+Here is an example of how to use the `NodeCacheStore` with a primary and secondary storage adapter:
+
+```javascript
+import {NodeStorageCache} from '@cacheable/node-cache';
+import {Keyv} from 'keyv';
+import {KeyvRedis} from '@keyv/redis';
+
+const primary = new Keyv(); // In-memory storage as primary
+const secondary = new Keyv({store: new KeyvRedis('redis://user:pass@localhost:6379')});
+const cache = new NodeStorageCache({primary, secondary});
+
+// with storage you have the same functionality as the NodeCache but will be using async/await
+await cache.set('foo', 'bar');
+await cache.get('foo'); // 'bar'
+
+// if you call getStats() this will now only be for the single instance of the adapter as it is in memory
+cache.getStats(); // {hits: 1, misses: 1, keys: 1, ksize: 2, vsize: 3}
+```
+
+When initializing the cache you can pass in the options below:
+
+```javascript
+export type NodeCacheStoreOptions = {
+	ttl?: number; // The standard ttl as number in milliseconds for every generated cache element. 0 = unlimited
+	primary?: Keyv; // The primary storage adapter
+	secondary?: Keyv; // The secondary storage adapter
+	maxKeys?: number; // Default is 0 (unlimited). If this is set it will throw and error if you try to set more keys than the max.
+	stats?: boolean; // Default is true, if this is set to false it will not track stats
+};
+```
+
+Note: the `ttl` is now in milliseconds and not seconds like `stdTTL` in `NodeCache`. You can learn more about using shorthand also in the [cacheable documentation](https://github.com/jaredwray/cacheable/blob/main/packages/cacheable/README.md#shorthand-for-time-to-live-ttl) as it is fully supported. Here is an example:
+
+```javascript
+const cache = new NodeCacheStore({ttl: 60000 }); // 1 minute as it defaults to milliseconds
+await cache.set('foo', 'bar', '1h'); // 1 hour
+await cache.set('longfoo', 'bar', '1d'); // 1 day
+```
+
+## NodeCacheStore 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
+* `get<T>(key: string | number): Promise<T>` - Get a value from the cache by key
+* `mget(keys: Array<string | number>): Promise<Record<string, unknown>>` - Get multiple values from the cache by keys
+* `take<T>(key: string | number): Promise<T>` - Get a value from the cache by key and delete it
+* `del(key: string | number): Promise<boolean>` - Delete a key
+* `mdel(keys: Array<string | number>): Promise<boolean>` - Delete multiple keys
+* `clear(): Promise<void>` - Clear the cache
+* `setTtl(key: string | number, ttl: number): Promise<boolean>` - Set the ttl of a key
+* `disconnect(): Promise<void>` - Disconnect the storage adapters
+* `stats`: `NodeCacheStats` - Get the stats of the cache
+* `ttl`: `number` | `string` - The standard ttl as number in seconds for every generated cache element. `< 0` or `undefined` = unlimited
+* `primary`: `Keyv` - The primary storage adapter
+* `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
+
 # 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
-[MIT © Jared Wray](./LICENSE)
+[MIT © Jared Wray](./LICENSE)

package/dist/index.cjs

@@ -215,7 +215,7 @@ var NodeCacheStore = class extends import_hookified.Hookified {
   /**
    * 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}
+   * @returns {T | undefined}
    */
   async take(key) {
     return this._cache.take(key.toString());

package/dist/index.d.cts

@@ -134,7 +134,7 @@ declare class NodeCacheStore extends Hookified {
     /**
      * 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}
+     * @returns {T | undefined}
      */
     take<T>(key: string | number): Promise<T | undefined>;
     /**

package/dist/index.d.ts

@@ -134,7 +134,7 @@ declare class NodeCacheStore extends Hookified {
     /**
      * 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}
+     * @returns {T | undefined}
      */
     take<T>(key: string | number): Promise<T | undefined>;
     /**

package/dist/index.js

@@ -188,7 +188,7 @@ var NodeCacheStore = class extends Hookified {
   /**
    * 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}
+   * @returns {T | undefined}
    */
   async take(key) {
     return this._cache.take(key.toString());

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cacheable/node-cache",
-  "version": "1.5.6",
+  "version": "1.5.7",
   "description": "Simple and Maintained fast NodeJS internal caching",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -31,6 +31,7 @@
     "cacheable-node"
   ],
   "devDependencies": {
+    "@types/eslint": "^9.6.1",
     "@types/node": "^22.15.30",
     "@vitest/coverage-v8": "^3.2.2",
     "rimraf": "^6.0.1",