📦 Installation

npm install tiny-lru# oryarn add tiny-lru# orpnpm add tiny-lru

⚡ Quick Start

import{lru}from"tiny-lru";// Create cache and start using immediatelyconstcache=lru(100);// Max 100 itemscache.set('user:123',{name:'John',age:30});constuser=cache.get('user:123');// {name: 'John', age: 30}// With TTL (5 second expiration)consttempCache=lru(50,5000);tempCache.set('session','abc123');// Automatically expires after 5 seconds

📑 Table of Contents

✨ Features & Benefits

Why Choose Tiny LRU?

Benchmark Comparison (Mean of 5 runs)

📊 Performance Deep Dive

When to Choose Tiny LRU

Running Your Own Benchmarks

# Run all performance benchmarksnpm run benchmark:all# Individual benchmark suitesnpm run benchmark:modern# Comprehensive Tinybench suitenpm run benchmark:perf# Performance Observer measurementsnpm run benchmark:comparison# Compare against other LRU libraries

🚀 Getting Started

Installation

npm install tiny-lru# oryarn add tiny-lru# orpnpm add tiny-lru

Quick Examples

import{lru}from"tiny-lru";// Basic cacheconstcache=lru(100);cache.set('key1','value1').set('key2','value2').set('key3','value3');console.log(cache.get('key1'));// 'value1'console.log(cache.size);// 3// With TTL (time-to-live)constcacheWithTtl=lru(50,30000);// 30 second TTLcacheWithTtl.set('temp-data',{important:true});// Automatically expires after 30 secondsconstresetCache=lru(25,10000,true);resetCache.set('session','user123');// Because resetTtl is true, TTL resets when you set() the same key again

CDN Usage (Browser)

<!-- ES Modules --><scripttype="module">import{lru,LRU}from'https://cdn.skypack.dev/tiny-lru';constcache=lru(100);</script><!-- UMD Bundle (global: window.lru) --><scriptsrc="https://unpkg.com/tiny-lru/dist/tiny-lru.umd.js"></script><script>const{lru,LRU}=window.lru;constcache=lru(100);// or: const cache = new LRU(100);</script>

TypeScript Usage

import{lru,LRU}from"tiny-lru";// Type-safe cacheconstcache=lru<string>(100);// or: const cache: LRU<string> = lru<string>(100);cache.set('user:123','John Doe');constuser:string|undefined=cache.get('user:123');// Class inheritanceclassMyCacheextendsLRU<User>{constructor(){super(1000,60000,true);// 1000 items, 1 min TTL, reset TTL on set}}

Configuration Options

Factory Function

import{lru}from"tiny-lru";constcache=lru(max,ttl=0,resetTtl=false);

Class Constructor

import{LRU}from"tiny-lru";constcache=newLRU(1000,60000,true);// 1000 items, 1 min TTL, reset TTL on set

Best Practices

// 1. Size your cache appropriatelyconstcache=lru(1000);// Not too small, not too large// 2. Use meaningful keyscache.set(`user:${userId}:profile`,userProfile);cache.set(`product:${productId}:details`,productDetails);// 3. Handle cache misses gracefullyfunctiongetData(key){constcached=cache.get(key);if(cached!==undefined){returncached;}// Fallback to slower data sourceconstdata=expensiveOperation(key);cache.set(key,data);returndata;}// 4. Clean up when neededprocess.on('exit',()=>{cache.clear();// Help garbage collection});

Optimization Tips

💡 Real-World Examples

API Response Caching

import{lru}from"tiny-lru";classApiClient{constructor(){this.cache=lru(100,300000);// 5 minute cache}asyncfetchUser(userId){constcacheKey=`user:${userId}`;// Return cached result if availableif(this.cache.has(cacheKey)){returnthis.cache.get(cacheKey);}// Fetch from API and cacheconstresponse=awaitfetch(`/api/users/${userId}`);constuser=awaitresponse.json();this.cache.set(cacheKey,user);returnuser;}}

Function Memoization

import{lru}from"tiny-lru";functionmemoize(fn,maxSize=100){constcache=lru(maxSize);returnfunction(...args){constkey=JSON.stringify(args);if(cache.has(key)){returncache.get(key);}constresult=fn.apply(this,args);cache.set(key,result);returnresult;};}// UsageconstexpensiveCalculation=memoize((n)=>{console.log(`Computing for${n}`);returnn*n*n;},50);console.log(expensiveCalculation(5));// Computing for 5 -> 125console.log(expensiveCalculation(5));// 125 (cached)

Session Management

import{lru}from"tiny-lru";classSessionManager{constructor(){// 30 minute TTL, with resetTtl enabled for set()this.sessions=lru(1000,1800000,true);}createSession(userId,data){constsessionId=this.generateId();constsession={      userId,      data,createdAt:Date.now()};this.sessions.set(sessionId,session);returnsessionId;}getSession(sessionId){// get() does not extend TTL; to extend, set the session again when resetTtl is truereturnthis.sessions.get(sessionId);}endSession(sessionId){this.sessions.delete(sessionId);}}

🔗 Interoperability

import_from"lodash";import{lru}from"tiny-lru";_.memoize.Cache=lru().constructor;constmemoized=_.memoize(myFunc);memoized.cache.max=10;

🛠️ Development

Testing

# Run all tests with coveragenpmtest# Run tests with verbose outputnpm run mocha# Lint codenpm run lint# Full build (lint + build)npm run build

----------|---------|----------|---------|---------|-------------------File      | % Stmts | % Branch | % Funcs | % Lines | Uncovered Line #s----------|---------|----------|---------|---------|-------------------All files |     100 |      100 |     100 |     100 | lru.js   |     100 |      100 |     100 |     100 |----------|---------|----------|---------|---------|-------------------

Contributing

Quick Start for Contributors

# Clone and setupgit clone https://github.com/avoidwork/tiny-lru.gitcd tiny-lrunpm install# Run testsnpmtest# Run lintingnpm run lint# Run benchmarksnpm run benchmark:all# Build distribution filesnpm run build

Development Workflow

Contribution Guidelines

📖 API Reference

Factory Function

lru(max, ttl, resetTtl)

import{lru}from"tiny-lru";// Basic cacheconstcache=lru(100);// With TTLconstcacheWithTtl=lru(50,30000);// 30 second TTL// With resetTtl enabled for set()constresetCache=lru(25,10000,true);// Validation errorslru(-1);// TypeError: Invalid max valuelru(100,-1);// TypeError: Invalid ttl valuelru(100,0,"no");// TypeError: Invalid resetTtl value

Properties

first

constcache=lru();cache.first;// null - empty cache

last

constcache=lru();cache.last;// null - empty cache

max

constcache=lru(500);cache.max;// 500

resetTtl

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

size

constcache=lru();cache.size;// 0 - empty cache

ttl

constcache=lru(100,3e4);cache.ttl;// 30000

Methods

clear()

cache.clear();

delete(key)

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

entries([keys])

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

evict()

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

expiresAt(key)

constcache=newLRU(100,5000);// 5 second TTLcache.set('key1','value1');console.log(cache.expiresAt('key1'));// timestamp 5 seconds from now

get(key)

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

has(key)

cache.set('key1','value1');console.log(cache.has('key1'));// trueconsole.log(cache.has('nonexistent'));// false

keys()

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

set(key, value)

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

setWithEvicted(key, value)

constcache=newLRU(2);cache.set('a',1).set('b',2);constevicted=cache.setWithEvicted('c',3);// evicted = {key: 'a', value: 1, ...}if(evicted){console.log(`Evicted:${evicted.key}`,evicted.value);}

values([keys])

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

📄 License