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 Start local, add Redis or Cloudflare KV
await cache.getOrSet(key, load);cache.getOrSet(key, loader)
With Redis L2, coordination is built in. No lock configuration required.
How refresh protection worksRequests for the same missing or expired key wait for the shared load across instances.
Redis renews the active lock automatically. Waiters retry released locks if the original loader fails.
At the wait deadline, use eligible stale data or return a clear error. A slow refresh does not trigger an unlocked load by default.
Run the same cache API in Hono on Workers, Hono on Node.js, or another Node.js framework. Cloudflare stores the shared values. LazyLayers adds lazy reads, local dedupe, adaptive MessagePack and gzip, TTLs, pattern deletion, and application 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, using the existing HC1 MessagePack format. |
| Lazy loading | KV exposes reads and writes. Your application owns the origin loader. | getOrSet runs that loader on a miss and fills KV and the optional isolate L1 for the next read. |
| Payload and cost | KV charges for stored bytes and per-key operations; data transfer has no KV egress charge. | Adaptive gzip compresses MessagePack only when it saves at least 15% of packed bytes. Local L1 hits can avoid KV reads; compression does not reduce operation charges. |
| Thundering herd | KV has no atomic per-key loader lease. | In-flight calls share one loader within a Worker cache or Node.js process. Cross-instance misses can still duplicate. |
| Expiry and purge | KV has a 60-second minimum physical expiry and prefix listing. | Logical TTLs, scoped wildcard deletion, and a bounded Worker scan. |
| Invalidation delivery | Queues deliver application messages to a consumer with retries. | invalidate and invalidateByPattern publish key or pattern messages; the consumer repeats KV deletion. |
Gzip is tried for packed values from 1 KiB and kept only when it saves at least 15% of packed bytes; savings depend on your data. KV is eventually consistent. Queue retries do not push into every isolate's L1. Cloudflare Event Subscriptions report builds and namespace lifecycle, not cache key changes. KV pricing ↗
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';
// Multi-tier cache: Sub-0.1ms L1 in-memory LRU + shared Redis L2
const cache = new LazyLayersCache({
ttlMs: 300_000,
levels: {
L1: {
maxEntries: 25_000, // Maximum in-memory capacity with LRU eviction
ttlMs: 60_000, // Hot L1 memory TTL (1 min)
},
L2: {
ttlMs: 300_000, // Redis backing store TTL (5 mins)
},
},
l2: new RedisStore(redis, { prefix: 'app:' }),
});
// Cold or expired key: shared loads and Redis lock renewal are automatic
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, // prevents loopback self-echo
broadcastSet: true, // primes peers with new values
});
// The first server runs the loader, then broadcasts the value.
// Peer instances warm L1 immediately without calling their loaders.
await cache.getOrSet(`user:${id}`, loadUser);
await cache.deleteByPattern('user:*'); // fans out wildcard deletionimport { 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 | undefinedWithout invalidation, another instance can continue serving its stale in-process L1 copy until that entry's TTL expires. With a healthy invalidation bus, the stale window collapses from minutes down to network propagation latency.
del and pattern just say what to forget. set brings the newly loaded value with it, allowing peer instances to warm L1 directly without redundant database trips.
del
Invalidate one key
no value
{
type: "del",
keys: ["user:42"],
source: "node-1",
generation: 7,
ts: 1740086400000
}Every peer drops user:42 from L1, L2, negative, stale and inflight. Only key and generation metadata travel.
pattern
Invalidate wildcard pattern
no value
{
type: "pattern",
pattern: "user:*",
source: "node-1",
generation: 7,
ts: 1740086400000
}Every peer drops each local entry whose key matches the wildcard pattern. No values travel on the wire.
set
Prime peers with the value
carries a value
{
type: "set",
keys: ["user:42"],
value: { id: 42, plan: "pro" },
generation: 8,
ttlMs: 60000
}The newly loaded value is broadcast so peers warm L1 directly from the event without running the loader again.
Per-key generations reject older del and set events, reducing stale resurrection under reordering. Read the consistency model →
Redis payload size using each library's default storage format. BentoCache default measurement includes its CacheEntry metadata envelope ({ value, createdAt, logicalExpiration }) because that is written to Redis; LazyLayers manages metadata separately and stores compact binary values directly.
Node v24.18.0 · Apple Silicon · BentoCache 1.6.1 vs LazyLayers 0.5.0 · byte counts deterministic, throughput median of 15 reps
Most of a JSON document is punctuation and repeated key names. Binary MessagePack stores the entire record in fewer bytes than JSON spends on values alone.
85 of 212 bytes — 40% of that record — is punctuation and key names you already know. The binary encoding fits the whole record into less than JSON spends on values alone.
The ratios are measured. Everything else is yours to set.
Adjust the inputs to model your workload.
Estimate only. Payload bytes exclude Redis key/object overhead, allocator fragmentation, indexes, persistence, and provider-specific pricing.
Inspect L1/L2 entries, TTL countdowns, compression savings, hit ratios, inflight reuse, and real-time invalidation traffic directly from the built-in live dashboard at /__lazylayers.
user:9841 fanned to 3 peers · 284 B · L1 primedsession:x7f9 invalidated cluster-wide · gen: 14catalog:prod:* wiped 42 local L1 keys · wildcard fanoutAt-most-once for ultra-low latency fanout, or durable brokers for persistent message delivery on reconnect.
Ephemeral. Zero extra broker infra if you already use Redis.
Fastest fanout and lowest latency. No replay for disconnected peers.
Persistent messages and dedicated per-instance queue bindings.
Replayable streams, explicit acks, redelivery tracking, max-deliver.
No infrastructure library is right for every workload. If your architecture has these requirements, LazyLayers is the wrong choice.
LazyLayers uses asynchronous bus invalidation and generation counters. It is an eventually consistent caching layer, not a distributed consensus engine like Raft.
Operations on L1 and L2 are individually atomic per key, but there is no multi-key distributed transaction coordinator.
LazyLayers is built to sit in front of databases and APIs. Cache entries can be evicted, expired, or purged at any time.
LazyLayers focuses on in-memory LRU, Redis, and Cloudflare KV. If you need Postgres, SQLite, MongoDB, or DynamoDB as cache stores, libraries like Keyv or BentoCache are better suited.
LazyLayers currently provides key prefixes and wildcard pattern invalidations (e.g. user:*). Complex multi-tag intersections are not supported in pre-1.0.
We deliberately spend some CPU cycles packing MessagePack and compressing tiered payloads to save 33%–92% Redis bytes. If storing 20-byte strings at 5,000,000 ops/sec, raw JSON.stringify will be faster.
“A cache should be allowed to be wrong for a bounded amount of time. If a value must never be stale, don't cache it.”
We let competitors win where they excel. Here is a feature-by-feature comparison across Node.js caching libraries.
| Capability | LazyLayers | BentoCache | Keyv / Cacheable |
|---|---|---|---|
| In-memory L1 (LRU) | ✓ Built-in | ✓ Built-in | ✓ Built-in |
| Shared Redis L2 | ✓ Built-in | ✓ Built-in | ✓ Built-in |
| Read-through getOrSet | ✓ Built-in | ✓ Built-in | ✓ Built-in |
| Per-process inflight dedupe | ✓ Automatic | ✓ Automatic | ✓ Automatic |
| Cross-instance stampede lock | ✓ Built-in Redis lock | ✓ Built-in driver lock | Plugin required |
| Cross-instance invalidation | ✓ Redis, RabbitMQ, NATS | ✓ Redis, Memory bus | Varies by adapter |
| Value broadcast / L1 priming | ✓ First-class (broadcastSet) | Delete-focused | — |
| NATS Core & JetStream | ✓ Built-in native drivers | Custom driver needed | — |
| RabbitMQ durable bus | ✓ Built-in amqplib driver | ✓ Community bus | — |
| Redis payload compression | ✓ MessagePack + LZ4/Zstd tiered | JSON default envelope | JSON / manual plugin |
| Live UI cache inspector | ✓ Built-in (/__lazylayers) | External APM tooling | — |
| Storage driver ecosystem | Focused (Memory, Redis) | Large (Redis, Memcached, Dynamo, Files) | Very large (Postgres, Mongo, SQLite, etc.) |
| Tagging & Namespaces | Prefixes & Wildcard patterns | Comprehensive tag trees | Strong namespaces |
| Maturity | Active (v0.5.x) | Mature (1.x) | Mature (1.x) |
Technical answers about guarantees, trade-offs, and failure boundaries.
Yes. Cold starts and expired keys use the same protection. Concurrent callers share an in-flight load, and Redis L2 automatically coordinates refreshes across instances. If only L1 expires, a live L2 value refills it without calling your loader. No lock configuration is required.
Redis locks renew automatically while the load is active. Other instances wait for the shared result, with a budget derived from the lock TTL and loader timeout. If that wait expires, getOrSet serves eligible stale data or throws DistributedLockTimeoutError instead of starting an unlocked load. Detected lock loss aborts the loader signal. This reduces duplicate work but cannot guarantee exactly-once execution during outages or when a loader ignores cancellation.
Every application instance keeps its own fast in-process L1 LRU cache. When one instance updates or deletes a record, other instances would otherwise continue serving their stale local copy until its TTL expires. An invalidation bus notifies peer instances immediately, reducing the stale window to network propagation latency.
Invalidation is delete-only: peers receive a key deletion event, drop the local entry, and reload it from L2 or database on their next read. Priming goes further: when a getOrSet loader resolves, the loaded value is broadcast so peers can warm their local L1 directly without executing the database loader. Set broadcastSet: false if you prefer delete-only fanout.
LazyLayers uses three distinct checks: (1) Event deduplication by ID with an LRU ring-buffer catches redeliveries on durable brokers; (2) Source filtering ignores self-broadcasts; (3) Per-key generation counters reject incoming events that are older than the local state, preventing stale sets from overwriting newer deletes.
Native JSON.stringify is built in C++ inside the V8 engine and heavily optimized. LazyLayers uses MessagePack and size-tiered LZ4/Zstd compression. We deliberately trade modest CPU time on writes/reads to reduce Redis payload size by 33%–92%. This substantially lowers Redis memory costs, network payload transfer, and replica sync bandwidth.
Under 256 bytes: raw MessagePack (no compression, since headers expand small buffers). Between 256 bytes and 4 KB: LZ4 (fastest compression with low CPU overhead). Above 4 KB: Zstd (where compression ratios produce the largest byte savings per microsecond). On Node 20 runtimes without native Zstd, it automatically falls back to LZ4.
No. Start with an in-process LRU cache. Node.js can add Redis or Cloudflare KV as shared L2; Workers can use a KV binding. Redis L2 supports distributed lock renewal and peer priming when paired with a bus. KV has no cross-instance loader lease; its optional application Queue retries invalidation in KV.
Set observability: true in cache options. LazyLayers exposes a lightweight, zero-dependency dashboard at /__lazylayers (with /observelazyily supported as an alias). It includes real-time L1/L2 memory inspection, compression savings gauges, and Prometheus metrics at /__lazylayers/metrics.
Yes. All fixtures are seeded and deterministic, so byte counts reproduce identically on any machine. Throughput benchmarks use 15-repetition fixed-iteration timing in benchmarks/run.mjs.
MIT licensed · TypeScript first · ESM + CommonJS · Node 20+ and Cloudflare Workers. Start in memory, then add Redis or Cloudflare KV when you need a shared L2.