Skip to main content

LRU Memory Cache Driver

The LRU (Least Recently Used) Memory Cache Driver is an in-memory cache that automatically evicts the least recently used items when it reaches its capacity.

When to Use​

  • You want fast, in-memory caching with automatic eviction
  • You have limited memory and want to avoid unbounded growth

Best For​

  • Caching computed values, API responses, or temporary data
  • Scenarios where memory usage must be controlled

Limitations​

  • Data is lost on restart
  • Not shared between processes or servers
  • No persistence
  • No namespaces support

Configuration​

src/config/cache.ts
import { LRUMemoryCacheDriver } from "@warlock.js/core";

const cacheConfigurations = {
  drivers: {
    lru: LRUMemoryCacheDriver,
  },
  default: "lru",
  options: {
    lru: {
      capacity: 500,
    },
  },
};

Options​

OptionTypeDefaultDescription
capacitynumber1000Maximum number of items in the cache

Capacity Configuration​

{
  capacity: 1000,              // Store up to 1000 items (default)
  // OR
  capacity: 500,               // Store up to 500 items
  // OR
  capacity: 10000,             // Store up to 10,000 items
}

Example Usage​

Storing and Retrieving Data​

import { cache } from "@warlock.js/core";

await cache.set("temp:1", 123);
const value = await cache.get("temp:1");

How LRU Works​

The LRU (Least Recently Used) algorithm works as follows:

  1. Capacity Limit: When the cache reaches its capacity limit, the least recently used item is automatically removed
  2. Access Updates: Every time an item is accessed (get or set), it becomes the most recently used
  3. Automatic Eviction: When adding a new item would exceed capacity, the oldest item is evicted

Example Eviction Scenario​

// Cache with capacity: 3
await cache.set("a", 1);  // Cache: {a: 1}
await cache.set("b", 2);  // Cache: {a: 1, b: 2}
await cache.set("c", 3);  // Cache: {a: 1, b: 2, c: 3}
await cache.set("d", 4);  // Cache: {b: 2, c: 3, d: 4} - 'a' was evicted
await cache.get("b");     // Cache: {c: 3, d: 4, b: 2} - 'b' moved to end
await cache.set("e", 5);  // Cache: {d: 4, b: 2, e: 5} - 'c' was evicted

Performance Characteristics​

  • Time Complexity: O(1) average for get/set operations
  • Space Complexity: O(n) where n is the capacity
  • Memory Usage: Predictable and bounded by capacity
  • Eviction: Automatic and efficient

Troubleshooting​

  • Data disappears after restart: This is expected. Use File or Redis for persistence.
  • Cache not shared between processes: Use Redis for distributed cache.
  • No namespaces? LRU driver does not support namespaces.
  • Items being evicted too quickly: Increase the capacity option.