lru.min

🔥 An extremely fast, efficient, and lightweight LRU Cache for JavaScript (Browser compatible).

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

# Node.js
npm i lru.min

# Bun
bun add lru.min

# Deno
deno add npm:lru.min

---

Usage

Quickstart

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.

Import

ES Modules

import { createLRU } from 'lru.min';

CommonJS

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

Browser

Requires ES6.

<script src="https://cdn.jsdelivr.net/npm/[email protected]/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.

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

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

const LRU = createLRU({
  max: 150_000,
  onEviction: (key, value) => {
    // do something
  },
});

Set a cache

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

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

undefined keys will simply be ignored.

• Complexity: O(1).

Get a cache

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

LRU.get('key');

• Complexity: O(1).

Peek a cache

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

LRU.peek('key');

• Complexity: O(1).

Check if a key exists

LRU.has('key');

• Complexity: O(1).

Delete a cache

LRU.delete('key');

• Complexity: O(1).

Evict from the oldest cache

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

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

LRU.resize(50_000);

• Complexity:
  • Increasing: O(newMax - max).
  • Downsizing: O(n).

Clear the cache

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

LRU.clear();

• Complexity:
  • Without onEviction: O(1).
  • Using onEviction: O(entries).

Debugging

Get the max size of the cache

LRU.max;

• Complexity: O(1).

Get the current size of the cache

LRU.size;

• Complexity: O(1).

Get the available slots in the cache

LRU.available;

• Complexity: O(1).

Iterating the cache

Get all keys

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

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

• Complexity: O(keys).

Get all values

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

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

• Complexity: O(values).

Get all entries

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

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.

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).

---

TypeScript

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

import { createLRU } from 'lru.min';

type Key = number;

type Value = {
  name: string;
};

const LRU = createLRU<Key, Value>({ max: 1000 });

LRU.set(1, { name: 'Peter' });
LRU.set(2, { name: 'Mary' });

Also:

import { createLRU, type CacheOptions } from 'lru.min';

type Key = number;

type Value = {
  name: string;
};

const options: CacheOptions<Key, Value> = {
  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' });

---

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

# Time:
  lru.min:    240.45ms
  lru-cache:  258.32ms
  quick-lru:  279.89ms

# CPU:
  lru.min:    275558.30µs
  lru-cache:  306858.30µs
  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.

let free: number[] = [];

const keyMap: Map<Key, number> = new Map();
const keyList: (Key | undefined)[] = new Array(max).fill(undefined);
const valList: (Value | undefined)[] = new Array(max).fill(undefined);
const next: number[] = new Array(max).fill(0);
const 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.