# lazy-layers-cache

> A focused TypeScript hybrid L1/L2 cache for Node.js with lazy loading, stampede protection, fail-open resilience, size-tiered compression, and distributed invalidation over Redis Pub/Sub, RabbitMQ, or NATS.

## What is lazy-layers-cache?

lazy-layers-cache is a Promise-based caching library for Node.js that provides a two-layer cache (L1 in-memory LRU + L2 Redis) with automatic distributed invalidation. It starts as an in-process LRU with no infrastructure and grows into a distributed cache layer as you need one.

Two methods do almost all the work:
- `getOrSet(key, loader)` — read through the layers, load once if nothing has it. Broadcasts result to peers.
- `delete(key)` — invalidate everywhere. Every instance drops the key.

## Key Features

- Lazy loading with getOrSet — one loader call per key across all concurrent callers
- In-flight promise deduplication prevents same-process stampede
- Automatic Redis-backed locking and renewal for cold and expired keys across instances
- Fail-open resilience: L2 and event-bus failures are logged and swallowed, local L1 continues serving
- Stale fallback: last-known-good values returned on loader errors or timeouts
- Negative caching: loader misses briefly cached to avoid hammering databases
- Circuit breakers for L2 and event-bus publish
- Soft and hard timeouts
- Distributed invalidation over Redis Pub/Sub, RabbitMQ, NATS Core, or NATS JetStream
- Size-tiered compression: none (< 256 B), lz4 (256 B–4 KB), zstd (4 KB+)
- 20+ typed cache events for metrics, logs, and tracing
- Live observability dashboard with Prometheus + OpenTelemetry
- TypeScript native, ESM and CommonJS

## Documentation Structure

- **Get Started**: Installation, Quickstart, Learning path, Walkthrough
- **Concepts**: Layers, Lazy loading, Invalidation, Serialization, Resilience
- **Event Buses**: Redis Pub/Sub, RabbitMQ, NATS Core, NATS JetStream
- **Guides**: Stampede protection, Failure handling, Observability
- **Architecture**: Execution paths, Event ordering
- **Reference**: Configuration, API, Stores, Event buses, Cache events, Environment variables
- **Setups**: Single process, Multi-instance, Production

## Quick Start

```bash
npm install lazy-layers-cache
```

```ts
import { LazyLayersCache } from "lazy-layers-cache";

const cache = new LazyLayersCache<string, User>({
  ttlMs: 60_000,
  levels: { L1: { maxEntries: 1_000, ttlMs: 10_000 } },
  inflight: { enabled: true, ttlMs: 5_000 },
});

const user = await cache.getOrSet(`user:${id}`, async () => {
  return db.users.findById(id);
});
```

## Serialization Tiers

| Size | Codec | Wire prefix | Why |
| --- | --- | --- | --- |
| < 256 B | none | HC1M | Compression makes small payloads bigger |
| 256 B – 4 KB | lz4 | HC1L | Smaller and ~5x faster than zstd at these sizes |
| 4 KB+ | zstd | HC1Z | Best ratio at scale; falls back to lz4 on Node 20 |

## Links

- Landing page: https://lazy-layers-cache.vercel.app/
- GitHub: https://github.com/Amon20044/LazyLayers
- npm: https://www.npmjs.com/package/lazy-layers-cache
- Full LLM context: https://lazy-layers-cache.vercel.app/llms-full.txt