lru.min

Why another LRU?

• 🎖️ 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.

---

Install

1# Node.js
2npm i lru.min

1# Bun
2bun add lru.min

1# Deno
2deno add npm:lru.min

---

Usage

Quickstart

1import { createLRU } from 'lru.min';
2
3const max = 2;
4const onEviction = (key, value) => {
5  console.log(`Key "${key}" with value "${value}" has been evicted.`);
6};
7
8const LRU = createLRU({
9  max,
10  onEviction,
11});
12
13LRU.set('A', 'My Value');
14LRU.set('B', 'Other Value');
15LRU.set('C', 'Another Value');
16
17// => Key "A" with value "My Value" has been evicted.
18
19LRU.has('B');
20LRU.get('B');
21LRU.delete('B');
22
23// => Key "B" with value "Other Value" has been evicted.
24
25LRU.peek('C');
26
27LRU.clear(); // LRU.evict(max)
28
29// => Key "C" with value "Another Value" has been evicted.
30
31LRU.set('D', "You're amazing 💛");
32
33LRU.size; // 1
34LRU.max; // 2
35LRU.available; // 1
36
37LRU.resize(10);
38
39LRU.size; // 1
40LRU.max; // 10
41LRU.available; // 9

For up-to-date documentation, always follow the README.md in the GitHub repository.

Import

ES Modules

1import { createLRU } from 'lru.min';

CommonJS

1const { createLRU } = require('lru.min');

Browser

Requires ES6.

1<script src="https://cdn.jsdelivr.net/npm/lru.min@1.x.x/browser/lru.min.js"></script>

• You can use tools such as Babel to increase the compatibility rate.

Create a new LRU Cache

Set maximum size when creating LRU.

1const LRU = createLRU({ max: 150_000 });

Also, you can set a callback for every deletion/eviction:

1const LRU = createLRU({
2  max: 150_000,
3  onEviction: (key, value) => {
4    // do something
5  },
6});

Set a cache

Adds a key-value pair to the cache. Updates the value if the key already exists

1LRU.set('key', 'value');

undefined keys will simply be ignored.

Get a cache

Retrieves the value for a given key and moves the key to the most recent position.

1LRU.get('key');

Peek a cache

Retrieves the value for a given key without changing its position.

1LRU.peek('key');

Check if a key exists

1LRU.has('key');

Delete a cache

1LRU.delete('key');

Evict from the oldest cache

Evicts the specified number of the oldest items from the cache.

1LRU.evict(1000);

[!TIP]

• Methods that perform eviction(s) when maximum size is reached: set and resize.
• Methods that always perform eviction(s): delete, clear, and evict itself.

Resize the cache

Resizes the cache to a new maximum size, evicting items if necessary.

1LRU.resize(50_000);

Clear the cache

Clears and disposes (if used) all key-value pairs from the cache.

1LRU.clear();

Debugging

Get the max size of the cache

1LRU.max;

Get the current size of the cache

1LRU.size;

Get the available slots in the cache

1LRU.available;

Iterating the cache

Get all keys

Iterates over all keys in the cache, from most recent to least recent.

1const keys = [...LRU.keys()];

Get all values

Iterates over all values in the cache, from most recent to least recent.

1const values = [...LRU.values()];

Get all entries

Iterates over [key, value] pairs in the cache, from most recent to least recent.

1const entries = [...LRU.entries()];

Run a callback for each entry

Iterates over each value-key pair in the cache, from most recent to least recent.

1LRU.forEach((value, key) => {
2  // do something
3});

TypeScript

You can set types for both keys and values. For example:

1import { createLRU } from 'lru.min';
2
3type Key = number;
4
5type Value = {
6  name: string;
7};
8
9const LRU = createLRU<Key, Value>({ max: 1000 });
10
11LRU.set(1, { name: 'Peter' });
12LRU.set(2, { name: 'Mary' });

Also:

1import { createLRU, type CacheOptions } from 'lru.min';
2
3type Key = number;
4
5type Value = {
6  name: string;
7};
8
9const options: CacheOptions<Key, Value> = {
10  max: 10,
11  onEviction(key, value) {
12    console.log(key, value);
13  },
14};
15
16// No need to repeat the type params
17const LRU = createLRU(options);
18
19LRU.set(1, { name: 'Peter' });
20LRU.set(2, { name: 'Mary' });

---

Performance

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
• quick-lru v7.0.0

1# Time:
2  lru.min:    240.45ms
3  lru-cache:  258.32ms
4  quick-lru:  279.89ms
5
6# CPU:
7  lru.min:    275558.30µs
8  lru-cache:  306858.30µs
9  quick-lru:  401318.80µs

• See detailed results and how the tests are run and compared in the benchmark directory.

---

Security Policy

Please check the SECURITY.md.

---

Contributing

See the Contributing Guide and please follow our Code of Conduct 🚀

---

Acknowledgements

lru.min is based and inspired on the architecture and code of both lru-cache and quick-lru, simplifying their core concepts for enhanced performance and compatibility.

For more comprehensive features such as TTL support, consider using and supporting them 🤝

• The architecture is mostly based on @isaacs — lru-cache.
• Most of the methods names and its functionalities were inspired by @sindresorhus — quick-lru.
• 

---

What comes from lru-cache?

Architecture's essence:

It's not the same code, but majority based on this.

1let free: number[] = [];
2
3const keyMap: Map<Key, number> = new Map();
4const keyList: (Key | undefined)[] = new Array(max).fill(undefined);
5const valList: (Value | undefined)[] = new Array(max).fill(undefined);
6const next: number[] = new Array(max).fill(0);
7const prev: number[] = new Array(max).fill(0);

---

What comes from quick-lru?

Name of methods and options (including their final functionality ideas):

• resize
• peek
• onEviction
• forEach
• entriesDescending as entries

---

License

lru.min is under the MIT License.
Copyright © 2024-present Weslley Araújo and lru.min contributors.