tiny-lru

# Tiny LRU ## What is Tiny LRU? **Tiny LRU** is a tool that helps programs remember things for a short time, so they can work faster and use less memory. It's useful for both websites and apps. ### What is a "Cache"? A cache is like a small, quick-access box where a program stores things it might need again soon. Instead of looking up information from scratch every time (which can be slow), it checks the cache first. ### What does "Least Recently Used" (LRU) mean? Imagine your cache is a box that can only fit a certain number of items. When the box is full and you want to add something new, you remove the item you haven't used in the longest time. This keeps the most recently used things handy, and clears out the old things you don't need anymore. ### Why use Tiny LRU? - **Speeds things up**: By remembering recent information, programs can respond faster. - **Saves resources**: Limits how much memory is used by only keeping the most important items. - **Works anywhere**: Can be used in many kinds of apps, big or small. ### When is it helpful? - Websites that show the same info to many people - Apps that look up data from the internet - Any program that wants to avoid repeating slow or expensive work ## How Does Tiny LRU Work? 1. You set a limit for how many things the cache can remember. 2. When the program needs to remember something, it puts it in the cache. 3. If the cache is full, it removes the oldest unused item to make space. 4. If the program needs something, it checks the cache first before doing extra work. ## Using the factory ```javascript import {lru} from "tiny-lru"; const cache = lru(max, ttl = 0, resetTtl = false); ``` ## Using the Class ```javascript import {LRU} from "tiny-lru"; const cache = new LRU(max, ttl = 0, resetTtl = false); ``` ```javascript import {LRU} from "tiny-lru"; class MyCache extends LRU {} ``` ## Interoperability Lodash provides a `memoize` function with a cache that can be swapped out as long as it implements the right interface. See the [lodash docs](https://lodash.com/docs#memoize) for more on `memoize`. ```javascript _.memoize.Cache = lru().constructor; const memoized = _.memoize(myFunc); memoized.cache.max = 10; ``` ## Testing Tiny-LRU has 100% code coverage with its tests. ```console --------------|---------|----------|---------|---------|------------------- File | % Stmts | % Branch | % Funcs | % Lines | Uncovered Line #s --------------|---------|----------|---------|---------|------------------- All files | 100 | 91.46 | 100 | 100 | tiny-lru.cjs | 100 | 91.46 | 100 | 100 | 11-31,134,181,215 --------------|---------|----------|---------|---------|------------------- ``` ## API Reference ### Properties #### first Item in "first" or "bottom" position; default is `null` ```javascript const cache = lru(); cache.first; // null - it's a new cache! ``` #### last Item in "last" or "top" position; default is `null` ```javascript const cache = lru(); cache.last; // null - it's a new cache! ``` #### max Max items to hold in cache; default is `1000` ```javascript const cache = lru(500); cache.max; // 500 ``` #### resetTtl Resets `item.expiry` with each `set()` if `true`; default is `false` ```javascript const cache = lru(500, 5*6e4, true); cache.resetTtl; // true ``` #### size Number of items in cache ```javascript const cache = lru(); cache.size; // 0 - it's a new cache! ``` #### ttl Milliseconds an item will remain in cache; lazy expiration upon next `get()` of an item ```javascript const cache = lru(100, 3e4); cache.ttl; // 30000; ``` ### Methods #### clear Clears the contents of the cache return {Object} LRU instance ```javascript cache.clear(); ``` #### delete Removes item from cache param {String} key Item key return {Object} LRU instance ```javascript cache.delete("myKey"); ``` #### entries(*["key1", "key2"]*) Returns an `Array` cache items param {Array} keys (Optional) Cache item keys to get, defaults to `this.keys()` if not provided return {Object} LRU instance ```javascript cache.entries(['myKey1', 'myKey2']); ``` #### evict Evicts the least recently used item from cache return {Object} LRU instance ```javascript cache.evict(); ``` #### expiresAt Gets expiration time for cached item param {String} key Item key return {Mixed} Undefined or number (epoch time) ```javascript const item = cache.expiresAt("myKey"); ``` #### get Gets cached item and moves it to the front param {String} key Item key return {Mixed} Undefined or Item value ```javascript const item = cache.get("myKey"); ``` #### has Returns a `Boolean` indicating if `key` is in cache return {Object} LRU instance ```javascript cache.has('myKey'); ``` #### keys Returns an `Array` of cache item keys (`first` to `last`) return {Array} Array of keys ```javascript console.log(cache.keys()); ``` #### set Sets item in cache as `first` param {String} key Item key param {Mixed} value Item value return {Object} LRU instance ```javascript cache.set("myKey", {prop: true}); ``` #### setWithEvicted Sets an item in the cache and returns the evicted item if the cache was full and an eviction occurred. If no eviction occurs, returns `null`. param {String} key Item key param {Mixed} value Item value param {Boolean} [resetTtl] Optionally reset the TTL for the item return {Object|null} The evicted item (shallow clone) or null ```javascript const evicted = cache.setWithEvicted("myKey", {prop: true}); if (evicted) { console.log("Evicted item:", evicted.key, evicted.value); } ``` #### values(*["key1", "key2"]*) Returns an `Array` cache items param {Array} keys (Optional) Cache item keys to get return {Array} Cache items ```javascript cache.values(['abc', 'def']); ``` ## License Copyright (c) 2025 Jason Mulligan Licensed under the BSD-3 license.