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