layercache 1.2.1 → 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-158%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
@@ -452,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
 
@@ -494,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
@@ -528,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-GF47Y3XR.js → chunk-IXCMHVHP.js}

@@ -7,19 +7,21 @@ var RedisTagIndex = class {
   client;
   prefix;
   scanCount;
+  knownKeysShards;
   constructor(options) {
     this.client = options.client;
     this.prefix = options.prefix ?? "layercache:tag-index";
     this.scanCount = options.scanCount ?? 100;
+    this.knownKeysShards = normalizeKnownKeysShards(options.knownKeysShards);
   }
   async touch(key) {
-    await this.client.sadd(this.knownKeysKey(), key);
+    await this.client.sadd(this.knownKeysKeyFor(key), 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);
+    pipeline.sadd(this.knownKeysKeyFor(key), key);
     for (const tag of existingTags) {
       pipeline.srem(this.tagKeysKey(tag), key);
     }
@@ -36,7 +38,7 @@ var RedisTagIndex = class {
     const keyTagsKey = this.keyTagsKey(key);
     const existingTags = await this.client.smembers(keyTagsKey);
     const pipeline = this.client.pipeline();
-    pipeline.srem(this.knownKeysKey(), key);
+    pipeline.srem(this.knownKeysKeyFor(key), key);
     pipeline.del(keyTagsKey);
     for (const tag of existingTags) {
       pipeline.srem(this.tagKeysKey(tag), key);
@@ -48,12 +50,14 @@ var RedisTagIndex = class {
   }
   async keysForPrefix(prefix) {
     const matches = [];
-    let cursor = "0";
-    do {
-      const [nextCursor, keys] = await this.client.sscan(this.knownKeysKey(), cursor, "COUNT", this.scanCount);
-      cursor = nextCursor;
-      matches.push(...keys.filter((key) => key.startsWith(prefix)));
-    } while (cursor !== "0");
+    for (const knownKeysKey of this.knownKeysKeys()) {
+      let cursor = "0";
+      do {
+        const [nextCursor, keys] = await this.client.sscan(knownKeysKey, cursor, "COUNT", this.scanCount);
+        cursor = nextCursor;
+        matches.push(...keys.filter((key) => key.startsWith(prefix)));
+      } while (cursor !== "0");
+    }
     return matches;
   }
   async tagsForKey(key) {
@@ -61,19 +65,21 @@ var RedisTagIndex = class {
   }
   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");
+    for (const knownKeysKey of this.knownKeysKeys()) {
+      let cursor = "0";
+      do {
+        const [nextCursor, keys] = await this.client.sscan(
+          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() {
@@ -94,8 +100,17 @@ var RedisTagIndex = class {
     } while (cursor !== "0");
     return matches;
   }
-  knownKeysKey() {
-    return `${this.prefix}:keys`;
+  knownKeysKeyFor(key) {
+    if (this.knownKeysShards === 1) {
+      return `${this.prefix}:keys`;
+    }
+    return `${this.prefix}:keys:${simpleHash(key) % this.knownKeysShards}`;
+  }
+  knownKeysKeys() {
+    if (this.knownKeysShards === 1) {
+      return [`${this.prefix}:keys`];
+    }
+    return Array.from({ length: this.knownKeysShards }, (_, index) => `${this.prefix}:keys:${index}`);
   }
   keyTagsKey(key) {
     return `${this.prefix}:key:${encodeURIComponent(key)}`;
@@ -104,6 +119,22 @@ var RedisTagIndex = class {
     return `${this.prefix}:tag:${encodeURIComponent(tag)}`;
   }
 };
+function normalizeKnownKeysShards(value) {
+  if (value === void 0) {
+    return 1;
+  }
+  if (!Number.isInteger(value) || value <= 0) {
+    throw new Error("RedisTagIndex.knownKeysShards must be a positive integer.");
+  }
+  return value;
+}
+function simpleHash(value) {
+  let hash = 0;
+  for (let index = 0; index < value.length; index += 1) {
+    hash = hash * 31 + value.charCodeAt(index) >>> 0;
+  }
+  return hash;
+}
 
 export {
   RedisTagIndex

package/dist/cli.cjs

@@ -118,19 +118,21 @@ var RedisTagIndex = class {
   client;
   prefix;
   scanCount;
+  knownKeysShards;
   constructor(options) {
     this.client = options.client;
     this.prefix = options.prefix ?? "layercache:tag-index";
     this.scanCount = options.scanCount ?? 100;
+    this.knownKeysShards = normalizeKnownKeysShards(options.knownKeysShards);
   }
   async touch(key) {
-    await this.client.sadd(this.knownKeysKey(), key);
+    await this.client.sadd(this.knownKeysKeyFor(key), 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);
+    pipeline.sadd(this.knownKeysKeyFor(key), key);
     for (const tag of existingTags) {
       pipeline.srem(this.tagKeysKey(tag), key);
     }
@@ -147,7 +149,7 @@ var RedisTagIndex = class {
     const keyTagsKey = this.keyTagsKey(key);
     const existingTags = await this.client.smembers(keyTagsKey);
     const pipeline = this.client.pipeline();
-    pipeline.srem(this.knownKeysKey(), key);
+    pipeline.srem(this.knownKeysKeyFor(key), key);
     pipeline.del(keyTagsKey);
     for (const tag of existingTags) {
       pipeline.srem(this.tagKeysKey(tag), key);
@@ -159,12 +161,14 @@ var RedisTagIndex = class {
   }
   async keysForPrefix(prefix) {
     const matches = [];
-    let cursor = "0";
-    do {
-      const [nextCursor, keys] = await this.client.sscan(this.knownKeysKey(), cursor, "COUNT", this.scanCount);
-      cursor = nextCursor;
-      matches.push(...keys.filter((key) => key.startsWith(prefix)));
-    } while (cursor !== "0");
+    for (const knownKeysKey of this.knownKeysKeys()) {
+      let cursor = "0";
+      do {
+        const [nextCursor, keys] = await this.client.sscan(knownKeysKey, cursor, "COUNT", this.scanCount);
+        cursor = nextCursor;
+        matches.push(...keys.filter((key) => key.startsWith(prefix)));
+      } while (cursor !== "0");
+    }
     return matches;
   }
   async tagsForKey(key) {
@@ -172,19 +176,21 @@ var RedisTagIndex = class {
   }
   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");
+    for (const knownKeysKey of this.knownKeysKeys()) {
+      let cursor = "0";
+      do {
+        const [nextCursor, keys] = await this.client.sscan(
+          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() {
@@ -205,8 +211,17 @@ var RedisTagIndex = class {
     } while (cursor !== "0");
     return matches;
   }
-  knownKeysKey() {
-    return `${this.prefix}:keys`;
+  knownKeysKeyFor(key) {
+    if (this.knownKeysShards === 1) {
+      return `${this.prefix}:keys`;
+    }
+    return `${this.prefix}:keys:${simpleHash(key) % this.knownKeysShards}`;
+  }
+  knownKeysKeys() {
+    if (this.knownKeysShards === 1) {
+      return [`${this.prefix}:keys`];
+    }
+    return Array.from({ length: this.knownKeysShards }, (_, index) => `${this.prefix}:keys:${index}`);
   }
   keyTagsKey(key) {
     return `${this.prefix}:key:${encodeURIComponent(key)}`;
@@ -215,6 +230,22 @@ var RedisTagIndex = class {
     return `${this.prefix}:tag:${encodeURIComponent(tag)}`;
   }
 };
+function normalizeKnownKeysShards(value) {
+  if (value === void 0) {
+    return 1;
+  }
+  if (!Number.isInteger(value) || value <= 0) {
+    throw new Error("RedisTagIndex.knownKeysShards must be a positive integer.");
+  }
+  return value;
+}
+function simpleHash(value) {
+  let hash = 0;
+  for (let index = 0; index < value.length; index += 1) {
+    hash = hash * 31 + value.charCodeAt(index) >>> 0;
+  }
+  return hash;
+}
 
 // src/cli.ts
 var CONNECT_TIMEOUT_MS = 5e3;

package/dist/cli.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   RedisTagIndex
-} from "./chunk-GF47Y3XR.js";
+} from "./chunk-IXCMHVHP.js";
 import {
   isStoredValueEnvelope,
   resolveStoredValue

package/dist/{edge-C1sBhTfv.d.cts → edge-DLpdQN0W.d.cts}

@@ -165,6 +165,7 @@ interface CacheSingleFlightExecutionOptions {
     leaseMs: number;
     waitTimeoutMs: number;
     pollIntervalMs: number;
+    renewIntervalMs?: number;
 }
 interface CacheSingleFlightCoordinator {
     execute<T>(key: string, options: CacheSingleFlightExecutionOptions, worker: () => Promise<T>, waiter: () => Promise<T>): Promise<T>;
@@ -198,6 +199,7 @@ interface CacheStackOptions {
     singleFlightLeaseMs?: number;
     singleFlightTimeoutMs?: number;
     singleFlightPollMs?: number;
+    singleFlightRenewIntervalMs?: number;
     /**
      * Maximum number of entries in `accessProfiles` and `circuitBreakers` maps
      * before the oldest entries are pruned. Prevents unbounded memory growth.
@@ -228,6 +230,8 @@ interface CacheRateLimitOptions {
     maxConcurrent?: number;
     intervalMs?: number;
     maxPerInterval?: number;
+    scope?: 'global' | 'key' | 'fetcher';
+    bucketKey?: string;
 }
 interface CacheWriteBehindOptions {
     flushIntervalMs?: number;
@@ -627,6 +631,7 @@ declare class CacheStack extends EventEmitter {
     private validateWriteOptions;
     private validateLayerNumberOption;
     private validatePositiveNumber;
+    private validateRateLimitOptions;
     private validateNonNegativeNumber;
     private validateCacheKey;
     private validateTtlPolicy;

package/dist/{edge-C1sBhTfv.d.ts → edge-DLpdQN0W.d.ts}

@@ -165,6 +165,7 @@ interface CacheSingleFlightExecutionOptions {
     leaseMs: number;
     waitTimeoutMs: number;
     pollIntervalMs: number;
+    renewIntervalMs?: number;
 }
 interface CacheSingleFlightCoordinator {
     execute<T>(key: string, options: CacheSingleFlightExecutionOptions, worker: () => Promise<T>, waiter: () => Promise<T>): Promise<T>;
@@ -198,6 +199,7 @@ interface CacheStackOptions {
     singleFlightLeaseMs?: number;
     singleFlightTimeoutMs?: number;
     singleFlightPollMs?: number;
+    singleFlightRenewIntervalMs?: number;
     /**
      * Maximum number of entries in `accessProfiles` and `circuitBreakers` maps
      * before the oldest entries are pruned. Prevents unbounded memory growth.
@@ -228,6 +230,8 @@ interface CacheRateLimitOptions {
     maxConcurrent?: number;
     intervalMs?: number;
     maxPerInterval?: number;
+    scope?: 'global' | 'key' | 'fetcher';
+    bucketKey?: string;
 }
 interface CacheWriteBehindOptions {
     flushIntervalMs?: number;
@@ -627,6 +631,7 @@ declare class CacheStack extends EventEmitter {
     private validateWriteOptions;
     private validateLayerNumberOption;
     private validatePositiveNumber;
+    private validateRateLimitOptions;
     private validateNonNegativeNumber;
     private validateCacheKey;
     private validateTtlPolicy;

package/dist/edge.d.cts

@@ -1,2 +1,2 @@
-export { e as CacheGetOptions, f as CacheLayer, h as CacheLayerSetManyEntry, t as CacheMetricsSnapshot, w as CacheRateLimitOptions, B as CacheTtlPolicy, D as CacheTtlPolicyContext, J as CacheWriteOptions, K as EvictionPolicy, M as MemoryLayer, N as MemoryLayerOptions, O as MemoryLayerSnapshotEntry, P as PatternMatcher, T as TagIndex, Q as createHonoCacheMiddleware } from './edge-C1sBhTfv.cjs';
+export { e as CacheGetOptions, f as CacheLayer, h as CacheLayerSetManyEntry, t as CacheMetricsSnapshot, w as CacheRateLimitOptions, B as CacheTtlPolicy, D as CacheTtlPolicyContext, J as CacheWriteOptions, K as EvictionPolicy, M as MemoryLayer, N as MemoryLayerOptions, O as MemoryLayerSnapshotEntry, P as PatternMatcher, T as TagIndex, Q as createHonoCacheMiddleware } from './edge-DLpdQN0W.cjs';
 import 'node:events';

package/dist/edge.d.ts

@@ -1,2 +1,2 @@
-export { e as CacheGetOptions, f as CacheLayer, h as CacheLayerSetManyEntry, t as CacheMetricsSnapshot, w as CacheRateLimitOptions, B as CacheTtlPolicy, D as CacheTtlPolicyContext, J as CacheWriteOptions, K as EvictionPolicy, M as MemoryLayer, N as MemoryLayerOptions, O as MemoryLayerSnapshotEntry, P as PatternMatcher, T as TagIndex, Q as createHonoCacheMiddleware } from './edge-C1sBhTfv.js';
+export { e as CacheGetOptions, f as CacheLayer, h as CacheLayerSetManyEntry, t as CacheMetricsSnapshot, w as CacheRateLimitOptions, B as CacheTtlPolicy, D as CacheTtlPolicyContext, J as CacheWriteOptions, K as EvictionPolicy, M as MemoryLayer, N as MemoryLayerOptions, O as MemoryLayerSnapshotEntry, P as PatternMatcher, T as TagIndex, Q as createHonoCacheMiddleware } from './edge-DLpdQN0W.js';
 import 'node:events';