evicting-cache 2.2.1 → 2.3.1

package/README.md

@@ -1,7 +1,14 @@
 # Evicting Cache
-JavaScript Cache using an LRU (Least Recently Used) algorithm
 
-The cache is backed by a LinkedMap, which is a Map that maintains insertion order. When the cache is full, the least recently used item is evicted.
+[![npm version](https://img.shields.io/npm/v/evicting-cache.svg)](https://www.npmjs.com/package/evicting-cache)
+[![npm downloads](https://img.shields.io/npm/dm/evicting-cache.svg)](https://www.npmjs.com/package/evicting-cache)
+[![License: ISC](https://img.shields.io/badge/License-ISC-blue.svg)](https://opensource.org/licenses/ISC)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.9-blue.svg)](https://www.typescriptlang.org/)
+[![Test Coverage](https://img.shields.io/badge/coverage-100%25-brightgreen.svg)](https://github.com/D1g1talEntr0py/evicting-cache)
+
+A lightweight, high-performance TypeScript implementation of an LRU (Least Recently Used) cache with automatic eviction.
+
+The cache is backed by JavaScript's native `Map`, leveraging its insertion order guarantee for efficient LRU semantics. When the cache reaches capacity, the least recently used item is automatically evicted.
 
 ## Installation
 
@@ -13,27 +20,256 @@ pnpm add evicting-cache
 npm install evicting-cache
 ```
 
+## Features
+
+- 🚀 **High Performance** - O(1) operations for get, put, delete, and evict
+- 📦 **Lightweight** - Zero dependencies, small bundle size
+- 🔄 **LRU Eviction** - Automatic removal of least recently used items
+- 📊 **Statistics Tracking** - Built-in hit/miss ratio monitoring
+- 🔢 **Batch Operations** - Efficient multi-key operations
+- 🎯 **Type Safe** - Full TypeScript support with generics
+- ✅ **100% Test Coverage** - Thoroughly tested and reliable
+- 🌐 **Modern ES Modules** - Native ESM support
+- 🔍 **Map-like API** - Familiar interface with additional features
+
 ## Usage
-```javascript
-import EvictingCache from 'evicting-cache';
 
-// Constructor accepts a number, which is the maximum number of items to store.
-// default is 100
-const cache = new EvictingCache(3);
+### Basic Example
+
+```typescript
+import { EvictingCache } from 'evicting-cache';
+
+// Create a cache with capacity of 3 items (default is 100)
+const cache = new EvictingCache<string, string>(3);
 
-// Obviously a contrived example, but this is what you get with AI...
 cache.put('key1', 'value1');
 cache.put('key2', 'value2');
 cache.put('key3', 'value3');
-cache.put('key4', 'value4');
+cache.put('key4', 'value4'); // 'key1' is evicted (LRU)
+
+console.log(cache.get('key1')); // null (evicted)
+console.log(cache.get('key2')); // 'value2'
+console.log(cache.get('key3')); // 'value3'
+console.log(cache.get('key4')); // 'value4'
+
+cache.put('key5', 'value5'); // 'key2' is evicted
+
+console.log(cache.get('key2')); // null (evicted)
+console.log(cache.size); // 3
+```
+
+### LRU Behavior
+
+```typescript
+const cache = new EvictingCache<string, number>(3);
+
+cache.put('a', 1);
+cache.put('b', 2);
+cache.put('c', 3);
+// Order: a, b, c (a is LRU)
+
+cache.get('a'); // Access 'a', moves it to most recent
+// Order: b, c, a (b is now LRU)
+
+cache.put('d', 4); // Evicts 'b' (LRU)
+// Order: c, a, d
+
+console.log(cache.has('b')); // false (evicted)
+```
+
+### Peek Without Affecting LRU
+
+```typescript
+const cache = new EvictingCache<string, string>(2);
+
+cache.put('x', 'hello');
+cache.put('y', 'world');
+
+// peek() reads without updating LRU order
+console.log(cache.peek('x')); // 'hello'
+// 'x' remains LRU
+
+cache.put('z', 'new'); // 'x' is evicted
+console.log(cache.has('x')); // false
+```
+
+### Get or Compute
+
+```typescript
+const cache = new EvictingCache<string, number>(10);
+
+// Get existing value or compute and cache it
+const value = cache.getOrPut('userId:123', () => {
+  // Expensive computation only happens if key is missing
+  return fetchUserFromDatabase('123');
+});
+
+// If producer throws, cache remains unchanged
+try {
+  cache.getOrPut('key', () => {
+    throw new Error('Failed to compute');
+  });
+} catch (error) {
+  // Cache state is unmodified
+}
+```
+
+### Batch Operations
+
+```typescript
+const cache = new EvictingCache<string, number>(100);
+
+// Add multiple entries at once
+cache.putAll([
+  ['a', 1],
+  ['b', 2],
+  ['c', 3]
+]);
+
+// Can also use a Map
+cache.putAll(new Map([['d', 4], ['e', 5]]));
+
+// Get multiple values (returns Map, excludes missing keys)
+const values = cache.getAll(['a', 'b', 'missing']);
+console.log(values.size); // 2
+console.log(values.get('a')); // 1
+console.log(values.has('missing')); // false
+
+// Delete multiple keys (returns count removed)
+const removed = cache.deleteAll(['a', 'c', 'missing']);
+console.log(removed); // 2
+```
+
+### Cache Statistics
+
+```typescript
+const cache = new EvictingCache<string, string>(10);
+
+cache.put('a', 'value1');
+cache.get('a'); // hit
+cache.get('b'); // miss
+cache.get('a'); // hit
+
+const stats = cache.getStats();
+console.log(stats.hits); // 2
+console.log(stats.misses); // 1
+console.log(stats.hitRate); // 0.667 (66.7%)
+
+// Reset statistics
+cache.resetStats();
+console.log(cache.getStats().hits); // 0
+```
+
+### Iteration
+
+```typescript
+const cache = new EvictingCache<string, number>(3);
+cache.put('a', 1);
+cache.put('b', 2);
+cache.put('c', 3);
+
+// Iterate over entries (LRU to MRU order)
+for (const [key, value] of cache) {
+  console.log(key, value);
+}
+
+// Or use forEach
+cache.forEach((value, key, cache) => {
+  console.log(key, value);
+});
+
+// Get keys, values, or entries
+console.log([...cache.keys()]); // ['a', 'b', 'c']
+console.log([...cache.values()]); // [1, 2, 3]
+console.log([...cache.entries()]); // [['a', 1], ['b', 2], ['c', 3]]
+```
+
+## API Reference
+
+### Constructor
+
+- `new EvictingCache<K, V>(capacity?: number)` - Creates a new cache with the specified capacity (default: 100)
+
+### Core Methods
+
+- `get(key: K): V | null` - Returns value and updates LRU order
+- `peek(key: K): V | null` - Returns value without updating LRU order
+- `put(key: K, value: V): void` - Adds or updates a key-value pair
+- `delete(key: K): boolean` - Removes a key from the cache
+- `has(key: K): boolean` - Checks if a key exists
+- `getOrPut(key: K, producer: () => V): V` - Gets existing value or computes and stores new one
+- `evict(): boolean` - Manually removes the LRU item
+- `clear(): void` - Removes all items from the cache
+
+### Batch Operations
+
+- `putAll(entries: Iterable<[K, V]>): void` - Adds multiple entries
+- `getAll(keys: Iterable<K>): Map<K, V>` - Gets multiple values
+- `deleteAll(keys: Iterable<K>): number` - Removes multiple keys
+
+### Statistics
+
+- `getStats(): { hits: number, misses: number, hitRate: number }` - Returns cache statistics
+- `resetStats(): void` - Resets statistics counters
+
+### Iteration
+
+- `keys(): IterableIterator<K>` - Returns an iterator over keys
+- `values(): IterableIterator<V>` - Returns an iterator over values
+- `entries(): IterableIterator<[K, V]>` - Returns an iterator over entries
+- `forEach(callback: (value: V, key: K, cache: EvictingCache<K, V>) => void, thisArg?: unknown): void` - Executes callback for each entry
+- `[Symbol.iterator]()` - Makes the cache iterable
+
+### Properties
+
+- `capacity: number` - Maximum number of items (read-only)
+- `size: number` - Current number of items (read-only)
+
+## Performance
+
+All core operations have **O(1)** time complexity:
+
+| Operation | Complexity | Updates LRU |
+|-----------|------------|-------------|
+| `get(key)` | O(1) | ✅ Yes |
+| `peek(key)` | O(1) | ❌ No |
+| `put(key, value)` | O(1) | ✅ Yes |
+| `delete(key)` | O(1) | ❌ N/A |
+| `evict()` | O(1) | ❌ N/A |
+| `has(key)` | O(1) | ❌ No |
+| `clear()` | O(1) | ❌ N/A |
+
+**Space complexity:** O(n) where n is the capacity
+
+## TypeScript Support
+
+Full TypeScript support with generic types:
+
+```typescript
+// Strongly typed cache
+const userCache = new EvictingCache<number, User>(100);
+const configCache = new EvictingCache<string, Config>(50);
+
+// Works with any key/value types
+const complexCache = new EvictingCache<{ id: number; tenant: string }, Promise<Data>>(25);
+```
+
+## Browser Compatibility
+
+Compatible with all modern browsers and Node.js environments that support ES2015+ features:
+- Chrome/Edge: ✅ Latest
+- Firefox: ✅ Latest
+- Safari: ✅ 15+
+- Node.js: ✅ 14+
+
+## License
+
+ISC License - See [LICENSE](LICENSE) file for details
 
-console.log(cache.get('key1')); // undefined
-console.log(cache.get('key2')); // value2
-console.log(cache.get('key3')); // value3
-console.log(cache.get('key4')); // value4
+## Contributing
 
-cache.put('key5', 'value5');
+Contributions are welcome! Please feel free to submit a Pull Request.
 
-console.log(cache.get('key2')); // undefined
+## Changelog
 
-```
+See [CHANGELOG.md](CHANGELOG.md) for release history.

package/dist/evicting-cache.d.ts

@@ -1,7 +1,14 @@
+type CacheStats = {
+    hits: number;
+    misses: number;
+    hitRate: number;
+};
 /** JavaScript implementation of a Least Recently Used(LRU) Cache using a Map. */
 declare class EvictingCache<K, V> {
     private readonly _capacity;
     private readonly cache;
+    private hits;
+    private misses;
     /**
      * Creates a new Evicting Cache with the given capacity.
      *
@@ -31,6 +38,13 @@ declare class EvictingCache<K, V> {
      * @returns {void}
      */
     put(key: K, value: V): void;
+    /**
+     * Removes the specified key from the cache.
+     *
+     * @param {K} key The key to remove.
+     * @returns {boolean} True if the key was in the cache and was removed, false otherwise.
+     */
+    delete(key: K): boolean;
     /**
      * Returns the value associated with the given key from the cache without updating the LRU order.
      *
@@ -40,6 +54,8 @@ declare class EvictingCache<K, V> {
     peek(key: K): V | null;
     /**
      * Returns the value for the key if it exists in the cache. If not, put the key-value pair into the cache and return the value.
+     * If the producer function throws an error, the cache state is not modified.
+     *
      * @param {K} key The key.
      * @param {function(): V} producer The value to put if the key does not exist in the cache.
      * @returns {V} The value corresponding to the key.
@@ -47,16 +63,55 @@ declare class EvictingCache<K, V> {
     getOrPut(key: K, producer: () => V): V;
     /**
      * Removes the least recently used key-value pair from the cache.
-     *
      * @returns {boolean} True if an item was removed, false otherwise.
      */
     evict(): boolean;
     /**
      * Clears the cache and the LRU list.
-     *
      * @returns {void}
      */
     clear(): void;
+    /**
+     * Executes a provided function once per each key/value pair in the cache, in insertion order.
+     * @param {(value: V, key: K, cache: EvictingCache<K, V>) => void} callbackfn Function to execute for each element.
+     * @param {unknown} [thisArg] Value to use as `this` when executing callback.
+     * @returns {void}
+     */
+    forEach(callbackfn: (value: V, key: K, cache: EvictingCache<K, V>) => void, thisArg?: unknown): void;
+    /**
+     * Adds multiple key-value pairs to the cache.
+     * Each pair is added individually, following the same LRU eviction rules as put().
+     * @param {Iterable<[K, V]>} entries The entries to add.
+     * @returns {void}
+     */
+    putAll(entries: Iterable<[K, V]>): void;
+    /**
+     * Gets multiple values from the cache.
+     * Each get updates the LRU order for that key.
+     *
+     * @param {Iterable<K>} keys The keys to get values for.
+     * @returns {Map<K, V>} A map of keys to their values (excludes missing keys).
+     */
+    getAll(keys: Iterable<K>): Map<K, V>;
+    /**
+     * Removes multiple keys from the cache.
+     *
+     * @param {Iterable<K>} keys The keys to remove.
+     * @returns {number} The number of keys that were removed.
+     */
+    deleteAll(keys: Iterable<K>): number;
+    /**
+     * Gets cache statistics including hit/miss counts and hit rate.
+     *
+     * @returns {CacheStats} Cache statistics.
+     */
+    getStats(): CacheStats;
+    /**
+     * Resets cache statistics to zero.
+     *
+     * @returns {void}
+     */
+    resetStats(): void;
     /**
      * Gets the capacity of the cache.
      * This is the maximum number of key-value pairs the cache can hold.
@@ -123,4 +178,4 @@ declare class EvictingCache<K, V> {
     private putAndEvict;
 }
 
-export { EvictingCache };
+export { EvictingCache };

package/dist/evicting-cache.js

@@ -1,2 +1,2 @@
-var r=class{_capacity;cache;constructor(e=100){if(e<1)throw new RangeError("capacity must be greater than 0");if(!Number.isInteger(e))throw new RangeError("capacity must be an integer");this._capacity=e,this.cache=new Map}get(e){let t=this.cache.get(e);return t===void 0?null:(this.cache.delete(e),this.cache.set(e,t),t)}has(e){return this.cache.has(e)}put(e,t){this.putAndEvict(e,t)}peek(e){return this.cache.get(e)??null}getOrPut(e,t){return this.get(e)??this.putAndEvict(e,t())}evict(){if(this.cache.size===0)return!1;let e=this.cache.keys().next().value;return this.cache.delete(e)}clear(){this.cache.clear()}get capacity(){return this._capacity}get size(){return this.cache.size}keys(){return this.cache.keys()}values(){return this.cache.values()}entries(){return this.cache.entries()}[Symbol.iterator](){return this.entries()}get[Symbol.toStringTag](){return"EvictingCache"}putAndEvict(e,t){return this.cache.has(e)?this.cache.delete(e):this._capacity<=this.cache.size&&this.evict(),this.cache.set(e,t),t}};export{r as EvictingCache};
+var r=class{_capacity;cache;hits=0;misses=0;constructor(e=100){if(e<1)throw new RangeError("capacity must be greater than 0");if(!Number.isInteger(e))throw new RangeError("capacity must be an integer");this._capacity=e,this.cache=new Map}get(e){let t=this.cache.get(e);return t===void 0?(this.misses++,null):(this.hits++,this.cache.delete(e),this.cache.set(e,t),t)}has(e){return this.cache.has(e)}put(e,t){this.putAndEvict(e,t)}delete(e){return this.cache.delete(e)}peek(e){return this.cache.get(e)??null}getOrPut(e,t){let s=this.get(e);if(s!==null)return s;let i=t();return this.putAndEvict(e,i)}evict(){let e=this.cache.keys().next();return e.done?!1:this.cache.delete(e.value)}clear(){this.cache.clear()}forEach(e,t){let s=t!==void 0?e.bind(t):e;this.cache.forEach((i,a)=>s(i,a,this))}putAll(e){for(let[t,s]of e)this.put(t,s)}getAll(e){let t=new Map;for(let s of e){let i=this.get(s);i!==null&&t.set(s,i)}return t}deleteAll(e){let t=0;for(let s of e)this.cache.delete(s)&&t++;return t}getStats(){let e=this.hits+this.misses;return{hits:this.hits,misses:this.misses,hitRate:e===0?0:this.hits/e}}resetStats(){this.hits=0,this.misses=0}get capacity(){return this._capacity}get size(){return this.cache.size}keys(){return this.cache.keys()}values(){return this.cache.values()}entries(){return this.cache.entries()}[Symbol.iterator](){return this.entries()}get[Symbol.toStringTag](){return"EvictingCache"}putAndEvict(e,t){return!this.cache.delete(e)&&this._capacity<=this.cache.size&&this.evict(),this.cache.set(e,t),t}};export{r as EvictingCache};
 //# sourceMappingURL=evicting-cache.js.map

package/dist/evicting-cache.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../src/evicting-cache.ts"],
-  "sourcesContent": ["/** JavaScript implementation of a Least Recently Used(LRU) Cache using a Map. */\nexport class EvictingCache<K, V> {\n\tprivate readonly _capacity: number;\n\tprivate readonly cache: Map<K, V>;\n\n\t/**\n\t * Creates a new Evicting Cache with the given capacity.\n\t *\n\t * @param {number} [capacity=100] The maximum number of key-value pairs the cache can hold.\n\t */\n\tconstructor(capacity: number = 100) {\n\t\tif (capacity < 1) { throw new RangeError('capacity must be greater than 0') }\n\t\tif (!Number.isInteger(capacity)) { throw new RangeError('capacity must be an integer') }\n\n\t\tthis._capacity = capacity;\n\t\tthis.cache = new Map();\n\t}\n\n\t/**\n\t * Returns the value associated with the given key from the cache and updates the LRU order.\n\t *\n\t * @param {K} key The key to get the value for.\n\t * @returns {V | null} The associated value if the key is in the cache, or null otherwise.\n\t */\n\tget(key: K): V | null {\n\t\tconst value = this.cache.get(key);\n\t\tif (value === undefined) { return null }\n\n\t\tthis.cache.delete(key);\n\t\t// Move the accessed item to the end (most recently used)\n\t\tthis.cache.set(key, value);\n\n\t\treturn value;\n\t}\n\n\t/**\n\t * Returns true if the given key is in the cache, false otherwise.\n\t *\n\t * @param {K} key The key to check.\n\t * @returns {boolean} True if the key is in the cache, false otherwise.\n\t */\n\thas(key: K): boolean {\n\t\treturn this.cache.has(key);\n\t}\n\n\t/**\n\t * Adds a new key-value pair to the cache and updates the LRU order.\n\t * If adding the new pair will exceed the capacity, removes the least recently used pair from the cache.\n\t *\n\t * @param {K} key The key to add.\n\t * @param {V} value The value to add.\n\t * @returns {void}\n\t */\n\tput(key: K, value: V): void {\n\t\tthis.putAndEvict(key, value);\n\t}\n\n\t/**\n\t * Returns the value associated with the given key from the cache without updating the LRU order.\n\t *\n\t * @param {K} key The key to get the value for.\n\t * @returns {V | null} The associated value if the key is in the cache, or null otherwise.\n\t */\n\tpeek(key: K): V | null {\n\t\treturn this.cache.get(key) ?? null;\n\t}\n\n\t/**\n\t * Returns the value for the key if it exists in the cache. If not, put the key-value pair into the cache and return the value.\n\t * @param {K} key The key.\n\t * @param {function(): V} producer The value to put if the key does not exist in the cache.\n\t * @returns {V} The value corresponding to the key.\n\t */\n\tgetOrPut(key: K, producer: () => V): V {\n\t\treturn this.get(key) ?? this.putAndEvict(key, producer());\n\t}\n\n\t/**\n\t * Removes the least recently used key-value pair from the cache.\n\t *\n\t * @returns {boolean} True if an item was removed, false otherwise.\n\t */\n\tevict(): boolean {\n\t\tif (this.cache.size === 0) { return false }\n\t\tconst key = this.cache.keys().next().value as K;\n\n\t\treturn this.cache.delete(key);\n\t}\n\n\t/**\n\t * Clears the cache and the LRU list.\n\t *\n\t * @returns {void}\n\t */\n\tclear(): void {\n\t\tthis.cache.clear();\n\t}\n\n\t/**\n\t * Gets the capacity of the cache.\n\t * This is the maximum number of key-value pairs the cache can hold.\n\t * This is not the number of key-value pairs in the cache.\n\t *\n\t * @readonly\n\t * @returns {number} The capacity of the cache.\n\t */\n\tget capacity(): number {\n\t\treturn this._capacity;\n\t}\n\n\t/**\n\t * Gets the size of the cache.\n\t * This is the number of key-value pairs in the cache.\n\t * This is not the capacity of the cache.\n\t * The capacity is the maximum number of key-value pairs the cache can hold.\n\t * The size is the number of key-value pairs currently in the cache.\n\t * The size will be less than or equal to the capacity.\n\t *\n\t * @returns {number} The size of the cache.\n\t */\n\tget size(): number {\n\t\treturn this.cache.size;\n\t}\n\n\t/**\n\t * Returns an iterator over the keys in the cache.\n\t * The keys are returned in the order of least recently used to most recently used.\n\t *\n\t * @returns {IterableIterator<K>} An iterator over the keys in the cache.\n\t */\n\tkeys(): IterableIterator<K> {\n\t\treturn this.cache.keys();\n\t}\n\n\t/**\n\t * Returns an iterator over the values in the cache.\n\t * The values are returned in the order of least recently used to most recently used.\n\t *\n\t * @returns {IterableIterator<V>} An iterator over the values in the cache.\n\t */\n\tvalues(): IterableIterator<V> {\n\t\treturn this.cache.values();\n\t}\n\n\t/**\n\t * Returns an iterator over the entries in the cache.\n\t * The entries are returned in the order of least recently used to most recently used.\n\t *\n\t * @returns {IterableIterator<[K, V]>} An iterator over the entries in the cache.\n\t */\n\tentries(): IterableIterator<[K, V]> {\n\t\treturn this.cache.entries();\n\t}\n\n\t/**\n\t * Returns an iterator over the entries in the cache.\n\t * The entries are returned in the order of least recently used to most recently used.\n\t *\n\t * @returns {IterableIterator<[K, V]>} An iterator over the entries in the cache.\n\t */\n\t[Symbol.iterator](): IterableIterator<[K, V]> {\n\t\treturn this.entries();\n\t}\n\n\t/**\n\t * Gets the description of the object.\n\t *\n\t * @override\n\t * @returns {string} The description of the object.\n\t */\n\tget [Symbol.toStringTag](): string {\n\t\treturn 'EvictingCache';\n\t}\n\n\t/**\n\t * Puts a key-value pair into the cache and evicts the least recently used item if necessary.\n\t * If the key already exists, the item is removed and re-added to update its position.\n\t * If the cache is full, the least recently used item is evicted and the new item is added.\n\t * @param {K} key The key to put.\n\t * @param {V} value The value to put.\n\t * @returns {V} The value that was put.\n\t */\n\tprivate putAndEvict(key: K, value: V): V {\n\t\tif (this.cache.has(key)) {\n\t\t\tthis.cache.delete(key);\n\t\t} else if (this._capacity <= this.cache.size) {\n\t\t\tthis.evict();\n\t\t}\n\n\t\tthis.cache.set(key, value);\n\n\t\treturn value;\n\t}\n}"],
-  "mappings": "AACO,IAAMA,EAAN,KAA0B,CACf,UACA,MAOjB,YAAYC,EAAmB,IAAK,CACnC,GAAIA,EAAW,EAAK,MAAM,IAAI,WAAW,iCAAiC,EAC1E,GAAI,CAAC,OAAO,UAAUA,CAAQ,EAAK,MAAM,IAAI,WAAW,6BAA6B,EAErF,KAAK,UAAYA,EACjB,KAAK,MAAQ,IAAI,GAClB,CAQA,IAAIC,EAAkB,CACrB,IAAMC,EAAQ,KAAK,MAAM,IAAID,CAAG,EAChC,OAAIC,IAAU,OAAoB,MAElC,KAAK,MAAM,OAAOD,CAAG,EAErB,KAAK,MAAM,IAAIA,EAAKC,CAAK,EAElBA,EACR,CAQA,IAAID,EAAiB,CACpB,OAAO,KAAK,MAAM,IAAIA,CAAG,CAC1B,CAUA,IAAIA,EAAQC,EAAgB,CAC3B,KAAK,YAAYD,EAAKC,CAAK,CAC5B,CAQA,KAAKD,EAAkB,CACtB,OAAO,KAAK,MAAM,IAAIA,CAAG,GAAK,IAC/B,CAQA,SAASA,EAAQE,EAAsB,CACtC,OAAO,KAAK,IAAIF,CAAG,GAAK,KAAK,YAAYA,EAAKE,EAAS,CAAC,CACzD,CAOA,OAAiB,CAChB,GAAI,KAAK,MAAM,OAAS,EAAK,MAAO,GACpC,IAAMF,EAAM,KAAK,MAAM,KAAK,EAAE,KAAK,EAAE,MAErC,OAAO,KAAK,MAAM,OAAOA,CAAG,CAC7B,CAOA,OAAc,CACb,KAAK,MAAM,MAAM,CAClB,CAUA,IAAI,UAAmB,CACtB,OAAO,KAAK,SACb,CAYA,IAAI,MAAe,CAClB,OAAO,KAAK,MAAM,IACnB,CAQA,MAA4B,CAC3B,OAAO,KAAK,MAAM,KAAK,CACxB,CAQA,QAA8B,CAC7B,OAAO,KAAK,MAAM,OAAO,CAC1B,CAQA,SAAoC,CACnC,OAAO,KAAK,MAAM,QAAQ,CAC3B,CAQA,CAAC,OAAO,QAAQ,GAA8B,CAC7C,OAAO,KAAK,QAAQ,CACrB,CAQA,IAAK,OAAO,WAAW,GAAY,CAClC,MAAO,eACR,CAUQ,YAAYA,EAAQC,EAAa,CACxC,OAAI,KAAK,MAAM,IAAID,CAAG,EACrB,KAAK,MAAM,OAAOA,CAAG,EACX,KAAK,WAAa,KAAK,MAAM,MACvC,KAAK,MAAM,EAGZ,KAAK,MAAM,IAAIA,EAAKC,CAAK,EAElBA,CACR,CACD",
-  "names": ["EvictingCache", "capacity", "key", "value", "producer"]
+  "sourcesContent": ["type CacheStats = {\n\thits: number;\n\tmisses: number;\n\thitRate: number;\n};\n\n/** JavaScript implementation of a Least Recently Used(LRU) Cache using a Map. */\nexport class EvictingCache<K, V> {\n\tprivate readonly _capacity: number;\n\tprivate readonly cache: Map<K, V>;\n\tprivate hits = 0;\n\tprivate misses = 0;\n\n\t/**\n\t * Creates a new Evicting Cache with the given capacity.\n\t *\n\t * @param {number} [capacity=100] The maximum number of key-value pairs the cache can hold.\n\t */\n\tconstructor(capacity: number = 100) {\n\t\tif (capacity < 1) { throw new RangeError('capacity must be greater than 0') }\n\t\tif (!Number.isInteger(capacity)) { throw new RangeError('capacity must be an integer') }\n\n\t\tthis._capacity = capacity;\n\t\tthis.cache = new Map();\n\t}\n\n\t/**\n\t * Returns the value associated with the given key from the cache and updates the LRU order.\n\t *\n\t * @param {K} key The key to get the value for.\n\t * @returns {V | null} The associated value if the key is in the cache, or null otherwise.\n\t */\n\tget(key: K): V | null {\n\t\tconst value = this.cache.get(key);\n\t\tif (value === undefined) {\n\t\t\tthis.misses++;\n\t\t\treturn null;\n\t\t}\n\n\t\tthis.hits++;\n\t\tthis.cache.delete(key);\n\t\t// Move the accessed item to the end (most recently used)\n\t\tthis.cache.set(key, value);\n\n\t\treturn value;\n\t}\n\n\t/**\n\t * Returns true if the given key is in the cache, false otherwise.\n\t *\n\t * @param {K} key The key to check.\n\t * @returns {boolean} True if the key is in the cache, false otherwise.\n\t */\n\thas(key: K): boolean {\n\t\treturn this.cache.has(key);\n\t}\n\n\t/**\n\t * Adds a new key-value pair to the cache and updates the LRU order.\n\t * If adding the new pair will exceed the capacity, removes the least recently used pair from the cache.\n\t *\n\t * @param {K} key The key to add.\n\t * @param {V} value The value to add.\n\t * @returns {void}\n\t */\n\tput(key: K, value: V): void {\n\t\tthis.putAndEvict(key, value);\n\t}\n\n\t/**\n\t * Removes the specified key from the cache.\n\t *\n\t * @param {K} key The key to remove.\n\t * @returns {boolean} True if the key was in the cache and was removed, false otherwise.\n\t */\n\tdelete(key: K): boolean {\n\t\treturn this.cache.delete(key);\n\t}\n\n\t/**\n\t * Returns the value associated with the given key from the cache without updating the LRU order.\n\t *\n\t * @param {K} key The key to get the value for.\n\t * @returns {V | null} The associated value if the key is in the cache, or null otherwise.\n\t */\n\tpeek(key: K): V | null {\n\t\treturn this.cache.get(key) ?? null;\n\t}\n\n\t/**\n\t * Returns the value for the key if it exists in the cache. If not, put the key-value pair into the cache and return the value.\n\t * If the producer function throws an error, the cache state is not modified.\n\t *\n\t * @param {K} key The key.\n\t * @param {function(): V} producer The value to put if the key does not exist in the cache.\n\t * @returns {V} The value corresponding to the key.\n\t */\n\tgetOrPut(key: K, producer: () => V): V {\n\t\tconst existing = this.get(key);\n\t\tif (existing !== null) { return existing }\n\n\t\t// If producer throws, cache state remains unchanged\n\t\tconst value = producer();\n\t\treturn this.putAndEvict(key, value);\n\t}\n\n\t/**\n\t * Removes the least recently used key-value pair from the cache.\n\t * @returns {boolean} True if an item was removed, false otherwise.\n\t */\n\tevict(): boolean {\n\t\tconst firstEntry = this.cache.keys().next();\n\t\tif (firstEntry.done) { return false }\n\n\t\treturn this.cache.delete(firstEntry.value);\n\t}\n\n\t/**\n\t * Clears the cache and the LRU list.\n\t * @returns {void}\n\t */\n\tclear(): void {\n\t\tthis.cache.clear();\n\t}\n\n\t/**\n\t * Executes a provided function once per each key/value pair in the cache, in insertion order.\n\t * @param {(value: V, key: K, cache: EvictingCache<K, V>) => void} callbackfn Function to execute for each element.\n\t * @param {unknown} [thisArg] Value to use as `this` when executing callback.\n\t * @returns {void}\n\t */\n\tforEach(callbackfn: (value: V, key: K, cache: EvictingCache<K, V>) => void, thisArg?: unknown): void {\n\t\tconst boundCallback = thisArg !== undefined ? callbackfn.bind(thisArg) : callbackfn;\n\t\tthis.cache.forEach((value, key) => boundCallback(value, key, this));\n\t}\n\n\t/**\n\t * Adds multiple key-value pairs to the cache.\n\t * Each pair is added individually, following the same LRU eviction rules as put().\n\t * @param {Iterable<[K, V]>} entries The entries to add.\n\t * @returns {void}\n\t */\n\tputAll(entries: Iterable<[K, V]>): void {\n\t\tfor (const [key, value] of entries) { this.put(key, value) }\n\t}\n\n\t/**\n\t * Gets multiple values from the cache.\n\t * Each get updates the LRU order for that key.\n\t *\n\t * @param {Iterable<K>} keys The keys to get values for.\n\t * @returns {Map<K, V>} A map of keys to their values (excludes missing keys).\n\t */\n\tgetAll(keys: Iterable<K>): Map<K, V> {\n\t\tconst result = new Map<K, V>();\n\t\tfor (const key of keys) {\n\t\t\tconst value = this.get(key);\n\t\t\tif (value !== null) { result.set(key, value) }\n\t\t}\n\n\t\treturn result;\n\t}\n\n\t/**\n\t * Removes multiple keys from the cache.\n\t *\n\t * @param {Iterable<K>} keys The keys to remove.\n\t * @returns {number} The number of keys that were removed.\n\t */\n\tdeleteAll(keys: Iterable<K>): number {\n\t\tlet count = 0;\n\t\tfor (const key of keys) {\n\t\t\tif (this.cache.delete(key)) { count++ }\n\t\t}\n\n\t\treturn count;\n\t}\n\n\t/**\n\t * Gets cache statistics including hit/miss counts and hit rate.\n\t *\n\t * @returns {CacheStats} Cache statistics.\n\t */\n\tgetStats(): CacheStats {\n\t\tconst total = this.hits + this.misses;\n\n\t\treturn { hits: this.hits, misses: this.misses, hitRate: total === 0 ? 0 : this.hits / total };\n\t}\n\n\t/**\n\t * Resets cache statistics to zero.\n\t *\n\t * @returns {void}\n\t */\n\tresetStats(): void {\n\t\tthis.hits = 0;\n\t\tthis.misses = 0;\n\t}\n\n\t/**\n\t * Gets the capacity of the cache.\n\t * This is the maximum number of key-value pairs the cache can hold.\n\t * This is not the number of key-value pairs in the cache.\n\t *\n\t * @readonly\n\t * @returns {number} The capacity of the cache.\n\t */\n\tget capacity(): number {\n\t\treturn this._capacity;\n\t}\n\n\t/**\n\t * Gets the size of the cache.\n\t * This is the number of key-value pairs in the cache.\n\t * This is not the capacity of the cache.\n\t * The capacity is the maximum number of key-value pairs the cache can hold.\n\t * The size is the number of key-value pairs currently in the cache.\n\t * The size will be less than or equal to the capacity.\n\t *\n\t * @returns {number} The size of the cache.\n\t */\n\tget size(): number {\n\t\treturn this.cache.size;\n\t}\n\n\t/**\n\t * Returns an iterator over the keys in the cache.\n\t * The keys are returned in the order of least recently used to most recently used.\n\t *\n\t * @returns {IterableIterator<K>} An iterator over the keys in the cache.\n\t */\n\tkeys(): IterableIterator<K> {\n\t\treturn this.cache.keys();\n\t}\n\n\t/**\n\t * Returns an iterator over the values in the cache.\n\t * The values are returned in the order of least recently used to most recently used.\n\t *\n\t * @returns {IterableIterator<V>} An iterator over the values in the cache.\n\t */\n\tvalues(): IterableIterator<V> {\n\t\treturn this.cache.values();\n\t}\n\n\t/**\n\t * Returns an iterator over the entries in the cache.\n\t * The entries are returned in the order of least recently used to most recently used.\n\t *\n\t * @returns {IterableIterator<[K, V]>} An iterator over the entries in the cache.\n\t */\n\tentries(): IterableIterator<[K, V]> {\n\t\treturn this.cache.entries();\n\t}\n\n\t/**\n\t * Returns an iterator over the entries in the cache.\n\t * The entries are returned in the order of least recently used to most recently used.\n\t *\n\t * @returns {IterableIterator<[K, V]>} An iterator over the entries in the cache.\n\t */\n\t[Symbol.iterator](): IterableIterator<[K, V]> {\n\t\treturn this.entries();\n\t}\n\n\t/**\n\t * Gets the description of the object.\n\t *\n\t * @override\n\t * @returns {string} The description of the object.\n\t */\n\tget [Symbol.toStringTag](): string {\n\t\treturn 'EvictingCache';\n\t}\n\n\t/**\n\t * Puts a key-value pair into the cache and evicts the least recently used item if necessary.\n\t * If the key already exists, the item is removed and re-added to update its position.\n\t * If the cache is full, the least recently used item is evicted and the new item is added.\n\t * @param {K} key The key to put.\n\t * @param {V} value The value to put.\n\t * @returns {V} The value that was put.\n\t */\n\tprivate putAndEvict(key: K, value: V): V {\n\t\tconst existed = this.cache.delete(key);\n\t\tif (!existed && this._capacity <= this.cache.size) { this.evict() }\n\n\t\tthis.cache.set(key, value);\n\n\t\treturn value;\n\t}\n}"],
+  "mappings": "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",
+  "names": ["EvictingCache", "capacity", "key", "value", "producer", "existing", "firstEntry", "callbackfn", "thisArg", "boundCallback", "entries", "keys", "result", "count", "total"]
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "evicting-cache",
   "author": "D1g1talEntr0py",
-  "version": "2.2.1",
+  "version": "2.3.1",
   "license": "ISC",
   "description": "Cache implementation with an LRU evicting policy",
   "type": "module",
@@ -24,19 +24,19 @@
   ],
   "devDependencies": {
     "@eslint/compat": "^1.4.0",
-    "@eslint/js": "^9.37.0",
+    "@eslint/js": "^9.38.0",
     "@types/eslint": "^9.6.1",
-    "@types/node": "^24.7.1",
-    "@typescript-eslint/eslint-plugin": "^8.46.0",
-    "@typescript-eslint/parser": "^8.46.0",
-    "@vitest/coverage-v8": "^3.2.4",
-    "eslint": "^9.37.0",
+    "@types/node": "^24.9.1",
+    "@typescript-eslint/eslint-plugin": "^8.46.2",
+    "@typescript-eslint/parser": "^8.46.2",
+    "@vitest/coverage-v8": "^4.0.4",
+    "eslint": "^9.38.0",
     "eslint-plugin-compat": "^6.0.2",
-    "eslint-plugin-jsdoc": "^61.1.0",
+    "eslint-plugin-jsdoc": "^61.1.9",
     "globals": "^16.4.0",
     "typescript": "^5.9.3",
-    "typescript-eslint": "^8.46.0",
-    "vitest": "^3.2.4"
+    "typescript-eslint": "^8.46.2",
+    "vitest": "^4.0.4"
   },
   "browserslist": [
     "defaults",
@@ -46,11 +46,13 @@
   "scripts": {
     "build": "tsbuild",
     "build:watch": "tsbuild --watch",
-    "type-check": "tsbuild --typeCheck",
+    "type-check": "tsbuild --type-check",
     "lint": "eslint",
     "test": "vitest run",
     "test:coverage": "vitest run --coverage",
     "test:watch": "vitest",
-    "prepublish": "pnpm lint && pnpm test && pnpm -s build"
+    "prepublish": "pnpm lint && pnpm test && pnpm -s build --minify --force",
+    "preversion": "pnpm lint && pnpm test",
+    "version": "node -e \"const fs=require('fs');const d=new Date().toISOString().split('T')[0];const v=require('./package.json').version;let c=fs.readFileSync('CHANGELOG.md','utf8');c=c.replace('## [Unreleased]','## ['+v+'] - '+d);fs.writeFileSync('CHANGELOG.md',c);\" && git add CHANGELOG.md"
   }
 }

package/src/evicting-cache.ts

@@ -1,7 +1,15 @@
+type CacheStats = {
+	hits: number;
+	misses: number;
+	hitRate: number;
+};
+
 /** JavaScript implementation of a Least Recently Used(LRU) Cache using a Map. */
 export class EvictingCache<K, V> {
 	private readonly _capacity: number;
 	private readonly cache: Map<K, V>;
+	private hits = 0;
+	private misses = 0;
 
 	/**
 	 * Creates a new Evicting Cache with the given capacity.
@@ -24,8 +32,12 @@ export class EvictingCache<K, V> {
 	 */
 	get(key: K): V | null {
 		const value = this.cache.get(key);
-		if (value === undefined) { return null }
+		if (value === undefined) {
+			this.misses++;
+			return null;
+		}
 
+		this.hits++;
 		this.cache.delete(key);
 		// Move the accessed item to the end (most recently used)
 		this.cache.set(key, value);
@@ -55,6 +67,16 @@ export class EvictingCache<K, V> {
 		this.putAndEvict(key, value);
 	}
 
+	/**
+	 * Removes the specified key from the cache.
+	 *
+	 * @param {K} key The key to remove.
+	 * @returns {boolean} True if the key was in the cache and was removed, false otherwise.
+	 */
+	delete(key: K): boolean {
+		return this.cache.delete(key);
+	}
+
 	/**
 	 * Returns the value associated with the given key from the cache without updating the LRU order.
 	 *
@@ -67,35 +89,114 @@ export class EvictingCache<K, V> {
 
 	/**
 	 * Returns the value for the key if it exists in the cache. If not, put the key-value pair into the cache and return the value.
+	 * If the producer function throws an error, the cache state is not modified.
+	 *
 	 * @param {K} key The key.
 	 * @param {function(): V} producer The value to put if the key does not exist in the cache.
 	 * @returns {V} The value corresponding to the key.
 	 */
 	getOrPut(key: K, producer: () => V): V {
-		return this.get(key) ?? this.putAndEvict(key, producer());
+		const existing = this.get(key);
+		if (existing !== null) { return existing }
+
+		// If producer throws, cache state remains unchanged
+		const value = producer();
+		return this.putAndEvict(key, value);
 	}
 
 	/**
 	 * Removes the least recently used key-value pair from the cache.
-	 *
 	 * @returns {boolean} True if an item was removed, false otherwise.
 	 */
 	evict(): boolean {
-		if (this.cache.size === 0) { return false }
-		const key = this.cache.keys().next().value as K;
+		const firstEntry = this.cache.keys().next();
+		if (firstEntry.done) { return false }
 
-		return this.cache.delete(key);
+		return this.cache.delete(firstEntry.value);
 	}
 
 	/**
 	 * Clears the cache and the LRU list.
-	 *
 	 * @returns {void}
 	 */
 	clear(): void {
 		this.cache.clear();
 	}
 
+	/**
+	 * Executes a provided function once per each key/value pair in the cache, in insertion order.
+	 * @param {(value: V, key: K, cache: EvictingCache<K, V>) => void} callbackfn Function to execute for each element.
+	 * @param {unknown} [thisArg] Value to use as `this` when executing callback.
+	 * @returns {void}
+	 */
+	forEach(callbackfn: (value: V, key: K, cache: EvictingCache<K, V>) => void, thisArg?: unknown): void {
+		const boundCallback = thisArg !== undefined ? callbackfn.bind(thisArg) : callbackfn;
+		this.cache.forEach((value, key) => boundCallback(value, key, this));
+	}
+
+	/**
+	 * Adds multiple key-value pairs to the cache.
+	 * Each pair is added individually, following the same LRU eviction rules as put().
+	 * @param {Iterable<[K, V]>} entries The entries to add.
+	 * @returns {void}
+	 */
+	putAll(entries: Iterable<[K, V]>): void {
+		for (const [key, value] of entries) { this.put(key, value) }
+	}
+
+	/**
+	 * Gets multiple values from the cache.
+	 * Each get updates the LRU order for that key.
+	 *
+	 * @param {Iterable<K>} keys The keys to get values for.
+	 * @returns {Map<K, V>} A map of keys to their values (excludes missing keys).
+	 */
+	getAll(keys: Iterable<K>): Map<K, V> {
+		const result = new Map<K, V>();
+		for (const key of keys) {
+			const value = this.get(key);
+			if (value !== null) { result.set(key, value) }
+		}
+
+		return result;
+	}
+
+	/**
+	 * Removes multiple keys from the cache.
+	 *
+	 * @param {Iterable<K>} keys The keys to remove.
+	 * @returns {number} The number of keys that were removed.
+	 */
+	deleteAll(keys: Iterable<K>): number {
+		let count = 0;
+		for (const key of keys) {
+			if (this.cache.delete(key)) { count++ }
+		}
+
+		return count;
+	}
+
+	/**
+	 * Gets cache statistics including hit/miss counts and hit rate.
+	 *
+	 * @returns {CacheStats} Cache statistics.
+	 */
+	getStats(): CacheStats {
+		const total = this.hits + this.misses;
+
+		return { hits: this.hits, misses: this.misses, hitRate: total === 0 ? 0 : this.hits / total };
+	}
+
+	/**
+	 * Resets cache statistics to zero.
+	 *
+	 * @returns {void}
+	 */
+	resetStats(): void {
+		this.hits = 0;
+		this.misses = 0;
+	}
+
 	/**
 	 * Gets the capacity of the cache.
 	 * This is the maximum number of key-value pairs the cache can hold.
@@ -181,11 +282,8 @@ export class EvictingCache<K, V> {
 	 * @returns {V} The value that was put.
 	 */
 	private putAndEvict(key: K, value: V): V {
-		if (this.cache.has(key)) {
-			this.cache.delete(key);
-		} else if (this._capacity <= this.cache.size) {
-			this.evict();
-		}
+		const existed = this.cache.delete(key);
+		if (!existed && this._capacity <= this.cache.size) { this.evict() }
 
 		this.cache.set(key, value);