V8.0.0 · 4–36× FASTER HITS · 2 REDIS TRIPS PER MISS

Cache in layers.
Run it your way.

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

ONE API. EVERY LAYER.getOrSet()
Fast local reads, coordinated across instancesThree Node.js instances each have a local L1 cache. Thin data paths connect directly to shared Redis L2. A separate teal pipe is the event bus, supporting Redis Pub/Sub, RabbitMQ, or NATS. LazyLayers coordinates peers; the origin loader runs when a requested value is missing. INSTANCE 01 INSTANCE 02 INSTANCE 03 L1 HITS EVENT BUS REDIS L2 Load only on a miss ORIGIN
await cache.getOrSet(key, load);
Works with
  • Node.js 20+ runtime
  • Cloudflare Workers · KV · Durable Objects
  • TypeScript types built in
  • Redis L2 store · pub/sub
  • NATS.io core · JetStream
  • RabbitMQ durable bus
  • MongoDB store · change streams
CACHE AT SCALE WORK SAVED
LazyLayersLazyLayers connects local memory, shared storage, and coordinated application instances. LazyLayers LESS WORK. AT EVERY LAYER.
01Cold starts & expiry
Share the refreshConcurrent requests for the same key share an in-flight load. Redis L2 automatically coordinates cold and expired keys across instances and renews active locks. N requestsdedupe + lock1 load
Share the refresh
02Network round trips
Keep hot reads localAn L1 memory hit returns locally, without a Redis round trip. appL1 hitL2 skipped
Keep hot reads local
03Drifting L1 caches
Coordinate every instanceA healthy event bus carries invalidations and optional value priming between peers. Propagation is asynchronous. v2 v2 v2invalidate · prime · fan out
Coordinate every instance
04Repeated missing keys
Remember the missesShort-lived negative entries avoid repeated origin lookups for a missing key. ∅ not foundshort TTLDB spared
Remember the misses
05Oversized payloads
Store less. Send less.MessagePack and size-aware compression reduce payload bytes, with a serialization CPU trade-off. JSONMessagePack + compressionfewer bytes
Store less. Send less.
06Invisible cache behavior
See every layerOptional live metrics expose hits, misses, invalidations, and dependency health. cache eventslive metrics
See every layer
Automatic stampede protection

Cold starts.
Expired keys.
Same simple call.

cache.getOrSet(key, loader)

With Redis L2, one server loads and the rest wait. No lock configuration required.

How refresh protection works
  1. Share the refresh

    Every request for the same missing or expired key, on every server, waits for one load. A miss costs two Redis round trips.

  2. Wake the waiters

    With an event bus, waiting servers get the value 0.8 ms after the load finishes, instead of polling for it.

  3. Keep waiting bounded

    Redis renews the lock while the load runs. At the deadline, serve eligible stale data or return a clear error, never an unlocked load.

Benchmarks · v8.0.0

Measured against the read-through caches you would pick instead.

Six libraries, one harness, a fresh process for every run. We show where we lose, too.

Warm read-through hit, reference mode
180ns
6,490 ns in 0.7
Redis round trips per miss, lock included
2trips
7 in 0.7
Until a waiting server has the value
0.8ms
36 ms in 0.7
Runtime dependency
1dep
8 in 0.7

Read-through warm hit

What does a cached getOrSet cost?

ns per call · lower is better

  1. lazy-layers-cache reference 180
  2. layered-loader 220
  3. async-cache-dedupe 658
  4. @epic-web/cachified 821
  5. bentocache no copy 1,120
  6. lazy-layers-cache encoded 1,504
  7. bentocache default 2,429
  8. cache-manager 9,337
  9. cacheable 9,470

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.

Show as a table
Read-through warm hit, ns per call
LibraryVersionSettingns per callmin – max
lazy-layers-cache8.0.0L1 reference mode180177 – 186
layered-loader17.0.0Loader with in-memory cache220212 – 223
async-cache-dedupe3.4.0memory storage658654 – 668
@epic-web/cachified5.6.3lru-cache store821810 – 862
bentocache1.6.1memory driver, serialize: false1,1201,117 – 1,136
lazy-layers-cache8.0.0L1 encoded mode (default)1,5041,499 – 1,536
bentocache1.6.1memory driver (default)2,4292,398 – 2,495
cache-manager7.2.9wrap, Keyv in-memory store9,3379,287 – 9,438
cacheable2.5.0getOrSet, in-memory primary9,4709,334 – 9,685

Apple M5, 10 logical CPUs · Node 24.21 · 2026-11-12 · fresh process per run, median of 5 · Every number, command and raw file ↗

Quickstart

Your first cache, in a few lines.

Start in memory. Add Redis for Node.js or Cloudflare KV for Workers and Node.js when your service needs shared storage.

cache.ts
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)
);
Many servers

Every server keeps its own memory.
One bus keeps them in step.

Without a bus, other servers keep serving their old copy until it expires. With one, they drop it about a millisecond after you write.

Without a bus, L1 caches driftThe first Node.js instance has a new value, while two disconnected peers retain their old L1 values until expiry. INSTANCE 01fresh · v2 INSTANCE 02stale · v1 INSTANCE 03stale · v1
One shared event bus, coordinated peersThe publishing instance sends an event through a shared tubular event bus. Connected peers apply invalidations or optional value priming. Redis Pub/Sub, RabbitMQ, and NATS are supported transports. INSTANCE 01publish INSTANCE 02apply INSTANCE 03apply EVENT BUS · del / pattern / set
Redis Pub/SubNATS / JetStreamRabbitMQDurable ObjectsMongoDB
  • 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 →

UNDER PRESSURE FALLBACK PATHS
01Redis unavailable
Requests keep movingWhen L2 fails, the circuit breaker skips the unhealthy cache and requests can fall through to the origin loader. Origin availability still matters. APPRedis offlineorigincircuit open → bypass L2
Requests keep moving
02Loader fails or stalls
A fallback, when it mattersWhen fail-safe is enabled and a retained stale value is available, serve that value on loader error or timeout. loader timeoutserve retained stale valueAPP
A fallback, when it matters
03The bus disconnects
Buffer brief interruptionsBounded publish queues retry brief event-bus failures. This does not guarantee delivery during prolonged outages or process restarts. bus disconnectedbounded publish retriesPEER APEER B
Buffer brief interruptions
04Events arrive late or twice
Reject stale & duplicate eventsGeneration checks filter stale invalidations and event IDs deduplicate replayed events. This is not a global ordering guarantee. v3 v2 v2 v3generation + event ID checks
Reject stale & duplicate events
Cloudflare KV + LazyLayers

Global KV storage.
A complete cache read path.

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.

worker.tsHono · Workers
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:*')
optional isolate L1Cloudflare KVorigin loader

L1 lasts only while that Worker isolate is reused. Another isolate starts empty, and Cloudflare may evict it at any time.

What each layer does

Cloudflare provides the platform primitives. LazyLayers supplies the cache behavior your app calls.

ConcernCloudflare providesLazyLayers adds
Shared cacheWorkers 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 loadingKV 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 herdKV has no per-key loader lease.Callers in one isolate or process share one load. Misses on different isolates can still each load.
InvalidationQueues 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 ↗

Works with

Plugs into what you already run.

No new infrastructure to start. Every adapter below ships in the package, behind optional peer dependencies.

Runs on

One API on servers and at the edge.

  • Node.js 20+ESM and CommonJS
  • Cloudflare WorkersWorker-safe entry
  • HonoWorkers or Node.js
  • Expressor any Node.js server
  • Fastifydashboard mounts in
  • TypeScripttypes built in

Stores in

Start in memory. Add a shared L2 when you need one.

  • MemoryS3-FIFO, LRU, SIEVE, FIFO
  • Redisioredis, Upstash, ElastiCache
  • Cloudflare KVbinding or REST
  • Durable Objectskeys, locks, counters
  • MongoDBkeys, locks, counters

Syncs over

Keep every server’s L1 current.

  • Redis Pub/Subat most once
  • NATS · JetStreamcore or durable
  • RabbitMQdurable queues
  • Durable Object RPCno broker
  • Change streamsgaps reconciled

Reports to

See hits, misses and loads per layer.

  • Prometheus/__lazylayers/metrics
  • OpenTelemetrydiagnostics_channel
  • Live dashboardtoken-protected
Compared

What you get that the others leave to you.

The same six libraries as the benchmarks, feature by feature.

Feature Lazy Layers8.0.0bentocache1.6.1cache-manager7.2.9cacheable2.5.0cachified5.6.3async-cache-dedupe3.4.0layered-loader17.0.0
Memory L1 in front of a shared L2✓✓✓✓one storeone 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✓✓—✓—partialgroups
Invalidate by pattern✓——————
L1 limited by bytes and process memory✓——————
Cloudflare Workers✓———KV adapter——
Prometheus metrics✓✓—————
Rows fully covered13 / 137 / 132 / 135 / 132 / 132 / 134 / 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 ↗

When to pick something else

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.


FAQ

The questions engineers
actually ask

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.

Start local.
Scale distributed.

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.