You need a bounded Map and nothing else
Pick lru-cache, quick-lru
They insert 2–3× faster and hold less per entry, because they skip TTLs, byte budgets and eviction bookkeeping.
LazyLayers gives Node.js and Cloudflare Workers a shared cache read path. Keep hot reads in memory, back them with Redis or Cloudflare KV, and load missing values through one call.
npm i lazy-layers-cache
MIT licensed One runtime dependency Start local, add Redis or Cloudflare KV
await cache.getOrSet(key, load);cache.getOrSet(key, loader)
With Redis L2, one server loads and the rest wait. No lock configuration required.
How refresh protection worksEvery request for the same missing or expired key, on every server, waits for one load. A miss costs two Redis round trips.
With an event bus, waiting servers get the value 0.8 ms after the load finishes, instead of polling for it.
Redis renews the lock while the load runs. At the deadline, serve eligible stale data or return a clear error, never an unlocked load.
Six libraries, one harness, a fresh process for every run. We show where we lose, too.
What does a cached getOrSet cost?
ns per call · lower is better
The fastest read-through hit tested. Reference mode returns the stored object; encoded mode, the default, decodes a private copy so callers cannot change the cached value.
10,000 resident keys, 500,000 awaited getOrSet calls in random order.
| Library | Version | Setting | ns per call | min – max |
|---|---|---|---|---|
| lazy-layers-cache | 8.0.0 | L1 reference mode | 180 | 177 – 186 |
| layered-loader | 17.0.0 | Loader with in-memory cache | 220 | 212 – 223 |
| async-cache-dedupe | 3.4.0 | memory storage | 658 | 654 – 668 |
| @epic-web/cachified | 5.6.3 | lru-cache store | 821 | 810 – 862 |
| bentocache | 1.6.1 | memory driver, serialize: false | 1,120 | 1,117 – 1,136 |
| lazy-layers-cache | 8.0.0 | L1 encoded mode (default) | 1,504 | 1,499 – 1,536 |
| bentocache | 1.6.1 | memory driver (default) | 2,429 | 2,398 – 2,495 |
| cache-manager | 7.2.9 | wrap, Keyv in-memory store | 9,337 | 9,287 – 9,438 |
| cacheable | 2.5.0 | getOrSet, in-memory primary | 9,470 | 9,334 – 9,685 |
How often does the cache send you to the database?
loader calls per 300,000 requests · lower is better
S3-FIFO, the default eviction policy, keeps the keys that are read again: 75.9% hits against 72.9%, so 11% fewer calls reach your database.
Zipf α = 1.0 over 100,000 keys, cache holds 10%; 300,000 getOrSet calls.
| Library | Version | Setting | loader calls per 300,000 requests | min – max |
|---|---|---|---|---|
| lazy-layers-cache | 8.0.0 | S3-FIFO (default), 75.89% hits | 72,341 | — |
| layered-loader | 17.0.0 | 72.85% hits | 81,442 | — |
| async-cache-dedupe | 3.4.0 | 72.85% hits | 81,442 | — |
| @epic-web/cachified | 5.6.3 | 72.85% hits | 81,442 | — |
| bentocache | 1.6.1 | 72.85% hits | 81,442 | — |
| cache-manager | 7.2.9 | 72.85% hits | 81,442 | — |
| cacheable | 2.5.0 | 72.85% hits | 81,442 | — |
How long until every caller has a value?
ms, loader takes 20 ms · lower is better
Dashed line: 20 ms loader, the least any library can take.
Every library ran the loader once. Lazy Layers is within 5 ms of the fastest, and is the only one that also coordinates the load across servers.
10,000 concurrent getOrSet calls for one cold key; the loader takes 20 ms.
| Library | Version | Setting | ms, loader takes 20 ms | min – max |
|---|---|---|---|---|
| async-cache-dedupe | 3.4.0 | memory storage | 25.1 | 24.8 – 25.2 |
| layered-loader | 17.0.0 | Loader with in-memory cache | 25.6 | 25.3 – 25.6 |
| lazy-layers-cache | 8.0.0 | L1 reference mode | 30.2 | 29.7 – 31.3 |
| cache-manager | 7.2.9 | wrap, Keyv in-memory store | 35.6 | 35.5 – 36.5 |
| @epic-web/cachified | 5.6.3 | lru-cache store | 45.1 | 45.1 – 45.9 |
| bentocache | 1.6.1 | memory driver, serialize: false | 89.8 | 89.2 – 91.2 |
| cacheable | 2.5.0 | getOrSet, in-memory primary | 99.9 | 99.8 – 102 |
Apple M5, 10 logical CPUs · Node 24.21 · 2026-11-12 · fresh process per run, median of 5 · Every number, command and raw file ↗
Start in memory. Add Redis for Node.js or Cloudflare KV for Workers and Node.js when your service needs shared storage.
import Redis from 'ioredis';
import { LazyLayersCache, RedisStore } from 'lazy-layers-cache';
// Memory L1 in front of a shared Redis L2
const cache = new LazyLayersCache({
ttlMs: 300_000,
levels: {
L1: {
maxEntries: 25_000, // S3-FIFO eviction by default
ttlMs: 60_000, // hot copy for 1 minute
},
L2: {
ttlMs: 300_000, // shared copy for 5 minutes
},
},
l2: new RedisStore(redis, { prefix: 'app:' }),
});
// Cold or expired key: one load across every server, lock renewed for you
const user = await cache.getOrSet(`user:${id}`, () =>
db.users.findById(id)
);
import { LazyLayersCache } from 'lazy-layers-cache';
// Local memory. No Redis or event bus needed.
const cache = new LazyLayersCache({
ttlMs: 60_000,
levels: { L1: { maxEntries: 10_000 } },
});
// Same key, concurrent calls: one loader per process.
const user = await cache.getOrSet(`user:${id}`, () =>
db.users.findById(id)
);
import { LazyLayersCache, RedisStore, RedisEventBus } from 'lazy-layers-cache';
const bus = new RedisEventBus(redis, 'cache.invalidate');
await bus.connect();
const cache = new LazyLayersCache({
l2: new RedisStore(redis),
eventBus: bus,
source: process.env.POD_NAME, // ignore our own events
});
// One server runs the loader and sends the value; peers warm L1 without loading.
await cache.getOrSet(`user:${id}`, loadUser, { tags: ['tenant:42'] });
// After a write, drop the stale copies everywhere.
await cache.invalidateTags(['tenant:42']);
await cache.deleteByPattern('user:*');
import { LazyLayersCache } from 'lazy-layers-cache';
interface UserProfile {
id: string;
name: string;
plan: 'free' | 'pro';
}
// Bind one cache instance to a strongly-typed value schema.
const users = new LazyLayersCache<string, UserProfile>({ ttlMs: 60_000 });
const user = await users.get('user:1'); // user is UserProfile | undefined
Without a bus, other servers keep serving their old copy until it expires. With one, they drop it about a millisecond after you write.
delDrop one key on every server.patternDrop every key matching tenant:42:*.setSend the loaded value, so peers skip the database.Late and duplicate events are rejected by generation checks. Read the consistency model →
The same cache API in Hono on Workers, Hono on Node.js, or any Node.js server. Cloudflare stores the shared values. LazyLayers adds lazy loads, local dedupe, compact encoding, TTLs, pattern deletion and invalidation messages.
const cache = new CloudflareWorkerCache(env.CACHE, {
prefix: 'users-api:',
l1, // optional: this isolate's short-lived memory
compression: 'auto',
invalidationPublisher: queuePublisher,
})
const user = await cache.getOrSet(key, loadUser)
// After the database write commits:
await cache.invalidateByPattern('tenant:42:user:*')
L1 lasts only while that Worker isolate is reused. Another isolate starts empty, and Cloudflare may evict it at any time.
Cloudflare provides the platform primitives. LazyLayers supplies the cache behavior your app calls.
| Concern | Cloudflare provides | LazyLayers adds |
|---|---|---|
| Shared cache | Workers KV stores and reads keys across locations. | One L2 adapter for Worker bindings and Node.js REST, in the same MessagePack format as Redis. |
| Lazy loading | KV reads and writes. Your application owns the origin. | getOrSet runs your loader on a miss and fills KV and the isolate’s L1 for the next read. |
| Thundering herd | KV has no per-key loader lease. | Callers in one isolate or process share one load. Misses on different isolates can still each load. |
| Invalidation | Queues deliver messages to a consumer, with retries. | invalidate and invalidateByPattern publish to the Queue; the consumer deletes from KV. |
KV is eventually consistent, and Queue retries do not reach every isolate’s L1. For locks and counters shared by every isolate, use the Durable Objects coordination entry. KV pricing ↗
No new infrastructure to start. Every adapter below ships in the package, behind optional peer dependencies.
One API on servers and at the edge.
Start in memory. Add a shared L2 when you need one.
Keep every server’s L1 current.
See hits, misses and loads per layer.
The same six libraries as the benchmarks, feature by feature.
| Feature | Lazy Layers8.0.0 | bentocache1.6.1 | cache-manager7.2.9 | cacheable2.5.0 | cachified5.6.3 | async-cache-dedupe3.4.0 | layered-loader17.0.0 |
|---|---|---|---|---|---|---|---|
| Memory L1 in front of a shared L2 | ✓ | ✓ | ✓ | ✓ | one store | one store | ✓ |
| One load per key per process | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| One load per key across servers | ✓ | — | — | — | — | — | — |
| Waiting servers woken when the load ends | ✓ | — | — | — | — | — | — |
| Peer L1 caches kept in sync over a bus | ✓ | ✓ | — | ✓ | — | — | ✓ |
| Peers warmed with the loaded value | ✓ | — | — | ✓ | — | — | — |
| Stale value when the origin fails | ✓ | ✓ | — | — | — | — | — |
| Stale-while-revalidate | ✓ | ✓ | — | — | ✓ | ✓ | ✓ |
| Invalidate by tag | ✓ | ✓ | — | ✓ | — | partial | groups |
| Invalidate by pattern | ✓ | — | — | — | — | — | — |
| L1 limited by bytes and process memory | ✓ | — | — | — | — | — | — |
| Cloudflare Workers | ✓ | — | — | — | KV adapter | — | — |
| Prometheus metrics | ✓ | ✓ | — | — | — | — | — |
| Rows fully covered | 13 / 13 | 7 / 13 | 2 / 13 | 5 / 13 | 2 / 13 | 2 / 13 | 4 / 13 |
Read from each library’s README at the version benchmarked, on 2026-11-12. A dash means its README does not mention the feature, which is not proof it lacks it. Full table with sources ↗
You need a bounded Map and nothing else
Pick lru-cache, quick-lru
They insert 2–3× faster and hold less per entry, because they skip TTLs, byte budgets and eviction bookkeeping.
You need a storage driver we do not ship
Pick bentocache
It ships SQL, DynamoDB, file and Upstash drivers. Lazy Layers ships Redis, Cloudflare KV, Durable Objects and MongoDB, plus a conformance kit for your own.
One process, and the lowest cost per miss
Pick layered-loader, async-cache-dedupe
A miss costs them a few hundred nanoseconds less. Lazy Layers spends that on bookkeeping that pays off once you run several servers.
Guarantees, trade-offs, and what happens when something fails.
lazy-layers-cache is an open-source L1/L2 cache for Node.js and Cloudflare Workers: an in-process L1 in front of a shared L2 (Redis, Cloudflare KV, Durable Objects or MongoDB), read through with getOrSet. It protects the origin from stampedes inside one process and across processes, and tells other instances about invalidations over an event bus. It is MIT-licensed, written in TypeScript, and has one runtime dependency.
Read through getOrSet(key, loader). Concurrent callers for the same missing key share one loader call in the process, and with Redis L2 a per-key lease lets one instance load the key while the others wait to be woken over the event bus. In BENCHMARKS.md, 10,000 concurrent callers on one cold key with a 20 ms loader ran it once and were all served in 30.8 ms.
Install lazy-layers-cache and ioredis, set REDIS_URL, and create one cache per process with setupCache({ namespace, redis: { required: true } }). That gives each instance its own in-memory L1 in front of a shared Redis L2, with Redis Pub/Sub carrying invalidations. Read with getOrSet and call invalidate(key) after each committed database write.
No. In one process, setupCache({ namespace, redis: false }) runs an in-memory L1 only. For several instances you can use Redis, Cloudflare KV, or the coordination entry point, which keeps locks, counters, rate limits and invalidation in Cloudflare Durable Objects or MongoDB.
invalidate, invalidateByPattern and invalidateTags publish a delete on an event bus, and every peer drops its own L1 copy. Supported buses are Redis Pub/Sub, RabbitMQ, NATS Core, NATS JetStream, Durable Object RPC and MongoDB change streams. A freshly loaded value can also be broadcast, so peers serve it without querying the database.
Yes. lazy-layers-cache/cloudflare is a Worker-safe entry point: getOrSet checks an optional isolate L1, then a KV binding, then your loader, and works with Hono. A Node.js service reads the same KV records through Cloudflare's REST API. KV is eventually consistent and has no atomic lease, so loads are deduplicated only within one Worker cache object or process.
The cache fails open: a Redis error becomes a miss and the loader runs, and circuit breakers stop repeated calls to the failing dependency. When the loader itself fails or times out, fail-safe serves a recent value, for 30 seconds past expiry by default. A request still fails when no eligible stale value exists.
S3-FIFO by default, with LRU, SIEVE and FIFO available; on Zipf traffic the in-memory store hit 78.23% with S3-FIFO against 73.59% for lru-cache. L1 is limited by entries and by bytes (20% of effective memory by default) and gives memory back when the heap or the process nears its limit. A small encoded entry retained 76.1 bytes with LRU and 98.4 with S3-FIFO.
Yes. staleWhileRevalidate returns a recently expired value at once and refreshes the key in the background, and earlyRefresh reloads a popular key before it expires. Values stored with { tags } are invalidated together with invalidateTags, in every layer and on every instance, without scanning keys.
In the read-through benchmark in BENCHMARKS.md, a warm hit cost 180 ns in reference mode against 1,120 ns for bentocache with serialize: false and 9,337 ns for cache-manager. Of the libraries compared, it is the only one whose README describes a cross-process load lease and an L1 limited by bytes. lru-cache and quick-lru insert faster and hold less per entry, and are the better choice when you need only a bounded in-memory map.
Node.js 20 or 22+; use 22+ with NATS, because its current transitive dependency declares that minimum. The package ships ESM, CommonJS and TypeScript declarations. Redis, RabbitMQ, NATS and native compression are optional peer dependencies you install only when you use them.
Wire formats are unchanged, so 0.7 and 8.0 instances can share Redis and an event bus during a rolling deploy. Install the integrations you use, such as ioredis, because they are now optional peer dependencies, and configure dashboard credentials if you relied on the old defaults. MIGRATION.md lists every change.
MIT licensed · one runtime dependency · ESM and CommonJS · Node.js 20+ and Cloudflare Workers. Start in memory, then add Redis or Cloudflare KV when you need a shared L2.