lru.min

lru.min

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

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

---

Install

# Node.js
npm i lru.min

# Bun
bun add lru.min

# Deno
deno add npm:lru.min

---

Usage

Import

ES Modules

import { createLRU } from 'lru.min';

CommonJS

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

Browser

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

Create a new LRU Cache

Set maximum size when creating LRU.

import { createLRU } from 'lru.min';

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.get('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);

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;

Get all keys

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

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

Get all values

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

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

Get all entries

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

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

Get all entries

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

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

Run a callback for each entry

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

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

---

Performance

The benchmark is performed by comparing 1,000,000 runs through a maximum cache limit of 100,000, getting 333,333 caches and delenting 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.
• 

---

License

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