lru.min

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

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

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

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

License

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