LRUCache.js - A LRU Cache implementation in JavaScript

LRUCache.js is a lightweight and efficient Least Recently Used (LRU) cache implementation for JavaScript. It stores a fixed number of items, automatically evicting the least recently used entry when the cache reaches its limit. Optional per-item TTL (time-to-live) support allows for automatic expiration of stale entries.

Features

• LRU eviction — least recently used entries are removed first
• Optional TTL — each entry can expire automatically
• Fast lookups, insertions, and deletions using Map
• Size-limited — configurable maximum number of entries
• Utility methods for keys, values, and cache cleanup
• Zero dependencies — works in Node.js and browsers

Installation

Install via npm:

npm install @rawify/lrucache

Or with yarn:

yarn add @rawify/lrucache

Or clone the repository:

git clone https://github.com/rawify/LRUCache.js

Usage

Include the lrucache.min.js file in your project:

<script src="path/to/lrucache.min.js"></script>

Or in a Node.js / ES module project:

const LRUCache = require('@rawify/lrucache');
// or
import LRUCache from '@rawify/lrucache';

Creating a Cache

const cache = new LRUCache(3); // limit = 3 entries

set(key, value, ttlMs?)

Adds or updates a cache entry. ttlMs is optional; if given, the entry expires after ttlMs milliseconds.

cache.set('a', 1);
cache.set('b', 2, 1000); // expires after 1s

get(key)

Retrieves the value for key and marks it as most recently used. Returns undefined if the key is not found or has expired.

cache.get('a'); // 1

has(key)

Checks if the key exists and is not expired, and marks it as most recently used.

cache.has('a'); // true

delete(key)

Removes the entry for key.

cache.delete('a');

clear()

Removes all entries.

cache.clear();

size()

Returns the number of non-expired entries.

cache.size(); // 2

keys()

Returns an array of keys for non-expired entries.

cache.keys(); // ['b', 'c']

values()

Returns an array of values for non-expired entries.

cache.values(); // [2, 3]

cleanup()

Removes expired entries and returns the number of removed keys.

cache.cleanup(); // 1

Example

const cache = new LRUCache(2);

cache.set('x', 42);
cache.set('y', 99);
cache.get('x'); // access x so it's most recent
cache.set('z', 123); // y gets evicted because it's least recent

console.log(cache.keys()); // ['x', 'z']

Coding Style

Like all my libraries, LRUCache.js is written to minimize size after compression with Google Closure Compiler in advanced mode. The code style is optimized to maximize compressibility. If you extend the library, please preserve this style.

Building the library

After cloning the Git repository run:

npm install
npm run build

Copyright and Licensing

Copyright (c) 2025, Robert Eisele Licensed under the MIT license.