layercache 1.3.4 → 2.0.0

package/README.md

@@ -19,7 +19,7 @@
   <a href="./LICENSE"><img src="https://img.shields.io/badge/license-Apache_2.0-green" alt="license"></a>
   <a href="https://www.typescriptlang.org/"><img src="https://img.shields.io/badge/TypeScript-first-3178C6?logo=typescript&logoColor=white" alt="TypeScript"></a>
   <img src="https://img.shields.io/badge/Node.js-%E2%89%A5_20-339933?logo=nodedotjs&logoColor=white" alt="Node.js >= 20">
-  <img src="https://img.shields.io/badge/tests-529_passing-brightgreen" alt="tests">
+  <img src="https://img.shields.io/badge/tests-549_passing-brightgreen" alt="tests">
   <a href="https://coveralls.io/github/flyingsquirrel0419/layercache?branch=main"><img src="https://coveralls.io/repos/github/flyingsquirrel0419/layercache/badge.svg?branch=main&t=20260410" alt="Coveralls"></a>
 </p>
 
@@ -64,8 +64,8 @@ import { CacheStack, MemoryLayer, RedisLayer } from 'layercache'
 import Redis from 'ioredis'
 
 const cache = new CacheStack([
-  new MemoryLayer({ ttl: 60, maxSize: 1_000 }),       // L1: in-process
-  new RedisLayer({ client: new Redis(), ttl: 3600 }),  // L2: shared
+  new MemoryLayer({ ttl: 60_000, maxSize: 1_000 }),       // L1: in-process
+  new RedisLayer({ client: new Redis(), ttl: 3_600_000 }),  // L2: shared
 ])
 
 // Read-through: fetcher runs once, all layers filled
@@ -77,7 +77,7 @@ const user = await cache.get('user:123', () => db.findUser(123))
 
 ```ts
 const cache = new CacheStack([
-  new MemoryLayer({ ttl: 60 })
+  new MemoryLayer({ ttl: 60_000 })
 ])
 ```
 
@@ -90,8 +90,8 @@ const cache = new CacheStack([
 import { CacheStack, MemoryLayer, RedisLayer, DiskLayer } from 'layercache'
 
 const cache = new CacheStack([
-  new MemoryLayer({ ttl: 60, maxSize: 5_000 }),
-  new RedisLayer({ client: new Redis(), ttl: 3600, compression: 'gzip' }),
+  new MemoryLayer({ ttl: 60_000, maxSize: 5_000 }),
+  new RedisLayer({ client: new Redis(), ttl: 3_600_000, compression: 'gzip' }),
   new DiskLayer({ directory: './var/cache', maxFiles: 10_000 }),
 ])
 ```
@@ -172,10 +172,10 @@ import {
 import Redis from 'ioredis'
 
 const cache = new CacheStack([
-  new MemoryLayer({ ttl: 60 }),    // s
+  new MemoryLayer({ ttl: 60_000 }),    // ms
   new RedisLayer({
     client: new Redis(),
-    ttl: 300                       // s
+    ttl: 300_000                       // ms
   })
 ])
 
@@ -194,38 +194,38 @@ const cache = new CacheStack([
 
 ## 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** |
+|  | node-cache-manager | keyv | cacheable | BentoCache | **layercache** |
+|---|:---:|:---:|:---:|:---:|:---:|
+| Multi-layer + auto backfill | Partial | Plugin | -- | Partial | **Yes** |
+| Stampede prevention | -- | -- | -- | Partial | **Yes** |
+| Tag invalidation | -- | Yes | Yes | Yes | **Yes** |
+| TypeScript-first | Partial | Yes | Yes | Yes | **Yes** |
+| Event hooks | Yes | 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** |
+|  | node-cache-manager | keyv | cacheable | BentoCache | **layercache** |
+|---|:---:|:---:|:---:|:---:|:---:|
+| Multi-layer with auto backfill | Partial | Plugin | -- | Partial | **Yes** |
+| Stampede prevention | -- | -- | -- | Partial | **Yes** |
+| Distributed single-flight | -- | -- | -- | -- | **Yes** |
+| Tag invalidation | -- | Yes | Yes | Yes | **Yes** |
+| Distributed tags | -- | -- | -- | -- | **Yes** |
+| Cross-server L1 flush | -- | -- | -- | Yes | **Yes** |
+| Stale-while-revalidate | -- | -- | -- | Yes | **Yes** |
+| Circuit breaker | -- | -- | -- | Yes | **Yes** |
+| Graceful degradation | -- | -- | -- | Yes | **Yes** |
+| Sliding / adaptive TTL | -- | -- | -- | -- | **Yes** |
+| Cache warming | -- | -- | -- | -- | **Yes** |
+| Persistence / snapshots | -- | -- | -- | -- | **Yes** |
+| Compression | -- | -- | Yes | -- | **Yes** |
+| Admin CLI | -- | -- | -- | -- | **Yes** |
+| TypeScript-first | Partial | Yes | Yes | Yes | **Yes** |
+| Wrap / decorator API | Yes | -- | -- | Partial | **Yes** |
+| Namespaces | -- | Yes | Yes | Yes | **Yes** |
+| Event hooks | Yes | Yes | Yes | Yes | **Yes** |
+| Custom layers | Partial | -- | -- | Yes | **Yes** |
 
 </details>
 
@@ -265,6 +265,7 @@ const cache = new CacheStack([
 | **Adaptive TTL** | Auto-ramp TTL for hot keys up to a ceiling |
 | **Refresh-ahead** | Proactively refresh before expiry |
 | **TTL policies** | Align expirations to calendar boundaries (`until-midnight`, `next-hour`, custom) |
+| **Context-aware entry options** | Derive TTLs and tags from the cached value right before storage |
 
 ### Resilience & Operations
 
@@ -286,7 +287,7 @@ const cache = new CacheStack([
 | **Metrics** | Hits, misses, fetches, stale hits, circuit breaker trips, and more |
 | **Per-layer latency** | Avg, max, and sample count using Welford's algorithm |
 | **Health checks** | Async health endpoint per layer with latency measurement |
-| **Event hooks** | `hit`, `miss`, `set`, `delete`, `stale-serve`, `stampede-dedupe`, `backfill`, `warm`, `error` |
+| **Event hooks** | `hit`, `miss`, `set`, `delete`, `expire`, `stale-serve`, `stampede-dedupe`, `backfill`, `warm`, `error` |
 | **OpenTelemetry** | Hook-based distributed tracing support without method monkey-patching |
 | **Prometheus exporter** | Metrics export including latency gauges |
 | **HTTP stats handler** | JSON endpoint for dashboards |
@@ -316,10 +317,10 @@ layercache plugs into the frameworks you already use:
 ```ts
 import { CacheStack, MemoryLayer, createExpressCacheMiddleware } from 'layercache'
 
-const cache = new CacheStack([new MemoryLayer({ ttl: 60 })])
+const cache = new CacheStack([new MemoryLayer({ ttl: 60_000 })])
 
 app.get('/api/users', createExpressCacheMiddleware(cache, {
-  ttl: 30,
+  ttl: 30_000,
   tags: ['users'],
   keyResolver: (req) => `users:${req.url}`
 }), async (req, res) => {
@@ -381,8 +382,8 @@ const coordinator = new RedisSingleFlightCoordinator({ client: redis })
 
 const cache = new CacheStack(
   [
-    new MemoryLayer({ ttl: 60, maxSize: 10_000 }),
-    new RedisLayer({ client: redis, ttl: 3600, prefix: 'myapp:cache:' })
+    new MemoryLayer({ ttl: 60_000, maxSize: 10_000 }),
+    new RedisLayer({ client: redis, ttl: 3_600_000, prefix: 'myapp:cache:' })
   ],
   {
     invalidationBus: bus,

package/dist/{chunk-BORDQ3LA.js → chunk-7KMKQ6QZ.js}

@@ -1,6 +1,6 @@
 import {
   PatternMatcher
-} from "./chunk-4PPBOOXT.js";
+} from "./chunk-KJDFYE5T.js";
 
 // src/internal/CacheStackValidation.ts
 var MAX_CACHE_KEY_LENGTH = 1024;
@@ -125,6 +125,19 @@ function validateCircuitBreakerOptions(options) {
   validatePositiveNumber("circuitBreaker.failureThreshold", options.failureThreshold);
   validatePositiveNumber("circuitBreaker.cooldownMs", options.cooldownMs);
 }
+function validateContextEntryOptions(name, options) {
+  if (!options) {
+    return;
+  }
+  validateLayerNumberOption(`${name}.ttl`, options.ttl);
+  validateLayerNumberOption(`${name}.negativeTtl`, options.negativeTtl);
+  validateLayerNumberOption(`${name}.staleWhileRevalidate`, options.staleWhileRevalidate);
+  validateLayerNumberOption(`${name}.staleIfError`, options.staleIfError);
+  validateLayerNumberOption(`${name}.ttlJitter`, options.ttlJitter);
+  validateTtlPolicy(`${name}.ttlPolicy`, options.ttlPolicy);
+  validateAdaptiveTtlOptions(options.adaptiveTtl);
+  validateTags(options.tags);
+}
 
 // src/invalidation/RedisTagIndex.ts
 var RedisTagIndex = class {
@@ -318,5 +331,6 @@ export {
   validateTtlPolicy,
   validateAdaptiveTtlOptions,
   validateCircuitBreakerOptions,
+  validateContextEntryOptions,
   RedisTagIndex
 };

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

@@ -1,6 +1,6 @@
 import {
   unwrapStoredValue
-} from "./chunk-4PPBOOXT.js";
+} from "./chunk-KJDFYE5T.js";
 
 // src/layers/MemoryLayer.ts
 var MemoryLayer = class {
@@ -57,7 +57,7 @@ var MemoryLayer = class {
     this.entries.delete(key);
     this.entries.set(key, {
       value,
-      expiresAt: ttl && ttl > 0 ? Date.now() + ttl * 1e3 : null,
+      expiresAt: ttl && ttl > 0 ? Date.now() + ttl : null,
       accessCount: 0,
       insertedAt: Date.now()
     });
@@ -88,7 +88,7 @@ var MemoryLayer = class {
     if (entry.expiresAt === null) {
       return null;
     }
-    return Math.max(0, Math.ceil((entry.expiresAt - Date.now()) / 1e3));
+    return Math.max(0, Math.ceil(entry.expiresAt - Date.now()));
   }
   async size() {
     this.pruneExpired();

package/dist/{chunk-4PPBOOXT.js → chunk-KJDFYE5T.js}

@@ -38,29 +38,29 @@ function isStoredValueEnvelope(value) {
   if (typeof v.freshUntil === "number" && typeof v.errorUntil === "number" && v.errorUntil < v.freshUntil) {
     return false;
   }
-  const maxTtlSeconds = 10 * 365 * 24 * 60 * 60;
-  if (!isValidEnvelopeTtlSeconds(v.freshTtlSeconds, maxTtlSeconds)) {
+  const maxTtlMs = 10 * 365 * 24 * 60 * 60 * 1e3;
+  if (!isValidEnvelopeTtlMs(v.freshTtlMs, maxTtlMs)) {
     return false;
   }
-  if (!isValidEnvelopeTtlSeconds(v.staleWhileRevalidateSeconds, maxTtlSeconds)) {
+  if (!isValidEnvelopeTtlMs(v.staleWhileRevalidateMs, maxTtlMs)) {
     return false;
   }
-  if (!isValidEnvelopeTtlSeconds(v.staleIfErrorSeconds, maxTtlSeconds)) {
+  if (!isValidEnvelopeTtlMs(v.staleIfErrorMs, maxTtlMs)) {
     return false;
   }
-  if (v.freshTtlSeconds == null && (v.staleWhileRevalidateSeconds != null || v.staleIfErrorSeconds != null)) {
+  if (v.freshTtlMs == null && (v.staleWhileRevalidateMs != null || v.staleIfErrorMs != null)) {
     return false;
   }
   return true;
 }
 function createStoredValueEnvelope(options) {
   const now = options.now ?? Date.now();
-  const freshTtlSeconds = normalizePositiveSeconds(options.freshTtlSeconds);
-  const staleWhileRevalidateSeconds = normalizePositiveSeconds(options.staleWhileRevalidateSeconds);
-  const staleIfErrorSeconds = normalizePositiveSeconds(options.staleIfErrorSeconds);
-  const freshUntil = freshTtlSeconds ? now + freshTtlSeconds * 1e3 : null;
-  const staleUntil = freshUntil && staleWhileRevalidateSeconds ? freshUntil + staleWhileRevalidateSeconds * 1e3 : null;
-  const errorUntil = freshUntil && staleIfErrorSeconds ? freshUntil + staleIfErrorSeconds * 1e3 : null;
+  const freshTtlMs = normalizePositiveMs(options.freshTtlMs);
+  const staleWhileRevalidateMs = normalizePositiveMs(options.staleWhileRevalidateMs);
+  const staleIfErrorMs = normalizePositiveMs(options.staleIfErrorMs);
+  const freshUntil = freshTtlMs ? now + freshTtlMs : null;
+  const staleUntil = freshUntil && staleWhileRevalidateMs ? freshUntil + staleWhileRevalidateMs : null;
+  const errorUntil = freshUntil && staleIfErrorMs ? freshUntil + staleIfErrorMs : null;
   return {
     __layercache: 1,
     kind: options.kind,
@@ -68,9 +68,9 @@ function createStoredValueEnvelope(options) {
     freshUntil,
     staleUntil,
     errorUntil,
-    freshTtlSeconds: freshTtlSeconds ?? null,
-    staleWhileRevalidateSeconds: staleWhileRevalidateSeconds ?? null,
-    staleIfErrorSeconds: staleIfErrorSeconds ?? null
+    freshTtlMs: freshTtlMs ?? null,
+    staleWhileRevalidateMs: staleWhileRevalidateMs ?? null,
+    staleIfErrorMs: staleIfErrorMs ?? null
   };
 }
 function resolveStoredValue(stored, now = Date.now()) {
@@ -97,7 +97,7 @@ function unwrapStoredValue(stored) {
   }
   return stored.value ?? null;
 }
-function remainingStoredTtlSeconds(stored, now = Date.now()) {
+function remainingStoredTtlMs(stored, now = Date.now()) {
   if (!isStoredValueEnvelope(stored)) {
     return void 0;
   }
@@ -109,9 +109,9 @@ function remainingStoredTtlSeconds(stored, now = Date.now()) {
   if (remainingMs <= 0) {
     return 1;
   }
-  return Math.max(1, Math.ceil(remainingMs / 1e3));
+  return Math.max(1, Math.ceil(remainingMs));
 }
-function remainingFreshTtlSeconds(stored, now = Date.now()) {
+function remainingFreshTtlMs(stored, now = Date.now()) {
   if (!isStoredValueEnvelope(stored) || stored.freshUntil === null) {
     return void 0;
   }
@@ -119,7 +119,7 @@ function remainingFreshTtlSeconds(stored, now = Date.now()) {
   if (remainingMs <= 0) {
     return 0;
   }
-  return Math.max(1, Math.ceil(remainingMs / 1e3));
+  return Math.max(1, Math.ceil(remainingMs));
 }
 function refreshStoredEnvelope(stored, now = Date.now()) {
   if (!isStoredValueEnvelope(stored)) {
@@ -128,12 +128,23 @@ function refreshStoredEnvelope(stored, now = Date.now()) {
   return createStoredValueEnvelope({
     kind: stored.kind,
     value: stored.value,
-    freshTtlSeconds: stored.freshTtlSeconds ?? void 0,
-    staleWhileRevalidateSeconds: stored.staleWhileRevalidateSeconds ?? void 0,
-    staleIfErrorSeconds: stored.staleIfErrorSeconds ?? void 0,
+    freshTtlMs: stored.freshTtlMs ?? void 0,
+    staleWhileRevalidateMs: stored.staleWhileRevalidateMs ?? void 0,
+    staleIfErrorMs: stored.staleIfErrorMs ?? void 0,
     now
   });
 }
+function expireStoredEnvelope(stored, now = Date.now()) {
+  if (!isStoredValueEnvelope(stored)) {
+    return stored;
+  }
+  const futureDeadlines = [stored.staleUntil, stored.errorUntil].filter((value) => value !== null);
+  const freshUntil = futureDeadlines.length > 0 ? Math.min(now, ...futureDeadlines) : now;
+  return {
+    ...stored,
+    freshUntil
+  };
+}
 function maxExpiry(stored) {
   const values = [stored.freshUntil, stored.staleUntil, stored.errorUntil].filter(
     (value) => value !== null
@@ -143,17 +154,17 @@ function maxExpiry(stored) {
   }
   return Math.max(...values);
 }
-function normalizePositiveSeconds(value) {
+function normalizePositiveMs(value) {
   if (!value || value <= 0) {
     return void 0;
   }
   return value;
 }
-function isValidEnvelopeTtlSeconds(value, maxTtlSeconds) {
+function isValidEnvelopeTtlMs(value, maxTtlMs) {
   if (value == null) {
     return true;
   }
-  return typeof value === "number" && Number.isFinite(value) && value > 0 && value <= maxTtlSeconds;
+  return typeof value === "number" && Number.isFinite(value) && value > 0 && value <= maxTtlMs;
 }
 
 // src/invalidation/PatternMatcher.ts
@@ -209,8 +220,9 @@ export {
   createStoredValueEnvelope,
   resolveStoredValue,
   unwrapStoredValue,
-  remainingStoredTtlSeconds,
-  remainingFreshTtlSeconds,
+  remainingStoredTtlMs,
+  remainingFreshTtlMs,
   refreshStoredEnvelope,
+  expireStoredEnvelope,
   PatternMatcher
 };

package/dist/cli.cjs

@@ -121,17 +121,17 @@ function isStoredValueEnvelope(value) {
   if (typeof v.freshUntil === "number" && typeof v.errorUntil === "number" && v.errorUntil < v.freshUntil) {
     return false;
   }
-  const maxTtlSeconds = 10 * 365 * 24 * 60 * 60;
-  if (!isValidEnvelopeTtlSeconds(v.freshTtlSeconds, maxTtlSeconds)) {
+  const maxTtlMs = 10 * 365 * 24 * 60 * 60 * 1e3;
+  if (!isValidEnvelopeTtlMs(v.freshTtlMs, maxTtlMs)) {
     return false;
   }
-  if (!isValidEnvelopeTtlSeconds(v.staleWhileRevalidateSeconds, maxTtlSeconds)) {
+  if (!isValidEnvelopeTtlMs(v.staleWhileRevalidateMs, maxTtlMs)) {
     return false;
   }
-  if (!isValidEnvelopeTtlSeconds(v.staleIfErrorSeconds, maxTtlSeconds)) {
+  if (!isValidEnvelopeTtlMs(v.staleIfErrorMs, maxTtlMs)) {
     return false;
   }
-  if (v.freshTtlSeconds == null && (v.staleWhileRevalidateSeconds != null || v.staleIfErrorSeconds != null)) {
+  if (v.freshTtlMs == null && (v.staleWhileRevalidateMs != null || v.staleIfErrorMs != null)) {
     return false;
   }
   return true;
@@ -160,11 +160,11 @@ function unwrapStoredValue(stored) {
   }
   return stored.value ?? null;
 }
-function isValidEnvelopeTtlSeconds(value, maxTtlSeconds) {
+function isValidEnvelopeTtlMs(value, maxTtlMs) {
   if (value == null) {
     return true;
   }
-  return typeof value === "number" && Number.isFinite(value) && value > 0 && value <= maxTtlSeconds;
+  return typeof value === "number" && Number.isFinite(value) && value > 0 && value <= maxTtlMs;
 }
 
 // src/invalidation/PatternMatcher.ts
@@ -483,14 +483,14 @@ async function main(argv = process.argv.slice(2)) {
       }
       if (!validateCliInput(args.key, validateCacheKey)) return;
       const payload = await redis.getBuffer(args.key);
-      const ttl = await redis.ttl(args.key);
+      const ttl = await redis.pttl(args.key);
       const decoded = decodeInspectablePayload(payload);
       process.stdout.write(
         `${JSON.stringify(
           {
             key: args.key,
             exists: payload !== null,
-            ttlSeconds: ttl >= 0 ? ttl : null,
+            ttlMs: ttl >= 0 ? ttl : null,
             sizeBytes: payload?.byteLength ?? 0,
             isEnvelope: isStoredValueEnvelope(decoded),
             state: payload === null ? null : resolveStoredValue(decoded).state,

package/dist/cli.js

@@ -4,11 +4,11 @@ import {
   validateCacheKey,
   validatePattern,
   validateTag
-} from "./chunk-BORDQ3LA.js";
+} from "./chunk-7KMKQ6QZ.js";
 import {
   isStoredValueEnvelope,
   resolveStoredValue
-} from "./chunk-4PPBOOXT.js";
+} from "./chunk-KJDFYE5T.js";
 
 // src/cli.ts
 import Redis from "ioredis";
@@ -99,14 +99,14 @@ async function main(argv = process.argv.slice(2)) {
       }
       if (!validateCliInput(args.key, validateCacheKey)) return;
       const payload = await redis.getBuffer(args.key);
-      const ttl = await redis.ttl(args.key);
+      const ttl = await redis.pttl(args.key);
       const decoded = decodeInspectablePayload(payload);
       process.stdout.write(
         `${JSON.stringify(
           {
             key: args.key,
             exists: payload !== null,
-            ttlSeconds: ttl >= 0 ? ttl : null,
+            ttlMs: ttl >= 0 ? ttl : null,
             sizeBytes: payload?.byteLength ?? 0,
             isEnvelope: isStoredValueEnvelope(decoded),
             state: payload === null ? null : resolveStoredValue(decoded).state,