cacheable 1.3.0 → 1.5.0

package/README.md

@@ -155,13 +155,13 @@ _This does not enable statistics for your layer 2 cache as that is a distributed
 
 * `set(key, value, ttl? | [{string, string, ttl?}])`: Sets a value in the cache.
 * `setMany([{key, value, ttl?}])`: Sets multiple values in the cache.
-* `get(key | [keys])`: Gets a value from the cache.
+* `get(key)`: Gets a value from the cache.
 * `getMany([keys])`: Gets multiple values from the cache.
-* `has(key | [key])`: Checks if a value exists in the cache.
+* `has(key)`: Checks if a value exists in the cache.
 * `hasMany([keys])`: Checks if multiple values exist in the cache.
 * `take(key)`: Takes a value from the cache and deletes it.
 * `takeMany([keys])`: Takes multiple values from the cache and deletes them.
-* `delete(key | [key])`: Deletes a value from the cache.
+* `delete(key)`: Deletes a value from the cache.
 * `deleteMany([keys])`: Deletes multiple values from the cache.
 * `clear()`: Clears the cache stores. Be careful with this as it will clear both layer 1 and layer 2.
 * `wrap(function, options)`: Wraps a function in a cache. (coming soon)
@@ -195,6 +195,15 @@ You can use `CacheableMemory` as a standalone cache or as a primary store for `c
 
 This simple in-memory cache uses multiple Map objects and a with `expiration` and `lru` policies if set to manage the in memory cache at scale.
 
+By default we use lazy expiration deletion which means on `get` and `getMany` type functions we look if it is expired and then delete it. If you want to have a more aggressive expiration policy you can set the `checkInterval` property to a value greater than `0` which will check for expired keys at the interval you set.
+
+### CacheableMemory Options
+
+* `ttl`: The time to live for the cache in milliseconds.
+* `useClones`: If the cache should use clones for the values. Default is `true`.
+* `lruSize`: The size of the LRU cache. Default is `0` which is unlimited.
+* `checkInterval`: The interval to check for expired keys in milliseconds. Default is `0` which is disabled.
+
 ### CacheableMemory API
 
 * `set(key, value, ttl?)`: Sets a value in the cache.
@@ -204,6 +213,9 @@ This simple in-memory cache uses multiple Map objects and a with `expiration` an
 * `clear()`: Clears the cache.
 * `size()`: The number of keys in the cache.
 * `keys()`: The keys in the cache.
+* `checkExpired()`: Checks for expired keys in the cache. This is used by the `checkInterval` property.
+* `startIntervalCheck()`: Starts the interval check for expired keys if `checkInterval` is above 0 ms.
+* `stopIntervalCheck()`: Stops the interval check for expired keys.
 
 
 ## How to Contribute

package/dist/index.cjs

@@ -293,8 +293,15 @@ var CacheableMemory = class {
   _hash9 = /* @__PURE__ */ new Map();
   _lru = new DoublyLinkedList();
   _ttl = 0;
+  // Turned off by default
   _useClone = true;
+  // Turned on by default
   _lruSize = 0;
+  // Turned off by default
+  _checkInterval = 0;
+  // Turned off by default
+  _interval = 0;
+  // Turned off by default
   constructor(options) {
     if (options?.ttl) {
       this._ttl = options.ttl;
@@ -305,6 +312,10 @@ var CacheableMemory = class {
     if (options?.lruSize) {
       this._lruSize = options.lruSize;
     }
+    if (options?.checkInterval) {
+      this._checkInterval = options.checkInterval;
+    }
+    this.startIntervalCheck();
   }
   get ttl() {
     return this._ttl;
@@ -325,6 +336,12 @@ var CacheableMemory = class {
     this._lruSize = value;
     this.lruResize();
   }
+  get checkInterval() {
+    return this._checkInterval;
+  }
+  set checkInterval(value) {
+    this._checkInterval = value;
+  }
   get size() {
     return this._hash0.size + this._hash1.size + this._hash2.size + this._hash3.size + this._hash4.size + this._hash5.size + this._hash6.size + this._hash7.size + this._hash8.size + this._hash9.size;
   }
@@ -482,6 +499,28 @@ var CacheableMemory = class {
       }
     }
   }
+  checkExpiration() {
+    const stores = this.concatStores();
+    for (const item of stores.values()) {
+      if (item.expires && Date.now() > item.expires) {
+        this.delete(item.key);
+      }
+    }
+  }
+  startIntervalCheck() {
+    if (this._checkInterval > 0) {
+      this._interval = setInterval(() => {
+        this.checkExpiration();
+      }, this._checkInterval);
+    }
+  }
+  stopIntervalCheck() {
+    if (this._interval) {
+      clearInterval(this._interval);
+    }
+    this._interval = 0;
+    this._checkInterval = 0;
+  }
   isPrimitive(value) {
     const result = false;
     if (value === null || value === void 0) {

package/dist/index.d.cts

@@ -50,6 +50,7 @@ type CacheableMemoryOptions = {
     ttl?: number;
     useClone?: boolean;
     lruSize?: number;
+    checkInterval?: number;
 };
 declare class CacheableMemory {
     private readonly _hashCache;
@@ -67,6 +68,8 @@ declare class CacheableMemory {
     private _ttl;
     private _useClone;
     private _lruSize;
+    private _checkInterval;
+    private _interval;
     constructor(options?: CacheableMemoryOptions);
     get ttl(): number;
     set ttl(value: number);
@@ -74,6 +77,8 @@ declare class CacheableMemory {
     set useClone(value: boolean);
     get lruSize(): number;
     set lruSize(value: number);
+    get checkInterval(): number;
+    set checkInterval(value: number);
     get size(): number;
     get keys(): IterableIterator<string>;
     get<T>(key: string): any;
@@ -88,6 +93,9 @@ declare class CacheableMemory {
     lruAddToFront(key: string): void;
     lruMoveToFront(key: string): void;
     lruResize(): void;
+    checkExpiration(): void;
+    startIntervalCheck(): void;
+    stopIntervalCheck(): void;
     private isPrimitive;
     private concatStores;
 }

package/dist/index.d.ts

@@ -50,6 +50,7 @@ type CacheableMemoryOptions = {
     ttl?: number;
     useClone?: boolean;
     lruSize?: number;
+    checkInterval?: number;
 };
 declare class CacheableMemory {
     private readonly _hashCache;
@@ -67,6 +68,8 @@ declare class CacheableMemory {
     private _ttl;
     private _useClone;
     private _lruSize;
+    private _checkInterval;
+    private _interval;
     constructor(options?: CacheableMemoryOptions);
     get ttl(): number;
     set ttl(value: number);
@@ -74,6 +77,8 @@ declare class CacheableMemory {
     set useClone(value: boolean);
     get lruSize(): number;
     set lruSize(value: number);
+    get checkInterval(): number;
+    set checkInterval(value: number);
     get size(): number;
     get keys(): IterableIterator<string>;
     get<T>(key: string): any;
@@ -88,6 +93,9 @@ declare class CacheableMemory {
     lruAddToFront(key: string): void;
     lruMoveToFront(key: string): void;
     lruResize(): void;
+    checkExpiration(): void;
+    startIntervalCheck(): void;
+    stopIntervalCheck(): void;
     private isPrimitive;
     private concatStores;
 }

package/dist/index.js

@@ -265,8 +265,15 @@ var CacheableMemory = class {
   _hash9 = /* @__PURE__ */ new Map();
   _lru = new DoublyLinkedList();
   _ttl = 0;
+  // Turned off by default
   _useClone = true;
+  // Turned on by default
   _lruSize = 0;
+  // Turned off by default
+  _checkInterval = 0;
+  // Turned off by default
+  _interval = 0;
+  // Turned off by default
   constructor(options) {
     if (options?.ttl) {
       this._ttl = options.ttl;
@@ -277,6 +284,10 @@ var CacheableMemory = class {
     if (options?.lruSize) {
       this._lruSize = options.lruSize;
     }
+    if (options?.checkInterval) {
+      this._checkInterval = options.checkInterval;
+    }
+    this.startIntervalCheck();
   }
   get ttl() {
     return this._ttl;
@@ -297,6 +308,12 @@ var CacheableMemory = class {
     this._lruSize = value;
     this.lruResize();
   }
+  get checkInterval() {
+    return this._checkInterval;
+  }
+  set checkInterval(value) {
+    this._checkInterval = value;
+  }
   get size() {
     return this._hash0.size + this._hash1.size + this._hash2.size + this._hash3.size + this._hash4.size + this._hash5.size + this._hash6.size + this._hash7.size + this._hash8.size + this._hash9.size;
   }
@@ -454,6 +471,28 @@ var CacheableMemory = class {
       }
     }
   }
+  checkExpiration() {
+    const stores = this.concatStores();
+    for (const item of stores.values()) {
+      if (item.expires && Date.now() > item.expires) {
+        this.delete(item.key);
+      }
+    }
+  }
+  startIntervalCheck() {
+    if (this._checkInterval > 0) {
+      this._interval = setInterval(() => {
+        this.checkExpiration();
+      }, this._checkInterval);
+    }
+  }
+  stopIntervalCheck() {
+    if (this._interval) {
+      clearInterval(this._interval);
+    }
+    this._interval = 0;
+    this._checkInterval = 0;
+  }
   isPrimitive(value) {
     const result = false;
     if (value === null || value === void 0) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cacheable",
-  "version": "1.3.0",
+  "version": "1.5.0",
   "description": "Simple Caching Engine using Keyv",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -18,6 +18,7 @@
   "private": false,
   "devDependencies": {
     "@keyv/redis": "^3.0.1",
+    "@types/node": "^22.6.1",
     "@vitest/coverage-v8": "^2.1.1",
     "lru-cache": "^11.0.1",
     "rimraf": "^6.0.1",