LazyLayers is a TypeScript tiered cache system for Node.js. Keep hot reads in memory with L1, add Redis L2 when instances share data, and coordinate invalidation as your app scales.
npm i lazy-layers-cache
MIT licensed No Redis required to start
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.
Start in memory. Add Redis and an event bus when your service needs them.
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 intentionally on in-memory LRU and Redis. 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. LazyLayers is designed for progressive adoption. You can use it as a standalone, zero-infrastructure in-process LRU cache. You can add Redis when you need a shared L2 store, add Pub/Sub or RabbitMQ/NATS when scaling out across multiple servers, and get automatic distributed locking and renewal whenever Redis L2 is present.
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+. Start as an in-process LRU with zero external dependencies, then add Redis and event buses as your architecture demands.