lru.min

🔥 An extremely fast and efficient LRU Cache for JavaScript (Browser compatible) — 6.8KB.

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(); // LRU.evict(max)

// => 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.

Get a cache

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

LRU.get('key');

Peek a cache

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

LRU.peek('key');

Check if a key exists

LRU.has('key');

Delete a cache

LRU.delete('key');

Evict from the oldest cache

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

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

LRU.resize(50_000);

Clear the cache

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

LRU.clear();

Debugging

Get the max size of the cache

LRU.max;

Get the current size of the cache

LRU.size;

Get the available slots in the cache

LRU.available;

Iterating the cache

Get all keys

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

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

Get all values

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

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

Get all entries

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

const entries = [...LRU.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
});

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.