Map as LRU is a lightweight and efficient LRU (Least Recently Used) cache implementation built on top of JavaScript's native Map. It provides a functional API for cache operations while maintaining LRU eviction behavior when the cache reaches its capacity limit.
- ✅ Lightweight: Built on native JavaScript Map
- ✅ Functional API: Immutable-style operations
- ✅ TypeScript Support: Full type safety with generics
- ✅ LRU Eviction: Automatically evicts least recently used items
- ✅ Map Compatible: Supports standard Map methods and iteration
- ✅ Peek Operation: Access values without affecting LRU order
- ✅ Flexible Keys: Supports any type as keys (string, number, object, etc.)
To install Map as LRU, use npm or pnpm:
npm install map-as-lruor
pnpm add map-as-lruHere is a basic example of how to use it:
import * as lru from 'map-as-lru';
// Create a cache with capacity of 3
const cache = lru.create<string, number>(3);
// Set values
lru.set(cache, 'a', 1);
lru.set(cache, 'b', 2);
lru.set(cache, 'c', 3);
// Get values (updates LRU order)
const value = lru.get(cache, 'a'); // 1
// Add more items - will evict least recently used
lru.set(cache, 'd', 4); // 'b' gets evicted
console.log(cache.has('b')); // false
console.log(cache.has('a')); // trueCreates a new LRU cache with the specified capacity.
function create<K, V>(
capacity: number,
iterable?: Iterable<readonly [K, V]> | null
): LRUCache<K, V>Parameters:
capacity(number): Maximum number of items the cache can holditerable(optional): Initial data to populate the cache
Returns: A new LRU cache instance
Example:
// Create empty cache
const cache1 = lru.create<string, number>(10);
// Create cache with initial data
const cache2 = lru.create(5, [
['key1', 'value1'],
['key2', 'value2']
]);Returns the maximum capacity of the cache.
function capacity(cache: LRUCache<any, any>): numberParameters:
cache: The LRU cache instance
Returns: The maximum capacity of the cache
Example:
const cache = lru.create<string, number>(10);
console.log(lru.capacity(cache)); // 10Sets a key-value pair in the cache. If the cache exceeds capacity, the least recently used item will be evicted.
function set<K, V>(cache: LRUCache<K, V>, key: K, value: V): voidParameters:
cache: The LRU cache instancekey: The key to setvalue: The value to associate with the key
Example:
const cache = lru.create<string, number>(3);
lru.set(cache, 'user:1', 100);
lru.set(cache, 'user:2', 200);Retrieves a value by key and marks it as recently used (updates LRU order).
function get<K, V>(cache: LRUCache<K, V>, key: K): V | undefinedParameters:
cache: The LRU cache instancekey: The key to retrieve
Returns: The value associated with the key, or undefined if not found
Example:
const cache = lru.create<string, number>(3);
lru.set(cache, 'key', 42);
const value = lru.get(cache, 'key'); // 42
const missing = lru.get(cache, 'nonexistent'); // undefinedRetrieves a value by key without affecting the LRU order.
function peek<K, V>(cache: LRUCache<K, V>, key: K): V | undefinedParameters:
cache: The LRU cache instancekey: The key to peek at
Returns: The value associated with the key, or undefined if not found
Example:
const cache = lru.create<string, number>(2);
lru.set(cache, 'a', 1);
lru.set(cache, 'b', 2);
// Peek doesn't affect order
lru.peek(cache, 'a'); // 1
// Adding a new item will still evict 'a' because peek didn't update order
lru.set(cache, 'c', 3);
console.log(cache.has('a')); // falseThe LRU cache supports all standard Map methods and properties for additional functionality:
cache.has(key): Check if a key existscache.delete(key): Remove a specific keycache.clear(): Remove all entriescache.size: Get current number of entriescache.keys(): Iterator over keyscache.values(): Iterator over valuescache.entries(): Iterator over key-value pairscache.forEach(callback): Execute a function for each entry
Example:
const cache = lru.create<string, number>(3);
lru.set(cache, 'a', 1);
lru.set(cache, 'b', 2);
console.log(cache.size); // 2
console.log(cache.has('a')); // true
// Iterate over entries
for (const [key, value] of cache.entries()) {
console.log(`${key}: ${value}`);
}
// Clear all entries
cache.clear();
console.log(cache.size); // 0import * as lru from 'map-as-lru';
const cache = lru.create<string, string>(3);
// Fill the cache
lru.set(cache, 'first', 'value1');
lru.set(cache, 'second', 'value2');
lru.set(cache, 'third', 'value3');
// Access an item to make it recently used
lru.get(cache, 'first');
// Add a fourth item - 'second' will be evicted (least recently used)
lru.set(cache, 'fourth', 'value4');
console.log(cache.has('second')); // false (evicted)
console.log(cache.has('first')); // true (recently accessed)// String keys
const stringCache = lru.create<string, any>(5);
lru.set(stringCache, 'user:123', { name: 'John' });
// Number keys
const numberCache = lru.create<number, string>(5);
lru.set(numberCache, 123, 'user data');
// Object keys
const objectCache = lru.create<object, string>(5);
const keyObj = { id: 1 };
lru.set(objectCache, keyObj, 'some value');const initialData: [string, number][] = [
['a', 1],
['b', 2],
['c', 3]
];
const cache = lru.create(5, initialData);
console.log(lru.get(cache, 'a')); // 1const cache = lru.create<string, number>(2);
lru.set(cache, 'a', 1);
lru.set(cache, 'b', 2);
// Using peek - doesn't affect LRU order
lru.peek(cache, 'a'); // 1
// Using get - updates LRU order
lru.get(cache, 'a'); // 1 (now 'a' is most recently used)
lru.set(cache, 'c', 3);
// With peek: 'a' would be evicted
// With get: 'b' would be evictedWe welcome contributions to Map as LRU! If you have any ideas, suggestions, or bug reports, please open an issue on our GitHub repository.
To contribute code, please follow these steps:
- Fork the repository.
- Create a new branch (
git checkout -b feature-branch). - Make your changes and commit them (
git commit -m 'Add new feature'). - Push to the branch (
git push origin feature-branch). - Open a pull request.
Please ensure your code adheres to our coding standards and includes appropriate tests.
This project is licensed under the MIT License.