layercache 1.3.1 → 1.3.3

package/dist/index.js

@@ -1,11 +1,22 @@
 import {
-  RedisTagIndex
-} from "./chunk-BQLL6IM5.js";
+  RedisTagIndex,
+  validateAdaptiveTtlOptions,
+  validateCacheKey,
+  validateCircuitBreakerOptions,
+  validateLayerNumberOption,
+  validateNonNegativeNumber,
+  validatePattern,
+  validatePositiveNumber,
+  validateRateLimitOptions,
+  validateTag,
+  validateTags,
+  validateTtlPolicy
+} from "./chunk-BORDQ3LA.js";
 import {
   MemoryLayer,
   TagIndex,
   createHonoCacheMiddleware
-} from "./chunk-GJBKCFE6.js";
+} from "./chunk-5RCAX2BQ.js";
 import {
   PatternMatcher,
   createStoredValueEnvelope,
@@ -715,6 +726,7 @@ var CacheStackLayerWriter = class {
 };
 
 // src/internal/CacheStackMaintenance.ts
+var MAX_KEY_EPOCHS = 5e4;
 var CacheStackMaintenance = class {
   keyEpochs = /* @__PURE__ */ new Map();
   writeBehindQueue = [];
@@ -758,6 +770,7 @@ var CacheStackMaintenance = class {
     for (const key of keys) {
       this.keyEpochs.set(key, this.currentKeyEpoch(key) + 1);
     }
+    this.pruneKeyEpochsIfNeeded();
   }
   isWriteOutdated(key, expectedClearEpoch, expectedKeyEpoch) {
     if (expectedClearEpoch !== void 0 && expectedClearEpoch !== this.clearEpoch) {
@@ -810,6 +823,16 @@ var CacheStackMaintenance = class {
   async waitForGenerationCleanup() {
     await this.generationCleanupPromise;
   }
+  pruneKeyEpochsIfNeeded() {
+    if (this.keyEpochs.size <= MAX_KEY_EPOCHS) {
+      return;
+    }
+    const sorted = [...this.keyEpochs.entries()].sort((a, b) => a[1] - b[1]);
+    const toDelete = Math.ceil(sorted.length * 0.1);
+    for (let i = 0; i < toDelete; i++) {
+      this.keyEpochs.delete(sorted[i][0]);
+    }
+  }
 };
 
 // src/internal/CacheStackRuntimePolicy.ts
@@ -849,16 +872,16 @@ function planFreshReadPolicies({
 }
 
 // src/internal/CacheStackSnapshotManager.ts
-import { randomBytes } from "crypto";
 import { constants, promises as fs } from "fs";
-import path from "path";
 
 // src/internal/CacheSnapshotFile.ts
-function isWithinSnapshotBase(realBaseDir, candidatePath, pathSeparator, path2) {
-  const relative = path2.relative(realBaseDir, candidatePath);
-  return !(relative === ".." || relative.startsWith(`..${pathSeparator}`) || path2.isAbsolute(relative));
+import { randomBytes } from "crypto";
+import { rename, unlink } from "fs/promises";
+function isWithinSnapshotBase(realBaseDir, candidatePath, pathSeparator, path) {
+  const relative = path.relative(realBaseDir, candidatePath);
+  return !(relative === ".." || relative.startsWith(`..${pathSeparator}`) || path.isAbsolute(relative));
 }
-async function findExistingAncestor(directory, fs3, path2) {
+async function findExistingAncestor(directory, fs3, path) {
   let current = directory;
   while (true) {
     try {
@@ -869,7 +892,7 @@ async function findExistingAncestor(directory, fs3, path2) {
         throw error;
       }
     }
-    const parent = path2.dirname(current);
+    const parent = path.dirname(current);
     if (parent === current) {
       return current;
     }
@@ -884,36 +907,36 @@ async function validateSnapshotFilePath(filePath, mode, snapshotBaseDir, cwd = p
     throw new Error("filePath must not contain null bytes.");
   }
   const { promises: fs3 } = await import("fs");
-  const path2 = await import("path");
-  const resolved = path2.resolve(filePath);
-  const baseDir = snapshotBaseDir === false ? false : path2.resolve(snapshotBaseDir ?? cwd);
+  const path = await import("path");
+  const resolved = path.resolve(filePath);
+  const baseDir = snapshotBaseDir === false ? false : path.resolve(snapshotBaseDir ?? cwd);
   if (baseDir === false) {
     return resolved;
   }
   await fs3.mkdir(baseDir, { recursive: true });
   const realBaseDir = await fs3.realpath(baseDir);
-  if (!isWithinSnapshotBase(realBaseDir, resolved, path2.sep, path2)) {
+  if (!isWithinSnapshotBase(realBaseDir, resolved, path.sep, path)) {
     throw new Error(`filePath is outside the allowed snapshot directory: ${realBaseDir}`);
   }
   if (mode === "read") {
     const realTarget = await fs3.realpath(resolved);
-    if (!isWithinSnapshotBase(realBaseDir, realTarget, path2.sep, path2)) {
+    if (!isWithinSnapshotBase(realBaseDir, realTarget, path.sep, path)) {
       throw new Error(`filePath is outside the allowed snapshot directory: ${realBaseDir}`);
     }
     return realTarget;
   }
-  const parentDir = path2.dirname(resolved);
-  const existingAncestor = await findExistingAncestor(parentDir, fs3, path2);
+  const parentDir = path.dirname(resolved);
+  const existingAncestor = await findExistingAncestor(parentDir, fs3, path);
   const realExistingAncestor = await fs3.realpath(existingAncestor);
-  if (!isWithinSnapshotBase(realBaseDir, realExistingAncestor, path2.sep, path2)) {
+  if (!isWithinSnapshotBase(realBaseDir, realExistingAncestor, path.sep, path)) {
     throw new Error(`filePath is outside the allowed snapshot directory: ${realBaseDir}`);
   }
   await fs3.mkdir(parentDir, { recursive: true });
   const realParentDir = await fs3.realpath(parentDir);
-  if (!isWithinSnapshotBase(realBaseDir, realParentDir, path2.sep, path2)) {
+  if (!isWithinSnapshotBase(realBaseDir, realParentDir, path.sep, path)) {
     throw new Error(`filePath is outside the allowed snapshot directory: ${realBaseDir}`);
   }
-  const targetPath = path2.join(realParentDir, path2.basename(resolved));
+  const targetPath = path.join(realParentDir, path.basename(resolved));
   try {
     const existing = await fs3.lstat(targetPath);
     if (existing.isSymbolicLink()) {
@@ -948,6 +971,17 @@ async function readUtf8HandleWithLimit(handle, byteLimit) {
   }
   return Buffer.concat(chunks).toString("utf8");
 }
+function atomicWriteTempPath(targetPath) {
+  return `${targetPath}.tmp-${randomBytes(8).toString("hex")}`;
+}
+async function commitAtomicWrite(tempPath, targetPath) {
+  try {
+    await rename(tempPath, targetPath);
+  } catch (error) {
+    await unlink(tempPath).catch(() => void 0);
+    throw error;
+  }
+}
 
 // src/internal/StructuredDataSanitizer.ts
 var DANGEROUS_KEYS = /* @__PURE__ */ new Set(["__proto__", "prototype", "constructor"]);
@@ -1026,10 +1060,7 @@ var CacheStackSnapshotManager = class {
   }
   async persistToFile(filePath, snapshotBaseDir, maxEntries) {
     const targetPath = await validateSnapshotFilePath(filePath, "write", snapshotBaseDir);
-    const tempPath = path.join(
-      path.dirname(targetPath),
-      `.layercache-${process.pid}-${Date.now()}-${randomBytes(8).toString("hex")}.tmp`
-    );
+    const tempPath = atomicWriteTempPath(targetPath);
     let handle;
     try {
       handle = await fs.open(tempPath, "wx");
@@ -1044,7 +1075,7 @@ var CacheStackSnapshotManager = class {
       await openedHandle.writeFile(wroteAny ? "\n]" : "]", "utf8");
       await openedHandle.close();
       handle = void 0;
-      await fs.rename(tempPath, targetPath);
+      await commitAtomicWrite(tempPath, targetPath);
     } catch (error) {
       await handle?.close().catch(() => void 0);
       await fs.unlink(tempPath).catch(() => void 0);
@@ -1138,130 +1169,6 @@ var CacheStackSnapshotManager = class {
   }
 };
 
-// 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/internal/CircuitBreakerManager.ts
 var CircuitBreakerManager = class {
   breakers = /* @__PURE__ */ new Map();
@@ -1359,6 +1266,7 @@ var CircuitBreakerManager = class {
 
 // src/internal/FetchRateLimiter.ts
 var MAX_BUCKETS = 1e4;
+var MAX_QUEUE_PER_BUCKET = 1e4;
 var FetchRateLimiter = class {
   buckets = /* @__PURE__ */ new Map();
   queuesByBucket = /* @__PURE__ */ new Map();
@@ -1367,6 +1275,7 @@ var FetchRateLimiter = class {
   nextFetcherBucketId = 0;
   drainTimer;
   isDisposed = false;
+  rateLimitBypasses = 0;
   async schedule(options, context, task) {
     if (this.isDisposed) {
       throw new Error("FetchRateLimiter has been disposed.");
@@ -1381,6 +1290,11 @@ var FetchRateLimiter = class {
     return new Promise((resolve2, reject) => {
       const bucketKey = this.resolveBucketKey(normalized, context);
       const queue = this.queuesByBucket.get(bucketKey) ?? [];
+      if (queue.length >= MAX_QUEUE_PER_BUCKET) {
+        this.rateLimitBypasses += 1;
+        task().then(resolve2, reject);
+        return;
+      }
       queue.push({
         bucketKey,
         options: normalized,
@@ -1685,7 +1599,13 @@ var MetricsCollector = class {
 };
 
 // src/internal/TtlResolver.ts
+import { randomBytes as randomBytes2 } from "crypto";
 var DEFAULT_NEGATIVE_TTL_SECONDS = 60;
+var secureRandom = {
+  value() {
+    return randomBytes2(4).readUInt32BE(0) / 4294967296;
+  }
+};
 var TtlResolver = class {
   accessProfiles = /* @__PURE__ */ new Map();
   maxProfileEntries;
@@ -1748,7 +1668,7 @@ var TtlResolver = class {
     if (!ttl || ttl <= 0 || !jitter || jitter <= 0) {
       return ttl;
     }
-    const delta = (Math.random() * 2 - 1) * jitter;
+    const delta = (secureRandom.value() * 2 - 1) * jitter;
     return Math.max(1, Math.round(ttl + delta));
   }
   resolvePolicyTtl(key, value, policy) {
@@ -2864,7 +2784,7 @@ var CacheStack = class extends EventEmitter {
       } catch (error) {
         if (this.backgroundRefreshAbort.get(key)) return;
         this.metricsCollector.increment("refreshErrors");
-        this.logger.debug?.("refresh-error", { key, error: this.formatError(error) });
+        this.logger.warn?.("background-refresh-error", { key, error: this.formatError(error) });
       } finally {
         this.backgroundRefreshes.delete(key);
         this.backgroundRefreshAbort.delete(key);
@@ -3162,7 +3082,12 @@ var CacheStack = class extends EventEmitter {
     }
   }
   shouldSkipLayer(layer) {
-    return shouldSkipLayer(this.layerDegradedUntil.get(layer.name));
+    const degradedUntil = this.layerDegradedUntil.get(layer.name);
+    const skip = shouldSkipLayer(degradedUntil);
+    if (!skip && degradedUntil !== void 0) {
+      this.layerDegradedUntil.delete(layer.name);
+    }
+    return skip;
   }
   async handleLayerFailure(layer, operation, error) {
     const recovery = resolveRecoverableLayerFailure(this.options.gracefulDegradation);
@@ -3964,12 +3889,12 @@ var RedisLayer = class {
 };
 
 // src/layers/DiskLayer.ts
-import { createHash as createHash2, randomBytes as randomBytes3 } from "crypto";
+import { createHash as createHash2, randomBytes as randomBytes4 } from "crypto";
 import { promises as fs2 } from "fs";
 import { join, resolve } from "path";
 
 // src/internal/PayloadProtection.ts
-import { createCipheriv, createDecipheriv, createHash, createHmac, randomBytes as randomBytes2, timingSafeEqual } from "crypto";
+import { createCipheriv, createDecipheriv, createHash, createHmac, randomBytes as randomBytes3, timingSafeEqual } from "crypto";
 var MAGIC_ENCRYPTED = Buffer.from("LCP1:");
 var MAGIC_SIGNED = Buffer.from("LCS1:");
 var ALGORITHM = "aes-256-gcm";
@@ -4033,7 +3958,7 @@ var PayloadProtection = class {
   }
   // ── Encryption (AES-256-GCM) ──────────────────────────────────────────
   encrypt(plaintext, key) {
-    const iv = randomBytes2(IV_LENGTH);
+    const iv = randomBytes3(IV_LENGTH);
     const cipher = createCipheriv(ALGORITHM, key, iv, { authTagLength: AUTH_TAG_LENGTH });
     const encrypted = Buffer.concat([cipher.update(plaintext), cipher.final()]);
     const authTag = cipher.getAuthTag();
@@ -4146,7 +4071,7 @@ var DiskLayer = class {
       const raw = Buffer.isBuffer(payload) ? payload : Buffer.from(payload, "utf8");
       const protectedPayload = this.protection.protect(raw);
       const targetPath = this.keyToPath(key);
-      const tempPath = `${targetPath}.${process.pid}.${Date.now()}.${randomBytes3(8).toString("hex")}.tmp`;
+      const tempPath = `${targetPath}.${process.pid}.${Date.now()}.${randomBytes4(8).toString("hex")}.tmp`;
       try {
         await fs2.writeFile(tempPath, protectedPayload);
         await fs2.rename(tempPath, targetPath);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "layercache",
-  "version": "1.3.1",
+  "version": "1.3.3",
   "description": "Production-ready multi-layer caching for Node.js. Stack memory + Redis + disk behind one API with stampede prevention, tag invalidation, stale serving, and full observability.",
   "keywords": [
     "cache",
@@ -18,7 +18,6 @@
     "nodejs",
     "express",
     "fastify",
-    "nestjs",
     "hono",
     "trpc",
     "graphql",
@@ -54,20 +53,15 @@
   },
   "files": [
     "dist",
-    "packages/nestjs/dist",
     "examples",
     "benchmarks"
   ],
   "engines": {
     "node": ">=20"
   },
-  "workspaces": [
-    "packages/nestjs"
-  ],
   "scripts": {
     "build": "tsup src/index.ts src/cli.ts src/edge.ts --format esm,cjs --dts",
-    "build:nestjs": "npm --workspace @cachestack/nestjs run build",
-    "build:all": "npm run build && npm run build:nestjs",
+    "build:all": "npm run build",
     "test": "vitest run",
     "test:coverage": "vitest run --coverage",
     "test:watch": "vitest",
@@ -96,16 +90,12 @@
   },
   "devDependencies": {
     "@biomejs/biome": "^1.9.4",
-    "@nestjs/common": "^11.1.0",
-    "@nestjs/core": "^11.1.0",
     "@types/autocannon": "^7.12.7",
     "@types/node": "^22.15.2",
     "@vitest/coverage-v8": "^4.1.2",
     "autocannon": "^8.0.0",
     "ioredis": "^5.6.1",
     "ioredis-mock": "^8.13.0",
-    "reflect-metadata": "^0.2.2",
-    "rxjs": "^7.8.1",
     "tsup": "^8.5.0",
     "tsx": "^4.19.3",
     "typescript": "^5.8.3",

package/examples/nestjs-module/app.module.ts

@@ -1,15 +0,0 @@
-import { Module } from '@nestjs/common'
-import Redis from 'ioredis'
-import { CacheStackModule } from '../../packages/nestjs/src'
-import { MemoryLayer, RedisLayer } from '../../src'
-
-const redis = new Redis(process.env.REDIS_URL)
-
-@Module({
-  imports: [
-    CacheStackModule.forRoot({
-      layers: [new MemoryLayer({ ttl: 20 }), new RedisLayer({ client: redis, ttl: 300 })]
-    })
-  ]
-})
-export class AppModule {}