lru-cache vs quick-lru vs lru vs lru-memoize
Caching Libraries in JavaScript Comparison
1 Year
lru-cachequick-lrulrulru-memoizeSimilar Packages:
What's Caching Libraries in JavaScript?

Caching Libraries in JavaScript are tools that help store data temporarily to speed up future access to that data. They are particularly useful in web applications to reduce the time it takes to retrieve data from slow sources, like databases or APIs. By keeping frequently accessed data in memory, these libraries can significantly improve performance and reduce the load on servers. Each caching library has its own features, such as setting limits on how much data can be stored, automatically removing old data when space runs out, and handling data that hasn’t been used in a while. Some libraries are simple and lightweight, while others offer more advanced features like time-based expiration, which automatically removes data after a certain period. Overall, caching libraries are essential tools for developers looking to optimize their applications and provide a faster experience for users.

Package Weekly Downloads Trend
Github Stars Ranking
Stat Detail
Package
Downloads
Stars
Size
Issues
Publish
License
lru-cache237,899,6375,608820 kB104 months agoISC
quick-lru28,651,70671215.2 kB43 months agoMIT
lru76,430137-129 years agoMIT
lru-memoize76,368318-306 years agoMIT
Feature Comparison: lru-cache vs quick-lru vs lru vs lru-memoize

Caching Strategy

  • lru-cache:

    The lru-cache package also uses the LRU caching strategy but adds more features, such as setting a maximum size for the cache (in bytes) and the ability to specify a time-to-live (TTL) for cached items. This allows for more fine-grained control over how and when items are evicted from the cache.

  • quick-lru:

    The quick-lru package provides a fast and efficient implementation of the LRU caching strategy with a focus on performance and low memory usage. It offers a simple API for adding, retrieving, and deleting items from the cache, making it easy to use in applications that require quick access to cached data.

  • lru:

    The lru package implements a basic LRU (Least Recently Used) caching strategy, which evicts the least recently accessed items when the cache reaches its limit. This strategy helps keep frequently accessed data in memory while freeing up space for new entries.

  • lru-memoize:

    The lru-memoize package combines LRU caching with memoization, a technique that stores the results of expensive function calls and returns the cached result when the same inputs occur again. This package is particularly useful for optimizing functions that are called repeatedly with the same arguments, as it reduces the need for redundant calculations.

Memory Management

  • lru-cache:

    The lru-cache package includes memory management features, such as setting a maximum size for the cache (in bytes) and supporting time-based expiration for cached items. This allows developers to control how much memory the cache uses and ensures that stale or unused items are removed automatically, preventing memory leaks.

  • quick-lru:

    The quick-lru package provides a lightweight and efficient implementation of LRU caching with minimal memory overhead. It does not include advanced memory management features, but its simple design and efficient eviction strategy help keep memory usage low while maintaining fast access to cached data.

  • lru:

    The lru package does not provide built-in memory management features, such as limiting the total size of the cache or automatically expiring items after a certain period. It relies on the LRU strategy to evict items based on their access patterns, which helps manage memory usage over time but does not prevent the cache from growing indefinitely.

  • lru-memoize:

    The lru-memoize package focuses on memory management for function results by caching the output of function calls based on their input arguments. It does not provide features for managing the overall memory usage of the cache, but it does limit the number of cached results based on the LRU strategy, which helps keep memory usage in check while still allowing for efficient caching of function results.

Expiration and Eviction

  • lru-cache:

    The lru-cache package supports both LRU eviction and time-based expiration of cached items. Developers can set a maximum size for the cache and specify a time-to-live (TTL) for each item, after which it will be automatically removed from the cache. This combination of LRU eviction and expiration helps keep the cache fresh and prevents it from holding onto stale data.

  • quick-lru:

    The quick-lru package implements LRU eviction but does not support expiration of cached items. It removes the least recently used items from the cache when it reaches its capacity, but once an item is cached, it will remain until it is evicted. This makes it a simple and efficient LRU cache, but it lacks the ability to automatically expire items after a certain time.

  • lru:

    The lru package implements eviction based on the LRU (Least Recently Used) algorithm, which removes the least recently accessed items from the cache when it reaches its capacity. However, it does not support expiration of cached items based on time or any other criteria, meaning that once an item is cached, it will remain in the cache until it is evicted due to LRU policy.

  • lru-memoize:

    The lru-memoize package focuses on caching the results of function calls based on their input arguments. It does not provide built-in expiration for cached items, but it limits the number of cached results based on the LRU strategy. Once the cache reaches its limit, the least recently used results are evicted to make room for new ones, ensuring that the cache remains efficient without retaining too many old values.

Use Case

  • lru-cache:

    The lru-cache package is suitable for applications that need a more robust caching solution with features like size limits, time-based expiration, and event hooks. It is ideal for scenarios where memory management and cache freshness are important, such as caching API responses or database queries.

  • quick-lru:

    The quick-lru package is ideal for performance-sensitive applications that need a fast and lightweight LRU caching solution. It is suitable for scenarios where you want to cache data with minimal overhead and do not require advanced features like expiration or size limits.

  • lru:

    The lru package is best suited for applications that require a simple and efficient LRU caching solution without any additional features. It is ideal for scenarios where you want to cache data based on access patterns but do not need advanced features like expiration or size limits.

  • lru-memoize:

    The lru-memoize package is designed for optimizing the performance of functions that are called repeatedly with the same arguments. It is ideal for use cases where you want to cache the results of expensive computations to avoid redundant calculations, such as in data processing or rendering tasks.

Ease of Use: Code Examples

  • lru-cache:

    LRU Cache Example with lru-cache

    import LRU from 'lru-cache';
    const cache = new LRU({
      max: 100, // Maximum size of the cache
      ttl: 1000 * 60 // Time-to-live for cached items (1 minute)
    });
    
    cache.set('key1', 'value1');
    console.log(cache.get('key1')); // Output: 'value1'
    
    setTimeout(() => {
      console.log(cache.get('key1')); // Output: undefined (item expired)
    }, 1000 * 61);
    
  • quick-lru:

    Simple LRU Cache Example with quick-lru

    import QuickLRU from 'quick-lru';
    const lru = new QuickLRU({ maxSize: 100 }); // Create an LRU cache with a max size of 100
    
    lru.set('key1', 'value1');
    lru.set('key2', 'value2');
    lru.set('key3', 'value3');
    lru.set('key4', 'value4'); // This will evict 'key1' as it is the least recently used
    
    console.log(lru.get('key1')); // Output: undefined
    console.log(lru.get('key2')); // Output: 'value2'
    
  • lru:

    Basic LRU Cache Example with lru

    import LRU from 'lru';
    const cache = new LRU(3); // Create an LRU cache with a limit of 3 items
    
    cache.set('a', 1);
    cache.set('b', 2);
    cache.set('c', 3);
    console.log(cache.get('a')); // Output: 1
    
    cache.set('d', 4); // 'b' is evicted because it is the least recently used
    console.log(cache.get('b')); // Output: undefined
    
  • lru-memoize:

    Memoization Example with lru-memoize

    import memoize from 'lru-memoize';
    const memoizedFn = memoize(3); // Limit cache to 3 items
    
    const slowFunction = (num) => {
      // Simulate a slow computation
      for (let i = 0; i < 1e9; i++); // Delay
      return num * 2;
    };
    
    const result1 = memoizedFn(slowFunction)(5);
    const result2 = memoizedFn(slowFunction)(5); // Cached result
    console.log(result1, result2); // Output: 10 10
    
How to Choose: lru-cache vs quick-lru vs lru vs lru-memoize
  • lru-cache:

    Choose lru-cache if you need a feature-rich LRU cache with support for maximum size, time-based expiration, and event hooks. It is suitable for applications that require more control over caching behavior and memory management.

  • quick-lru:

    Choose quick-lru if you need a fast and efficient LRU cache with a simple API and low memory overhead. It is designed for performance and is suitable for applications where speed is critical, and you want a no-frills caching solution.

  • lru:

    Choose lru if you need a simple, lightweight implementation of an LRU (Least Recently Used) cache without any additional features. It is ideal for projects where you want to implement LRU caching with minimal overhead and complexity.

  • lru-memoize:

    Choose lru-memoize if you need an LRU caching solution specifically for memoizing function results. It is ideal for optimizing performance in applications where the same function is called repeatedly with the same arguments, as it caches the results to avoid redundant computations.

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.

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.