layercache 1.0.0 → 1.0.2

package/README.md

@@ -6,6 +6,7 @@
 [![npm downloads](https://img.shields.io/npm/dw/layercache)](https://www.npmjs.com/package/layercache)
 [![license](https://img.shields.io/npm/l/layercache)](LICENSE)
 [![TypeScript](https://img.shields.io/badge/TypeScript-first-blue)](https://www.typescriptlang.org/)
+[![test coverage](https://img.shields.io/badge/tests-49%20passing-brightgreen)](https://github.com/flyingsquirrel0419/layercache)
 
 ```
 L1 hit  ~0.01 ms  ← served from memory, zero network
@@ -41,9 +42,27 @@ On a hit, the value is returned from the fastest layer that has it, and automati
 - **Tag-based invalidation** — `set('user:123:posts', posts, { tags: ['user:123'] })` then `invalidateByTag('user:123')`
 - **Pattern invalidation** — `invalidateByPattern('user:*')`
 - **Per-layer TTL overrides** — different TTLs for memory vs. Redis in one call
+- **Negative caching** — cache known misses for a short TTL to protect the database
+- **Stale strategies** — `staleWhileRevalidate` and `staleIfError` as opt-in read behavior
+- **TTL jitter** — spread expirations to avoid synchronized stampedes
+- **Sliding & adaptive TTL** — extend TTL on every read or ramp it up for hot keys
+- **Refresh-ahead** — trigger background refresh when TTL drops below a threshold
+- **Best-effort writes** — tolerate partial layer write failures when desired
+- **Bulk reads** — `mget` uses layer-level `getMany()` when available
 - **Distributed tag index** — `RedisTagIndex` keeps tag state consistent across multiple servers
+- **Optional distributed single-flight** — plug in a coordinator to dedupe misses across instances
 - **Cross-server L1 invalidation** — Redis pub/sub bus flushes stale memory on other instances when you write or delete
-- **Metrics** — hit/miss/fetch/backfill counters built in
+- **`wrap()` decorator API** — turn any async function into a cached version with auto-generated keys
+- **Cache warming** — pre-populate layers with a prioritised list of entries at startup
+- **Namespaces** — scope a `CacheStack` to a key prefix for multi-tenant or module isolation
+- **Event hooks** — `EventEmitter`-based events for hits, misses, stale serves, errors, and more
+- **Graceful degradation** — skip a failing layer for a configurable retry window
+- **Circuit breaker** — per-key or global; opens after N failures, recovers after cooldown
+- **Compression** — transparent gzip/brotli in `RedisLayer` with a byte threshold
+- **Metrics & stats** — per-layer hit/miss counters, circuit-breaker trips, degraded operations; HTTP stats handler
+- **Persistence** — `exportState` / `importState` for in-process snapshots; `persistToFile` / `restoreFromFile` for disk
+- **Admin CLI** — `layercache stats | keys | invalidate` against any Redis URL
+- **Framework integrations** — Fastify plugin, tRPC middleware, GraphQL resolver wrapper
 - **MessagePack serializer** — drop-in replacement for lower Redis memory usage
 - **NestJS module** — `CacheStackModule.forRoot(...)` with `@InjectCacheStack()`
 - **Custom layers** — implement the 5-method `CacheLayer` interface to plug in Memcached, DynamoDB, or anything else
@@ -106,7 +125,12 @@ const user = await cache.get<User>('user:123', () => db.findUser(123))
 // With options
 const user = await cache.get<User>('user:123', () => db.findUser(123), {
   ttl: { memory: 30, redis: 600 }, // per-layer TTL
-  tags: ['user', 'user:123']       // tag this key for bulk invalidation
+  tags: ['user', 'user:123'],      // tag this key for bulk invalidation
+  negativeCache: true,             // cache null fetches
+  negativeTtl: 15,                 // short TTL for misses
+  staleWhileRevalidate: 30,        // serve stale and refresh in background
+  staleIfError: 300,               // serve stale if refresh fails
+  ttlJitter: 5                     // +/- 5s expiry spread
 })
 ```
 
@@ -117,7 +141,10 @@ Writes to all layers simultaneously.
 ```ts
 await cache.set('user:123', user, {
   ttl: { memory: 60, redis: 600 }, // per-layer TTL (seconds)
-  tags: ['user', 'user:123']
+  tags: ['user', 'user:123'],
+  staleWhileRevalidate: { redis: 30 },
+  staleIfError: { redis: 120 },
+  ttlJitter: { redis: 5 }
 })
 
 await cache.set('user:123', user, {
@@ -149,6 +176,8 @@ await cache.invalidateByPattern('user:*') // deletes user:1, user:2, …
 
 Concurrent multi-key fetch, each with its own optional fetcher.
 
+If every entry is a simple read (`{ key }` only), `CacheStack` will use layer-level `getMany()` fast paths when the layer implements one.
+
 ```ts
 const [user1, user2] = await cache.mget([
   { key: 'user:1', fetch: () => db.findUser(1) },
@@ -159,9 +188,109 @@ const [user1, user2] = await cache.mget([
 ### `cache.getMetrics(): CacheMetricsSnapshot`
 
 ```ts
-const { hits, misses, fetches, backfills } = cache.getMetrics()
+const { hits, misses, fetches, staleHits, refreshes, writeFailures } = cache.getMetrics()
+```
+
+### `cache.resetMetrics(): void`
+
+Resets all counters to zero — useful for per-interval reporting.
+
+```ts
+cache.resetMetrics()
+```
+
+### `cache.getStats(): CacheStatsSnapshot`
+
+Returns metrics, per-layer degradation state, and the number of in-flight background refreshes.
+
+```ts
+const { metrics, layers, backgroundRefreshes } = cache.getStats()
+// layers: [{ name, isLocal, degradedUntil }]
+```
+
+### `cache.wrap(prefix, fetcher, options?)`
+
+Wraps an async function so every call is transparently cached. The key is derived from the function arguments unless you supply a `keyResolver`.
+
+```ts
+const getUser = cache.wrap('user', (id: number) => db.findUser(id))
+
+const user = await getUser(123) // key → "user:123"
+
+// Custom key resolver
+const getUser = cache.wrap(
+  'user',
+  (id: number) => db.findUser(id),
+  { keyResolver: (id) => String(id), ttl: 300 }
+)
+```
+
+### `cache.warm(entries, options?)`
+
+Pre-populate layers at startup from a prioritised list. Higher `priority` values run first.
+
+```ts
+await cache.warm(
+  [
+    { key: 'config',     fetcher: () => db.getConfig(),     priority: 10 },
+    { key: 'user:1',     fetcher: () => db.findUser(1),     priority: 5  },
+    { key: 'user:2',     fetcher: () => db.findUser(2),     priority: 5  },
+  ],
+  { concurrency: 4, continueOnError: true }
+)
+```
+
+### `cache.namespace(prefix): CacheNamespace`
+
+Returns a scoped view with the same full API (`get`, `set`, `delete`, `clear`, `mget`, `wrap`, `warm`, `invalidateByTag`, `invalidateByPattern`, `getMetrics`). `clear()` only touches `prefix:*` keys.
+
+```ts
+const users = cache.namespace('users')
+const posts = cache.namespace('posts')
+
+await users.set('123', userData)          // stored as "users:123"
+await users.clear()                       // only deletes "users:*"
+```
+
+---
+
+## Negative + stale caching
+
+`negativeCache` stores fetcher misses for a short TTL, which is useful for "user not found" or "feature flag absent" style lookups.
+
+```ts
+const user = await cache.get(`user:${id}`, () => db.findUser(id), {
+  negativeCache: true,
+  negativeTtl: 15
+})
+```
+
+`staleWhileRevalidate` returns the last cached value immediately after expiry and refreshes it in the background. `staleIfError` keeps serving the stale value if the refresh fails.
+
+```ts
+await cache.set('config', currentConfig, {
+  ttl: 60,
+  staleWhileRevalidate: 30,
+  staleIfError: 300
+})
+```
+
+---
+
+## Write failure policy
+
+Default writes are strict: if any layer write fails, the operation throws.
+
+If you prefer "at least one layer succeeds", enable best-effort mode:
+
+```ts
+const cache = new CacheStack([...], {
+  writePolicy: 'best-effort'
+})
 ```
 
+`best-effort` logs the failed layers, increments `writeFailures`, and only throws if *every* layer failed.
+
 ---
 
 ## Cache stampede prevention
@@ -190,6 +319,28 @@ new CacheStack([...], { stampedePrevention: false })
 
 ## Distributed deployments
 
+### Distributed single-flight
+
+Local stampede prevention only deduplicates requests inside one Node.js process. To dedupe cross-instance misses, configure a shared coordinator.
+
+```ts
+import { RedisSingleFlightCoordinator } from 'layercache'
+
+const coordinator = new RedisSingleFlightCoordinator({ client: redis })
+
+const cache = new CacheStack(
+  [new MemoryLayer({ ttl: 60 }), new RedisLayer({ client: redis, ttl: 300 })],
+  {
+    singleFlightCoordinator: coordinator,
+    singleFlightLeaseMs: 30_000,
+    singleFlightTimeoutMs: 5_000,
+    singleFlightPollMs: 50
+  }
+)
+```
+
+When another instance already owns the miss, the current process waits for the value to appear in the shared layer instead of running the fetcher again.
+
 ### Cross-server L1 invalidation
 
 When one server writes or deletes a key, other servers' memory layers go stale. The `RedisInvalidationBus` propagates invalidation events over Redis pub/sub so every instance stays consistent.
@@ -287,6 +438,200 @@ await cache.set('key', value, { ttl: { local: 15, shared: 600 } })
 
 ---
 
+## Sliding & adaptive TTL
+
+**Sliding TTL** resets the TTL on every read so frequently-accessed keys never expire.
+
+```ts
+const value = await cache.get('session:abc', fetchSession, { slidingTtl: true })
+```
+
+**Adaptive TTL** automatically increases the TTL of hot keys up to a ceiling.
+
+```ts
+await cache.get('popular-post', fetchPost, {
+  adaptiveTtl: {
+    hotAfter: 5,      // ramp up after 5 hits
+    step: 60,         // add 60s per hit
+    maxTtl: 3600      // cap at 1h
+  }
+})
+```
+
+**Refresh-ahead** triggers a background refresh when the remaining TTL drops below a threshold, so callers never see a miss.
+
+```ts
+await cache.get('leaderboard', fetchLeaderboard, {
+  ttl: 120,
+  refreshAhead: 30  // start refreshing when ≤30s remain
+})
+```
+
+---
+
+## Graceful degradation & circuit breaker
+
+**Graceful degradation** marks a layer as degraded on failure and skips it for a retry window, keeping the cache available even if Redis is briefly unreachable.
+
+```ts
+new CacheStack([...], {
+  gracefulDegradation: { retryAfterMs: 10_000 }
+})
+```
+
+**Circuit breaker** opens after repeated fetcher failures for a key, returning `null` instead of hammering a broken downstream.
+
+```ts
+new CacheStack([...], {
+  circuitBreaker: {
+    failureThreshold: 5,  // open after 5 consecutive failures
+    cooldownMs: 30_000    // retry after 30s
+  }
+})
+
+// Or per-operation
+await cache.get('fragile-key', fetch, {
+  circuitBreaker: { failureThreshold: 3, cooldownMs: 10_000 }
+})
+```
+
+---
+
+## Compression
+
+`RedisLayer` can transparently compress values before writing. Values smaller than `compressionThreshold` are stored as-is.
+
+```ts
+new RedisLayer({
+  client: redis,
+  ttl: 300,
+  compression: 'gzip',           // or 'brotli'
+  compressionThreshold: 1_024    // bytes — skip compression for small values
+})
+```
+
+---
+
+## Stats & HTTP endpoint
+
+`cache.getStats()` returns a full snapshot suitable for dashboards or health checks.
+
+```ts
+const stats = cache.getStats()
+// {
+//   metrics: { hits, misses, fetches, circuitBreakerTrips, ... },
+//   layers:  [{ name, isLocal, degradedUntil }],
+//   backgroundRefreshes: 2
+// }
+```
+
+Mount a JSON endpoint with the built-in HTTP handler (works with Express, Fastify, Next.js):
+
+```ts
+import { createCacheStatsHandler } from 'layercache'
+import http from 'node:http'
+
+const statsHandler = createCacheStatsHandler(cache)
+http.createServer(statsHandler).listen(9090)
+// GET / → JSON stats
+```
+
+Or use the Fastify plugin:
+
+```ts
+import { createFastifyLayercachePlugin } from 'layercache/integrations/fastify'
+
+await fastify.register(createFastifyLayercachePlugin(cache, {
+  statsPath: '/cache/stats'   // default; set exposeStatsRoute: false to disable
+}))
+// fastify.cache is now available in all handlers
+```
+
+---
+
+## Persistence & snapshots
+
+Transfer cache state between `CacheStack` instances or survive a restart.
+
+```ts
+// In-memory snapshot
+const snapshot = await cache.exportState()
+await anotherCache.importState(snapshot)
+
+// Disk snapshot
+await cache.persistToFile('./cache-snapshot.json')
+await cache.restoreFromFile('./cache-snapshot.json')
+```
+
+---
+
+## Event hooks
+
+`CacheStack` extends `EventEmitter`. Subscribe to events for monitoring or custom side-effects.
+
+| Event | Payload |
+|-------|---------|
+| `hit` | `{ key, layer }` |
+| `miss` | `{ key }` |
+| `set` | `{ key }` |
+| `delete` | `{ key }` |
+| `stale-serve` | `{ key, state, layer }` |
+| `stampede-dedupe` | `{ key }` |
+| `backfill` | `{ key, fromLayer, toLayer }` |
+| `warm` | `{ key }` |
+| `error` | `{ event, context }` |
+
+```ts
+cache.on('hit',   ({ key, layer }) => metrics.inc('cache.hit',  { layer }))
+cache.on('miss',  ({ key })        => metrics.inc('cache.miss'))
+cache.on('error', ({ event, context }) => logger.error(event, context))
+```
+
+---
+
+## Framework integrations
+
+### tRPC
+
+```ts
+import { createTrpcCacheMiddleware } from 'layercache/integrations/trpc'
+
+const cacheMiddleware = createTrpcCacheMiddleware(cache, 'trpc', { ttl: 60 })
+
+export const cachedProcedure = t.procedure.use(cacheMiddleware)
+```
+
+### GraphQL
+
+```ts
+import { cacheGraphqlResolver } from 'layercache/integrations/graphql'
+
+const resolvers = {
+  Query: {
+    user: cacheGraphqlResolver(cache, 'user', (_root, { id }) => db.findUser(id), {
+      keyResolver: (_root, { id }) => id,
+      ttl: 300
+    })
+  }
+}
+```
+
+---
+
+## Admin CLI
+
+Inspect and manage a Redis-backed cache without writing code.
+
+```bash
+# Requires ioredis
+npx layercache stats     --redis redis://localhost:6379
+npx layercache keys      --redis redis://localhost:6379 --pattern "user:*"
+npx layercache invalidate --redis redis://localhost:6379 --tag user:123
+npx layercache invalidate --redis redis://localhost:6379 --pattern "session:*"
+```
+
+---
+
 ## MessagePack serialization
 
 Reduces Redis memory usage and speeds up serialization for large values:
@@ -316,6 +661,8 @@ class MemcachedLayer implements CacheLayer {
   readonly isLocal = false
 
   async get<T>(key: string): Promise<T | null> { /* … */ }
+  async getEntry?(key: string): Promise<unknown | null> { /* optional raw access */ }
+  async getMany?(keys: string[]): Promise<Array<unknown | null>> { /* optional bulk read */ }
   async set(key: string, value: unknown, ttl?: number): Promise<void> { /* … */ }
   async delete(key: string): Promise<void> { /* … */ }
   async clear(): Promise<void> { /* … */ }
@@ -433,24 +780,35 @@ Example output from a local run:
 
 ## Comparison
 
-| | node-cache | ioredis | cache-manager | **layercache** |
+| | node-cache-manager | keyv | cacheable | **layercache** |
 |---|:---:|:---:|:---:|:---:|
-| Multi-layer | ❌ | ❌ | △ | ✅ |
+| Multi-layer | △ | Plugin | ❌ | ✅ |
 | Auto backfill | ❌ | ❌ | ❌ | ✅ |
 | Stampede prevention | ❌ | ❌ | ❌ | ✅ |
-| Tag invalidation | ❌ | ❌ | ❌ | ✅ |
+| Tag invalidation | ❌ | ❌ | ✅ | ✅ |
 | Distributed tags | ❌ | ❌ | ❌ | ✅ |
 | Cross-server L1 flush | ❌ | ❌ | ❌ | ✅ |
-| TypeScript-first | ❌ | ✅ | △ | ✅ |
-| NestJS module | ❌ | ❌ | ✅ | ✅ |
-| Custom layers | ❌ | — | △ | ✅ |
+| TypeScript-first | △ | ✅ | ✅ | ✅ |
+| Wrap / decorator API | ✅ | ❌ | ❌ | ✅ |
+| Cache warming | ❌ | ❌ | ❌ | ✅ |
+| Namespaces | ❌ | ✅ | ✅ | ✅ |
+| Sliding / adaptive TTL | ❌ | ❌ | ❌ | ✅ |
+| Event hooks | ✅ | ✅ | ✅ | ✅ |
+| Circuit breaker | ❌ | ❌ | ❌ | ✅ |
+| Graceful degradation | ❌ | ❌ | ❌ | ✅ |
+| Compression | ❌ | ❌ | ✅ | ✅ |
+| Persistence / snapshots | ❌ | ❌ | ❌ | ✅ |
+| Admin CLI | ❌ | ❌ | ❌ | ✅ |
+| Pluggable logger | ❌ | ❌ | ✅ | ✅ |
+| NestJS module | ❌ | ❌ | ❌ | ✅ |
+| Custom layers | △ | ❌ | ❌ | ✅ |
 
 ---
 
 ## Debug logging
 
 ```bash
-DEBUG=cachestack:debug node server.js
+DEBUG=layercache:debug node server.js
 ```
 
 Or pass a logger instance:
@@ -476,8 +834,8 @@ new CacheStack([...], {
 ## Contributing
 
 ```bash
-git clone https://github.com/flyingsquirrel0419/cachestack
-cd cachestack
+git clone https://github.com/flyingsquirrel0419/layercache
+cd layercache
 npm install
 npm test          # vitest
 npm run build:all # esm + cjs + nestjs package

package/dist/chunk-IILH5XTS.js

@@ -0,0 +1,103 @@
+// src/invalidation/PatternMatcher.ts
+var PatternMatcher = class {
+  static matches(pattern, value) {
+    const escaped = pattern.replace(/[.+^${}()|[\]\\]/g, "\\$&");
+    const regex = new RegExp(`^${escaped.replace(/\*/g, ".*").replace(/\?/g, ".")}$`);
+    return regex.test(value);
+  }
+};
+
+// src/invalidation/RedisTagIndex.ts
+var RedisTagIndex = class {
+  client;
+  prefix;
+  scanCount;
+  constructor(options) {
+    this.client = options.client;
+    this.prefix = options.prefix ?? "layercache:tag-index";
+    this.scanCount = options.scanCount ?? 100;
+  }
+  async touch(key) {
+    await this.client.sadd(this.knownKeysKey(), key);
+  }
+  async track(key, tags) {
+    const keyTagsKey = this.keyTagsKey(key);
+    const existingTags = await this.client.smembers(keyTagsKey);
+    const pipeline = this.client.pipeline();
+    pipeline.sadd(this.knownKeysKey(), key);
+    for (const tag of existingTags) {
+      pipeline.srem(this.tagKeysKey(tag), key);
+    }
+    pipeline.del(keyTagsKey);
+    if (tags.length > 0) {
+      pipeline.sadd(keyTagsKey, ...tags);
+      for (const tag of new Set(tags)) {
+        pipeline.sadd(this.tagKeysKey(tag), key);
+      }
+    }
+    await pipeline.exec();
+  }
+  async remove(key) {
+    const keyTagsKey = this.keyTagsKey(key);
+    const existingTags = await this.client.smembers(keyTagsKey);
+    const pipeline = this.client.pipeline();
+    pipeline.srem(this.knownKeysKey(), key);
+    pipeline.del(keyTagsKey);
+    for (const tag of existingTags) {
+      pipeline.srem(this.tagKeysKey(tag), key);
+    }
+    await pipeline.exec();
+  }
+  async keysForTag(tag) {
+    return this.client.smembers(this.tagKeysKey(tag));
+  }
+  async matchPattern(pattern) {
+    const matches = [];
+    let cursor = "0";
+    do {
+      const [nextCursor, keys] = await this.client.sscan(
+        this.knownKeysKey(),
+        cursor,
+        "MATCH",
+        pattern,
+        "COUNT",
+        this.scanCount
+      );
+      cursor = nextCursor;
+      matches.push(...keys.filter((key) => PatternMatcher.matches(pattern, key)));
+    } while (cursor !== "0");
+    return matches;
+  }
+  async clear() {
+    const indexKeys = await this.scanIndexKeys();
+    if (indexKeys.length === 0) {
+      return;
+    }
+    await this.client.del(...indexKeys);
+  }
+  async scanIndexKeys() {
+    const matches = [];
+    let cursor = "0";
+    const pattern = `${this.prefix}:*`;
+    do {
+      const [nextCursor, keys] = await this.client.scan(cursor, "MATCH", pattern, "COUNT", this.scanCount);
+      cursor = nextCursor;
+      matches.push(...keys);
+    } while (cursor !== "0");
+    return matches;
+  }
+  knownKeysKey() {
+    return `${this.prefix}:keys`;
+  }
+  keyTagsKey(key) {
+    return `${this.prefix}:key:${encodeURIComponent(key)}`;
+  }
+  tagKeysKey(tag) {
+    return `${this.prefix}:tag:${encodeURIComponent(tag)}`;
+  }
+};
+
+export {
+  PatternMatcher,
+  RedisTagIndex
+};