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

As every library I publish, LRUCache.js is also built to be as small as possible after compressing it with Google Closure Compiler in advanced mode. Thus the coding style orientates a little on maxing-out the compression rate. Please make sure you keep this style if you plan to extend the library.

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.