Tiny LRU

What is an LRU Cache?

Installation

npm install tiny-lru

Quick Start

import { lru } from "tiny-lru";
// Create a cache that holds up to 100 items
const cache = lru(100);
// Store and retrieve data
cache.set("user:42", { name: "Alice", score: 1500 });
const user = cache.get("user:42"); // { name: "Alice", score: 1500 }
// Chain operations
cache.set("a", 1).set("b", 2).set("c", 3);
// Check what's in the cache
cache.has("a"); // true
cache.size; // 3
cache.keys(); // ['a', 'b', 'c'] (LRU order)

TypeScript

import { LRU } from "tiny-lru";
interface User {
 id: number;
 name: string;
}
const cache = new LRU<User>(100);
cache.set("user:1", { id: 1, name: "Alice" });
const user: User | undefined = cache.get("user:1");

With TTL (Time-to-Live)

// Cache that expires after 5 seconds
const sessionCache = lru(100, 5000);
sessionCache.set("session:id", { userId: 123 });
// After 5 seconds, this returns undefined
sessionCache.get("session:id");

const cache = lru(100, 60000, true); // 1 minute TTL, resets on update
cache.set("key", "value");
cache.set("key", "new value"); // TTL resets

When to Use Tiny LRU

API Reference

Factory Function: lru(max?, ttl?, resetTtl?)

import { lru } from "tiny-lru";
const cache1 = lru(); // 1000 items, no TTL
const cache2 = lru(500); // 500 items, no TTL
const cache3 = lru(100, 30000); // 100 items, 30s TTL
const cache4 = lru(100, 60000, true); // with resetTtl enabled

Class: new LRU(max?, ttl?, resetTtl?)

import { LRU } from "tiny-lru";
const cache = new LRU(100, 5000);

Properties

Methods

Common Patterns

Memoization

function memoize(fn, maxSize = 100) {
 const cache = lru(maxSize);
 return function (...args) {
 const key = JSON.stringify(args);
 if (cache.has(key)) {
 return cache.get(key);
 }
 const result = fn(...args);
 cache.set(key, result);
 return result;
 };
}
// Cache expensive computations
const fib = memoize((n) => (n <= 1 ? n : fib(n - 1) + fib(n - 2)), 50);
fib(100); // fast - cached
fib(100); // even faster - from cache

Cache-Aside Pattern

// Cache instance shared across calls (outside the function)
const cache = lru(1000, 60000); // 1 minute cache
async function getUser(userId) {
 // Check cache first
 const cached = cache.get(`user:${userId}`);
 if (cached) {
 return cached;
 }
 // Fetch from database
 const user = await db.users.findById(userId);
 // Store in cache
 cache.set(`user:${userId}`, user);
 return user;
}

Finding What Was Evicted

const cache = lru(3);
cache.set("a", 1).set("b", 2).set("c", 3);
const evicted = cache.setWithEvicted("d", 4);
console.log(evicted); // { key: 'a', value: 1, expiry: 0 }
cache.keys(); // ['b', 'c', 'd']

Advanced Usage

Batch Operations with Keys

const cache = lru(100);
cache.set("users:1", { name: "Alice" });
cache.set("users:2", { name: "Bob" });
cache.set("users:3", { name: "Carol" });
// Get values for specific keys (order matches input array)
const values = cache.values(["users:3", "users:1"]);
// ['Carol', 'Alice'] - matches input key order

Interop with Lodash

import _ from "lodash";
import { lru } from "tiny-lru";
_.memoize.Cache = lru().constructor;
const slowFunc = _.memoize(expensiveOperation);
slowFunc.cache.max = 100; // Configure cache size

Session and Authentication Caching

import { LRU } from "tiny-lru";
class AuthCache {
 constructor() {
 // Session cache: 30 minutes with TTL reset on update
 this.sessions = new LRU(10000, 1800000, true);
 // Token validation cache: 5 minutes, no reset
 this.tokens = new LRU(5000, 300000, false);
 // Permission cache: 15 minutes
 this.permissions = new LRU(5000, 900000);
 }
 cacheSession(sessionId, userData, domain = "app") {
 const key = `${domain}:session:${sessionId}`;
 this.sessions.set(key, {
 userId: userData.userId,
 permissions: userData.permissions,
 loginTime: Date.now(),
 lastActivity: Date.now(),
 });
 }
 getSession(sessionId, domain = "app") {
 const key = `${domain}:session:${sessionId}`;
 return this.sessions.get(key);
 }
}

LLM Response Caching

import { LRU } from "tiny-lru";
class LLMCache {
 constructor() {
 // Cache up to 1000 responses for 1 hour
 this.cache = new LRU(1000, 3600000); // 1 hour TTL
 }
 async getResponse(model, prompt, params = {}) {
 const key = this.generateKey(model, prompt, params);
 // Check cache first
 const cached = this.cache.get(key);
 if (cached) {
 return { ...cached, fromCache: true };
 }
 // Make expensive API call
 const response = await this.callLLMAPI(model, prompt, params);
 // Cache the response
 this.cache.set(key, {
 response: response.text,
 tokens: response.tokens,
 timestamp: Date.now(),
 });
 return { ...response, fromCache: false };
 }
 generateKey(model, prompt, params = {}) {
 const paramsHash = this.hashObject(params);
 const promptHash = this.hashString(prompt);
 return `llm:${model}:${promptHash}:${paramsHash}`;
 }
 hashString(str) {
 let hash = 0;
 for (let i = 0; i < str.length; i++) {
 const char = str.charCodeAt(i);
 hash = (hash << 5) - hash + char;
 hash = hash & hash;
 }
 return Math.abs(hash).toString(36);
 }
 hashObject(obj) {
 return this.hashString(JSON.stringify(obj, Object.keys(obj).sort()));
 }
}

Why Tiny LRU?

Performance

Benchmarks

npm run benchmark:all

Development

npm install # Install dependencies
npm test # Run lint and tests
npm run lint # Lint and check formatting
npm run fix # Fix lint and formatting issues
npm run build # Build distribution files
npm run coverage # Generate test coverage report

Build Output

Tests

Test Coverage

Contributing

Security

Multi-Domain Key Convention

{domain}:{service}:{resource}:{identifier}[:{version}]

Documentation

License