Tiny LRU

A lightweight, high-performance Least Recently Used (LRU) cache implementation for JavaScript with optional TTL (time-to-live) support. Works in both Node.js and browser environments.

Installation

1npm install tiny-lru

Usage

Factory Function

1import {lru} from "tiny-lru";
2const cache = lru(max, ttl = 0, resetTtl = false);

Class Constructor

1import {LRU} from "tiny-lru";
2
3// Create a cache with 1000 items, 1 minute TTL, reset on access
4const cache = new LRU(1000, 60000, true);
5
6// Create a cache with TTL
7const cache2 = new LRU(100, 5000); // 100 items, 5 second TTL
8cache2.set('key1', 'value1');
9// After 5 seconds, key1 will be expired

Class Inheritance

1import {LRU} from "tiny-lru";
2class MyCache extends LRU {
3  constructor(max, ttl, resetTtl) {
4    super(max, ttl, resetTtl);
5  }
6}

Parameters

• max {Number} - Maximum number of items to store. 0 means unlimited (default: 1000)
• ttl {Number} - Time-to-live in milliseconds, 0 disables expiration (default: 0)
• resetTtl {Boolean} - Reset TTL on each set() operation (default: false)

Parameter Validation

The factory function validates parameters and throws TypeError for invalid values:

1// Invalid parameters will throw TypeError
2try {
3  const cache = lru(-1);        // Invalid max value
4} catch (error) {
5  console.error(error.message); // "Invalid max value"
6}
7
8try {
9  const cache = lru(100, -1);   // Invalid ttl value  
10} catch (error) {
11  console.error(error.message); // "Invalid ttl value"
12}
13
14try {
15  const cache = lru(100, 0, "true"); // Invalid resetTtl value
16} catch (error) {
17  console.error(error.message); // "Invalid resetTtl value"
18}

Interoperability

Compatible with Lodash's memoize function cache interface:

1import _ from "lodash";
2import {lru} from "tiny-lru";
3
4_.memoize.Cache = lru().constructor;
5const memoized = _.memoize(myFunc);
6memoized.cache.max = 10;

Testing

Tiny-LRU maintains 100% code coverage:

1--------------|---------|----------|---------|---------|-------------------
2File          | % Stmts | % Branch | % Funcs | % Lines | Uncovered Line #s 
3--------------|---------|----------|---------|---------|-------------------
4All files     |     100 |    96.34 |     100 |     100 |                   
5 tiny-lru.cjs |     100 |    96.34 |     100 |     100 | 190,225,245       
6--------------|---------|----------|---------|---------|-------------------

Benchmarks

Tiny-LRU includes a comprehensive benchmark suite for performance analysis and comparison. The benchmark suite uses modern Node.js best practices and popular benchmarking tools.

Benchmark Files

Modern Benchmarks (modern-benchmark.js) ⭐

Comprehensive benchmark suite using Tinybench

Features:

• Statistically analyzed latency and throughput values
• Standard deviation, margin of error, variance calculations
• Proper warmup phases and statistical significance
• Realistic workload scenarios

Test categories:

• SET operations: Empty cache, full cache, eviction scenarios
• GET operations: Hit/miss patterns, access patterns
• Mixed operations: Real-world 80/20 read-write scenarios
• Special operations: Delete, clear, different data types
• Memory usage analysis

Performance Observer Benchmarks (performance-observer-benchmark.js)

Native Node.js performance measurement using Performance Observer

Features:

• Function-level timing using performance.timerify()
• PerformanceObserver for automatic measurement collection
• Custom high-resolution timer implementations
• Scalability testing across different cache sizes

Running Benchmarks

1# Run all modern benchmarks
2npm run benchmark:all
3
4# Run individual benchmark suites
5npm run benchmark:modern    # Tinybench suite
6npm run benchmark:perf      # Performance Observer suite
7
8# Or run directly
9node benchmarks/modern-benchmark.js
10node benchmarks/performance-observer-benchmark.js
11
12# Run with garbage collection exposed (for memory analysis)
13node --expose-gc benchmarks/modern-benchmark.js

Understanding Results

Tinybench Output

┌─────────┬─────────────────────────────┬─────────────────┬────────────────────┬──────────┬─────────┐
│ (index) │          Task Name          │     ops/sec     │ Average Time (ns)  │  Margin  │ Samples │
├─────────┼─────────────────────────────┼─────────────────┼────────────────────┼──────────┼─────────┤
│    0    │ 'set-random-empty-cache-100'│   '2,486,234'   │ 402.21854775934    │ '±0.45%' │ 1243117 │

• ops/sec: Operations per second (higher is better)
• Average Time: Average execution time in nanoseconds
• Margin: Statistical margin of error
• Samples: Number of samples collected for statistical significance

Performance Observer Output

┌─────────────┬─────────┬────────────┬────────────┬────────────┬───────────────┬─────────┬────────┐
│   Function  │  Calls  │  Avg (ms)  │  Min (ms)  │  Max (ms)  │  Median (ms)  │ Std Dev │Ops/sec │
├─────────────┼─────────┼────────────┼────────────┼────────────┼───────────────┼─────────┼────────┤
│   lru.set   │  1000   │   0.0024   │   0.0010   │   0.0156   │    0.0020     │  0.0012 │ 417292 │

Performance Tips

For accurate benchmark results:

1. Close other applications to reduce system noise
2. Run multiple times and compare results
3. Use consistent hardware for comparisons
4. Enable garbage collection with --expose-gc for memory tests
5. Consider CPU frequency scaling on laptops

Good Performance Indicators

• ✅ Consistent ops/sec across runs
• ✅ Low margin of error (< 5%)
• ✅ GET operations faster than SET
• ✅ Cache hits faster than misses

See benchmarks/README.md for complete documentation and advanced usage.

API Reference

Properties

first

{Object|null} - Item in first (least recently used) position

1const cache = lru();
2cache.first; // null - empty cache

last

{Object|null} - Item in last (most recently used) position

1const cache = lru();
2cache.last; // null - empty cache

max

{Number} - Maximum number of items to hold in cache

1const cache = lru(500);
2cache.max; // 500

resetTtl

{Boolean} - Whether to reset TTL on each set() operation

1const cache = lru(500, 5*6e4, true);
2cache.resetTtl; // true

size

{Number} - Current number of items in cache

1const cache = lru();
2cache.size; // 0 - empty cache

ttl

{Number} - TTL in milliseconds (0 = no expiration)

1const cache = lru(100, 3e4);
2cache.ttl; // 30000

Methods

clear()

Removes all items from cache.

Returns: {Object} LRU instance

1cache.clear();

delete(key)

Removes specified item from cache.

Parameters:

• key {String} - Item key

Returns: {Object} LRU instance

1cache.set('key1', 'value1');
2cache.delete('key1');
3console.log(cache.has('key1')); // false

See also: has(), clear()

entries([keys])

Returns array of cache items as [key, value] pairs.

Parameters:

• keys {Array} - Optional array of specific keys to retrieve (defaults to all keys)

Returns: {Array} Array of [key, value] pairs

1cache.set('a', 1).set('b', 2);
2console.log(cache.entries()); // [['a', 1], ['b', 2]]
3console.log(cache.entries(['a'])); // [['a', 1]]

See also: keys(), values()

evict()

Removes the least recently used item from cache.

Returns: {Object} LRU instance

1cache.set('old', 'value').set('new', 'value');
2cache.evict(); // Removes 'old' item

See also: setWithEvicted()

expiresAt(key)

Gets expiration timestamp for cached item.

Parameters:

• key {String} - Item key

Returns: {Number|undefined} Expiration time (epoch milliseconds) or undefined if key doesn't exist

1const cache = new LRU(100, 5000); // 5 second TTL
2cache.set('key1', 'value1');
3console.log(cache.expiresAt('key1')); // timestamp 5 seconds from now

See also: get(), has()

get(key)

Retrieves cached item and promotes it to most recently used position.

Parameters:

• key {String} - Item key

Returns: {*} Item value or undefined if not found/expired

1cache.set('key1', 'value1');
2console.log(cache.get('key1')); // 'value1'
3console.log(cache.get('nonexistent')); // undefined

See also: set(), has()

has(key)

Checks if key exists in cache (without promoting it).

Parameters:

• key {String} - Item key

Returns: {Boolean} True if key exists and is not expired

1cache.set('key1', 'value1');
2console.log(cache.has('key1')); // true
3console.log(cache.has('nonexistent')); // false

See also: get(), delete()

keys()

Returns array of all cache keys in LRU order (first = least recent).

Returns: {Array} Array of keys

1cache.set('a', 1).set('b', 2);
2cache.get('a'); // Move 'a' to most recent
3console.log(cache.keys()); // ['b', 'a']

See also: values(), entries()

set(key, value)

Stores item in cache as most recently used.

Parameters:

• key {String} - Item key
• value {*} - Item value

Returns: {Object} LRU instance

1cache.set('key1', 'value1')
2     .set('key2', 'value2')
3     .set('key3', 'value3');

See also: get(), setWithEvicted()

setWithEvicted(key, value)

Stores item and returns evicted item if cache was full.

Parameters:

• key {String} - Item key
• value {*} - Item value

Returns: {Object|null} Evicted item {key, value, expiry, prev, next} or null

1const cache = new LRU(2);
2cache.set('a', 1).set('b', 2);
3const evicted = cache.setWithEvicted('c', 3); // evicted = {key: 'a', value: 1, ...}
4if (evicted) {
5  console.log(`Evicted: ${evicted.key}`, evicted.value);
6}

See also: set(), evict()

values([keys])

Returns array of cache values.

Parameters:

• keys {Array} - Optional array of specific keys to retrieve (defaults to all keys)

Returns: {Array} Array of values

1cache.set('a', 1).set('b', 2);
2console.log(cache.values()); // [1, 2]
3console.log(cache.values(['a'])); // [1]

See also: keys(), entries()

Examples

Basic Usage

1import {lru} from "tiny-lru";
2
3// Create a cache with max 100 items
4const cache = lru(100);
5cache.set('key1', 'value1');
6console.log(cache.get('key1')); // 'value1'
7
8// Method chaining
9cache.set("user:123", {name: "John", age: 30})
10     .set("session:abc", {token: "xyz", expires: Date.now()});
11
12const user = cache.get("user:123"); // Promotes to most recent
13console.log(cache.size); // 2

TTL with Auto-Expiration

1import {LRU} from "tiny-lru";
2
3const cache = new LRU(50, 5000); // 50 items, 5s TTL
4cache.set("temp-data", {result: "computed"});
5
6setTimeout(() => {
7  console.log(cache.get("temp-data")); // undefined - expired
8}, 6000);

Reset TTL on Access

1const cache = lru(100, 10000, true); // Reset TTL on each set()
2cache.set("session", {user: "admin"});
3// Each subsequent set() resets the 10s TTL

License

Copyright (c) 2025 Jason Mulligan
Licensed under the BSD-3 license.