Skip to content

Memory Cache Driver

In-memory storage with optional automatic eviction when a size limit is reached.

  • Local development
  • Caching data for the duration of a process
  • Fastest possible cache (no disk or network I/O)
  • Temporary data
  • Caching API responses, user sessions, or computed values
  • Data is lost on restart
  • Not shared between processes or servers — with more than one server use Redis or Postgres
  • Keys are stored flat: get("users") after set("users.1", …) is a miss, and maxSize counts entries (evicting in LRU order)
  • increment, pull and update are atomic within the process only
  • Memory growth: the driver keeps at most maxSize entries, 10,000 by default, evicting the least recently used ones; maxSize: Infinity removes the limit
src/config/cache.ts
import { env } from "@mongez/dotenv";
import { CacheConfigurations, MemoryCacheDriver } from "@warlock.js/cache";
const cacheConfigurations: CacheConfigurations = {
drivers: {
memory: MemoryCacheDriver,
},
default: env("CACHE_DRIVER", "memory"),
options: {
memory: {
globalPrefix: "dev-app",
ttl: "1h",
maxSize: 1000, // optional: max 1000 items with LRU eviction
},
},
};
export default cacheConfigurations;
OptionTypeDefaultDescription
globalPrefixstring | FunctionundefinedGlobal prefix for all cache keys
ttlnumber | stringInfinityDefault TTL — seconds or a duration string ("1h", "7d")
maxSizenumber10000Maximum number of items. When exceeded, least recently used items are evicted. Infinity (or 0) removes the limit
{
globalPrefix: "myapp", // Static prefix
// OR
globalPrefix: () => `app-${environment()}`, // Dynamic prefix
}
{
ttl: Infinity, // never expire (default)
// OR
ttl: 3600, // 1 hour, numeric seconds
// OR
ttl: "1h", // human-readable duration string
// OR
ttl: "1d", // 24 hours
}

The maxSize option limits the number of items in the cache. When the limit is reached, the least recently used (LRU) items are automatically evicted. It defaults to 10000, so keys built from request input (page numbers, filters, query strings) cannot grow the heap without bound. Set maxSize: Infinity to keep every entry until it expires.

Rate-limit counters and login lockouts kept in a bounded memory cache can be evicted by a flood of distinct keys (and are per process anyway): in production, keep them in a shared store (redis or pg), or set maxSize: Infinity on the memory driver that holds them.

Eviction touches only the oldest entries; a write past the limit costs the same however large the cache is.

{
maxSize: 1000, // Cache will hold maximum 1000 items
// When 1001st item is added, least recently used item is removed
}

When to use maxSize:

  • You want to prevent unbounded memory growth
  • You have predictable cache size requirements
  • You want automatic eviction without using the dedicated LRU driver

How it works:

  • Uses LRU (Least Recently Used) eviction algorithm
  • Tracks access order automatically
  • Evicts oldest items when limit is reached
  • Works alongside TTL expiration (both can remove items)

Example:

import { CacheConfigurations, MemoryCacheDriver } from "@warlock.js/cache";
const cacheConfigurations: CacheConfigurations = {
drivers: {
memory: MemoryCacheDriver,
},
options: {
memory: {
maxSize: 500, // max 500 items
ttl: "1h", // items expire after 1 hour
// items can be removed by: expiration OR eviction when full
},
},
};
import { cache } from "@warlock.js/cache";
await cache.set("products.123", { name: "Laptop", price: 999 }, "1h");
const product = await cache.get("products.123");

The memory driver uses an in-memory data structure to store cache entries. Key points:

  • Size limits: Use maxSize option to limit cache size with automatic LRU eviction
  • Eviction: Items are removed when they expire, manually deleted, or evicted when maxSize limit is reached
  • Fast access: O(1) average time complexity for get/set operations
  • LRU tracking: When maxSize is set, access order is tracked for efficient eviction
  • Process isolation: Each Node.js process has its own cache instance
  • Data disappears after restart: This is expected. Use File or Redis drivers for persistence.
  • Cache not shared between processes: Use Redis for distributed cache.
  • Memory usage growing: Set maxSize option or use LRU Memory Cache Driver for automatic eviction.
  • Items being evicted unexpectedly: Check if maxSize is set and if cache is reaching the limit.

✅ Supported (brute force). set({ vector }) indexes the entry; similar() does an O(N) cosine scan. Suitable for development and small datasets — see Similarity Retrieval. Past a few thousand entries, switch to the pg driver with pgvector.