@cacheable/node-cache 1.5.7 → 1.6.0

package/README.md

@@ -60,6 +60,16 @@ cache.set('foo', 'bar');
 cache.get('foo'); // 'bar'
 ```
 
+`NodeCache` also offers the ability to set the type of values that can be cached in Typescript environments.
+
+```typescript
+import {NodeCache} from '@cacheable/node-cache';
+
+const cache = new NodeCache<string>();
+cache.set('foo', 'bar');
+cache.get('foo'); // 'bar'
+```
+
 # NodeCache Performance
 
 The performance is comparable if not faster to the original `node-cache` package, but with additional features and improvements.
@@ -77,14 +87,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

package/dist/index.cjs

@@ -79,7 +79,7 @@ var NodeCacheStore = class extends import_hookified.Hookified {
   }
   /**
    * Primary cache store.
-   * @returns {Keyv}
+   * @returns {Keyv<T>}
    * @readonly
    */
   get primary() {
@@ -87,7 +87,7 @@ var NodeCacheStore = class extends import_hookified.Hookified {
   }
   /**
    * Primary cache store.
-   * @param {Keyv} primary
+   * @param {Keyv<T>} primary
    */
   set primary(primary) {
     this._cache.primary = primary;
@@ -95,7 +95,7 @@ var NodeCacheStore = class extends import_hookified.Hookified {
   /**
    * 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}
+   * @returns {Keyv<T> | undefined}
    */
   get secondary() {
     return this._cache.secondary;
@@ -131,7 +131,7 @@ var NodeCacheStore = class extends import_hookified.Hookified {
   /**
    * Set a key/value pair in the cache.
    * @param {string | number} key
-   * @param {any} value
+   * @param {T} value
    * @param {number} [ttl]
    * @returns {boolean}
    */
@@ -146,7 +146,7 @@ var NodeCacheStore = class extends import_hookified.Hookified {
   }
   /**
    * Set multiple key/value pairs in the cache.
-   * @param {NodeCacheItem[]} list
+   * @param {PartialNodeCacheItem[]} list
    * @returns {void}
    */
   async mset(list) {
@@ -260,11 +260,11 @@ var NodeCache = class extends import_hookified2.Hookified {
   /**
    * 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 {T} value
    * @param {number | string} [ttl] - this is in seconds and undefined will use the default ttl
    * @returns {boolean}
    */
-  set(key, value, ttl) {
+  set(key, value, ttl = 0) {
     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);
     }
@@ -298,7 +298,7 @@ var NodeCache = class extends import_hookified2.Hookified {
   }
   /**
    * 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
+   * @param {PartialNodeCacheItem<T>[]} data an array of key value pairs with optional ttl
    * @returns {boolean}
    */
   mset(data) {

package/dist/index.d.cts

@@ -2,7 +2,7 @@ import { Hookified } from 'hookified';
 import { Cacheable } from 'cacheable';
 import { Keyv } from 'keyv';
 
-type NodeCacheStoreOptions = {
+type NodeCacheStoreOptions<T> = {
     /**
      * Time to live in milliseconds. This is a breaking change from the original NodeCache.
      */
@@ -14,21 +14,21 @@ type NodeCacheStoreOptions = {
     /**
      * Primary cache store.
      */
-    primary?: Keyv;
+    primary?: Keyv<T>;
     /**
      * Secondary cache store. Learn more about the secondary cache store in the cacheable documentation.
      * [storage-tiering-and-caching](https://github.com/jaredwray/cacheable/tree/main/packages/cacheable#storage-tiering-and-caching)
      */
-    secondary?: Keyv;
+    secondary?: Keyv<T>;
     /**
      * Enable stats tracking. This is a breaking change from the original NodeCache.
      */
     stats?: boolean;
 };
-declare class NodeCacheStore extends Hookified {
+declare class NodeCacheStore<T> extends Hookified {
     private _maxKeys;
     private readonly _cache;
-    constructor(options?: NodeCacheStoreOptions);
+    constructor(options?: NodeCacheStoreOptions<T>);
     /**
      * Cacheable instance.
      * @returns {Cacheable}
@@ -48,21 +48,21 @@ declare class NodeCacheStore extends Hookified {
     set ttl(ttl: number | string | undefined);
     /**
      * Primary cache store.
-     * @returns {Keyv}
+     * @returns {Keyv<T>}
      * @readonly
      */
-    get primary(): Keyv;
+    get primary(): Keyv<T>;
     /**
      * Primary cache store.
-     * @param {Keyv} primary
+     * @param {Keyv<T>} primary
      */
-    set primary(primary: Keyv);
+    set primary(primary: Keyv<T>);
     /**
      * 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}
+     * @returns {Keyv<T> | undefined}
      */
-    get secondary(): Keyv | undefined;
+    get secondary(): Keyv<T> | undefined;
     /**
      * 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.
@@ -85,17 +85,17 @@ declare class NodeCacheStore extends Hookified {
     /**
      * Set a key/value pair in the cache.
      * @param {string | number} key
-     * @param {any} value
+     * @param {T} value
      * @param {number} [ttl]
      * @returns {boolean}
      */
-    set(key: string | number, value: any, ttl?: number): Promise<boolean>;
+    set(key: string | number, value: T, ttl?: number): Promise<boolean>;
     /**
      * Set multiple key/value pairs in the cache.
-     * @param {NodeCacheItem[]} list
+     * @param {PartialNodeCacheItem[]} list
      * @returns {void}
      */
-    mset(list: NodeCacheItem[]): Promise<void>;
+    mset(list: Array<PartialNodeCacheItem<T>>): Promise<void>;
     /**
      * Get a value from the cache.
      * @param {string | number} key
@@ -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;
     /**
@@ -167,7 +172,7 @@ type NodeCacheOptions = {
      */
     maxKeys?: number;
 };
-type NodeCacheItem = {
+type PartialNodeCacheItem<T> = {
     /**
      * The key of the item
      */
@@ -175,12 +180,18 @@ type NodeCacheItem = {
     /**
      * The value of the item
      */
-    value: unknown;
+    value: T;
     /**
      * The ttl of the item in seconds. 0 = unlimited
      */
     ttl?: number;
 };
+type NodeCacheItem<T> = PartialNodeCacheItem<T> & {
+    /**
+     * The ttl of the item in milliseconds. 0 = unlimited
+     */
+    ttl: number;
+};
 declare enum NodeCacheErrors {
     ECACHEFULL = "Cache max keys amount exceeded",
     EKEYTYPE = "The key argument has to be of type `string` or `number`. Found: `__key`",
@@ -209,9 +220,9 @@ type NodeCacheStats = {
      */
     vsize: number;
 };
-declare class NodeCache extends Hookified {
+declare class NodeCache<T> extends Hookified {
     readonly options: NodeCacheOptions;
-    readonly store: Map<string, any>;
+    readonly store: Map<string, NodeCacheItem<T>>;
     private _stats;
     private readonly _cacheable;
     private intervalId;
@@ -219,23 +230,23 @@ declare class NodeCache extends Hookified {
     /**
      * 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 {T} value
      * @param {number | string} [ttl] - this is in seconds and undefined will use the default ttl
      * @returns {boolean}
      */
-    set(key: string | number, value: any, ttl?: number | string): boolean;
+    set(key: string | number, value: T, ttl?: number | string): boolean;
     /**
      * 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
+     * @param {PartialNodeCacheItem<T>[]} data an array of key value pairs with optional ttl
      * @returns {boolean}
      */
-    mset(data: NodeCacheItem[]): boolean;
+    mset(data: Array<PartialNodeCacheItem<T>>): boolean;
     /**
      * 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<T>(key: string | number): T | undefined;
+    get(key: string | number): T | undefined;
     /**
      * 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.
@@ -321,4 +332,4 @@ declare class NodeCache extends Hookified {
     private createError;
 }
 
-export { NodeCache, NodeCacheErrors, type NodeCacheItem, type NodeCacheOptions, type NodeCacheStats, NodeCacheStore, type NodeCacheStoreOptions, NodeCache as default };
+export { NodeCache, NodeCacheErrors, type NodeCacheItem, type NodeCacheOptions, type NodeCacheStats, NodeCacheStore, type NodeCacheStoreOptions, type PartialNodeCacheItem, NodeCache as default };

package/dist/index.d.ts

@@ -2,7 +2,7 @@ import { Hookified } from 'hookified';
 import { Cacheable } from 'cacheable';
 import { Keyv } from 'keyv';
 
-type NodeCacheStoreOptions = {
+type NodeCacheStoreOptions<T> = {
     /**
      * Time to live in milliseconds. This is a breaking change from the original NodeCache.
      */
@@ -14,21 +14,21 @@ type NodeCacheStoreOptions = {
     /**
      * Primary cache store.
      */
-    primary?: Keyv;
+    primary?: Keyv<T>;
     /**
      * Secondary cache store. Learn more about the secondary cache store in the cacheable documentation.
      * [storage-tiering-and-caching](https://github.com/jaredwray/cacheable/tree/main/packages/cacheable#storage-tiering-and-caching)
      */
-    secondary?: Keyv;
+    secondary?: Keyv<T>;
     /**
      * Enable stats tracking. This is a breaking change from the original NodeCache.
      */
     stats?: boolean;
 };
-declare class NodeCacheStore extends Hookified {
+declare class NodeCacheStore<T> extends Hookified {
     private _maxKeys;
     private readonly _cache;
-    constructor(options?: NodeCacheStoreOptions);
+    constructor(options?: NodeCacheStoreOptions<T>);
     /**
      * Cacheable instance.
      * @returns {Cacheable}
@@ -48,21 +48,21 @@ declare class NodeCacheStore extends Hookified {
     set ttl(ttl: number | string | undefined);
     /**
      * Primary cache store.
-     * @returns {Keyv}
+     * @returns {Keyv<T>}
      * @readonly
      */
-    get primary(): Keyv;
+    get primary(): Keyv<T>;
     /**
      * Primary cache store.
-     * @param {Keyv} primary
+     * @param {Keyv<T>} primary
      */
-    set primary(primary: Keyv);
+    set primary(primary: Keyv<T>);
     /**
      * 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}
+     * @returns {Keyv<T> | undefined}
      */
-    get secondary(): Keyv | undefined;
+    get secondary(): Keyv<T> | undefined;
     /**
      * 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.
@@ -85,17 +85,17 @@ declare class NodeCacheStore extends Hookified {
     /**
      * Set a key/value pair in the cache.
      * @param {string | number} key
-     * @param {any} value
+     * @param {T} value
      * @param {number} [ttl]
      * @returns {boolean}
      */
-    set(key: string | number, value: any, ttl?: number): Promise<boolean>;
+    set(key: string | number, value: T, ttl?: number): Promise<boolean>;
     /**
      * Set multiple key/value pairs in the cache.
-     * @param {NodeCacheItem[]} list
+     * @param {PartialNodeCacheItem[]} list
      * @returns {void}
      */
-    mset(list: NodeCacheItem[]): Promise<void>;
+    mset(list: Array<PartialNodeCacheItem<T>>): Promise<void>;
     /**
      * Get a value from the cache.
      * @param {string | number} key
@@ -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;
     /**
@@ -167,7 +172,7 @@ type NodeCacheOptions = {
      */
     maxKeys?: number;
 };
-type NodeCacheItem = {
+type PartialNodeCacheItem<T> = {
     /**
      * The key of the item
      */
@@ -175,12 +180,18 @@ type NodeCacheItem = {
     /**
      * The value of the item
      */
-    value: unknown;
+    value: T;
     /**
      * The ttl of the item in seconds. 0 = unlimited
      */
     ttl?: number;
 };
+type NodeCacheItem<T> = PartialNodeCacheItem<T> & {
+    /**
+     * The ttl of the item in milliseconds. 0 = unlimited
+     */
+    ttl: number;
+};
 declare enum NodeCacheErrors {
     ECACHEFULL = "Cache max keys amount exceeded",
     EKEYTYPE = "The key argument has to be of type `string` or `number`. Found: `__key`",
@@ -209,9 +220,9 @@ type NodeCacheStats = {
      */
     vsize: number;
 };
-declare class NodeCache extends Hookified {
+declare class NodeCache<T> extends Hookified {
     readonly options: NodeCacheOptions;
-    readonly store: Map<string, any>;
+    readonly store: Map<string, NodeCacheItem<T>>;
     private _stats;
     private readonly _cacheable;
     private intervalId;
@@ -219,23 +230,23 @@ declare class NodeCache extends Hookified {
     /**
      * 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 {T} value
      * @param {number | string} [ttl] - this is in seconds and undefined will use the default ttl
      * @returns {boolean}
      */
-    set(key: string | number, value: any, ttl?: number | string): boolean;
+    set(key: string | number, value: T, ttl?: number | string): boolean;
     /**
      * 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
+     * @param {PartialNodeCacheItem<T>[]} data an array of key value pairs with optional ttl
      * @returns {boolean}
      */
-    mset(data: NodeCacheItem[]): boolean;
+    mset(data: Array<PartialNodeCacheItem<T>>): boolean;
     /**
      * 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<T>(key: string | number): T | undefined;
+    get(key: string | number): T | undefined;
     /**
      * 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.
@@ -321,4 +332,4 @@ declare class NodeCache extends Hookified {
     private createError;
 }
 
-export { NodeCache, NodeCacheErrors, type NodeCacheItem, type NodeCacheOptions, type NodeCacheStats, NodeCacheStore, type NodeCacheStoreOptions, NodeCache as default };
+export { NodeCache, NodeCacheErrors, type NodeCacheItem, type NodeCacheOptions, type NodeCacheStats, NodeCacheStore, type NodeCacheStoreOptions, type PartialNodeCacheItem, NodeCache as default };

package/dist/index.js

@@ -52,7 +52,7 @@ var NodeCacheStore = class extends Hookified {
   }
   /**
    * Primary cache store.
-   * @returns {Keyv}
+   * @returns {Keyv<T>}
    * @readonly
    */
   get primary() {
@@ -60,7 +60,7 @@ var NodeCacheStore = class extends Hookified {
   }
   /**
    * Primary cache store.
-   * @param {Keyv} primary
+   * @param {Keyv<T>} primary
    */
   set primary(primary) {
     this._cache.primary = primary;
@@ -68,7 +68,7 @@ var NodeCacheStore = class extends Hookified {
   /**
    * 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}
+   * @returns {Keyv<T> | undefined}
    */
   get secondary() {
     return this._cache.secondary;
@@ -104,7 +104,7 @@ var NodeCacheStore = class extends Hookified {
   /**
    * Set a key/value pair in the cache.
    * @param {string | number} key
-   * @param {any} value
+   * @param {T} value
    * @param {number} [ttl]
    * @returns {boolean}
    */
@@ -119,7 +119,7 @@ var NodeCacheStore = class extends Hookified {
   }
   /**
    * Set multiple key/value pairs in the cache.
-   * @param {NodeCacheItem[]} list
+   * @param {PartialNodeCacheItem[]} list
    * @returns {void}
    */
   async mset(list) {
@@ -233,11 +233,11 @@ var NodeCache = class extends Hookified2 {
   /**
    * 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 {T} value
    * @param {number | string} [ttl] - this is in seconds and undefined will use the default ttl
    * @returns {boolean}
    */
-  set(key, value, ttl) {
+  set(key, value, ttl = 0) {
     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);
     }
@@ -271,7 +271,7 @@ var NodeCache = class extends Hookified2 {
   }
   /**
    * 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
+   * @param {PartialNodeCacheItem<T>[]} data an array of key value pairs with optional ttl
    * @returns {boolean}
    */
   mset(data) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cacheable/node-cache",
-  "version": "1.5.7",
+  "version": "1.6.0",
   "description": "Simple and Maintained fast NodeJS internal caching",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -32,18 +32,18 @@
   ],
   "devDependencies": {
     "@types/eslint": "^9.6.1",
-    "@types/node": "^22.15.30",
-    "@vitest/coverage-v8": "^3.2.2",
+    "@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",
@@ -53,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"
   }
 }