lru.min

lru.min

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

Why

🤝 Compatibility

• lru.min ensures is fully compatible with both Node.js (8+), Bun, Deno and, browser environments.

🎖️ Performance

• Check comparisons between Node.js, Bun and Deno.

Note that although performance is indeed important, the main purpose behind lru.min is the high compatibility level.

---

Install

# Node.js
npm i lru.min

# Bun
bun add lru.min

# Deno
deno add npm:lru.min

---

Usage

• ⚠️ Please wait until v1.x.x before using this package.
• 📘 Public repository coming soon.

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');

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.

You can see how the tests are run and compared in the benchmark directory.

• lru-cache v11.0.0
• quick-lru v7.0.0

Node.js

# ES Modules
lru.min: 247.45ms
lru-cache: 255.93ms
quick-lru: 312.90ms

# CommonJS
lru.min: 236.35ms
lru-cache: 258.74ms
quick-lru: not compatible

Bun

# ES Modules
lru.min: 298.42ms
quick-lru: 315.37ms
lru-cache: 359.23ms

# CommonJS
lru.min: 363.79ms
lru-cache: 371.39ms
quick-lru: not compatible

Deno

# ES Modules
lru.min: 222.60ms
lru-cache: 227.80ms
quick-lru: 253.00ms

---

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.