layercache 1.2.0 → 1.2.2

package/README.md

@@ -1,12 +1,12 @@
 # layercache
 
-**Multi-layer caching for Node.js — memory → Redis → your DB, unified in one API.**
+**Production-ready multi-layer caching for Node.js — memory, Redis, persistence, invalidation, and resilience in one API.**
 
 [![npm version](https://img.shields.io/npm/v/layercache)](https://www.npmjs.com/package/layercache)
 [![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-132%20passing-brightgreen)](https://github.com/flyingsquirrel0419/layercache)
+[![test coverage](https://img.shields.io/badge/tests-164%20passing-brightgreen)](https://github.com/flyingsquirrel0419/layercache)
 
 ```
 L1 hit  ~0.01 ms  ← served from memory, zero network
@@ -26,6 +26,8 @@ Most Node.js services end up with the same problem:
 
 layercache solves all three. You declare your layers once and call `get`. Everything else is handled.
 
+It is designed for production services that need predictable cache behavior under load: stampede prevention, cross-instance invalidation, layered TTL control, operational metrics, and safer persistence defaults.
+
 ```ts
 const user = await cache.get('user:123', () => db.findUser(123))
 //                                         ↑ only called on a full miss
@@ -40,15 +42,22 @@ On a hit, the value is returned from the fastest layer that has it, and automati
 - **Layered reads & automatic backfill** — hits in slower layers propagate up
 - **Cache stampede prevention** — mutex-based deduplication per key
 - **Tag-based invalidation** — `set('user:123:posts', posts, { tags: ['user:123'] })` then `invalidateByTag('user:123')`
+- **Batch tag invalidation** — `invalidateByTags(['tenant:a', 'users'], 'all')` for OR/AND invalidation in one call
 - **Pattern invalidation** — `invalidateByPattern('user:*')`
+- **Prefix invalidation** — efficient `invalidateByPrefix('user:123:')` for hierarchical keys
+- **Generation-based invalidation** — `generation` prefixes keys with `vN:` and `bumpGeneration()` rotates the namespace instantly
 - **Per-layer TTL overrides** — different TTLs for memory vs. Redis in one call
+- **TTL policies** — align TTLs to time boundaries (`until-midnight`, `next-hour`, `{ alignTo }`, or a function)
 - **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
+- **Fetcher rate limiting** — cap concurrent fetchers or requests per interval
 - **Best-effort writes** — tolerate partial layer write failures when desired
+- **Write-behind mode** — write local layers immediately and flush slower remote layers asynchronously
 - **Bulk reads** — `mget` uses layer-level `getMany()` when available
+- **Bulk writes** — `mset` uses layer-level `setMany()` 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
@@ -59,17 +68,22 @@ On a hit, the value is returned from the fastest layer that has it, and automati
 - **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 async gzip/brotli in `RedisLayer` (non-blocking) with a byte threshold
+- **Serializer fallback chains** — transparently read legacy payloads (for example JSON) and rewrite them with the primary serializer
 - **Metrics & stats** — per-layer hit/miss counters, **per-layer latency tracking**, circuit-breaker trips, degraded operations; HTTP stats handler
+- **Health checks** — `cache.healthCheck()` returns per-layer health and latency
 - **Persistence** — `exportState` / `importState` for in-process snapshots; `persistToFile` / `restoreFromFile` for disk
-- **Admin CLI** — `layercache stats | keys | invalidate` against any Redis URL
-- **Framework integrations** — Express middleware, Fastify plugin, tRPC middleware, GraphQL resolver wrapper
+- **Admin CLI** — `layercache stats | keys | inspect | invalidate` against any Redis URL
+- **Framework integrations** — Express middleware, Fastify plugin, Hono middleware, tRPC middleware, GraphQL resolver wrapper
+- **OpenTelemetry plugin** — instrument `get` / `set` / invalidation flows with spans
 - **MessagePack serializer** — drop-in replacement for lower Redis memory usage
 - **NestJS module** — `CacheStackModule.forRoot(...)` and `forRootAsync(...)` with `@InjectCacheStack()`
 - **`getOrThrow()`** — throws `CacheMissError` instead of returning `null`, for strict use cases
 - **`inspect()`** — debug a key: see which layers hold it, remaining TTLs, tags, and staleness state
+- **MemoryLayer cleanup hooks** — periodic TTL cleanup and `onEvict` callbacks
 - **Conditional caching** — `shouldCache` predicate to skip caching specific fetcher results
-- **Nested namespaces** — `namespace('a').namespace('b')` for composable key prefixes
+- **Nested namespaces** — `namespace('a').namespace('b')` for composable key prefixes with namespace-scoped metrics
 - **Custom layers** — implement the 5-method `CacheLayer` interface to plug in Memcached, DynamoDB, or anything else
+- **Edge-safe entry point** — `layercache/edge` exports the non-Node helpers for Worker-style runtimes
 - **ESM + CJS** — works with both module systems, Node.js ≥ 18
 
 ---
@@ -168,6 +182,15 @@ await cache.set('user:123:posts', posts, { tags: ['user:123'] })
 await cache.invalidateByTag('user:123') // both keys gone
 ```
 
+### `cache.invalidateByTags(tags, mode?): Promise<void>`
+
+Delete keys that match any or all of a set of tags.
+
+```ts
+await cache.invalidateByTags(['tenant:a', 'users'], 'all') // keys tagged with both
+await cache.invalidateByTags(['users', 'posts'], 'any')    // keys tagged with either
+```
+
 ### `cache.invalidateByPattern(pattern): Promise<void>`
 
 Glob-style deletion against the tracked key set.
@@ -176,6 +199,16 @@ Glob-style deletion against the tracked key set.
 await cache.invalidateByPattern('user:*') // deletes user:1, user:2, …
 ```
 
+### `cache.invalidateByPrefix(prefix): Promise<void>`
+
+Prefer this over glob invalidation when your keys are hierarchical.
+
+```ts
+await cache.invalidateByPrefix('user:123:') // deletes user:123:profile, user:123:posts, ...
+```
+
+The prefix is matched as-is. You do not need to append `*`, and namespace helpers pass their namespace prefix directly.
+
 ### `cache.mget<T>(entries): Promise<Array<T | null>>`
 
 Concurrent multi-key fetch, each with its own optional fetcher.
@@ -195,6 +228,13 @@ const [user1, user2] = await cache.mget([
 const { hits, misses, fetches, staleHits, refreshes, writeFailures } = cache.getMetrics()
 ```
 
+### `cache.healthCheck(): Promise<CacheHealthCheckResult[]>`
+
+```ts
+const health = await cache.healthCheck()
+// [{ layer: 'memory', healthy: true, latencyMs: 0.03 }, ...]
+```
+
 ### `cache.resetMetrics(): void`
 
 Resets all counters to zero — useful for per-interval reporting.
@@ -229,6 +269,21 @@ const getUser = cache.wrap(
 )
 ```
 
+### Generation-based invalidation
+
+Add a generation prefix to every key and rotate it when you want to invalidate the whole cache namespace without scanning:
+
+```ts
+const cache = new CacheStack([...], { generation: 1 })
+
+await cache.set('user:123', user)
+cache.bumpGeneration() // now reads use v2:user:123
+```
+
+### OpenTelemetry note
+
+`createOpenTelemetryPlugin()` currently wraps a `CacheStack` instance's methods directly. Use one OpenTelemetry plugin per cache instance; if you need to compose multiple wrappers, install them in a fixed order and uninstall them in reverse order.
+
 ### `cache.warm(entries, options?)`
 
 Pre-populate layers at startup from a prioritised list. Higher `priority` values run first.
@@ -246,7 +301,7 @@ await cache.warm(
 
 ### `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.
+Returns a scoped view with the same full API (`get`, `set`, `delete`, `clear`, `mget`, `wrap`, `warm`, `invalidateByTag`, `invalidateByPattern`, `getMetrics`). `clear()` only touches `prefix:*` keys, and namespace metrics are serialized per `CacheStack` instance so unrelated caches do not block each other while metrics are collected.
 
 ```ts
 const users = cache.namespace('users')
@@ -305,6 +360,19 @@ const data = await cache.get('api:response', fetchFromApi, {
 // If fetchFromApi returns { status: 500 }, the value is returned but NOT cached
 ```
 
+### TTL policies
+
+Align expirations to calendar or boundary-based schedules:
+
+```ts
+await cache.set('daily-report', report, { ttlPolicy: 'until-midnight' })
+await cache.set('hourly-rollup', rollup, { ttlPolicy: 'next-hour' })
+await cache.set('aligned', value, { ttlPolicy: { alignTo: 300 } }) // next 5-minute boundary
+await cache.set('custom', value, {
+  ttlPolicy: ({ key, value }) => key.startsWith('hot:') ? 30 : 300
+})
+```
+
 ---
 
 ## Negative + stale caching
@@ -386,13 +454,14 @@ const cache = new CacheStack(
   {
     singleFlightCoordinator: coordinator,
     singleFlightLeaseMs: 30_000,
+    singleFlightRenewIntervalMs: 10_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.
+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. `RedisSingleFlightCoordinator` also renews its Redis lease while the worker is still running, so long fetches are less likely to expire their lock mid-flight. Keep `singleFlightLeaseMs` comfortably above your expected fetch latency, and use `singleFlightRenewIntervalMs` if you need tighter control over renewal cadence.
 
 ### Cross-server L1 invalidation
 
@@ -428,7 +497,8 @@ import { RedisTagIndex } from 'layercache'
 
 const sharedTagIndex = new RedisTagIndex({
   client: redis,
-  prefix: 'myapp:tag-index' // namespaced so it doesn't collide with other data
+  prefix: 'myapp:tag-index', // namespaced so it doesn't collide with other data
+  knownKeysShards: 8
 })
 
 // Every CacheStack instance should use the same Redis-backed tag index config
@@ -462,6 +532,38 @@ new RedisLayer({
 })
 ```
 
+For production Redis, also set an explicit `prefix`, enforce Redis authentication/network isolation, and configure Redis `maxmemory` / eviction policy so cache growth cannot starve unrelated workloads.
+
+### DiskLayer safety
+
+`DiskLayer` is best used with an application-controlled directory and an explicit `maxFiles` bound.
+
+```ts
+import { resolve } from 'node:path'
+
+const disk = new DiskLayer({
+  directory: resolve('./var/cache/layercache'),
+  maxFiles: 10_000
+})
+```
+
+The library hashes cache keys before turning them into filenames, validates the configured directory, uses atomic temp-file writes, and removes malformed on-disk entries. You should still keep the directory outside any user-controlled path and set filesystem permissions so only your app can read or write it.
+
+### Scoped fetcher rate limiting
+
+Rate limits are global by default, but you can scope them per cache key or per fetcher function when different backends should not throttle each other.
+
+```ts
+await cache.get('user:123', fetchUser, {
+  fetcherRateLimit: {
+    maxConcurrent: 1,
+    scope: 'key'
+  }
+})
+```
+
+Use `scope: 'fetcher'` to share a bucket across calls using the same fetcher function reference, or `bucketKey: 'billing-api'` for a custom named bucket.
+
 ---
 
 ## Per-layer TTL overrides

package/dist/chunk-46UH7LNM.js

@@ -0,0 +1,312 @@
+import {
+  PatternMatcher,
+  unwrapStoredValue
+} from "./chunk-ZMDB5KOK.js";
+
+// src/layers/MemoryLayer.ts
+var MemoryLayer = class {
+  name;
+  defaultTtl;
+  isLocal = true;
+  maxSize;
+  evictionPolicy;
+  onEvict;
+  entries = /* @__PURE__ */ new Map();
+  cleanupTimer;
+  constructor(options = {}) {
+    this.name = options.name ?? "memory";
+    this.defaultTtl = options.ttl;
+    this.maxSize = options.maxSize ?? 1e3;
+    this.evictionPolicy = options.evictionPolicy ?? "lru";
+    this.onEvict = options.onEvict;
+    if (options.cleanupIntervalMs && options.cleanupIntervalMs > 0) {
+      this.cleanupTimer = setInterval(() => {
+        this.pruneExpired();
+      }, options.cleanupIntervalMs);
+      this.cleanupTimer.unref?.();
+    }
+  }
+  async get(key) {
+    const value = await this.getEntry(key);
+    return unwrapStoredValue(value);
+  }
+  async getEntry(key) {
+    const entry = this.entries.get(key);
+    if (!entry) {
+      return null;
+    }
+    if (this.isExpired(entry)) {
+      this.entries.delete(key);
+      return null;
+    }
+    if (this.evictionPolicy === "lru") {
+      this.entries.delete(key);
+      entry.accessCount += 1;
+      this.entries.set(key, entry);
+    } else if (this.evictionPolicy === "lfu") {
+      entry.accessCount += 1;
+    }
+    return entry.value;
+  }
+  async getMany(keys) {
+    const values = [];
+    for (const key of keys) {
+      values.push(await this.getEntry(key));
+    }
+    return values;
+  }
+  async setMany(entries) {
+    for (const entry of entries) {
+      await this.set(entry.key, entry.value, entry.ttl);
+    }
+  }
+  async set(key, value, ttl = this.defaultTtl) {
+    this.entries.delete(key);
+    this.entries.set(key, {
+      value,
+      expiresAt: ttl && ttl > 0 ? Date.now() + ttl * 1e3 : null,
+      accessCount: 0,
+      insertedAt: Date.now()
+    });
+    while (this.entries.size > this.maxSize) {
+      this.evict();
+    }
+  }
+  async has(key) {
+    const entry = this.entries.get(key);
+    if (!entry) {
+      return false;
+    }
+    if (this.isExpired(entry)) {
+      this.entries.delete(key);
+      return false;
+    }
+    return true;
+  }
+  async ttl(key) {
+    const entry = this.entries.get(key);
+    if (!entry) {
+      return null;
+    }
+    if (this.isExpired(entry)) {
+      this.entries.delete(key);
+      return null;
+    }
+    if (entry.expiresAt === null) {
+      return null;
+    }
+    return Math.max(0, Math.ceil((entry.expiresAt - Date.now()) / 1e3));
+  }
+  async size() {
+    this.pruneExpired();
+    return this.entries.size;
+  }
+  async delete(key) {
+    this.entries.delete(key);
+  }
+  async deleteMany(keys) {
+    for (const key of keys) {
+      this.entries.delete(key);
+    }
+  }
+  async clear() {
+    this.entries.clear();
+  }
+  async ping() {
+    return true;
+  }
+  async dispose() {
+    if (this.cleanupTimer) {
+      clearInterval(this.cleanupTimer);
+      this.cleanupTimer = void 0;
+    }
+  }
+  async keys() {
+    this.pruneExpired();
+    return [...this.entries.keys()];
+  }
+  exportState() {
+    this.pruneExpired();
+    return [...this.entries.entries()].map(([key, entry]) => ({
+      key,
+      value: entry.value,
+      expiresAt: entry.expiresAt
+    }));
+  }
+  importState(entries) {
+    for (const entry of entries) {
+      if (entry.expiresAt !== null && entry.expiresAt <= Date.now()) {
+        continue;
+      }
+      this.entries.set(entry.key, {
+        value: entry.value,
+        expiresAt: entry.expiresAt,
+        accessCount: 0,
+        insertedAt: Date.now()
+      });
+    }
+    while (this.entries.size > this.maxSize) {
+      this.evict();
+    }
+  }
+  evict() {
+    if (this.evictionPolicy === "lru" || this.evictionPolicy === "fifo") {
+      const oldestKey = this.entries.keys().next().value;
+      if (oldestKey !== void 0) {
+        const entry = this.entries.get(oldestKey);
+        this.entries.delete(oldestKey);
+        if (entry) {
+          this.onEvict?.(oldestKey, unwrapStoredValue(entry.value));
+        }
+      }
+      return;
+    }
+    let victimKey;
+    let minCount = Number.POSITIVE_INFINITY;
+    let minInsertedAt = Number.POSITIVE_INFINITY;
+    for (const [key, entry] of this.entries.entries()) {
+      if (entry.accessCount < minCount || entry.accessCount === minCount && entry.insertedAt < minInsertedAt) {
+        minCount = entry.accessCount;
+        minInsertedAt = entry.insertedAt;
+        victimKey = key;
+      }
+    }
+    if (victimKey !== void 0) {
+      const victim = this.entries.get(victimKey);
+      this.entries.delete(victimKey);
+      if (victim) {
+        this.onEvict?.(victimKey, unwrapStoredValue(victim.value));
+      }
+    }
+  }
+  pruneExpired() {
+    for (const [key, entry] of this.entries.entries()) {
+      if (this.isExpired(entry)) {
+        this.entries.delete(key);
+      }
+    }
+  }
+  isExpired(entry) {
+    return entry.expiresAt !== null && entry.expiresAt <= Date.now();
+  }
+};
+
+// src/invalidation/TagIndex.ts
+var TagIndex = class {
+  tagToKeys = /* @__PURE__ */ new Map();
+  keyToTags = /* @__PURE__ */ new Map();
+  knownKeys = /* @__PURE__ */ new Set();
+  maxKnownKeys;
+  constructor(options = {}) {
+    this.maxKnownKeys = options.maxKnownKeys;
+  }
+  async touch(key) {
+    this.knownKeys.add(key);
+    this.pruneKnownKeysIfNeeded();
+  }
+  async track(key, tags) {
+    this.knownKeys.add(key);
+    this.pruneKnownKeysIfNeeded();
+    if (tags.length === 0) {
+      return;
+    }
+    const existingTags = this.keyToTags.get(key);
+    if (existingTags) {
+      for (const tag of existingTags) {
+        this.tagToKeys.get(tag)?.delete(key);
+      }
+    }
+    const tagSet = new Set(tags);
+    this.keyToTags.set(key, tagSet);
+    for (const tag of tagSet) {
+      const keys = this.tagToKeys.get(tag) ?? /* @__PURE__ */ new Set();
+      keys.add(key);
+      this.tagToKeys.set(tag, keys);
+    }
+  }
+  async remove(key) {
+    this.removeKey(key);
+  }
+  async keysForTag(tag) {
+    return [...this.tagToKeys.get(tag) ?? /* @__PURE__ */ new Set()];
+  }
+  async keysForPrefix(prefix) {
+    return [...this.knownKeys].filter((key) => key.startsWith(prefix));
+  }
+  async tagsForKey(key) {
+    return [...this.keyToTags.get(key) ?? /* @__PURE__ */ new Set()];
+  }
+  async matchPattern(pattern) {
+    return [...this.knownKeys].filter((key) => PatternMatcher.matches(pattern, key));
+  }
+  async clear() {
+    this.tagToKeys.clear();
+    this.keyToTags.clear();
+    this.knownKeys.clear();
+  }
+  pruneKnownKeysIfNeeded() {
+    if (this.maxKnownKeys === void 0 || this.knownKeys.size <= this.maxKnownKeys) {
+      return;
+    }
+    const toRemove = Math.ceil(this.maxKnownKeys * 0.1);
+    let removed = 0;
+    for (const key of this.knownKeys) {
+      if (removed >= toRemove) {
+        break;
+      }
+      this.removeKey(key);
+      removed += 1;
+    }
+  }
+  removeKey(key) {
+    this.knownKeys.delete(key);
+    const tags = this.keyToTags.get(key);
+    if (!tags) {
+      return;
+    }
+    for (const tag of tags) {
+      const keys = this.tagToKeys.get(tag);
+      if (!keys) {
+        continue;
+      }
+      keys.delete(key);
+      if (keys.size === 0) {
+        this.tagToKeys.delete(tag);
+      }
+    }
+    this.keyToTags.delete(key);
+  }
+};
+
+// src/integrations/hono.ts
+function createHonoCacheMiddleware(cache, options = {}) {
+  const allowedMethods = new Set((options.methods ?? ["GET"]).map((method) => method.toUpperCase()));
+  return async (context, next) => {
+    const method = (context.req.method ?? "GET").toUpperCase();
+    if (!allowedMethods.has(method)) {
+      await next();
+      return;
+    }
+    const key = options.keyResolver ? options.keyResolver(context.req) : `${method}:${context.req.path ?? context.req.url ?? "/"}`;
+    const cached = await cache.get(key, void 0, options);
+    if (cached !== null) {
+      context.header?.("x-cache", "HIT");
+      context.header?.("content-type", "application/json; charset=utf-8");
+      context.json(cached);
+      return;
+    }
+    const originalJson = context.json.bind(context);
+    context.json = (body, status) => {
+      context.header?.("x-cache", "MISS");
+      void cache.set(key, body, options);
+      return originalJson(body, status);
+    };
+    await next();
+  };
+}
+
+export {
+  MemoryLayer,
+  TagIndex,
+  createHonoCacheMiddleware
+};