@cacheable/node-cache 1.5.6 → 1.5.8

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';
-
-const cache = new NodeCacheStore();
-cache.set('foo', 'bar');
-cache.get('foo'); // 'bar'
-```
-
-## NodeCacheStoreOptions
-
-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:
+# NodeCache Performance
 
-```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
+The performance is comparable if not faster to the original `node-cache` package, but with additional features and improvements.
 
-* `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
+|               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  |
 
-# API
+# NodeCache API
 
 ## `constructor(options?: NodeCacheOptions)`
 
@@ -138,14 +77,24 @@ Create a new cache instance. You can pass in options to set the configuration:
 
 ```javascript
 export type NodeCacheOptions = {
-	stdTTL?: number; // The standard ttl as number in seconds for every generated cache element. 0 = unlimited. If string, it will be parsed as shorthand and default to milliseconds if it is a number as a string.
-	checkperiod?: number; // Default is 600, 0 means no periodic check
-	useClones?: boolean; // Default is true
-	deleteOnExpire?: boolean; // Default is true, if false it will keep the key and not delete during an interval check and the value on get() will be undefined
-	maxKeys?: number; // Default is -1 (unlimited). If this is set it will throw and error if you try to set more keys than the max.
+	stdTTL?: number; 
+	checkperiod?: number;
+	useClones?: boolean;
+	deleteOnExpire?: boolean;
+	maxKeys?: number;
 };
 ```
 
+Here is a description of the options:
+
+| Option | Default Setting | Description |
+|--------|----------------|-------------|
+| `stdTTL` | `0` | The standard time to live (TTL) in seconds for every generated cache element. If set to `0`, it means unlimited. If a string is provided, it will be parsed as shorthand and default to milliseconds if it is a number as a string. |
+| `checkperiod` | `600` | The interval in seconds to check for expired keys. If set to `0`, it means no periodic check will be performed. |
+| `useClones` | `true` | If set to `true`, the cache will clone the returned items via `get()` functions. This means that every time you set a value into the cache, `node-cache` makes a deep clone of it. When you get that value back, you receive another deep clone. This mimics the behavior of an external cache like Redis or Memcached, meaning mutations to the returned object do not affect the cached copy (and vice versa). If set to `false`, the original object will be returned, and mutations will affect the cached copy. |
+| `deleteOnExpire` | `true` | If set to `true`, the key will be deleted when it expires. If set to `false`, the key will remain in the cache, but the value returned by `get()` will be `undefined`. You can manage the key with the `on('expired')` event. |
+| `maxKeys` | `-1` | If set to a positive number, it will limit the number of keys in the cache. If the number of keys exceeds this limit, it will throw an error when trying to set more keys than the maximum. If set to `-1`, it means unlimited keys are allowed. |
+
 When initializing the cache you can pass in the options to set the configuration like the example below where we set the `stdTTL` to 10 seconds and `checkperiod` to 5 seconds.:
 
 ```javascript
@@ -161,7 +110,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 +118,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 +136,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 +144,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 +156,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 +180,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 +188,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 +213,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 +235,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 +244,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 +265,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>;
     /**
@@ -154,7 +154,12 @@ type NodeCacheOptions = {
      */
     checkperiod?: number;
     /**
-     * Clones the returned items via get functions. Default is true.
+     * If set to true (Default Setting), the cache will clone the returned items via get() functions.
+     * This means that every time you set a value into the cache, node-cache makes a deep clone of it.
+     * When you get that value back, you receive another deep clone.
+     * This mimics the behavior of an external cache like Redis or Memcached, meaning mutations to the
+     * returned object do not affect the cached copy (and vice versa). If set to false, the original
+     * object will be returned, and mutations will affect the cached copy.
      */
     useClones?: boolean;
     /**

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>;
     /**
@@ -154,7 +154,12 @@ type NodeCacheOptions = {
      */
     checkperiod?: number;
     /**
-     * Clones the returned items via get functions. Default is true.
+     * If set to true (Default Setting), the cache will clone the returned items via get() functions.
+     * This means that every time you set a value into the cache, node-cache makes a deep clone of it.
+     * When you get that value back, you receive another deep clone.
+     * This mimics the behavior of an external cache like Redis or Memcached, meaning mutations to the
+     * returned object do not affect the cached copy (and vice versa). If set to false, the original
+     * object will be returned, and mutations will affect the cached copy.
      */
     useClones?: boolean;
     /**

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.8",
   "description": "Simple and Maintained fast NodeJS internal caching",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -31,18 +31,19 @@
     "cacheable-node"
   ],
   "devDependencies": {
-    "@types/node": "^22.15.30",
-    "@vitest/coverage-v8": "^3.2.2",
+    "@types/eslint": "^9.6.1",
+    "@types/node": "^24.0.7",
+    "@vitest/coverage-v8": "^3.2.4",
     "rimraf": "^6.0.1",
     "tsup": "^8.5.0",
     "typescript": "^5.8.3",
-    "vitest": "^3.2.2",
-    "xo": "^1.1.0"
+    "vitest": "^3.2.4",
+    "xo": "^1.1.1"
   },
   "dependencies": {
-    "hookified": "^1.9.1",
-    "keyv": "^5.3.3",
-    "cacheable": "^1.10.0"
+    "hookified": "^1.10.0",
+    "keyv": "^5.3.4",
+    "cacheable": "^1.10.1"
   },
   "files": [
     "dist",
@@ -52,7 +53,7 @@
     "build": "rimraf ./dist && tsup src/index.ts --format cjs,esm --dts --clean",
     "prepublish": "pnpm build",
     "test": "xo --fix && vitest run --coverage",
-    "test:ci": "xo && vitest run",
+    "test:ci": "xo && vitest run --coverage",
     "clean": "rimraf ./dist ./coverage ./node_modules"
   }
 }