From 82dc7ec153018eb8d426a0a933266d00ed6e1b49 Mon Sep 17 00:00:00 2001 From: Jason Mulligan Date: Sat, 26 Sep 2026 22:40:19 -0400 Subject: [PATCH 1/2] fix: skip expired items in keys() keys() now filters expired items, consistent with entries(), values(), and toJSON(). Previously it returned every key regardless of expiry, so iterating keys() then calling get(key) could yield undefined for expired entries. Adds a regression test and corrects the getMany() README line to match its tested behavior. --- README.md | 2 +- src/lru.js | 13 ++++++------- tests/unit/lru.test.js | 8 ++++++++ 3 files changed, 15 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index dab03f5..cd55e71 100644 --- a/README.md +++ b/README.md @@ -172,7 +172,7 @@ const cache = new LRU(100, 5000); | `expiresAt(key)` | Get expiration timestamp for a key. Returns `number | undefined`. | | `forEach(callback, thisArg?)` | Iterate over items in LRU order. Returns `this` for chaining. | | `get(key)` | Retrieve a value. Moves item to most recent. Returns value or `undefined`. | -| `getMany(keys)` | Batch retrieve multiple items. Returns object mapping keys to values (missing/expired keys omitted). | +| `getMany(keys)` | Batch retrieve multiple items. Returns object mapping keys to values (undefined for missing/expired keys). | | `has(key)` | Check if key exists and is not expired. Returns `boolean`. | | `hasAll(keys)` | Check if ALL keys exist. Returns `boolean`. | | `hasAny(keys)` | Check if ANY key exists. Returns `boolean`. | diff --git a/src/lru.js b/src/lru.js index 8b03036..1d8a418 100644 --- a/src/lru.js +++ b/src/lru.js @@ -312,17 +312,16 @@ export class LRU { /** * Returns an array of all keys in the cache, ordered from least to most recently used. + * Expired items are skipped, consistent with entries(), values(), and toJSON(). * * @returns {string[]} Array of keys in LRU order. */ keys() { - const result = Array.from({ length: this.size }); - let x = this.first; - let i = 0; - - while (x !== null) { - result[i++] = x.key; - x = x.next; + const result = []; + for (let x = this.first; x !== null; x = x.next) { + if (!this.#isExpired(x)) { + result.push(x.key); + } } return result; diff --git a/tests/unit/lru.test.js b/tests/unit/lru.test.js index a15cb67..bfb4002 100644 --- a/tests/unit/lru.test.js +++ b/tests/unit/lru.test.js @@ -1661,6 +1661,14 @@ describe("LRU Cache", function () { assert.deepEqual(cache.values(), []); }); + it("should skip expired items in keys()", async function () { + const cache = new LRU(5, 50, false); + cache.set("a", 1); + cache.set("b", 2); + await new Promise((resolve) => setTimeout(resolve, 80)); + assert.deepEqual(cache.keys(), []); + }); + it("should skip expired items in entries()", async function () { const cache = new LRU(5, 50, false); cache.set("a", 1); From 2d10f4d65a410c6566a7fb30f0c98cbfe38403c0 Mon Sep 17 00:00:00 2001 From: Jason Mulligan Date: Sat, 26 Sep 2026 22:49:34 -0400 Subject: [PATCH 2/2] feat: add fireOnEvict option to cleanup() cleanup() now accepts an optional fireOnEvict parameter. When true, it invokes the onEvict callback for each expired item removed. Defaults to false, preserving the existing silent behavior so no existing callers are affected. Adds tests for both paths and updates docs and types. --- README.md | 2 +- coverage.txt | 4 ++-- docs/API.md | 11 ++++++++++- src/lru.js | 10 +++++++++- tests/unit/lru.test.js | 30 ++++++++++++++++++++++++++++++ types/lru.d.ts | 3 ++- 6 files changed, 54 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index cd55e71..a571c6e 100644 --- a/README.md +++ b/README.md @@ -164,7 +164,7 @@ const cache = new LRU(100, 5000); | Method | Description | | --------------------------- | ---------------------------------------------- | -| `cleanup()` | Remove expired items without LRU update. Returns count of removed items. | +| `cleanup(fireOnEvict?)` | Remove expired items without LRU update. Returns count of removed items. Pass `true` to fire `onEvict` for each removed item. | | `clear()` | Remove all items. Returns `this` for chaining. | | `delete(key)` | Remove an item by key. Returns `this` for chaining. | | `entries(keys?)` | Get `[key, value]` pairs. Without keys: LRU order. With keys: input array order. | diff --git a/coverage.txt b/coverage.txt index e37deb0..78f784b 100644 --- a/coverage.txt +++ b/coverage.txt @@ -3,8 +3,8 @@ ℹ file | line % | branch % | funcs % | uncovered lines ℹ ---------------------------------------------------------- ℹ src | | | | -ℹ lru.js | 100.00 | 99.39 | 100.00 | +ℹ lru.js | 100.00 | 99.40 | 100.00 | ℹ ---------------------------------------------------------- -ℹ all files | 100.00 | 99.39 | 100.00 | +ℹ all files | 100.00 | 99.40 | 100.00 | ℹ ---------------------------------------------------------- ℹ end of coverage report diff --git a/docs/API.md b/docs/API.md index c233550..8e39237 100644 --- a/docs/API.md +++ b/docs/API.md @@ -163,15 +163,24 @@ console.log(cache.ttl); // 60000 ### `cleanup()` -Removes expired items without affecting LRU order. Silently removes expired items without triggering the `onEvict()` callback. +Removes expired items without affecting LRU order. By default it silently removes expired items without triggering the `onEvict()` callback. Pass `true` to fire `onEvict()` for each removed item. ```javascript cache.set("a", 1).set("b", 2); // ... wait for items to expire const removed = cache.cleanup(); console.log(removed); // 2 (number of items removed) + +// Fire onEvict for each purged item +const removedWithCallback = cache.cleanup(true); ``` +**Parameters:** + +| Name | Type | Default | Description | +| -------------- | --------- | ------- | ------------------------------------------------ | +| `fireOnEvict` | `boolean` | `false` | When `true`, invokes `onEvict()` for each removed item. | + **Returns:** `number` - Number of expired items removed **Note:** Only removes items when TTL is enabled (`ttl > 0`). Does not support method chaining (returns `number`). diff --git a/src/lru.js b/src/lru.js index 1d8a418..d4c8a73 100644 --- a/src/lru.js +++ b/src/lru.js @@ -547,9 +547,10 @@ export class LRU { * Remove expired items without affecting LRU order. * Unlike get(), this does not move items to the end. * + * @param {boolean} [fireOnEvict=false] - When true, invokes the onEvict callback for each removed item. * @returns {number} Number of expired items removed. */ - cleanup() { + cleanup(fireOnEvict = false) { if (this.ttl === 0 || this.size === 0) { return 0; } @@ -567,6 +568,13 @@ export class LRU { this.#unlink(x); x.prev = null; x.next = null; + if (fireOnEvict && this.#onEvict !== null) { + this.#onEvict({ + key: x.key, + value: x.value, + expiry: x.expiry, + }); + } } } x = next; diff --git a/tests/unit/lru.test.js b/tests/unit/lru.test.js index bfb4002..9113aaa 100644 --- a/tests/unit/lru.test.js +++ b/tests/unit/lru.test.js @@ -1063,6 +1063,36 @@ describe("LRU Cache", function () { const removed = cache.cleanup(); assert.equal(removed, 0); }); + + it("should fire onEvict for each removed item when fireOnEvict is true", async function () { + cache.set("a", 1); + cache.set("b", 2); + + await new Promise((resolve) => setTimeout(resolve, 150)); + + const evicted = []; + cache.onEvict((item) => evicted.push(item.key)); + + const removed = cache.cleanup(true); + assert.equal(removed, 2); + assert.equal(cache.size, 0); + assert.deepEqual(evicted, ["a", "b"]); + }); + + it("should not fire onEvict when fireOnEvict is false (default)", async function () { + cache.set("a", 1); + cache.set("b", 2); + + await new Promise((resolve) => setTimeout(resolve, 150)); + + const evicted = []; + cache.onEvict((item) => evicted.push(item.key)); + + const removed = cache.cleanup(); + assert.equal(removed, 2); + assert.equal(cache.size, 0); + assert.deepEqual(evicted, []); + }); }); describe("toJSON method", function () { diff --git a/types/lru.d.ts b/types/lru.d.ts index 919d738..7da1e04 100644 --- a/types/lru.d.ts +++ b/types/lru.d.ts @@ -153,9 +153,10 @@ export class LRU { /** * Remove expired items without affecting LRU order. * Unlike get(), this does not move items to the end. + * @param fireOnEvict When true, invokes the onEvict callback for each removed item * @returns Number of expired items removed */ - cleanup(): number; + cleanup(fireOnEvict?: boolean): number; /** * Serialize cache to JSON-compatible format.