🔥 An extremely fast and efficient LRU cache for JavaScript with high compatibility (including Browsers).
npm install lru.min
🔥 An extremely fast, efficient, and lightweight LRU Cache for JavaScript (Browser compatible).
- 🎖️ lru.min is fully compatible with both Node.js _(8+)_, Bun, Deno and, browser environments. All of this, while maintaining the same high performance _(and a little more)_ as the most popular LRU packages.
---
``bash`Node.js
npm i lru.min
`bash`Bun
bun add lru.min
`bash`Deno
deno add npm:lru.min
---
`js
import { createLRU } from 'lru.min';
const max = 2;
const onEviction = (key, value) => {
console.log(Key "${key}" with value "${value}" has been evicted.);
};
const LRU = createLRU({
max,
onEviction,
});
LRU.set('A', 'My Value');
LRU.set('B', 'Other Value');
LRU.set('C', 'Another Value');
// => Key "A" with value "My Value" has been evicted.
LRU.has('B');
LRU.get('B');
LRU.delete('B');
// => Key "B" with value "Other Value" has been evicted.
LRU.peek('C');
LRU.clear(); // ← recommended | LRU.evict(max) → (slower alternative)
// => Key "C" with value "Another Value" has been evicted.
LRU.set('D', "You're amazing 💛");
LRU.size; // 1
LRU.max; // 2
LRU.available; // 1
LRU.resize(10);
LRU.size; // 1
LRU.max; // 10
LRU.available; // 9
`
> For _up-to-date_ documentation, always follow the README.md in the GitHub repository.
#### ES Modules
`js`
import { createLRU } from 'lru.min';
#### CommonJS
`js`
const { createLRU } = require('lru.min');
#### Browser
> Requires ES6.
`html`
- You can use tools such as Babel to increase the compatibility rate.
> Set maximum size when creating LRU.
`ts`
const LRU = createLRU({ max: 150_000 });
Also, you can set a callback for every deletion/eviction:
`ts`
const LRU = createLRU({
max: 150_000,
onEviction: (key, value) => {
// do something
},
});
Adds a key-value pair to the cache. Updates the value if the key already exists
`ts`
LRU.set('key', 'value');
> undefined keys will simply be ignored.
- Complexity: O(1).
Retrieves the value for a given key and moves the key to the most recent position.
`ts`
LRU.get('key');
- Complexity: O(1).
Retrieves the value for a given key without changing its position.
`ts`
LRU.peek('key');
- Complexity: O(1).
`ts`
LRU.has('key');
- Complexity: O(1).
`ts`
LRU.delete('key');
- Complexity: O(1).
Evicts the specified number of the oldest items from the cache.
`ts`
LRU.evict(1000);
- Complexity: O(key) — even if passed a number greater than the number of items, only existing items will be evicted.
> [!TIP]
>
> - Methods that perform eviction(s) when maximum size is reached: set and resize.delete
> - Methods that always perform eviction(s): , clear, and evict itself.
Resizes the cache to a new maximum size, evicting items if necessary.
`ts`
LRU.resize(50_000);
- Complexity:
- Increasing: O(newMax - max).
- Downsizing: O(n).
Clears and disposes (if used) all key-value pairs from the cache.
`ts`
LRU.clear();
- Complexity:
- Without onEviction: O(1).onEviction
- Using : O(entries).
#### Get the max size of the cache
`ts`
LRU.max;
- Complexity: O(1).
#### Get the current size of the cache
`ts`
LRU.size;
- Complexity: O(1).
#### Get the available slots in the cache
`ts`
LRU.available;
- Complexity: O(1).
#### Get all keys
Iterates over all keys in the cache, from most recent to least recent.
`ts`
const keys = [...LRU.keys()];
- Complexity: O(keys).
#### Get all values
Iterates over all values in the cache, from most recent to least recent.
`ts`
const values = [...LRU.values()];
- Complexity: O(values).
#### Get all entries
Iterates over [key, value] pairs in the cache, from most recent to least recent.
`ts`
const entries = [...LRU.entries()];
- Complexity: O(entries).
#### Run a callback for each entry
Iterates over each value-key pair in the cache, from most recent to least recent.
`ts`
LRU.forEach((value, key) => {
// do something
});
- Complexity: O(entries).
---
> [!NOTE]
>
> - We use O(keys), O(values), O(entries), and O(newMax - max) to explicitly indicate what is being iterated over. In traditional complexity notation, this would be represented as O(n).
---
You can set types for both keys and values. For example:
`ts
import { createLRU } from 'lru.min';
type Key = number;
type Value = {
name: string;
};
const LRU = createLRU
LRU.set(1, { name: 'Peter' });
LRU.set(2, { name: 'Mary' });
`
Also:
`ts
import { createLRU, type CacheOptions } from 'lru.min';
type Key = number;
type Value = {
name: string;
};
const options: CacheOptions
max: 10,
onEviction(key, value) {
console.log(key, value);
},
};
// No need to repeat the type params
const LRU = createLRU(options);
LRU.set(1, { name: 'Peter' });
LRU.set(2, { name: 'Mary' });
`
---
The benchmark is performed by comparing 1,000,000 runs through a maximum cache limit of 100,000, getting 333,333 caches and deleting 200,000 keys 10 consecutive times, clearing the cache every run.
> - lru-cache v11.0.0
`shTime:
lru.min: 240.45ms
lru-cache: 258.32ms
- See detailed results and how the tests are run and compared in the benchmark directory.
---
Please check the SECURITY.md.
---
See the Contributing Guide and please follow our Code of Conduct 🚀
---
- 
- lru.min is inspired by lru-cache architecture and quick-lru usage, simplifying and improving their concepts for enhanced performance and compatibility.
> [!IMPORTANT]
>
> No lru-cache or quick-lru code is used in lru.min. For more comprehensive features such as TTL support, consider using and supporting them 🤝
---
lru.min is under the MIT License.
Copyright © 2024-present Weslley Araújo and lru.min contributors.