lru-cache vs cacheable-request vs node-cache vs apicache vs cache-manager vs memory-cache
Choosing the Right Caching Strategy for Node.js Applications
Search packages..
lru-cachecacheable-requestnode-cacheapicachecache-managermemory-cacheSimilar Packages:

Choosing the Right Caching Strategy for Node.js Applications

These six packages offer different approaches to caching in Node.js environments, ranging from simple in-memory storage to HTTP-specific caching layers. lru-cache provides a fundamental Least Recently Used algorithm implementation, while node-cache and memory-cache offer straightforward in-memory key-value storage with TTL support. cache-manager acts as a wrapper allowing multiple cache stores (memory, Redis, etc.) with a unified API. apicache focuses specifically on Express middleware for caching HTTP responses, and cacheable-request adds HTTP caching semantics to request clients. Each serves distinct architectural needs from low-level data structures to high-level HTTP response caching.

Npm Package Weekly Downloads Trend

3 Years

Github Stars Ranking

Stat Detail

Package
Downloads
Stars
Size
Issues
Publish
License
lru-cache390,646,9085,858844 kB322 days agoBlueOak-1.0.0
cacheable-request27,090,5341,96979.5 kB03 months agoMIT
node-cache4,425,4722,375-776 years agoMIT
apicache44,8711,248-634 years agoMIT
cache-manager01,96952.2 kB03 months agoMIT
memory-cache01,600-329 years agoBSD-2-Clause

Choosing the Right Caching Strategy for Node.js Applications

Caching is essential for building performant Node.js applications, but picking the wrong tool can lead to memory leaks, stale data, or unnecessary complexity. The six packages we are comparing — apicache, cache-manager, cacheable-request, lru-cache, memory-cache, and node-cache — each solve different parts of the caching puzzle. Some focus on HTTP responses, others on data structures, and some on abstraction layers. Let's break down how they work and when to use each one.

🏗️ Core Architecture: What Each Package Actually Does

lru-cache is a pure data structure implementation.

  • It provides a Least Recently Used eviction algorithm.
  • No built-in TTL (time-to-live) in older versions, though newer versions support it.
  • You manage the cache lifecycle yourself.
// lru-cache: Basic usage
import { LRUCache } from 'lru-cache';

const cache = new LRUCache({
  max: 500,
  ttl: 1000 * 60 * 5 // 5 minutes
});

cache.set('key', 'value');
const value = cache.get('key');

node-cache is a full in-memory cache with TTL and events.

  • Built on top of basic object storage with cleanup intervals.
  • Supports key patterns, cloning, and event hooks.
  • Runs entirely in process memory.
// node-cache: With TTL and events
import NodeCache from 'node-cache';

const cache = new NodeCache({ stdTTL: 100 });

cache.on('expired', (key, value) => {
  console.log(`Key ${key} expired`);
});

cache.set('key', 'value', 200);
const value = cache.get('key');

memory-cache is a minimal in-memory store.

  • Very simple API with basic TTL support.
  • No event system or advanced features.
  • Good for quick prototyping.
// memory-cache: Simple set/get
import cache from 'memory-cache';

cache.put('key', 'value', 1000 * 60); // 1 minute
const value = cache.get('key');
cache.del('key');

cache-manager is an abstraction layer over multiple stores.

  • Wraps different cache backends (memory, Redis, etc.) with one API.
  • Supports multi-caching (writing to multiple stores at once).
  • Allows swapping implementations without code changes.
// cache-manager: With memory store
import cacheManager from 'cache-manager';
import memoryStore from 'cache-manager-remember';

const cache = cacheManager.caching({
  store: memoryStore,
  ttl: 60,
  max: 100
});

await cache.set('key', 'value');
const value = await cache.get('key');

apicache is Express middleware for HTTP response caching.

  • Caches entire HTTP responses automatically.
  • Configurable by status code, URL, and TTL.
  • ⚠️ Deprecated: No longer actively maintained as of 2023.
// apicache: Express middleware
import apicache from 'apicache';
import express from 'express';

const app = express();
app.use(apicache.middleware);

app.get('/api/data', apicache.middleware('5 minutes'), (req, res) => {
  res.json({ data: 'cached response' });
});

cacheable-request adds HTTP caching to request clients.

  • Wraps HTTP clients to respect cache headers.
  • Stores responses based on HTTP semantics (ETag, Last-Modified).
  • Works with got, request, or native http.
// cacheable-request: HTTP caching
import CacheableRequest from 'cacheable-request';
import http from 'http';

const cacheableRequest = new CacheableRequest(http.request);

const req = cacheableRequest('https://api.example.com/data', {
  cacheOptions: { cacheTtl: 1000 * 60 * 5 }
});

req.on('response', (res) => {
  console.log('Status:', res.statusCode);
});

⏱️ TTL and Expiration Handling

How each package handles time-based expiration varies significantly.

  • lru-cache uses TTL per entry in newer versions (v7+). Older versions relied on LRU eviction only.
  • node-cache has global and per-key TTL with automatic cleanup intervals.
  • memory-cache supports per-key TTL but no global cleanup configuration.
  • cache-manager delegates TTL to the underlying store implementation.
  • apicache uses TTL for HTTP response validity.
  • cacheable-request respects HTTP Cache-Control headers plus optional overrides.
// lru-cache: Per-entry TTL
const cache = new LRUCache({ ttl: 5000 });
cache.set('key', 'value', 5000); // 5 seconds

// node-cache: Global and per-key TTL
const cache = new NodeCache({ stdTTL: 60 });
cache.set('key', 'value', 120); // Overrides global to 2 minutes

// memory-cache: Per-key TTL only
cache.put('key', 'value', 60000); // 60 seconds

// cache-manager: Store-dependent TTL
await cache.set('key', 'value', 60); // 60 seconds

// apicache: Middleware TTL string
app.get('/api', apicache.middleware('10 minutes'), handler);

// cacheable-request: HTTP header based
const req = cacheableRequest(url, { cacheOptions: { cacheTtl: 60000 } });

🔄 Eviction Strategies: LRU vs TTL vs Manual

Understanding how items leave the cache is critical for memory management.

  • lru-cache evicts based on access order when max size is reached. Least recently used items go first.
  • node-cache evicts based on TTL expiration with periodic cleanup checks.
  • memory-cache evicts based on TTL expiration during get operations.
  • cache-manager depends on the store — memory uses LRU or TTL, Redis uses TTL.
  • apicache evicts based on TTL and memory limits.
  • cacheable-request evicts based on HTTP cache headers and storage limits.
// lru-cache: LRU eviction when max reached
const cache = new LRUCache({ max: 100 });
// When 101st item added, oldest accessed item is removed

// node-cache: TTL-based cleanup
const cache = new NodeCache({ checkperiod: 60 }); // Check every 60 seconds

// memory-cache: Lazy cleanup on get
// Items removed when accessed after expiration

// cache-manager: Configurable per store
const cache = cacheManager.caching({ store: 'memory', max: 100 });

// apicache: Memory limit configuration
apicache.options({ debug: true, defaultDuration: 3600000 });

// cacheable-request: Storage-based eviction
const cacheableRequest = new CacheableRequest(http.request, { cacheAdapter: new Keyv() });

🌐 HTTP vs Data Caching: Different Use Cases

Some packages cache HTTP responses, others cache application data.

  • apicache and cacheable-request focus on HTTP layer caching.
  • lru-cache, node-cache, memory-cache, and cache-manager focus on application data.
// apicache: HTTP response caching
app.get('/users', apicache.middleware('5 minutes'), getUsers);

// cacheable-request: HTTP client caching
const getData = () => cacheableRequest('https://api.example.com/users');

// node-cache: Application data caching
const users = await cache.get('users');
if (!users) {
  const data = await db.query('SELECT * FROM users');
  cache.set('users', data);
}

// lru-cache: Application data with LRU
const cache = new LRUCache({ max: 1000 });
cache.set('userId', userData);

// memory-cache: Simple data caching
cache.put('session', sessionData, 3600000);

// cache-manager: Unified data caching
await cache.set('config', configData, 300);

⚠️ Maintenance Status and Production Readiness

Not all packages are equally maintained for production use.

  • apicache — ⚠️ No longer actively maintained. Last significant update was in 2021. Consider alternatives like route-cache or custom middleware for new projects.
  • memory-cache — ⚠️ Minimal maintenance. Works but lacks modern features and active development.
  • lru-cache — ✅ Actively maintained. Widely used as a dependency by many major packages.
  • node-cache — ✅ Stable and maintained. Good for in-process caching needs.
  • cache-manager — ✅ Actively maintained. Regular updates and community support.
  • cacheable-request — ✅ Maintained. Works well with modern HTTP clients.
// For new projects, prefer maintained packages
import { LRUCache } from 'lru-cache'; // ✅ Recommended
import NodeCache from 'node-cache'; // ✅ Recommended
import cacheManager from 'cache-manager'; // ✅ Recommended

// Avoid for new production projects
import apicache from 'apicache'; // ⚠️ Deprecated
import cache from 'memory-cache'; // ⚠️ Minimal maintenance

📊 Feature Comparison Table

Featurelru-cachenode-cachememory-cachecache-managerapicachecacheable-request
TypeData StructureIn-Memory CacheIn-Memory CacheCache AbstractionHTTP MiddlewareHTTP Client Wrapper
TTL Support✅ (v7+)✅✅✅ (Store-dependent)✅✅ (HTTP Headers)
LRU Eviction✅❌❌✅ (Memory store)✅❌
Events/Hooks❌✅❌✅✅✅
Multi-Store❌❌❌✅❌❌
HTTP Aware❌❌❌❌✅✅
Maintenance✅ Active✅ Stable⚠️ Minimal✅ Active⚠️ Deprecated✅ Active
Best ForLow-level cachingIn-process dataSimple prototypingFlexible backendsExpress response cachingExternal API calls

🎯 Real-World Selection Guide

Scenario 1: Caching Database Query Results

You need to cache query results in memory with automatic expiration.

  • ✅ Best choice: node-cache or lru-cache
  • Why? You need TTL and reliable eviction without external dependencies.
// Using node-cache for query results
const cache = new NodeCache({ stdTTL: 300 });

async function getUser(id) {
  const cached = cache.get(`user:${id}`);
  if (cached) return cached;
  
  const user = await db.users.findById(id);
  cache.set(`user:${id}`, user);
  return user;
}

Scenario 2: Caching External API Responses

You make frequent calls to third-party APIs and want to respect their cache headers.

  • ✅ Best choice: cacheable-request
  • Why? It handles ETag, Last-Modified, and Cache-Control automatically.
// Using cacheable-request for external APIs
const cacheableRequest = new CacheableRequest(http.request);

async function fetchExternalData(url) {
  return new Promise((resolve, reject) => {
    const req = cacheableRequest(url);
    req.on('response', res => {
      // Handle response with caching applied
    });
    req.end();
  });
}

Scenario 3: Express API Response Caching

You want to cache entire HTTP responses for GET endpoints.

  • ✅ Best choice: Custom middleware or cache-manager with Express
  • Why? apicache is deprecated. Build custom logic or use maintained alternatives.
// Custom Express caching with cache-manager
app.get('/api/data', async (req, res) => {
  const cached = await cache.get(req.url);
  if (cached) return res.json(cached);
  
  const data = await fetchData();
  await cache.set(req.url, data, 60);
  res.json(data);
});

Scenario 4: Multi-Environment Caching Strategy

You need to switch between memory (development) and Redis (production) without code changes.

  • ✅ Best choice: cache-manager
  • Why? Unified API allows swapping stores via configuration.
// cache-manager with configurable store
const store = process.env.NODE_ENV === 'production' ? 'redis' : 'memory';

const cache = cacheManager.caching({
  store: store,
  ttl: 60,
  redis: { host: 'localhost', port: 6379 }
});

Scenario 5: High-Performance In-Memory Cache

You need maximum performance for a hot path with strict memory limits.

  • ✅ Best choice: lru-cache
  • Why? Highly optimized, minimal overhead, precise control over memory usage.
// lru-cache for performance-critical paths
const cache = new LRUCache({
  max: 10000,
  ttl: 60000,
  updateAgeOnGet: true
});

💡 Final Recommendations

For most applications, start with node-cache for simple in-memory needs or cache-manager if you anticipate needing Redis later. Both are well-maintained and offer good developer experience.

For HTTP-specific caching, use cacheable-request for external API calls. Avoid apicache in new projects due to its deprecated status — instead, build custom Express middleware using cache-manager or a Redis-backed solution.

For low-level optimization, lru-cache is the gold standard. It is used by many major packages internally and provides the best performance for LRU-based eviction.

Avoid memory-cache for production systems requiring long-term support. While simple, it lacks the features and maintenance commitment of node-cache or cache-manager.

Remember that caching adds complexity — always measure the performance impact and ensure your cache invalidation strategy matches your data consistency requirements. A well-configured cache can speed up your application significantly, but a poorly managed one can lead to stale data and hard-to-debug issues.

How to Choose: lru-cache vs cacheable-request vs node-cache vs apicache vs cache-manager vs memory-cache

  • lru-cache:

    Choose lru-cache when you need a performant, low-level LRU data structure without extra features like TTL or clustering. It is highly optimized and widely used as a dependency by other caching libraries. Perfect for scenarios where you need fine-grained control over cache eviction based on access patterns rather than time.

  • cacheable-request:

    Choose cacheable-request when you need HTTP-level caching that respects standard cache headers (ETag, Last-Modified, Cache-Control). It wraps HTTP clients like got or request to automatically handle caching based on server responses. Best for applications making many external API calls where you want to respect upstream cache policies.

  • node-cache:

    Choose node-cache when you need a reliable in-memory cache with TTL, event hooks, and key pattern matching in a single Node.js process. It offers more features than memory-cache while remaining simple to use. Suitable for applications that need periodic cleanup and cache event monitoring without external dependencies.

  • apicache:

    Choose apicache if you need quick HTTP response caching for Express applications without writing custom logic. It works as middleware to cache entire route responses based on status codes and TTL. However, note that this package is no longer actively maintained, so evaluate newer alternatives for production systems requiring long-term support.

  • cache-manager:

    Choose cache-manager when you need flexibility to swap cache backends (memory, Redis, file system) without changing your application code. It provides a unified API across different stores and supports clustering. Ideal for applications that might need to scale from simple in-memory caching to distributed Redis caching later.

  • memory-cache:

    Choose memory-cache for simple, lightweight in-memory caching with basic TTL support in small Node.js applications. It has a very simple API but lacks advanced features like clustering or multiple stores. Consider this only for development or small-scale projects where complexity must be minimized.

Similar Npm Packages to lru-cache

lru-cache is a popular caching library for Node.js and JavaScript applications that implements a Least Recently Used (LRU) caching strategy. This means that it automatically removes the least recently accessed items from the cache when it reaches its maximum size, ensuring that the most frequently used data remains available. This makes lru-cache an excellent choice for optimizing performance in applications that require quick access to frequently used data.

While lru-cache is a robust solution for caching, there are several alternatives available that also provide caching capabilities. Here are a few notable options:

  • memory-cache is a simple and lightweight caching library for Node.js applications. It allows you to store key-value pairs in memory with an optional expiration time. Unlike lru-cache, memory-cache does not implement an LRU eviction policy, making it a straightforward choice for applications that require basic caching without the complexity of eviction strategies. It's ideal for small projects or scenarios where caching needs are minimal.

  • node-cache is another caching library designed specifically for Node.js applications. It provides a simple API for storing and retrieving data in memory, along with features like time-to-live (TTL) for cache entries. While it does not implement an LRU eviction policy by default, it offers a more comprehensive set of features compared to memory-cache, making it suitable for applications that require more control over caching behavior.

  • quick-lru is a lightweight and fast LRU cache implementation for JavaScript. It is designed to be simple and efficient, providing a minimal API for managing cached items. quick-lru is an excellent choice for developers looking for a straightforward LRU caching solution without the overhead of additional features. Its performance and simplicity make it a great alternative for applications that need efficient caching without unnecessary complexity.

To see how lru-cache compares with memory-cache, node-cache, and quick-lru, check out the comparison: Comparing lru-cache vs memory-cache vs node-cache vs quick-lru.

Similar Npm Packages to cacheable-request

cacheable-request is a Node.js library that enhances HTTP requests by adding caching capabilities. It allows developers to cache the responses of HTTP requests, reducing the need for repeated network calls and improving application performance. This library is particularly useful for applications that frequently request the same resources, as it can significantly reduce latency and server load. While cacheable-request provides a solid foundation for caching HTTP requests, there are several alternatives in the Node.js ecosystem that offer similar functionalities. Here are a few notable ones:

  • axios-cache-adapter is an adapter for Axios that adds caching functionality to HTTP requests. It allows developers to cache responses and configure cache settings easily. If you are already using Axios for making HTTP requests, integrating axios-cache-adapter can be a seamless way to add caching without changing your existing code structure. This library is particularly useful for applications that rely heavily on Axios and require efficient caching mechanisms.

  • cache-manager is a multi-store caching library for Node.js that provides a unified API for various caching stores, including memory, Redis, and more. It allows developers to manage cache easily and supports features like time-to-live (TTL) and cache expiration. If you need a more comprehensive caching solution that can work with different storage backends, cache-manager is a versatile choice.

  • lru-cache is a simple and efficient implementation of a Least Recently Used (LRU) cache. It is designed for in-memory caching, making it suitable for scenarios where you need fast access to cached data. If your application requires a straightforward in-memory caching solution without the overhead of network requests, lru-cache is an excellent option.

  • memory-cache is another lightweight in-memory caching library for Node.js. It provides a simple API for storing and retrieving cached data in memory. If you are looking for a minimalistic caching solution that is easy to implement and use, memory-cache is a good choice.

  • node-cache is a simple caching module for Node.js that allows you to store key-value pairs in memory. It supports features like TTL and automatic cache expiration. If you need a straightforward caching mechanism for your Node.js application without complex configurations, node-cache is a suitable option.

To see how cacheable-request compares with these alternatives, check out the comparison: Comparing axios-cache-adapter vs cache-manager vs cacheable-request vs lru-cache vs memory-cache vs node-cache.

Similar Npm Packages to node-cache

node-cache is a simple and efficient caching module for Node.js applications. It provides an easy-to-use API for storing and retrieving cached data in memory, making it ideal for scenarios where quick access to frequently used data is required. With features like time-to-live (TTL) for cache entries and automatic cleanup of expired items, node-cache helps improve application performance by reducing the need for repeated data fetching or computation.

While node-cache is a solid choice for in-memory caching, there are several alternatives that offer different features and capabilities. Here are a few notable options:

  • lru-cache is a popular caching library that implements a Least Recently Used (LRU) caching strategy. This means that when the cache reaches its limit, it automatically removes the least recently accessed items to make space for new ones. lru-cache is particularly useful for applications that require efficient memory management and want to ensure that frequently accessed data remains available. Its flexibility and performance make it a great choice for caching scenarios where memory constraints are a concern.

  • memory-cache is another lightweight caching library for Node.js that provides a simple API for in-memory caching. It allows developers to store key-value pairs with optional expiration times. While memory-cache is straightforward and easy to use, it does not implement advanced caching strategies like LRU. It is best suited for smaller applications or scenarios where simplicity is preferred over complex caching mechanisms.

  • node-persist is a persistent storage library for Node.js that allows you to store data in a file-based cache. Unlike in-memory caching solutions, node-persist provides durability by saving data to the filesystem, making it suitable for applications that require data persistence across restarts. It offers a simple API for storing and retrieving data, along with features like automatic serialization and deserialization of JavaScript objects.

To compare these caching libraries, check out the following link: Comparing lru-cache vs memory-cache vs node-cache vs node-persist.

Similar Npm Packages to apicache

apicache is a caching middleware for Node.js applications, designed specifically for HTTP requests. It provides a simple way to cache API responses, reducing the load on servers and improving response times for clients. By caching responses, apicache helps to enhance the performance of applications, especially those that rely heavily on API calls. While apicache is a powerful tool for caching HTTP responses, there are several alternatives available in the Node.js ecosystem. Here are a few notable options:

  • lru-cache is a popular caching library that implements a Least Recently Used (LRU) caching strategy. It is designed for general-purpose caching and can be used in various scenarios, including caching API responses. With lru-cache, you can control the maximum size of the cache, ensuring that it automatically removes the least recently used entries when the limit is reached. This makes it a great choice for applications that require efficient memory management and fast access to cached data.

  • memory-cache is a simple in-memory caching library for Node.js. It provides a straightforward API for setting, getting, and deleting cache entries. Memory-cache is lightweight and easy to use, making it suitable for applications that need a quick and simple caching solution without the overhead of more complex libraries. However, since it stores data in memory, it is best suited for scenarios where the cached data does not need to persist across server restarts.

  • node-cache is another caching library for Node.js that provides a simple key-value store with an expiration feature. It allows you to set time-to-live (TTL) values for cache entries, automatically removing them after a specified duration. Node-cache is useful for caching data that is time-sensitive or for reducing the frequency of expensive operations, such as database queries or API calls.

To see how apicache compares with lru-cache, memory-cache, and node-cache, check out the comparison: Comparing apicache vs lru-cache vs memory-cache vs node-cache.

Similar Npm Packages to cache-manager

cache-manager is a versatile caching library for Node.js applications. It provides a simple and consistent API for managing caching across different storage engines, such as memory, Redis, and more. With cache-manager, developers can easily implement caching strategies to improve application performance and reduce the load on backend services. While cache-manager is a robust solution for caching, there are several alternatives available that cater to different use cases. Here are a few notable options:

  • apicache is a lightweight caching middleware for Express.js applications. It allows developers to cache API responses easily, improving response times and reducing server load. apicache is particularly useful for applications that require quick access to frequently requested data, as it can significantly enhance performance with minimal configuration. If you're building an API with Express and want a straightforward way to implement caching, apicache is an excellent choice.

  • cacheable-request is a caching wrapper for HTTP requests. It allows developers to cache responses from HTTP requests, making it a great option for applications that rely heavily on external APIs. By using cacheable-request, developers can reduce the number of requests made to external services, thereby improving performance and reducing costs. This library is particularly useful for applications that need to fetch data from APIs frequently and can benefit from caching those responses.

  • lru-cache is a simple and efficient implementation of a Least Recently Used (LRU) cache. It is designed to store a limited number of items in memory, automatically evicting the least recently used items when the cache reaches its size limit. lru-cache is ideal for scenarios where memory usage is a concern, and you want to ensure that your application only retains the most relevant data in cache. Its straightforward API makes it easy to integrate into any Node.js application.

  • memory-cache is a simple in-memory caching library for Node.js. It provides a straightforward API for storing and retrieving data in memory, making it suitable for applications that require quick access to cached data without the overhead of more complex caching solutions. If you need a lightweight and easy-to-use caching solution for your Node.js application, memory-cache is a solid option.

  • node-cache is another in-memory caching library for Node.js that offers a simple key-value store. It supports features like time-to-live (TTL) for cache entries, allowing developers to control how long data remains in the cache. node-cache is useful for applications that require a straightforward caching mechanism without the complexity of external storage solutions.

To explore how these caching libraries compare, check out the comparison: Comparing apicache vs cache-manager vs cacheable-request vs lru-cache vs memory-cache vs node-cache.

Similar Npm Packages to memory-cache

memory-cache is a simple and efficient caching library for Node.js applications. It allows developers to store key-value pairs in memory, providing a fast way to access frequently used data without the need for repeated calculations or database queries. While memory-cache is a great choice for in-memory caching, there are several alternatives that offer similar functionality. Here are a few noteworthy options:

  • lru-cache is a popular caching library that implements a Least Recently Used (LRU) cache algorithm. This means that it automatically removes the least recently accessed items when the cache reaches its limit, making it ideal for applications where memory usage needs to be optimized. lru-cache is particularly useful for scenarios where you want to maintain a limited amount of cached data while ensuring that the most frequently accessed items remain available. Its flexibility and efficiency make it a preferred choice for many developers looking for a robust caching solution.
  • node-cache is another caching library designed specifically for Node.js applications. It provides a simple API for storing and retrieving cached data, along with features like time-to-live (TTL) for cache entries, allowing developers to set expiration times for cached items. node-cache is well-suited for applications that require a straightforward caching mechanism with the ability to manage cache lifetimes effectively. Its ease of use and built-in expiration features make it a solid choice for many caching scenarios.
  • quick-lru is a lightweight and efficient LRU caching library that focuses on performance. It is designed to be simple and fast, making it an excellent choice for applications that require a minimalistic approach to caching. quick-lru allows developers to easily set limits on the cache size and provides a straightforward API for adding and retrieving cached items. If you are looking for a high-performance caching solution without unnecessary complexity, quick-lru is worth considering.

To see how memory-cache compares with lru-cache, node-cache, and quick-lru, check out the comparison: Comparing lru-cache vs memory-cache vs node-cache vs quick-lru.

README for lru-cache

lru-cache

A cache object that deletes the least-recently-used items.

Specify a max number of the most recently used items that you want to keep, and this cache will keep that many of the most recently accessed items.

This is not primarily a TTL cache, and does not make strong TTL guarantees. There is no preemptive pruning of expired items by default, but you may set a TTL on the cache or on a single set. If you do so, it will treat expired items as missing, and delete them when fetched. If you are more interested in TTL caching than LRU caching, check out @isaacs/ttlcache.

As of version 7, this is one of the most performant LRU implementations available in JavaScript, and supports a wide diversity of use cases. However, note that using some of the features will necessarily impact performance, by causing the cache to have to do more work. See the "Performance" section below.

Installation

npm install lru-cache --save

Usage

// hybrid module, either works
import { LRUCache } from 'lru-cache'
// or:
const { LRUCache } = require('lru-cache')
// or in minified form for web browsers:
import { LRUCache } from 'http://unpkg.com/lru-cache@9/dist/mjs/index.min.mjs'

// At least one of 'max', 'ttl', or 'maxSize' is required, to prevent
// unsafe unbounded storage.
//
// In most cases, it's best to specify a max for performance, so all
// the required memory allocation is done up-front.
//
// All the other options are optional, see the sections below for
// documentation on what each one does.  Most of them can be
// overridden for specific items in get()/set()
const options = {
  max: 500,

  // for use with tracking overall storage size
  maxSize: 5000,
  sizeCalculation: (value, key) => {
    return 1
  },

  // for use when you need to clean up something when objects
  // are evicted from the cache
  dispose: (value, key, reason) => {
    freeFromMemoryOrWhatever(value)
  },

  // for use when you need to know that an item is being inserted
  // note that this does NOT allow you to prevent the insertion,
  // it just allows you to know about it.
  onInsert: (value, key, reason) => {
    logInsertionOrWhatever(key, value)
  },

  // how long to live in ms
  ttl: 1000 * 60 * 5,

  // return stale items before removing from cache?
  allowStale: false,

  updateAgeOnGet: false,
  updateAgeOnHas: false,

  // async method to use for cache.fetch(), for
  // stale-while-revalidate type of behavior
  fetchMethod: async (key, staleValue, { options, signal, context }) => {},
}

const cache = new LRUCache(options)

cache.set('key', 'value')
cache.get('key') // "value"

// non-string keys ARE fully supported
// but note that it must be THE SAME object, not
// just a JSON-equivalent object.
var someObject = { a: 1 }
cache.set(someObject, 'a value')
// Object keys are not toString()-ed
cache.set('[object Object]', 'a different value')
assert.equal(cache.get(someObject), 'a value')
// A similar object with same keys/values won't work,
// because it's a different object identity
assert.equal(cache.get({ a: 1 }), undefined)

cache.clear() // empty the cache

If you put more stuff in the cache, then less recently used items will fall out. That's what an LRU cache is.

For full description of the API and all options, please see the LRUCache typedocs

Storage Bounds Safety

This implementation aims to be as flexible as possible, within the limits of safe memory consumption and optimal performance.

At initial object creation, storage is allocated for max items. If max is set to zero, then some performance is lost, and item count is unbounded. Either maxSize or ttl must be set if max is not specified.

If maxSize is set, then this creates a safe limit on the maximum storage consumed, but without the performance benefits of pre-allocation. When maxSize is set, every item must provide a size, either via the sizeCalculation method provided to the constructor, or via a size or sizeCalculation option provided to cache.set(). The size of every item must be a positive integer.

If neither max nor maxSize are set, then ttl tracking must be enabled. Note that, even when tracking item ttl, items are not preemptively deleted when they become stale, unless ttlAutopurge is enabled. Instead, they are only purged the next time the key is requested. Thus, if ttlAutopurge, max, and maxSize are all not set, then the cache will potentially grow unbounded.

In this case, a warning is printed to standard error. Future versions may require the use of ttlAutopurge if max and maxSize are not specified.

If you truly wish to use a cache that is bound only by TTL expiration, consider using a Map object, and calling setTimeout to delete entries when they expire. It will perform much better than an LRU cache.

Here is an implementation you may use, under the same license as this package:

// a storage-unbounded ttl cache that is not an lru-cache
const cache = {
  data: new Map(),
  timers: new Map(),
  set: (k, v, ttl) => {
    if (cache.timers.has(k)) {
      clearTimeout(cache.timers.get(k))
    }
    cache.timers.set(
      k,
      setTimeout(() => cache.delete(k), ttl),
    )
    cache.data.set(k, v)
  },
  get: k => cache.data.get(k),
  has: k => cache.data.has(k),
  delete: k => {
    if (cache.timers.has(k)) {
      clearTimeout(cache.timers.get(k))
    }
    cache.timers.delete(k)
    return cache.data.delete(k)
  },
  clear: () => {
    cache.data.clear()
    for (const v of cache.timers.values()) {
      clearTimeout(v)
    }
    cache.timers.clear()
  },
}

If that isn't to your liking, check out @isaacs/ttlcache.

Storing Undefined Values

This cache never stores undefined values, as undefined is used internally in a few places to indicate that a key is not in the cache.

You may call cache.set(key, undefined), but this is just an alias for cache.delete(key). Note that this has the effect that cache.has(key) will return false after setting it to undefined.

cache.set(myKey, undefined)
cache.has(myKey) // false!

If you need to track undefined values, and still note that the key is in the cache, an easy workaround is to use a sigil object of your own.

import { LRUCache } from 'lru-cache'
const undefinedValue = Symbol('undefined')
const cache = new LRUCache(...)
const mySet = (key, value) =>
  cache.set(key, value === undefined ? undefinedValue : value)
const myGet = (key, value) => {
  const v = cache.get(key)
  return v === undefinedValue ? undefined : v
}

Performance

As of January 2022, version 7 of this library is one of the most performant LRU cache implementations in JavaScript.

Benchmarks can be extremely difficult to get right. In particular, the performance of set/get/delete operations on objects will vary wildly depending on the type of key used. V8 is highly optimized for objects with keys that are short strings, especially integer numeric strings. Thus any benchmark which tests solely using numbers as keys will tend to find that an object-based approach performs the best.

Note that coercing anything to strings to use as object keys is unsafe, unless you can be 100% certain that no other type of value will be used. For example:

const myCache = {}
const set = (k, v) => (myCache[k] = v)
const get = k => myCache[k]

set({}, 'please hang onto this for me')
set('[object Object]', 'oopsie')

Also beware of "Just So" stories regarding performance. Garbage collection of large (especially: deep) object graphs can be incredibly costly, with several "tipping points" where it increases exponentially. As a result, putting that off until later can make it much worse, and less predictable. If a library performs well, but only in a scenario where the object graph is kept shallow, then that won't help you if you are using large objects as keys.

In general, when attempting to use a library to improve performance (such as a cache like this one), it's best to choose an option that will perform well in the sorts of scenarios where you'll actually use it.

This library is optimized for repeated gets and minimizing eviction time, since that is the expected need of a LRU. Set operations are somewhat slower on average than a few other options, in part because of that optimization. It is assumed that you'll be caching some costly operation, ideally as rarely as possible, so optimizing set over get would be unwise.

If performance matters to you:

  1. If it's at all possible to use small integer values as keys, and you can guarantee that no other types of values will be used as keys, then do that, and use a cache such as lru-fast, or mnemonist's LRUCache which uses an Object as its data store.

  2. Failing that, if at all possible, use short non-numeric strings (ie, less than 256 characters) as your keys, and use mnemonist's LRUCache.

  3. If the types of your keys will be anything else, especially long strings, strings that look like floats, objects, or some mix of types, or if you aren't sure, then this library will work well for you.

    If you do not need the features that this library provides (like asynchronous fetching, a variety of TTL staleness options, and so on), then mnemonist's LRUMap is a very good option, and just slightly faster than this module (since it does considerably less).

  4. Do not use a dispose function, size tracking, or especially ttl behavior, unless absolutely needed. These features are convenient, and necessary in some use cases, and every attempt has been made to make the performance impact minimal, but it isn't nothing.

Testing

When writing tests that involve TTL-related functionality, note that this module creates an internal reference to the global performance or Date objects at import time. If you import it statically at the top level, those references cannot be mocked or overridden in your test environment.

To avoid this, dynamically import the package within your tests so that the references are captured after your mocks are applied. For example:

// ❌ Not recommended
import { LRUCache } from 'lru-cache'
// mocking timers, e.g. jest.useFakeTimers()

// ✅ Recommended for TTL tests
// mocking timers, e.g. jest.useFakeTimers()
const { LRUCache } = await import('lru-cache')

This ensures that your mocked timers or time sources are respected when testing TTL behavior.

Additionally, you can pass in a perf option when creating your LRUCache instance. This option accepts any object with a now method that returns a number.

For example, this would be a very bare-bones time-mocking system you could use in your tests, without any particular test framework:

import { LRUCache } from 'lru-cache'

let myClockTime = 0

const cache = new LRUCache<string>({
  max: 10,
  ttl: 1000,
  perf: {
    now: () => myClockTime,
  },
})

// run tests, updating myClockTime as needed

Breaking Changes in Version 7

This library changed to a different algorithm and internal data structure in version 7, yielding significantly better performance, albeit with some subtle changes as a result.

If you were relying on the internals of LRUCache in version 6 or before, it probably will not work in version 7 and above.

Breaking Changes in Version 8

  • The fetchContext option was renamed to context, and may no longer be set on the cache instance itself.
  • Rewritten in TypeScript, so pretty much all the types moved around a lot.
  • The AbortController/AbortSignal polyfill was removed. For this reason, Node version 16.14.0 or higher is now required.
  • Internal properties were moved to actual private class properties.
  • Keys and values must not be null or undefined.
  • Minified export available at 'lru-cache/min', for both CJS and MJS builds.

Breaking Changes in Version 9

  • Named export only, no default export.
  • AbortController polyfill returned, albeit with a warning when used.

Breaking Changes in Version 10

  • cache.fetch() return type is now Promise<V | undefined> instead of Promise<V | void>. This is an irrelevant change practically speaking, but can require changes for TypeScript users.

For more info, see the change log.

npm-compare.com is an independent website designed to help developers choose the most suitable npm packages. We are not affiliated with npm, Inc, the official website for the npm registry. Note that npm is a registered trademark of npm, Inc. Please share your feedback via our GitHub repository. For more details, please refer to our Terms & Privacy.