layercache 1.3.2 → 1.3.3

package/README.md

@@ -1,3 +1,7 @@
+<p align="center">
+  <strong>English</strong> | <a href="./docs/i18n/README.ko.md">한국어</a> | <a href="./docs/i18n/README.zh-CN.md">简体中文</a> | <a href="./docs/i18n/README.ja.md">日本語</a> | <a href="./docs/i18n/README.es.md">Español</a>
+</p>
+
 <p align="center">
   <img src="./logo.png" width="520" alt="layercache logo">
 </p>
@@ -5,8 +9,8 @@
 <h1 align="center">layercache</h1>
 
 <p align="center">
-  <strong>The multi-layer caching toolkit that Node.js deserves.</strong><br>
-  <em>Stack memory + Redis + disk. One API. Zero stampedes.</em>
+  <strong>100 concurrent requests. 1 DB call. Always.</strong><br>
+  <em>Multi-layer cache (Memory → Redis → Disk) with stampede prevention built in.</em>
 </p>
 
 <p align="center">
@@ -22,7 +26,7 @@
 <p align="center">
   <a href="https://layercache.flyingsquirrel.me">Website</a>&nbsp;&nbsp;|&nbsp;&nbsp;
   <a href="#-quick-start">Quick Start</a>&nbsp;&nbsp;|&nbsp;&nbsp;
-  <a href="#-features">Features</a>&nbsp;&nbsp;|&nbsp;&nbsp;
+  <a href="#-performance">Performance</a>&nbsp;&nbsp;|&nbsp;&nbsp;
   <a href="./docs/api.md">API Reference</a>&nbsp;&nbsp;|&nbsp;&nbsp;
   <a href="#-integrations">Integrations</a>&nbsp;&nbsp;|&nbsp;&nbsp;
   <a href="#-comparison">Comparison</a>&nbsp;&nbsp;|&nbsp;&nbsp;
@@ -32,37 +36,20 @@
 
 ---
 
-## The Problem
-
-Every growing Node.js service hits the same caching wall:
+## Why layercache?
 
+```ts
+// 100 concurrent requests hit an empty cache at the same time.
+// Without stampede prevention, your DB gets 100 calls.
+const results = await Promise.all(
+  Array.from({ length: 100 }, () =>
+    cache.get('user:1', () => db.findUser(1))
+  )
+)
+// fetcherExecutions: 1  ← your DB was called exactly once
 ```
-Memory-only cache    --> Fast, but each instance has a different view of data
-Redis-only cache     --> Shared, but every request pays a network round-trip
-Hand-rolled hybrid   --> Works... until you need stampede prevention, invalidation,
-                         stale serving, observability, and distributed consistency
-```
-
-## The Solution
 
-**layercache** gives you a unified multi-layer cache with production-grade features built in:
-
-```
-              ┌───────────────────────────────────────┐
-your app ---->│             layercache                │
-              │                                       │
-              │  L1 Memory    ~0.01ms  (per-process)  │
-              │      |                                │
-              │  L2 Redis     ~0.5ms   (shared)       │
-              │      |                                │
-              │  L3 Disk      ~2ms     (persistent)   │
-              │      |                                │
-              │  Fetcher      ~20ms    (runs once)    │
-              └───────────────────────────────────────┘
-
-On a hit  --> serves the fastest layer, backfills the rest
-On a miss --> fetcher runs ONCE (even under 100x concurrency)
-```
+layercache is a multi-layer cache (Memory → Redis → Disk) for Node.js. Stampede prevention, tag invalidation, and distributed consistency are built in — no extra config required.
 
 ---
 
@@ -113,8 +100,144 @@ const cache = new CacheStack([
 
 ---
 
+## Performance
+
+```
+Environment: Node.js v20.20.1, Redis 7-alpine, Linux x86_64
+CPU: AMD EPYC 4584PX 16-Core  |  RAM: 1.9 GB
+Layers: MemoryLayer(ttl=60, maxSize=2000) + RedisLayer(ttl=300)
+```
+
+```
+┌──────────────────────────────┬──────────┬──────────┬──────────┬──────────┐
+│ Scenario                     │  avg ms  │  p95 ms  │  min ms  │  max ms  │
+├──────────────────────────────┼──────────┼──────────┼──────────┼──────────┤
+│ L1 memory hit (warm)         │   0.011  │   0.016  │   0.004  │   0.405  │
+│ L1 hit in layered setup      │   0.006  │   0.007  │   0.004  │   0.077  │
+│ No cache / origin fetch      │   6.844  │  11.196  │   4.683  │  11.196  │
+└──────────────────────────────┴──────────┴──────────┴──────────┴──────────┘
+
+┌──────────────────────────────┬────────────────────┐
+│                              │  75 concurrent req │
+├──────────────────────────────┼────────────────────┤
+│ Without layercache           │  75 origin calls   │
+│ With layercache              │   1 origin call    │  ← stampede prevention
+└──────────────────────────────┴────────────────────┘
+```
+
+Benchmark commands and full scenario notes: [docs/benchmarking.md](./docs/benchmarking.md)
+
+---
+
+## Migrating from node-cache-manager?
+
+<table>
+<tr>
+<th>Before</th>
+<th>After</th>
+</tr>
+<tr>
+<td>
+
+```ts
+import { caching, multiCaching }
+  from 'cache-manager'
+import { redisStore }
+  from 'cache-manager-redis-yet'
+
+const mem = await caching('memory', {
+  max: 100,
+  ttl: 60 * 1000        // ms
+})
+const red = await caching(redisStore, {
+  url: 'redis://localhost:6379',
+  ttl: 300 * 1000       // ms
+})
+const cache = multiCaching([mem, red])
+
+// stampede prevention:  ❌
+// auto backfill:        ❌
+// tag invalidation:     ❌
+```
+
+</td>
+<td>
+
+```ts
+import {
+  CacheStack,
+  MemoryLayer,
+  RedisLayer
+} from 'layercache'
+import Redis from 'ioredis'
+
+const cache = new CacheStack([
+  new MemoryLayer({ ttl: 60 }),    // s
+  new RedisLayer({
+    client: new Redis(),
+    ttl: 300                       // s
+  })
+])
+
+// stampede prevention:  ✅
+// auto backfill:        ✅
+// tag invalidation:     ✅
+```
+
+</td>
+</tr>
+</table>
+
+> Full migration guides for [keyv and cacheable](./docs/migration-guide.md).
+
+---
+
+## Comparison
+
+|  | node-cache-manager | keyv | cacheable | **layercache** |
+|---|:---:|:---:|:---:|:---:|
+| Multi-layer + auto backfill | Partial | Plugin | -- | **Yes** |
+| Stampede prevention | -- | -- | -- | **Yes** |
+| Tag invalidation | -- | Yes | Yes | **Yes** |
+| TypeScript-first | Partial | Yes | Yes | **Yes** |
+| Event hooks | Yes | Yes | Yes | **Yes** |
+
+<details>
+<summary>Full comparison (19 features)</summary>
+
+|  | node-cache-manager | keyv | cacheable | **layercache** |
+|---|:---:|:---:|:---:|:---:|
+| Multi-layer with auto backfill | Partial | Plugin | -- | **Yes** |
+| Stampede prevention | -- | -- | -- | **Yes** |
+| Distributed single-flight | -- | -- | -- | **Yes** |
+| Tag invalidation | -- | Yes | Yes | **Yes** |
+| Distributed tags | -- | -- | -- | **Yes** |
+| Cross-server L1 flush | -- | -- | -- | **Yes** |
+| Stale-while-revalidate | -- | -- | -- | **Yes** |
+| Circuit breaker | -- | -- | -- | **Yes** |
+| Graceful degradation | -- | -- | -- | **Yes** |
+| Sliding / adaptive TTL | -- | -- | -- | **Yes** |
+| Cache warming | -- | -- | -- | **Yes** |
+| Persistence / snapshots | -- | -- | -- | **Yes** |
+| Compression | -- | -- | Yes | **Yes** |
+| Admin CLI | -- | -- | -- | **Yes** |
+| TypeScript-first | Partial | Yes | Yes | **Yes** |
+| Wrap / decorator API | Yes | -- | -- | **Yes** |
+| Namespaces | -- | Yes | Yes | **Yes** |
+| Event hooks | Yes | Yes | Yes | **Yes** |
+| Custom layers | Partial | -- | -- | **Yes** |
+
+</details>
+
+> See the full [comparison guide](./docs/comparison.md) for detailed breakdowns.
+
+---
+
 ## Features
 
+<details>
+<summary><b>Core Caching, Invalidation, Resilience & Observability (click to expand)</b></summary>
+
 ### Core Caching
 
 | Feature | What it does |
@@ -169,6 +292,8 @@ const cache = new CacheStack([
 | **HTTP stats handler** | JSON endpoint for dashboards |
 | **Admin CLI** | `npx layercache stats\|keys\|invalidate` for Redis-backed caches |
 
+</details>
+
 ---
 
 ## Integrations
@@ -272,55 +397,6 @@ const cache = new CacheStack(
 
 ---
 
-## Performance
-
-```
-┌─────────────────────┬──────────────┐
-│ Scenario            │ Avg Latency  │
-├─────────────────────┼──────────────┤
-│ L1 memory hit       │   ~0.006 ms  │
-│ L2 Redis hit        │   ~0.020 ms  │
-│ No cache (sim. DB)  │   ~1.08  ms  │
-└─────────────────────┴──────────────┘
-
-┌─────────────────────┬────────┐
-│ concurrentRequests  │  100   │
-│ fetcherExecutions   │    1   │  <-- stampede prevention
-└─────────────────────┴────────┘
-```
-
-Benchmark commands, fixtures, and scenario notes live in [docs/benchmarking.md](./docs/benchmarking.md).
-
----
-
-## Comparison
-
-|  | node-cache-manager | keyv | cacheable | **layercache** |
-|---|:---:|:---:|:---:|:---:|
-| Multi-layer with auto backfill | Partial | Plugin | -- | **Yes** |
-| Stampede prevention | -- | -- | -- | **Yes** |
-| Distributed single-flight | -- | -- | -- | **Yes** |
-| Tag invalidation | -- | -- | Yes | **Yes** |
-| Distributed tags | -- | -- | -- | **Yes** |
-| Cross-server L1 flush | -- | -- | -- | **Yes** |
-| Stale-while-revalidate | -- | -- | -- | **Yes** |
-| Circuit breaker | -- | -- | -- | **Yes** |
-| Graceful degradation | -- | -- | -- | **Yes** |
-| Sliding / adaptive TTL | -- | -- | -- | **Yes** |
-| Cache warming | -- | -- | -- | **Yes** |
-| Persistence / snapshots | -- | -- | -- | **Yes** |
-| Compression | -- | -- | Yes | **Yes** |
-| Admin CLI | -- | -- | -- | **Yes** |
-| TypeScript-first | Partial | Yes | Yes | **Yes** |
-| Wrap / decorator API | Yes | -- | -- | **Yes** |
-| Namespaces | -- | Yes | Yes | **Yes** |
-| Event hooks | Yes | Yes | Yes | **Yes** |
-| Custom layers | Partial | -- | -- | **Yes** |
-
-> See the full [comparison guide](./docs/comparison.md) for detailed breakdowns.
-
----
-
 ## Documentation
 
 | Document | Description |

package/dist/{chunk-GJBKCFE6.js → chunk-5RCAX2BQ.js}

@@ -195,7 +195,7 @@ var MAX_PATTERN_RECURSION_DEPTH = 500;
 var TagIndex = class {
   tagToKeys = /* @__PURE__ */ new Map();
   keyToTags = /* @__PURE__ */ new Map();
-  knownKeys = /* @__PURE__ */ new Set();
+  knownKeys = /* @__PURE__ */ new Map();
   maxKnownKeys;
   nextNodeId = 1;
   root = this.createTrieNode();
@@ -283,10 +283,11 @@ var TagIndex = class {
     };
   }
   insertKnownKey(key) {
-    if (this.knownKeys.has(key)) {
+    const isNew = !this.knownKeys.has(key);
+    this.knownKeys.set(key, Date.now());
+    if (!isNew) {
       return;
     }
-    this.knownKeys.add(key);
     let node = this.root;
     for (const character of key) {
       let child = node.children.get(character);
@@ -381,14 +382,13 @@ var TagIndex = class {
     if (this.maxKnownKeys === void 0 || this.knownKeys.size <= this.maxKnownKeys) {
       return;
     }
+    const sorted = [...this.knownKeys.entries()].sort((a, b) => a[1] - b[1]);
     const toRemove = Math.ceil(this.maxKnownKeys * 0.1);
-    let removed = 0;
-    for (const key of this.knownKeys) {
-      if (removed >= toRemove) {
-        break;
+    for (let i = 0; i < toRemove && i < sorted.length; i += 1) {
+      const entry = sorted[i];
+      if (entry) {
+        this.removeKey(entry[0]);
       }
-      this.removeKey(key);
-      removed += 1;
     }
   }
   removeKey(key) {

package/dist/{chunk-BQLL6IM5.js → chunk-BORDQ3LA.js}

@@ -2,6 +2,130 @@ import {
   PatternMatcher
 } from "./chunk-4PPBOOXT.js";
 
+// src/internal/CacheStackValidation.ts
+var MAX_CACHE_KEY_LENGTH = 1024;
+var MAX_PATTERN_LENGTH = 1024;
+var MAX_TAGS_PER_OPERATION = 128;
+function validatePositiveNumber(name, value) {
+  if (value === void 0) {
+    return;
+  }
+  if (!Number.isFinite(value) || value <= 0) {
+    throw new Error(`${name} must be a positive finite number.`);
+  }
+}
+function validateNonNegativeNumber(name, value) {
+  if (!Number.isFinite(value) || value < 0) {
+    throw new Error(`${name} must be a non-negative finite number.`);
+  }
+}
+function validateLayerNumberOption(name, value) {
+  if (value === void 0) {
+    return;
+  }
+  if (typeof value === "number") {
+    validateNonNegativeNumber(name, value);
+    return;
+  }
+  for (const [layerName, layerValue] of Object.entries(value)) {
+    if (layerValue === void 0) {
+      continue;
+    }
+    validateNonNegativeNumber(`${name}.${layerName}`, layerValue);
+  }
+}
+function validateRateLimitOptions(name, options) {
+  if (!options) {
+    return;
+  }
+  validatePositiveNumber(`${name}.maxConcurrent`, options.maxConcurrent);
+  validatePositiveNumber(`${name}.intervalMs`, options.intervalMs);
+  validatePositiveNumber(`${name}.maxPerInterval`, options.maxPerInterval);
+  if (options.scope && !["global", "key", "fetcher"].includes(options.scope)) {
+    throw new Error(`${name}.scope must be one of "global", "key", or "fetcher".`);
+  }
+  if (options.bucketKey !== void 0 && options.bucketKey.length === 0) {
+    throw new Error(`${name}.bucketKey must not be empty.`);
+  }
+}
+function validateCacheKey(key) {
+  if (key.length === 0) {
+    throw new Error("Cache key must not be empty.");
+  }
+  if (key.length > MAX_CACHE_KEY_LENGTH) {
+    throw new Error(`Cache key length must be at most ${MAX_CACHE_KEY_LENGTH} characters.`);
+  }
+  if (/[\u0000-\u001F\u007F]/.test(key)) {
+    throw new Error("Cache key contains unsupported control characters.");
+  }
+  if (/[\uD800-\uDFFF]/.test(key)) {
+    throw new Error("Cache key contains unsupported surrogate code points.");
+  }
+  return key;
+}
+function validateTag(tag) {
+  if (tag.length === 0) {
+    throw new Error("Cache tag must not be empty.");
+  }
+  if (tag.length > MAX_CACHE_KEY_LENGTH) {
+    throw new Error(`Cache tag length must be at most ${MAX_CACHE_KEY_LENGTH} characters.`);
+  }
+  if (/[\u0000-\u001F\u007F]/.test(tag)) {
+    throw new Error("Cache tag contains unsupported control characters.");
+  }
+  if (/[\uD800-\uDFFF]/.test(tag)) {
+    throw new Error("Cache tag contains unsupported surrogate code points.");
+  }
+  return tag;
+}
+function validateTags(tags) {
+  if (!tags) {
+    return;
+  }
+  if (tags.length > MAX_TAGS_PER_OPERATION) {
+    throw new Error(`options.tags must contain at most ${MAX_TAGS_PER_OPERATION} tags.`);
+  }
+  for (const tag of tags) {
+    validateTag(tag);
+  }
+}
+function validatePattern(pattern) {
+  if (pattern.length === 0) {
+    throw new Error("Pattern must not be empty.");
+  }
+  if (pattern.length > MAX_PATTERN_LENGTH) {
+    throw new Error(`Pattern length must be at most ${MAX_PATTERN_LENGTH} characters.`);
+  }
+  if (/[\u0000-\u001F\u007F]/.test(pattern)) {
+    throw new Error("Pattern contains unsupported control characters.");
+  }
+}
+function validateTtlPolicy(name, policy) {
+  if (!policy || typeof policy === "function" || policy === "until-midnight" || policy === "next-hour") {
+    return;
+  }
+  if ("alignTo" in policy) {
+    validatePositiveNumber(`${name}.alignTo`, policy.alignTo);
+    return;
+  }
+  throw new Error(`${name} is invalid.`);
+}
+function validateAdaptiveTtlOptions(options) {
+  if (!options || options === true) {
+    return;
+  }
+  validatePositiveNumber("adaptiveTtl.hotAfter", options.hotAfter);
+  validateLayerNumberOption("adaptiveTtl.step", options.step);
+  validateLayerNumberOption("adaptiveTtl.maxTtl", options.maxTtl);
+}
+function validateCircuitBreakerOptions(options) {
+  if (!options) {
+    return;
+  }
+  validatePositiveNumber("circuitBreaker.failureThreshold", options.failureThreshold);
+  validatePositiveNumber("circuitBreaker.cooldownMs", options.cooldownMs);
+}
+
 // src/invalidation/RedisTagIndex.ts
 var RedisTagIndex = class {
   client;
@@ -183,5 +307,16 @@ function simpleHash(value) {
 }
 
 export {
+  validatePositiveNumber,
+  validateNonNegativeNumber,
+  validateLayerNumberOption,
+  validateRateLimitOptions,
+  validateCacheKey,
+  validateTag,
+  validateTags,
+  validatePattern,
+  validateTtlPolicy,
+  validateAdaptiveTtlOptions,
+  validateCircuitBreakerOptions,
   RedisTagIndex
 };

package/dist/cli.cjs

@@ -36,6 +36,51 @@ __export(cli_exports, {
 module.exports = __toCommonJS(cli_exports);
 var import_ioredis = __toESM(require("ioredis"), 1);
 
+// src/internal/CacheStackValidation.ts
+var MAX_CACHE_KEY_LENGTH = 1024;
+var MAX_PATTERN_LENGTH = 1024;
+function validateCacheKey(key) {
+  if (key.length === 0) {
+    throw new Error("Cache key must not be empty.");
+  }
+  if (key.length > MAX_CACHE_KEY_LENGTH) {
+    throw new Error(`Cache key length must be at most ${MAX_CACHE_KEY_LENGTH} characters.`);
+  }
+  if (/[\u0000-\u001F\u007F]/.test(key)) {
+    throw new Error("Cache key contains unsupported control characters.");
+  }
+  if (/[\uD800-\uDFFF]/.test(key)) {
+    throw new Error("Cache key contains unsupported surrogate code points.");
+  }
+  return key;
+}
+function validateTag(tag) {
+  if (tag.length === 0) {
+    throw new Error("Cache tag must not be empty.");
+  }
+  if (tag.length > MAX_CACHE_KEY_LENGTH) {
+    throw new Error(`Cache tag length must be at most ${MAX_CACHE_KEY_LENGTH} characters.`);
+  }
+  if (/[\u0000-\u001F\u007F]/.test(tag)) {
+    throw new Error("Cache tag contains unsupported control characters.");
+  }
+  if (/[\uD800-\uDFFF]/.test(tag)) {
+    throw new Error("Cache tag contains unsupported surrogate code points.");
+  }
+  return tag;
+}
+function validatePattern(pattern) {
+  if (pattern.length === 0) {
+    throw new Error("Pattern must not be empty.");
+  }
+  if (pattern.length > MAX_PATTERN_LENGTH) {
+    throw new Error(`Pattern length must be at most ${MAX_PATTERN_LENGTH} characters.`);
+  }
+  if (/[\u0000-\u001F\u007F]/.test(pattern)) {
+    throw new Error("Pattern contains unsupported control characters.");
+  }
+}
+
 // src/internal/StoredValue.ts
 function isStoredValueEnvelope(value) {
   if (typeof value !== "object" || value === null) {
@@ -388,13 +433,17 @@ async function main(argv = process.argv.slice(2)) {
       throw new Error(`Failed to connect to Redis at ${maskRedisUrl(redisUrl)}: ${message}`);
     });
     if (args.command === "stats") {
-      const keys = await scanKeys(redis, args.pattern ?? "*");
-      process.stdout.write(`${JSON.stringify({ totalKeys: keys.length, pattern: args.pattern ?? "*" }, null, 2)}
+      const pattern = args.pattern ?? "*";
+      if (args.pattern && !validateCliInput(args.pattern, validatePattern)) return;
+      const keys = await scanKeys(redis, pattern);
+      process.stdout.write(`${JSON.stringify({ totalKeys: keys.length, pattern }, null, 2)}
 `);
       return;
     }
     if (args.command === "keys") {
-      const keys = await scanKeys(redis, args.pattern ?? "*");
+      const pattern = args.pattern ?? "*";
+      if (args.pattern && !validateCliInput(args.pattern, validatePattern)) return;
+      const keys = await scanKeys(redis, pattern);
       if (keys.length > 0) {
         process.stdout.write(`${keys.join("\n")}
 `);
@@ -403,6 +452,7 @@ async function main(argv = process.argv.slice(2)) {
     }
     if (args.command === "invalidate") {
       if (args.tag) {
+        if (!validateCliInput(args.tag, validateTag)) return;
         const tagIndex = new RedisTagIndex({ client: redis, prefix: args.tagIndexPrefix ?? "layercache:tag-index" });
         const keys2 = await tagIndex.keysForTag(args.tag);
         if (keys2.length > 0) {
@@ -412,11 +462,18 @@ async function main(argv = process.argv.slice(2)) {
 `);
         return;
       }
-      const keys = await scanKeys(redis, args.pattern ?? "*");
+      const effectivePattern = args.pattern ?? "*";
+      if (args.pattern && !validateCliInput(args.pattern, validatePattern)) return;
+      const keys = await scanKeys(redis, effectivePattern);
+      if (!args.pattern && !args.force && keys.length > 0) {
+        process.stderr.write(`Warning: this operation will invalidate ${keys.length} keys. Use --force to confirm.
+`);
+        return;
+      }
       if (keys.length > 0) {
         await batchDelete(redis, keys);
       }
-      process.stdout.write(`${JSON.stringify({ deletedKeys: keys.length, pattern: args.pattern ?? "*" }, null, 2)}
+      process.stdout.write(`${JSON.stringify({ deletedKeys: keys.length, pattern: effectivePattern }, null, 2)}
 `);
       return;
     }
@@ -424,6 +481,7 @@ async function main(argv = process.argv.slice(2)) {
       if (!args.key) {
         throw new Error("inspect requires --key <key>.");
       }
+      if (!validateCliInput(args.key, validateCacheKey)) return;
       const payload = await redis.getBuffer(args.key);
       const ttl = await redis.ttl(args.key);
       const decoded = decodeInspectablePayload(payload);
@@ -498,6 +556,8 @@ function parseArgs(argv) {
       index += 1;
     } else if (token === "--require-tls") {
       parsed.requireTls = true;
+    } else if (token === "--force") {
+      parsed.force = true;
     }
   }
   return parsed;
@@ -574,6 +634,18 @@ function maskRedisUrl(url) {
     return url.replace(/:([^@/]+)@/, ":***@");
   }
 }
+function validateCliInput(value, validator) {
+  try {
+    validator(value);
+    return true;
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    process.stderr.write(`Error: ${message}
+`);
+    process.exitCode = 1;
+    return false;
+  }
+}
 if (process.argv[1]?.endsWith("cli.cjs") || process.argv[1]?.endsWith("cli.js")) {
   void main();
 }