layercache 1.3.3 → 1.4.0

package/dist/index.cjs

@@ -248,6 +248,9 @@ var CacheNamespace = class _CacheNamespace {
   async invalidateByTag(tag) {
     await this.trackMetrics(() => this.cache.invalidateByTag(this.qualifyTag(tag)));
   }
+  async expireByTag(tag) {
+    await this.trackMetrics(() => this.cache.expireByTag(this.qualifyTag(tag)));
+  }
   async invalidateByTags(tags, mode = "any") {
     await this.trackMetrics(
       () => this.cache.invalidateByTags(
@@ -256,12 +259,26 @@ var CacheNamespace = class _CacheNamespace {
       )
     );
   }
+  async expireByTags(tags, mode = "any") {
+    await this.trackMetrics(
+      () => this.cache.expireByTags(
+        tags.map((tag) => this.qualifyTag(tag)),
+        mode
+      )
+    );
+  }
   async invalidateByPattern(pattern) {
     await this.trackMetrics(() => this.cache.invalidateByPattern(this.qualify(pattern)));
   }
+  async expireByPattern(pattern) {
+    await this.trackMetrics(() => this.cache.expireByPattern(this.qualify(pattern)));
+  }
   async invalidateByPrefix(prefix) {
     await this.trackMetrics(() => this.cache.invalidateByPrefix(this.qualify(prefix)));
   }
+  async expireByPrefix(prefix) {
+    await this.trackMetrics(() => this.cache.expireByPrefix(this.qualify(prefix)));
+  }
   /**
    * Returns detailed metadata about a single cache key within this namespace.
    */
@@ -602,68 +619,6 @@ function planGenerationCleanupBatches(keys, generationCleanup) {
   return batches;
 }
 
-// src/internal/CacheStackInvalidationSupport.ts
-var CacheStackInvalidationSupport = class {
-  constructor(options) {
-    this.options = options;
-  }
-  options;
-  async collectKeysForTag(tag, maxKeys) {
-    const keys = /* @__PURE__ */ new Set();
-    if (this.options.tagIndex.forEachKeyForTag) {
-      await this.options.tagIndex.forEachKeyForTag(tag, async (key) => {
-        keys.add(key);
-        this.assertWithinInvalidationKeyLimit(keys.size, maxKeys);
-      });
-      return [...keys];
-    }
-    for (const key of await this.options.tagIndex.keysForTag(tag)) {
-      keys.add(key);
-      this.assertWithinInvalidationKeyLimit(keys.size, maxKeys);
-    }
-    return [...keys];
-  }
-  intersectKeys(groups) {
-    if (groups.length === 0) {
-      return [];
-    }
-    const [firstGroup, ...rest] = groups;
-    const restSets = rest.map((group) => new Set(group));
-    return [...new Set(firstGroup)].filter((key) => restSets.every((group) => group.has(key)));
-  }
-  async deleteKeysFromLayers(layers, keys) {
-    await Promise.all(
-      layers.map(async (layer) => {
-        if (this.options.shouldSkipLayer(layer)) {
-          return;
-        }
-        if (layer.deleteMany) {
-          try {
-            await layer.deleteMany(keys);
-          } catch (error) {
-            await this.options.handleLayerFailure(layer, "delete", error);
-          }
-          return;
-        }
-        await Promise.all(
-          keys.map(async (key) => {
-            try {
-              await layer.delete(key);
-            } catch (error) {
-              await this.options.handleLayerFailure(layer, "delete", error);
-            }
-          })
-        );
-      })
-    );
-  }
-  assertWithinInvalidationKeyLimit(size, maxKeys) {
-    if (maxKeys !== false && size > maxKeys) {
-      throw new Error(`Invalidation matched too many keys (${size} > ${maxKeys}).`);
-    }
-  }
-};
-
 // src/internal/StoredValue.ts
 function isStoredValueEnvelope(value) {
   if (typeof value !== "object" || value === null) {
@@ -704,29 +659,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,
@@ -734,9 +689,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()) {
@@ -763,7 +718,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;
   }
@@ -775,9 +730,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;
   }
@@ -785,7 +740,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)) {
@@ -794,12 +749,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
@@ -809,19 +775,110 @@ 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/internal/CacheStackInvalidationSupport.ts
+var CacheStackInvalidationSupport = class {
+  constructor(options) {
+    this.options = options;
+  }
+  options;
+  async collectKeysForTag(tag, maxKeys) {
+    const keys = /* @__PURE__ */ new Set();
+    if (this.options.tagIndex.forEachKeyForTag) {
+      await this.options.tagIndex.forEachKeyForTag(tag, async (key) => {
+        keys.add(key);
+        this.assertWithinInvalidationKeyLimit(keys.size, maxKeys);
+      });
+      return [...keys];
+    }
+    for (const key of await this.options.tagIndex.keysForTag(tag)) {
+      keys.add(key);
+      this.assertWithinInvalidationKeyLimit(keys.size, maxKeys);
+    }
+    return [...keys];
+  }
+  intersectKeys(groups) {
+    if (groups.length === 0) {
+      return [];
+    }
+    const [firstGroup, ...rest] = groups;
+    const restSets = rest.map((group) => new Set(group));
+    return [...new Set(firstGroup)].filter((key) => restSets.every((group) => group.has(key)));
+  }
+  async deleteKeysFromLayers(layers, keys) {
+    await Promise.all(
+      layers.map(async (layer) => {
+        if (this.options.shouldSkipLayer(layer)) {
+          return;
+        }
+        if (layer.deleteMany) {
+          try {
+            await layer.deleteMany(keys);
+          } catch (error) {
+            await this.options.handleLayerFailure(layer, "delete", error);
+          }
+          return;
+        }
+        await Promise.all(
+          keys.map(async (key) => {
+            try {
+              await layer.delete(key);
+            } catch (error) {
+              await this.options.handleLayerFailure(layer, "delete", error);
+            }
+          })
+        );
+      })
+    );
+  }
+  async expireKeysInLayers(layers, keys) {
+    const foundKeys = /* @__PURE__ */ new Set();
+    await Promise.all(
+      layers.map(async (layer) => {
+        if (this.options.shouldSkipLayer(layer)) {
+          return;
+        }
+        await Promise.all(
+          keys.map(async (key) => {
+            try {
+              const stored = layer.getEntry ? await layer.getEntry(key) : await layer.get(key);
+              if (stored === null) {
+                return;
+              }
+              foundKeys.add(key);
+              const expired = expireStoredEnvelope(stored);
+              if (expired === stored) {
+                return;
+              }
+              await layer.set(key, expired, remainingStoredTtlMs(expired));
+            } catch (error) {
+              await this.options.handleLayerFailure(layer, "expire", error);
+            }
+          })
+        );
+      })
+    );
+    return foundKeys;
+  }
+  assertWithinInvalidationKeyLimit(size, maxKeys) {
+    if (maxKeys !== false && size > maxKeys) {
+      throw new Error(`Invalidation matched too many keys (${size} > ${maxKeys}).`);
+    }
+  }
+};
+
 // src/internal/CacheStackLayerWriter.ts
 var CacheStackLayerWriter = class {
   constructor(options) {
@@ -933,12 +990,12 @@ var CacheStackLayerWriter = class {
   }
   buildLayerSetEntry(layer, key, kind, value, writeOptions, now) {
     const freshTtl = this.options.resolveFreshTtl(key, layer.name, kind, writeOptions, layer.defaultTtl, value);
-    const staleWhileRevalidate = this.options.resolveLayerSeconds(
+    const staleWhileRevalidate = this.options.resolveLayerMs(
       layer.name,
       writeOptions?.staleWhileRevalidate,
       this.options.globalStaleWhileRevalidate
     );
-    const staleIfError = this.options.resolveLayerSeconds(
+    const staleIfError = this.options.resolveLayerMs(
       layer.name,
       writeOptions?.staleIfError,
       this.options.globalStaleIfError
@@ -946,12 +1003,12 @@ var CacheStackLayerWriter = class {
     const payload = createStoredValueEnvelope({
       kind,
       value,
-      freshTtlSeconds: freshTtl,
-      staleWhileRevalidateSeconds: staleWhileRevalidate,
-      staleIfErrorSeconds: staleIfError,
+      freshTtlMs: freshTtl,
+      staleWhileRevalidateMs: staleWhileRevalidate,
+      staleIfErrorMs: staleIfError,
       now
     });
-    const ttl = remainingStoredTtlSeconds(payload, now) ?? freshTtl;
+    const ttl = remainingStoredTtlMs(payload, now) ?? freshTtl;
     return {
       key,
       value: payload,
@@ -1094,18 +1151,420 @@ function planFreshReadPolicies({
   stored,
   hasFetcher,
   slidingTtl,
-  refreshAheadSeconds
+  refreshAheadMs
 }) {
   const refreshedStored = slidingTtl && isStoredValueEnvelope(stored) ? refreshStoredEnvelope(stored) : void 0;
-  const refreshedStoredTtl = refreshedStored ? remainingStoredTtlSeconds(refreshedStored) ?? void 0 : void 0;
-  const remainingFreshTtl = remainingFreshTtlSeconds(stored) ?? 0;
+  const refreshedStoredTtl = refreshedStored ? remainingStoredTtlMs(refreshedStored) ?? void 0 : void 0;
+  const remainingFreshTtl = remainingFreshTtlMs(stored) ?? 0;
   return {
     refreshedStored,
     refreshedStoredTtl,
-    shouldScheduleBackgroundRefresh: hasFetcher && refreshAheadSeconds > 0 && remainingFreshTtl > 0 && remainingFreshTtl <= refreshAheadSeconds
+    shouldScheduleBackgroundRefresh: hasFetcher && refreshAheadMs > 0 && remainingFreshTtl > 0 && remainingFreshTtl <= refreshAheadMs
   };
 }
 
+// src/internal/CacheStackReader.ts
+var DEFAULT_SINGLE_FLIGHT_LEASE_MS = 3e4;
+var DEFAULT_SINGLE_FLIGHT_TIMEOUT_MS = 5e3;
+var DEFAULT_SINGLE_FLIGHT_POLL_MS = 50;
+var DEFAULT_BACKGROUND_REFRESH_TIMEOUT_MS = 3e4;
+var CacheStackReader = class {
+  constructor(options) {
+    this.options = options;
+  }
+  options;
+  backgroundRefreshes = /* @__PURE__ */ new Map();
+  backgroundRefreshAbort = /* @__PURE__ */ new Map();
+  get activeRefreshCount() {
+    return this.backgroundRefreshes.size;
+  }
+  async getPrepared(normalizedKey, fetcher, options) {
+    const hit = await this.readFromLayers(normalizedKey, options, "allow-stale");
+    if (hit.found) {
+      this.options.ttlResolver.recordAccess(normalizedKey);
+      if (this.isNegativeStoredValue(hit.stored)) {
+        this.options.metricsCollector.increment("negativeCacheHits");
+      }
+      if (hit.state === "fresh") {
+        this.options.metricsCollector.increment("hits");
+        await this.applyFreshReadPolicies(normalizedKey, hit, options, fetcher);
+        return hit.value;
+      }
+      if (hit.state === "stale-while-revalidate") {
+        this.options.metricsCollector.increment("hits");
+        this.options.metricsCollector.increment("staleHits");
+        this.options.emit("stale-serve", { key: normalizedKey, state: hit.state, layer: hit.layerName });
+        if (fetcher) {
+          this.scheduleBackgroundRefresh(normalizedKey, fetcher, options, this.createFetcherContext(normalizedKey, hit));
+        }
+        return hit.value;
+      }
+      if (!fetcher) {
+        this.options.metricsCollector.increment("hits");
+        this.options.metricsCollector.increment("staleHits");
+        this.options.emit("stale-serve", { key: normalizedKey, state: hit.state, layer: hit.layerName });
+        return hit.value;
+      }
+      try {
+        return await this.fetchWithGuards(
+          normalizedKey,
+          fetcher,
+          options,
+          void 0,
+          void 0,
+          false,
+          this.createFetcherContext(normalizedKey, hit)
+        );
+      } catch (error) {
+        this.options.metricsCollector.increment("staleHits");
+        this.options.metricsCollector.increment("refreshErrors");
+        this.options.logger.debug?.("stale-if-error", {
+          key: normalizedKey,
+          error: this.options.formatError(error)
+        });
+        return hit.value;
+      }
+    }
+    this.options.metricsCollector.increment("misses");
+    if (!fetcher) {
+      return null;
+    }
+    return this.fetchWithGuards(normalizedKey, fetcher, options, void 0, void 0, true, {
+      key: normalizedKey,
+      currentValue: void 0,
+      state: "miss"
+    });
+  }
+  async readLayerEntry(layer, key) {
+    if (this.options.shouldSkipLayer(layer)) {
+      return null;
+    }
+    if (layer.getEntry) {
+      try {
+        return await layer.getEntry(key);
+      } catch (error) {
+        return this.options.handleLayerFailure(layer, "read", error);
+      }
+    }
+    try {
+      return await layer.get(key);
+    } catch (error) {
+      return this.options.handleLayerFailure(layer, "read", error);
+    }
+  }
+  async backfill(key, stored, upToIndex, options) {
+    if (upToIndex < 0) {
+      return;
+    }
+    for (let index = 0; index <= upToIndex; index += 1) {
+      const layer = this.options.layers[index];
+      if (!layer || this.options.shouldSkipLayer(layer)) {
+        continue;
+      }
+      const ttl = remainingStoredTtlMs(stored) ?? this.options.resolveLayerMs(layer.name, options?.ttl, void 0, layer.defaultTtl);
+      try {
+        await layer.set(key, stored, ttl);
+      } catch (error) {
+        await this.options.handleLayerFailure(layer, "backfill", error);
+        continue;
+      }
+      this.options.metricsCollector.increment("backfills");
+      this.options.logger.debug?.("backfill", { key, layer: layer.name });
+      this.options.emit("backfill", { key, layer: layer.name });
+    }
+  }
+  abortAllRefreshes() {
+    for (const key of this.backgroundRefreshAbort.keys()) {
+      this.backgroundRefreshAbort.set(key, true);
+    }
+  }
+  getAllRefreshPromises() {
+    return [...this.backgroundRefreshes.values()];
+  }
+  async readFromLayers(key, options, mode) {
+    let sawRetainableValue = false;
+    for (let index = 0; index < this.options.layers.length; index += 1) {
+      const layer = this.options.layers[index];
+      if (!layer) continue;
+      const readStart = performance.now();
+      const stored = await this.readLayerEntry(layer, key);
+      const readDuration = performance.now() - readStart;
+      this.options.metricsCollector.recordLatency(layer.name, readDuration);
+      if (stored === null) {
+        this.options.metricsCollector.incrementLayer("missesByLayer", layer.name);
+        continue;
+      }
+      const resolved = resolveStoredValue(stored);
+      if (resolved.state === "expired") {
+        await layer.delete(key);
+        continue;
+      }
+      sawRetainableValue = true;
+      if (mode === "fresh-only" && resolved.state !== "fresh") {
+        continue;
+      }
+      await this.options.tagIndex.touch(key);
+      await this.backfill(key, stored, index - 1, options);
+      this.options.metricsCollector.incrementLayer("hitsByLayer", layer.name);
+      this.options.logger.debug?.("hit", { key, layer: layer.name, state: resolved.state });
+      this.options.emit("hit", {
+        key,
+        layer: layer.name,
+        state: resolved.state
+      });
+      return {
+        found: true,
+        value: resolved.value,
+        stored,
+        state: resolved.state,
+        layerIndex: index,
+        layerName: layer.name
+      };
+    }
+    if (!sawRetainableValue) {
+      await this.options.tagIndex.remove(key);
+    }
+    this.options.logger.debug?.("miss", { key, mode });
+    this.options.emit("miss", { key, mode });
+    return { found: false, value: null, stored: null, state: "miss" };
+  }
+  async fetchWithGuards(key, fetcher, options, expectedClearEpoch, expectedKeyEpoch, initialMissConfirmed = false, fetcherContext = {
+    key,
+    currentValue: void 0,
+    state: "miss"
+  }) {
+    const fetchTask = async () => {
+      const shouldRecheckFreshLayers = !(initialMissConfirmed && this.options.singleFlightCoordinator);
+      if (shouldRecheckFreshLayers) {
+        const secondHit = await this.readFromLayers(key, options, "fresh-only");
+        if (secondHit.found) {
+          this.options.metricsCollector.increment("hits");
+          return secondHit.value;
+        }
+      }
+      return this.fetchAndPopulate(key, fetcher, options, expectedClearEpoch, expectedKeyEpoch, fetcherContext);
+    };
+    const singleFlightTask = async () => {
+      if (!this.options.singleFlightCoordinator) {
+        return fetchTask();
+      }
+      try {
+        return await this.options.singleFlightCoordinator.execute(
+          key,
+          this.resolveSingleFlightOptions(),
+          fetchTask,
+          () => this.waitForFreshValue(key, fetcher, options, expectedClearEpoch, expectedKeyEpoch, fetcherContext)
+        );
+      } catch (error) {
+        if (!this.options.isGracefulDegradationEnabled()) {
+          throw error;
+        }
+        this.options.metricsCollector.increment("degradedOperations");
+        this.options.logger.warn?.("single-flight-coordinator-degraded", {
+          key,
+          error: this.options.formatError(error)
+        });
+        this.options.emitError("single-flight", {
+          key,
+          degraded: true,
+          error: this.options.formatError(error)
+        });
+        return fetchTask();
+      }
+    };
+    if (this.options.stampedePrevention === false) {
+      return singleFlightTask();
+    }
+    return this.options.stampedeGuard.execute(key, singleFlightTask);
+  }
+  async waitForFreshValue(key, fetcher, options, expectedClearEpoch, expectedKeyEpoch, fetcherContext = {
+    key,
+    currentValue: void 0,
+    state: "miss"
+  }) {
+    const timeoutMs = this.options.singleFlightTimeoutMs ?? DEFAULT_SINGLE_FLIGHT_TIMEOUT_MS;
+    const pollIntervalMs = this.options.singleFlightPollMs ?? DEFAULT_SINGLE_FLIGHT_POLL_MS;
+    const deadline = Date.now() + timeoutMs;
+    this.options.metricsCollector.increment("singleFlightWaits");
+    this.options.emit("stampede-dedupe", { key });
+    while (Date.now() < deadline) {
+      const hit = await this.readFromLayers(key, options, "fresh-only");
+      if (hit.found) {
+        this.options.metricsCollector.increment("hits");
+        return hit.value;
+      }
+      await this.options.sleep(pollIntervalMs);
+    }
+    return this.fetchAndPopulate(key, fetcher, options, expectedClearEpoch, expectedKeyEpoch, fetcherContext);
+  }
+  async fetchAndPopulate(key, fetcher, options, expectedClearEpoch, expectedKeyEpoch, fetcherContext = {
+    key,
+    currentValue: void 0,
+    state: "miss"
+  }) {
+    this.options.circuitBreakerManager.assertClosed(key, options?.circuitBreaker ?? this.options.circuitBreaker);
+    this.options.metricsCollector.increment("fetches");
+    const fetchStart = Date.now();
+    let fetched;
+    try {
+      fetched = await this.options.fetchRateLimiter.schedule(
+        options?.fetcherRateLimit ?? this.options.fetcherRateLimit,
+        { key, fetcher },
+        () => fetcher(fetcherContext)
+      );
+      this.options.circuitBreakerManager.recordSuccess(key);
+      this.options.logger.debug?.("fetch", { key, durationMs: Date.now() - fetchStart });
+    } catch (error) {
+      this.options.recordCircuitFailure(key, options?.circuitBreaker ?? this.options.circuitBreaker, error);
+      throw error;
+    }
+    if (fetched === null || fetched === void 0) {
+      if (!this.shouldNegativeCache(options)) {
+        return null;
+      }
+      if (this.options.maintenance.isWriteOutdated(key, expectedClearEpoch, expectedKeyEpoch)) {
+        this.options.logger.debug?.("skip-negative-store-after-invalidation", {
+          key,
+          expectedClearEpoch,
+          clearEpoch: this.options.maintenance.currentClearEpoch(),
+          expectedKeyEpoch,
+          keyEpoch: this.options.maintenance.currentKeyEpoch(key)
+        });
+        return null;
+      }
+      await this.options.storeEntry(key, "empty", null, options);
+      return null;
+    }
+    if (options?.shouldCache) {
+      try {
+        if (!options.shouldCache(fetched)) {
+          return fetched;
+        }
+      } catch (error) {
+        this.options.logger.warn?.("shouldCache-error", {
+          key,
+          error: this.options.formatError(error)
+        });
+      }
+    }
+    if (this.options.maintenance.isWriteOutdated(key, expectedClearEpoch, expectedKeyEpoch)) {
+      this.options.logger.debug?.("skip-store-after-invalidation", {
+        key,
+        expectedClearEpoch,
+        clearEpoch: this.options.maintenance.currentClearEpoch(),
+        expectedKeyEpoch,
+        keyEpoch: this.options.maintenance.currentKeyEpoch(key)
+      });
+      return fetched;
+    }
+    await this.options.storeEntry(key, "value", fetched, options);
+    return fetched;
+  }
+  runScheduleBackgroundRefresh(key, fetcher, options, fetcherContext) {
+    this.scheduleBackgroundRefresh(key, fetcher, options, fetcherContext);
+  }
+  scheduleBackgroundRefresh(key, fetcher, options, fetcherContext = {
+    key,
+    currentValue: void 0,
+    state: "miss"
+  }) {
+    if (!shouldStartBackgroundRefresh({
+      isDisconnecting: this.options.isDisconnecting(),
+      hasRefreshInFlight: this.backgroundRefreshes.has(key)
+    })) {
+      return;
+    }
+    const clearEpoch = this.options.maintenance.currentClearEpoch();
+    const keyEpoch = this.options.maintenance.currentKeyEpoch(key);
+    this.backgroundRefreshAbort.set(key, false);
+    const refresh = (async () => {
+      this.options.metricsCollector.increment("refreshes");
+      try {
+        if (this.backgroundRefreshAbort.get(key)) return;
+        await this.runBackgroundRefresh(key, fetcher, options, clearEpoch, keyEpoch, fetcherContext);
+      } catch (error) {
+        if (this.backgroundRefreshAbort.get(key)) return;
+        this.options.metricsCollector.increment("refreshErrors");
+        this.options.logger.warn?.("background-refresh-error", {
+          key,
+          error: this.options.formatError(error)
+        });
+      } finally {
+        this.backgroundRefreshes.delete(key);
+        this.backgroundRefreshAbort.delete(key);
+      }
+    })();
+    this.backgroundRefreshes.set(key, refresh);
+  }
+  async runBackgroundRefresh(key, fetcher, options, expectedClearEpoch, expectedKeyEpoch, fetcherContext = {
+    key,
+    currentValue: void 0,
+    state: "miss"
+  }) {
+    const timeoutMs = this.options.backgroundRefreshTimeoutMs ?? DEFAULT_BACKGROUND_REFRESH_TIMEOUT_MS;
+    await this.fetchWithGuards(
+      key,
+      (context) => this.options.withTimeout(fetcher(context), timeoutMs, () => {
+        return new Error(`Background refresh timed out after ${timeoutMs}ms for key "${key}".`);
+      }),
+      options,
+      expectedClearEpoch,
+      expectedKeyEpoch,
+      false,
+      fetcherContext
+    );
+  }
+  async runApplyFreshReadPolicies(key, hit, options, fetcher) {
+    return this.applyFreshReadPolicies(key, hit, options, fetcher);
+  }
+  async applyFreshReadPolicies(key, hit, options, fetcher) {
+    const plan = planFreshReadPolicies({
+      stored: hit.stored,
+      hasFetcher: Boolean(fetcher),
+      slidingTtl: options?.slidingTtl ?? false,
+      refreshAheadMs: this.options.resolveLayerMs(hit.layerName, options?.refreshAhead, this.options.refreshAhead, 0) ?? 0
+    });
+    if (plan.refreshedStored) {
+      for (let index = 0; index <= hit.layerIndex; index += 1) {
+        const layer = this.options.layers[index];
+        if (!layer || this.options.shouldSkipLayer(layer)) {
+          continue;
+        }
+        try {
+          await layer.set(key, plan.refreshedStored, plan.refreshedStoredTtl);
+        } catch (error) {
+          await this.options.handleLayerFailure(layer, "sliding-ttl", error);
+        }
+      }
+    }
+    if (fetcher && plan.shouldScheduleBackgroundRefresh) {
+      this.options.scheduleBackgroundRefreshDispatch(key, fetcher, options, this.createFetcherContext(key, hit));
+    }
+  }
+  createFetcherContext(key, hit) {
+    return {
+      key,
+      currentValue: hit.value === null ? void 0 : hit.value,
+      state: hit.state,
+      layer: hit.layerName
+    };
+  }
+  resolveSingleFlightOptions() {
+    return {
+      leaseMs: this.options.singleFlightLeaseMs ?? DEFAULT_SINGLE_FLIGHT_LEASE_MS,
+      waitTimeoutMs: this.options.singleFlightTimeoutMs ?? DEFAULT_SINGLE_FLIGHT_TIMEOUT_MS,
+      pollIntervalMs: this.options.singleFlightPollMs ?? DEFAULT_SINGLE_FLIGHT_POLL_MS,
+      renewIntervalMs: this.options.singleFlightRenewIntervalMs
+    };
+  }
+  shouldNegativeCache(options) {
+    return options?.negativeCache ?? this.options.negativeCaching ?? false;
+  }
+  isNegativeStoredValue(stored) {
+    return isStoredValueEnvelope(stored) && stored.kind === "empty";
+  }
+};
+
 // src/internal/CacheStackSnapshotManager.ts
 var import_node_fs = require("fs");
 
@@ -1371,7 +1830,7 @@ var CacheStackSnapshotManager = class {
         await visitor({
           key: exportedKey,
           value: stored,
-          ttl: remainingStoredTtlSeconds(stored)
+          ttl: remainingStoredTtlMs(stored)
         });
       };
       if (layer.forEachKey) {
@@ -1527,6 +1986,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/internal/CircuitBreakerManager.ts
 var CircuitBreakerManager = class {
@@ -1959,7 +2431,7 @@ var MetricsCollector = class {
 
 // src/internal/TtlResolver.ts
 var import_node_crypto2 = require("crypto");
-var DEFAULT_NEGATIVE_TTL_SECONDS = 60;
+var DEFAULT_NEGATIVE_TTL_MS = 6e4;
 var secureRandom = {
   value() {
     return (0, import_node_crypto2.randomBytes)(4).readUInt32BE(0) / 4294967296;
@@ -1986,17 +2458,17 @@ var TtlResolver = class {
   }
   resolveFreshTtl(key, layerName, kind, options, fallbackTtl, globalNegativeTtl, globalTtl, value) {
     const policyTtl = kind === "value" ? this.resolvePolicyTtl(key, value, options?.ttlPolicy) : void 0;
-    const baseTtl = kind === "empty" ? this.resolveLayerSeconds(
+    const baseTtl = kind === "empty" ? this.resolveLayerMs(
       layerName,
       options?.negativeTtl,
       globalNegativeTtl,
-      this.resolveLayerSeconds(layerName, options?.ttl, globalTtl, policyTtl ?? fallbackTtl) ?? DEFAULT_NEGATIVE_TTL_SECONDS
-    ) : this.resolveLayerSeconds(layerName, options?.ttl, globalTtl, policyTtl ?? fallbackTtl);
+      this.resolveLayerMs(layerName, options?.ttl, globalTtl, policyTtl ?? fallbackTtl) ?? DEFAULT_NEGATIVE_TTL_MS
+    ) : this.resolveLayerMs(layerName, options?.ttl, globalTtl, policyTtl ?? fallbackTtl);
     const adaptiveTtl = this.applyAdaptiveTtl(key, layerName, baseTtl, options?.adaptiveTtl);
-    const jitter = this.resolveLayerSeconds(layerName, options?.ttlJitter, void 0);
+    const jitter = this.resolveLayerMs(layerName, options?.ttlJitter, void 0);
     return this.applyJitter(adaptiveTtl, jitter);
   }
-  resolveLayerSeconds(layerName, override, globalDefault, fallback) {
+  resolveLayerMs(layerName, override, globalDefault, fallback) {
     if (override !== void 0) {
       return this.readLayerNumber(layerName, override) ?? fallback;
     }
@@ -2018,8 +2490,8 @@ var TtlResolver = class {
     if (profile.hits < hotAfter) {
       return ttl;
     }
-    const step = this.resolveLayerSeconds(layerName, config.step, void 0, Math.max(1, Math.round(ttl / 2))) ?? 0;
-    const maxTtl = this.resolveLayerSeconds(layerName, config.maxTtl, void 0, ttl + step * 4) ?? ttl;
+    const step = this.resolveLayerMs(layerName, config.step, void 0, Math.max(1, Math.round(ttl / 2))) ?? 0;
+    const maxTtl = this.resolveLayerMs(layerName, config.maxTtl, void 0, ttl + step * 4) ?? ttl;
     const multiplier = Math.floor(profile.hits / hotAfter);
     return Math.min(maxTtl, ttl + step * multiplier);
   }
@@ -2041,17 +2513,17 @@ var TtlResolver = class {
     if (policy === "until-midnight") {
       const nextMidnight = new Date(now);
       nextMidnight.setHours(24, 0, 0, 0);
-      return Math.max(1, Math.ceil((nextMidnight.getTime() - now.getTime()) / 1e3));
+      return Math.max(1, Math.ceil(nextMidnight.getTime() - now.getTime()));
     }
     if (policy === "next-hour") {
       const nextHour = new Date(now);
       nextHour.setMinutes(60, 0, 0);
-      return Math.max(1, Math.ceil((nextHour.getTime() - now.getTime()) / 1e3));
+      return Math.max(1, Math.ceil(nextHour.getTime() - now.getTime()));
     }
-    const alignToSeconds = policy.alignTo;
-    const currentSeconds = Math.floor(Date.now() / 1e3);
-    const nextBoundary = Math.ceil((currentSeconds + 1) / alignToSeconds) * alignToSeconds;
-    return Math.max(1, nextBoundary - currentSeconds);
+    const alignToMs = policy.alignTo;
+    const currentMs = Date.now();
+    const nextBoundary = Math.ceil((currentMs + 1) / alignToMs) * alignToMs;
+    return Math.max(1, nextBoundary - currentMs);
   }
   readLayerNumber(layerName, value) {
     if (typeof value === "number") {
@@ -2423,10 +2895,6 @@ var CacheMissError = class extends Error {
 };
 
 // src/CacheStack.ts
-var DEFAULT_SINGLE_FLIGHT_LEASE_MS = 3e4;
-var DEFAULT_SINGLE_FLIGHT_TIMEOUT_MS = 5e3;
-var DEFAULT_SINGLE_FLIGHT_POLL_MS = 50;
-var DEFAULT_BACKGROUND_REFRESH_TIMEOUT_MS = 3e4;
 var DEFAULT_SNAPSHOT_MAX_BYTES = 16 * 1024 * 1024;
 var DEFAULT_SNAPSHOT_MAX_ENTRIES = 1e4;
 var DEFAULT_INVALIDATION_MAX_KEYS = 1e4;
@@ -2506,7 +2974,7 @@ var CacheStack = class extends import_node_events.EventEmitter {
       },
       enqueueWriteBehind: this.enqueueWriteBehind.bind(this),
       resolveFreshTtl: this.resolveFreshTtl.bind(this),
-      resolveLayerSeconds: this.resolveLayerSeconds.bind(this),
+      resolveLayerMs: this.resolveLayerMs.bind(this),
       globalStaleWhileRevalidate: this.options.staleWhileRevalidate,
       globalStaleIfError: this.options.staleIfError,
       writePolicy: this.options.writePolicy,
@@ -2537,7 +3005,7 @@ var CacheStack = class extends import_node_events.EventEmitter {
       layers: this.layers,
       tagIndex: this.tagIndex,
       snapshotSerializer: this.snapshotSerializer,
-      readLayerEntry: this.readLayerEntry.bind(this),
+      readLayerEntry: (layer, key) => this.reader.readLayerEntry(layer, key),
       shouldSkipLayer: (layer) => this.shouldSkipLayer(layer),
       handleLayerFailure: async (layer, operation, error) => this.handleLayerFailure(layer, operation, error),
       qualifyKey: this.qualifyKey.bind(this),
@@ -2545,6 +3013,41 @@ var CacheStack = class extends import_node_events.EventEmitter {
       validateCacheKey,
       formatError: this.formatError.bind(this)
     });
+    this.reader = new CacheStackReader({
+      layers: this.layers,
+      metricsCollector: this.metricsCollector,
+      maintenance: this.maintenance,
+      tagIndex: this.tagIndex,
+      circuitBreakerManager: this.circuitBreakerManager,
+      fetchRateLimiter: this.fetchRateLimiter,
+      stampedeGuard: this.stampedeGuard,
+      ttlResolver: this.ttlResolver,
+      logger: this.logger,
+      shouldSkipLayer: (layer) => this.shouldSkipLayer(layer),
+      handleLayerFailure: async (layer, operation, error) => this.handleLayerFailure(layer, operation, error),
+      emit: (event, data) => this.emit(event, data),
+      emitError: (operation, context) => this.emitError(operation, context),
+      formatError: (error) => this.formatError(error),
+      storeEntry: (key, kind, value, options2) => this.storeEntry(key, kind, value, options2),
+      recordCircuitFailure: (key, options2, error) => this.recordCircuitFailure(key, options2, error),
+      resolveLayerMs: (layerName, override, globalDefault, fallback) => this.resolveLayerMs(layerName, override, globalDefault, fallback),
+      sleep: (ms) => this.sleep(ms),
+      withTimeout: (promise, ms, createError) => this.withTimeout(promise, ms, createError),
+      isDisconnecting: () => this.isDisconnecting,
+      isGracefulDegradationEnabled: () => this.isGracefulDegradationEnabled(),
+      scheduleBackgroundRefreshDispatch: (key, fetcher, options2, fetcherContext) => this.scheduleBackgroundRefresh(key, fetcher, options2, fetcherContext),
+      stampedePrevention: options.stampedePrevention,
+      singleFlightCoordinator: options.singleFlightCoordinator,
+      singleFlightLeaseMs: options.singleFlightLeaseMs,
+      singleFlightTimeoutMs: options.singleFlightTimeoutMs,
+      singleFlightPollMs: options.singleFlightPollMs,
+      singleFlightRenewIntervalMs: options.singleFlightRenewIntervalMs,
+      backgroundRefreshTimeoutMs: options.backgroundRefreshTimeoutMs,
+      negativeCaching: options.negativeCaching,
+      refreshAhead: options.refreshAhead,
+      circuitBreaker: options.circuitBreaker,
+      fetcherRateLimit: options.fetcherRateLimit
+    });
     this.initializeWriteBehind(options.writeBehind);
     this.startup = this.initialize();
   }
@@ -2563,8 +3066,6 @@ var CacheStack = class extends import_node_events.EventEmitter {
   invalidation;
   layerWriter;
   snapshots;
-  backgroundRefreshes = /* @__PURE__ */ new Map();
-  backgroundRefreshAbort = /* @__PURE__ */ new Map();
   layerDegradedUntil = /* @__PURE__ */ new Map();
   maintenance = new CacheStackMaintenance();
   ttlResolver;
@@ -2572,6 +3073,7 @@ var CacheStack = class extends import_node_events.EventEmitter {
   nextOperationId = 0;
   currentGeneration;
   isDisconnecting = false;
+  reader;
   disconnectPromise;
   /**
    * Read-through cache get.
@@ -2584,51 +3086,9 @@ var CacheStack = class extends import_node_events.EventEmitter {
       const normalizedKey = this.qualifyKey(validateCacheKey(key));
       this.validateWriteOptions(options);
       await this.awaitStartup("get");
-      return this.getPrepared(normalizedKey, fetcher, options);
+      return this.reader.getPrepared(normalizedKey, fetcher, options);
     });
   }
-  async getPrepared(normalizedKey, fetcher, options) {
-    const hit = await this.readFromLayers(normalizedKey, options, "allow-stale");
-    if (hit.found) {
-      this.ttlResolver.recordAccess(normalizedKey);
-      if (this.isNegativeStoredValue(hit.stored)) {
-        this.metricsCollector.increment("negativeCacheHits");
-      }
-      if (hit.state === "fresh") {
-        this.metricsCollector.increment("hits");
-        await this.applyFreshReadPolicies(normalizedKey, hit, options, fetcher);
-        return hit.value;
-      }
-      if (hit.state === "stale-while-revalidate") {
-        this.metricsCollector.increment("hits");
-        this.metricsCollector.increment("staleHits");
-        this.emit("stale-serve", { key: normalizedKey, state: hit.state, layer: hit.layerName });
-        if (fetcher) {
-          this.scheduleBackgroundRefresh(normalizedKey, fetcher, options);
-        }
-        return hit.value;
-      }
-      if (!fetcher) {
-        this.metricsCollector.increment("hits");
-        this.metricsCollector.increment("staleHits");
-        this.emit("stale-serve", { key: normalizedKey, state: hit.state, layer: hit.layerName });
-        return hit.value;
-      }
-      try {
-        return await this.fetchWithGuards(normalizedKey, fetcher, options);
-      } catch (error) {
-        this.metricsCollector.increment("staleHits");
-        this.metricsCollector.increment("refreshErrors");
-        this.logger.debug?.("stale-if-error", { key: normalizedKey, error: this.formatError(error) });
-        return hit.value;
-      }
-    }
-    this.metricsCollector.increment("misses");
-    if (!fetcher) {
-      return null;
-    }
-    return this.fetchWithGuards(normalizedKey, fetcher, options, void 0, void 0, true);
-  }
   /**
    * Alias for `get(key, fetcher, options)` — explicit get-or-set pattern.
    * Fetches and caches the value if not already present.
@@ -2681,7 +3141,7 @@ var CacheStack = class extends import_node_events.EventEmitter {
     return false;
   }
   /**
-   * Returns the remaining TTL in seconds for the key in the fastest layer
+   * Returns the remaining TTL in milliseconds for the key in the fastest layer
    * that has it, or null if the key is not found / has no TTL.
    */
   async ttl(key) {
@@ -2779,7 +3239,7 @@ var CacheStack = class extends import_node_events.EventEmitter {
             const optionsSignature = serializeOptions(entry.options);
             const existing = pendingReads.get(entry.key);
             if (!existing) {
-              const promise = this.getPrepared(entry.key, entry.fetch, entry.options);
+              const promise = this.reader.getPrepared(entry.key, entry.fetch, entry.options);
               pendingReads.set(entry.key, {
                 promise,
                 fetch: entry.fetch,
@@ -2815,7 +3275,7 @@ var CacheStack = class extends import_node_events.EventEmitter {
         if (keys.length === 0) {
           break;
         }
-        const values = layer.getMany ? await layer.getMany(keys) : await Promise.all(keys.map((key) => this.readLayerEntry(layer, key)));
+        const values = layer.getMany ? await layer.getMany(keys) : await Promise.all(keys.map((key) => this.reader.readLayerEntry(layer, key)));
         for (let offset = 0; offset < values.length; offset += 1) {
           const key = keys[offset];
           const stored = values[offset];
@@ -2831,7 +3291,7 @@ var CacheStack = class extends import_node_events.EventEmitter {
             this.metricsCollector.increment("staleHits", indexesByKey.get(key)?.length ?? 1);
           }
           await this.tagIndex.touch(key);
-          await this.backfill(key, stored, layerIndex - 1);
+          await this.reader.backfill(key, stored, layerIndex - 1);
           resultsByKey.set(key, resolved.value);
           pending.delete(key);
           this.metricsCollector.increment("hits", indexesByKey.get(key)?.length ?? 1);
@@ -2917,20 +3377,45 @@ var CacheStack = class extends import_node_events.EventEmitter {
       await this.publishInvalidation({ scope: "keys", keys, sourceId: this.instanceId, operation: "invalidate" });
     });
   }
-  async invalidateByTags(tags, mode = "any") {
-    await this.observeOperation("layercache.invalidate_by_tags", void 0, async () => {
+  async expireByTag(tag) {
+    await this.observeOperation("layercache.expire_by_tag", void 0, async () => {
+      validateTag(tag);
+      await this.awaitStartup("expireByTag");
+      const keys = await this.invalidation.collectKeysForTag(tag, this.invalidationMaxKeys());
+      await this.expireKeys(keys);
+      await this.publishInvalidation({ scope: "keys", keys, sourceId: this.instanceId, operation: "expire" });
+    });
+  }
+  async invalidateByTags(tags, mode = "any") {
+    await this.observeOperation("layercache.invalidate_by_tags", void 0, async () => {
+      if (tags.length === 0) {
+        return;
+      }
+      validateTags(tags);
+      await this.awaitStartup("invalidateByTags");
+      const keysByTag = await Promise.all(
+        tags.map((tag) => this.invalidation.collectKeysForTag(tag, this.invalidationMaxKeys()))
+      );
+      const keys = mode === "all" ? this.invalidation.intersectKeys(keysByTag) : [...new Set(keysByTag.flat())];
+      this.invalidation.assertWithinInvalidationKeyLimit(keys.length, this.invalidationMaxKeys());
+      await this.deleteKeys(keys);
+      await this.publishInvalidation({ scope: "keys", keys, sourceId: this.instanceId, operation: "invalidate" });
+    });
+  }
+  async expireByTags(tags, mode = "any") {
+    await this.observeOperation("layercache.expire_by_tags", void 0, async () => {
       if (tags.length === 0) {
         return;
       }
       validateTags(tags);
-      await this.awaitStartup("invalidateByTags");
+      await this.awaitStartup("expireByTags");
       const keysByTag = await Promise.all(
         tags.map((tag) => this.invalidation.collectKeysForTag(tag, this.invalidationMaxKeys()))
       );
       const keys = mode === "all" ? this.invalidation.intersectKeys(keysByTag) : [...new Set(keysByTag.flat())];
       this.invalidation.assertWithinInvalidationKeyLimit(keys.length, this.invalidationMaxKeys());
-      await this.deleteKeys(keys);
-      await this.publishInvalidation({ scope: "keys", keys, sourceId: this.instanceId, operation: "invalidate" });
+      await this.expireKeys(keys);
+      await this.publishInvalidation({ scope: "keys", keys, sourceId: this.instanceId, operation: "expire" });
     });
   }
   async invalidateByPattern(pattern) {
@@ -2945,6 +3430,18 @@ var CacheStack = class extends import_node_events.EventEmitter {
       await this.publishInvalidation({ scope: "keys", keys, sourceId: this.instanceId, operation: "invalidate" });
     });
   }
+  async expireByPattern(pattern) {
+    await this.observeOperation("layercache.expire_by_pattern", void 0, async () => {
+      validatePattern(pattern);
+      await this.awaitStartup("expireByPattern");
+      const keys = await this.keyDiscovery.collectKeysMatchingPattern(
+        this.qualifyPattern(pattern),
+        this.invalidationMaxKeys()
+      );
+      await this.expireKeys(keys);
+      await this.publishInvalidation({ scope: "keys", keys, sourceId: this.instanceId, operation: "expire" });
+    });
+  }
   async invalidateByPrefix(prefix) {
     await this.observeOperation("layercache.invalidate_by_prefix", void 0, async () => {
       await this.awaitStartup("invalidateByPrefix");
@@ -2954,6 +3451,15 @@ var CacheStack = class extends import_node_events.EventEmitter {
       await this.publishInvalidation({ scope: "keys", keys, sourceId: this.instanceId, operation: "invalidate" });
     });
   }
+  async expireByPrefix(prefix) {
+    await this.observeOperation("layercache.expire_by_prefix", void 0, async () => {
+      await this.awaitStartup("expireByPrefix");
+      const qualifiedPrefix = this.qualifyKey(validateCacheKey(prefix));
+      const keys = await this.keyDiscovery.collectKeysWithPrefix(qualifiedPrefix, this.invalidationMaxKeys());
+      await this.expireKeys(keys);
+      await this.publishInvalidation({ scope: "keys", keys, sourceId: this.instanceId, operation: "expire" });
+    });
+  }
   getMetrics() {
     return this.metricsCollector.snapshot;
   }
@@ -2965,7 +3471,7 @@ var CacheStack = class extends import_node_events.EventEmitter {
         isLocal: Boolean(layer.isLocal),
         degradedUntil: this.layerDegradedUntil.get(layer.name) ?? null
       })),
-      backgroundRefreshes: this.backgroundRefreshes.size
+      backgroundRefreshes: this.reader.activeRefreshCount
     };
   }
   resetMetrics() {
@@ -3030,9 +3536,9 @@ var CacheStack = class extends import_node_events.EventEmitter {
     const normalizedKey = this.qualifyKey(userKey);
     await this.awaitStartup("inspect");
     const foundInLayers = [];
-    let freshTtlSeconds = null;
-    let staleTtlSeconds = null;
-    let errorTtlSeconds = null;
+    let freshTtlMs = null;
+    let staleTtlMs = null;
+    let errorTtlMs = null;
     let isStale = false;
     for (const layer of this.layers) {
       if (this.shouldSkipLayer(layer)) {
@@ -3049,9 +3555,9 @@ var CacheStack = class extends import_node_events.EventEmitter {
       foundInLayers.push(layer.name);
       if (foundInLayers.length === 1 && resolved.envelope) {
         const now = Date.now();
-        freshTtlSeconds = resolved.envelope.freshUntil !== null ? Math.max(0, Math.ceil((resolved.envelope.freshUntil - now) / 1e3)) : null;
-        staleTtlSeconds = resolved.envelope.staleUntil !== null ? Math.max(0, Math.ceil((resolved.envelope.staleUntil - now) / 1e3)) : null;
-        errorTtlSeconds = resolved.envelope.errorUntil !== null ? Math.max(0, Math.ceil((resolved.envelope.errorUntil - now) / 1e3)) : null;
+        freshTtlMs = resolved.envelope.freshUntil !== null ? Math.max(0, Math.ceil(resolved.envelope.freshUntil - now)) : null;
+        staleTtlMs = resolved.envelope.staleUntil !== null ? Math.max(0, Math.ceil(resolved.envelope.staleUntil - now)) : null;
+        errorTtlMs = resolved.envelope.errorUntil !== null ? Math.max(0, Math.ceil(resolved.envelope.errorUntil - now)) : null;
         isStale = resolved.state === "stale-while-revalidate" || resolved.state === "stale-if-error";
       }
     }
@@ -3059,7 +3565,7 @@ var CacheStack = class extends import_node_events.EventEmitter {
       return null;
     }
     const tags = await this.getTagsForKey(normalizedKey);
-    return { key: userKey, foundInLayers, freshTtlSeconds, staleTtlSeconds, errorTtlSeconds, isStale, tags };
+    return { key: userKey, foundInLayers, freshTtlMs, staleTtlMs, errorTtlMs, isStale, tags };
   }
   async exportState() {
     await this.awaitStartup("exportState");
@@ -3085,11 +3591,9 @@ var CacheStack = class extends import_node_events.EventEmitter {
         await this.unsubscribeInvalidation?.();
         await this.flushWriteBehindQueue();
         await this.maintenance.waitForGenerationCleanup();
-        for (const key of this.backgroundRefreshAbort.keys()) {
-          this.backgroundRefreshAbort.set(key, true);
-        }
+        this.reader.abortAllRefreshes();
         await Promise.allSettled(
-          [...this.backgroundRefreshes.values()].map((promise) => {
+          this.reader.getAllRefreshPromises().map((promise) => {
             let timer;
             return Promise.race([
               promise,
@@ -3102,8 +3606,6 @@ var CacheStack = class extends import_node_events.EventEmitter {
             });
           })
         );
-        this.backgroundRefreshes.clear();
-        this.backgroundRefreshAbort.clear();
         this.maintenance.disposeWriteBehindTimer();
         this.fetchRateLimiter.dispose();
         await Promise.allSettled(this.layers.map((layer) => layer.dispose?.() ?? Promise.resolve()));
@@ -3119,141 +3621,36 @@ var CacheStack = class extends import_node_events.EventEmitter {
       await this.handleInvalidationMessage(message);
     });
   }
-  async fetchWithGuards(key, fetcher, options, expectedClearEpoch, expectedKeyEpoch, initialMissConfirmed = false) {
-    const fetchTask = async () => {
-      const shouldRecheckFreshLayers = !(initialMissConfirmed && this.options.singleFlightCoordinator);
-      if (shouldRecheckFreshLayers) {
-        const secondHit = await this.readFromLayers(key, options, "fresh-only");
-        if (secondHit.found) {
-          this.metricsCollector.increment("hits");
-          return secondHit.value;
-        }
-      }
-      return this.fetchAndPopulate(key, fetcher, options, expectedClearEpoch, expectedKeyEpoch);
-    };
-    const singleFlightTask = async () => {
-      if (!this.options.singleFlightCoordinator) {
-        return fetchTask();
-      }
-      try {
-        return await this.options.singleFlightCoordinator.execute(
-          key,
-          this.resolveSingleFlightOptions(),
-          fetchTask,
-          () => this.waitForFreshValue(key, fetcher, options, expectedClearEpoch, expectedKeyEpoch)
-        );
-      } catch (error) {
-        if (!this.isGracefulDegradationEnabled()) {
-          throw error;
-        }
-        this.metricsCollector.increment("degradedOperations");
-        this.logger.warn?.("single-flight-coordinator-degraded", { key, error: this.formatError(error) });
-        this.emitError("single-flight", { key, degraded: true, error: this.formatError(error) });
-        return fetchTask();
-      }
-    };
-    if (this.options.stampedePrevention === false) {
-      return singleFlightTask();
-    }
-    return this.stampedeGuard.execute(key, singleFlightTask);
-  }
-  async waitForFreshValue(key, fetcher, options, expectedClearEpoch, expectedKeyEpoch) {
-    const timeoutMs = this.options.singleFlightTimeoutMs ?? DEFAULT_SINGLE_FLIGHT_TIMEOUT_MS;
-    const pollIntervalMs = this.options.singleFlightPollMs ?? DEFAULT_SINGLE_FLIGHT_POLL_MS;
-    const deadline = Date.now() + timeoutMs;
-    this.metricsCollector.increment("singleFlightWaits");
-    this.emit("stampede-dedupe", { key });
-    while (Date.now() < deadline) {
-      const hit = await this.readFromLayers(key, options, "fresh-only");
-      if (hit.found) {
-        this.metricsCollector.increment("hits");
-        return hit.value;
-      }
-      await this.sleep(pollIntervalMs);
-    }
-    return this.fetchAndPopulate(key, fetcher, options, expectedClearEpoch, expectedKeyEpoch);
-  }
-  async fetchAndPopulate(key, fetcher, options, expectedClearEpoch, expectedKeyEpoch) {
-    this.circuitBreakerManager.assertClosed(key, options?.circuitBreaker ?? this.options.circuitBreaker);
-    this.metricsCollector.increment("fetches");
-    const fetchStart = Date.now();
-    let fetched;
-    try {
-      fetched = await this.fetchRateLimiter.schedule(
-        options?.fetcherRateLimit ?? this.options.fetcherRateLimit,
-        { key, fetcher },
-        fetcher
-      );
-      this.circuitBreakerManager.recordSuccess(key);
-      this.logger.debug?.("fetch", { key, durationMs: Date.now() - fetchStart });
-    } catch (error) {
-      this.recordCircuitFailure(key, options?.circuitBreaker ?? this.options.circuitBreaker, error);
-      throw error;
-    }
-    if (fetched === null || fetched === void 0) {
-      if (!this.shouldNegativeCache(options)) {
-        return null;
-      }
-      if (this.maintenance.isWriteOutdated(key, expectedClearEpoch, expectedKeyEpoch)) {
-        this.logger.debug?.("skip-negative-store-after-invalidation", {
-          key,
-          expectedClearEpoch,
-          clearEpoch: this.maintenance.currentClearEpoch(),
-          expectedKeyEpoch,
-          keyEpoch: this.maintenance.currentKeyEpoch(key)
-        });
-        return null;
-      }
-      await this.storeEntry(key, "empty", null, options);
-      return null;
-    }
-    if (options?.shouldCache) {
-      try {
-        if (!options.shouldCache(fetched)) {
-          return fetched;
-        }
-      } catch (error) {
-        this.logger.warn?.("shouldCache-error", { key, error: this.formatError(error) });
-      }
-    }
-    if (this.maintenance.isWriteOutdated(key, expectedClearEpoch, expectedKeyEpoch)) {
-      this.logger.debug?.("skip-store-after-invalidation", {
-        key,
-        expectedClearEpoch,
-        clearEpoch: this.maintenance.currentClearEpoch(),
-        expectedKeyEpoch,
-        keyEpoch: this.maintenance.currentKeyEpoch(key)
-      });
-      return fetched;
-    }
-    await this.storeEntry(key, "value", fetched, options);
-    return fetched;
-  }
   async storeEntry(key, kind, value, options) {
+    const resolvedOptions = this.resolveContextOptions(key, kind, value, options);
     const clearEpoch = this.maintenance.currentClearEpoch();
     const keyEpoch = this.maintenance.currentKeyEpoch(key);
-    await this.layerWriter.writeAcrossLayers(key, kind, value, options);
+    await this.layerWriter.writeAcrossLayers(key, kind, value, resolvedOptions);
     if (this.maintenance.isWriteOutdated(key, clearEpoch, keyEpoch)) {
       return;
     }
-    if (options?.tags) {
-      await this.tagIndex.track(key, options.tags);
+    if (resolvedOptions?.tags) {
+      await this.tagIndex.track(key, resolvedOptions.tags);
     } else {
       await this.tagIndex.touch(key);
     }
     this.metricsCollector.increment("sets");
-    this.logger.debug?.("set", { key, kind, tags: options?.tags });
-    this.emit("set", { key, kind, tags: options?.tags });
+    this.logger.debug?.("set", { key, kind, tags: resolvedOptions?.tags });
+    this.emit("set", { key, kind, tags: resolvedOptions?.tags });
     if (this.shouldBroadcastL1Invalidation()) {
       await this.publishInvalidation({ scope: "key", keys: [key], sourceId: this.instanceId, operation: "write" });
     }
   }
   async writeBatch(entries) {
-    const { clearEpoch, entryEpochs } = await this.layerWriter.writeBatch(entries);
+    const resolvedEntries = entries.map((entry) => ({
+      ...entry,
+      options: this.resolveContextOptions(entry.key, "value", entry.value, entry.options)
+    }));
+    const { clearEpoch, entryEpochs } = await this.layerWriter.writeBatch(resolvedEntries);
     if (clearEpoch !== this.maintenance.currentClearEpoch()) {
       return;
     }
-    for (const entry of entries) {
+    for (const entry of resolvedEntries) {
       if (this.maintenance.isWriteOutdated(entry.key, clearEpoch, entryEpochs.get(entry.key))) {
         continue;
       }
@@ -3275,87 +3672,6 @@ var CacheStack = class extends import_node_events.EventEmitter {
       });
     }
   }
-  async readFromLayers(key, options, mode) {
-    let sawRetainableValue = false;
-    for (let index = 0; index < this.layers.length; index += 1) {
-      const layer = this.layers[index];
-      if (!layer) continue;
-      const readStart = performance.now();
-      const stored = await this.readLayerEntry(layer, key);
-      const readDuration = performance.now() - readStart;
-      this.metricsCollector.recordLatency(layer.name, readDuration);
-      if (stored === null) {
-        this.metricsCollector.incrementLayer("missesByLayer", layer.name);
-        continue;
-      }
-      const resolved = resolveStoredValue(stored);
-      if (resolved.state === "expired") {
-        await layer.delete(key);
-        continue;
-      }
-      sawRetainableValue = true;
-      if (mode === "fresh-only" && resolved.state !== "fresh") {
-        continue;
-      }
-      await this.tagIndex.touch(key);
-      await this.backfill(key, stored, index - 1, options);
-      this.metricsCollector.incrementLayer("hitsByLayer", layer.name);
-      this.logger.debug?.("hit", { key, layer: layer.name, state: resolved.state });
-      this.emit("hit", { key, layer: layer.name, state: resolved.state });
-      return {
-        found: true,
-        value: resolved.value,
-        stored,
-        state: resolved.state,
-        layerIndex: index,
-        layerName: layer.name
-      };
-    }
-    if (!sawRetainableValue) {
-      await this.tagIndex.remove(key);
-    }
-    this.logger.debug?.("miss", { key, mode });
-    this.emit("miss", { key, mode });
-    return { found: false, value: null, stored: null, state: "miss" };
-  }
-  async readLayerEntry(layer, key) {
-    if (this.shouldSkipLayer(layer)) {
-      return null;
-    }
-    if (layer.getEntry) {
-      try {
-        return await layer.getEntry(key);
-      } catch (error) {
-        return this.handleLayerFailure(layer, "read", error);
-      }
-    }
-    try {
-      return await layer.get(key);
-    } catch (error) {
-      return this.handleLayerFailure(layer, "read", error);
-    }
-  }
-  async backfill(key, stored, upToIndex, options) {
-    if (upToIndex < 0) {
-      return;
-    }
-    for (let index = 0; index <= upToIndex; index += 1) {
-      const layer = this.layers[index];
-      if (!layer || this.shouldSkipLayer(layer)) {
-        continue;
-      }
-      const ttl = remainingStoredTtlSeconds(stored) ?? this.resolveLayerSeconds(layer.name, options?.ttl, void 0, layer.defaultTtl);
-      try {
-        await layer.set(key, stored, ttl);
-      } catch (error) {
-        await this.handleLayerFailure(layer, "backfill", error);
-        continue;
-      }
-      this.metricsCollector.increment("backfills");
-      this.logger.debug?.("backfill", { key, layer: layer.name });
-      this.emit("backfill", { key, layer: layer.name });
-    }
-  }
   resolveFreshTtl(key, layerName, kind, options, fallbackTtl, value) {
     return this.ttlResolver.resolveFreshTtl(
       key,
@@ -3368,58 +3684,47 @@ var CacheStack = class extends import_node_events.EventEmitter {
       value
     );
   }
-  resolveLayerSeconds(layerName, override, globalDefault, fallback) {
-    return this.ttlResolver.resolveLayerSeconds(layerName, override, globalDefault, fallback);
-  }
-  shouldNegativeCache(options) {
-    return options?.negativeCache ?? this.options.negativeCaching ?? false;
+  resolveLayerMs(layerName, override, globalDefault, fallback) {
+    return this.ttlResolver.resolveLayerMs(layerName, override, globalDefault, fallback);
   }
-  scheduleBackgroundRefresh(key, fetcher, options) {
-    if (!shouldStartBackgroundRefresh({
-      isDisconnecting: this.isDisconnecting,
-      hasRefreshInFlight: this.backgroundRefreshes.has(key)
-    })) {
-      return;
+  resolveContextOptions(key, kind, value, options) {
+    if (!options?.contextOptions) {
+      return options;
+    }
+    const { contextOptions, ...baseOptions } = options;
+    let overrides;
+    try {
+      overrides = contextOptions({ key, value, kind });
+    } catch (error) {
+      throw new Error(`options.contextOptions() failed for key "${key}": ${this.formatError(error)}`);
+    }
+    if (!overrides) {
+      return baseOptions;
+    }
+    if (!this.isPlainObject(overrides)) {
+      throw new Error(
+        `options.contextOptions() must return a plain object or undefined for key "${key}". Async resolvers are not supported.`
+      );
+    }
+    try {
+      validateContextEntryOptions("options.contextOptions()", overrides);
+    } catch (error) {
+      throw new Error(
+        `options.contextOptions() returned invalid entry options for key "${key}": ${this.formatError(error)}`
+      );
     }
-    const clearEpoch = this.maintenance.currentClearEpoch();
-    const keyEpoch = this.maintenance.currentKeyEpoch(key);
-    this.backgroundRefreshAbort.set(key, false);
-    const refresh = (async () => {
-      this.metricsCollector.increment("refreshes");
-      try {
-        if (this.backgroundRefreshAbort.get(key)) return;
-        await this.runBackgroundRefresh(key, fetcher, options, clearEpoch, keyEpoch);
-      } catch (error) {
-        if (this.backgroundRefreshAbort.get(key)) return;
-        this.metricsCollector.increment("refreshErrors");
-        this.logger.warn?.("background-refresh-error", { key, error: this.formatError(error) });
-      } finally {
-        this.backgroundRefreshes.delete(key);
-        this.backgroundRefreshAbort.delete(key);
-      }
-    })();
-    this.backgroundRefreshes.set(key, refresh);
-  }
-  async runBackgroundRefresh(key, fetcher, options, expectedClearEpoch, expectedKeyEpoch) {
-    const timeoutMs = this.options.backgroundRefreshTimeoutMs ?? DEFAULT_BACKGROUND_REFRESH_TIMEOUT_MS;
-    await this.fetchWithGuards(
-      key,
-      () => this.withTimeout(fetcher(), timeoutMs, () => {
-        return new Error(`Background refresh timed out after ${timeoutMs}ms for key "${key}".`);
-      }),
-      options,
-      expectedClearEpoch,
-      expectedKeyEpoch
-    );
-  }
-  resolveSingleFlightOptions() {
     return {
-      leaseMs: this.options.singleFlightLeaseMs ?? DEFAULT_SINGLE_FLIGHT_LEASE_MS,
-      waitTimeoutMs: this.options.singleFlightTimeoutMs ?? DEFAULT_SINGLE_FLIGHT_TIMEOUT_MS,
-      pollIntervalMs: this.options.singleFlightPollMs ?? DEFAULT_SINGLE_FLIGHT_POLL_MS,
-      renewIntervalMs: this.options.singleFlightRenewIntervalMs
+      ...baseOptions,
+      ...overrides
     };
   }
+  isPlainObject(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+      return false;
+    }
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+  }
   async deleteKeys(keys) {
     if (keys.length === 0) {
       return;
@@ -3436,6 +3741,30 @@ var CacheStack = class extends import_node_events.EventEmitter {
     this.logger.debug?.("delete", { keys });
     this.emit("delete", { keys });
   }
+  async expireKeys(keys) {
+    if (keys.length === 0) {
+      return;
+    }
+    this.maintenance.bumpKeyEpochs(keys);
+    const foundKeys = await this.expireKeysInLayers(keys, this.layers);
+    for (const key of keys) {
+      if (foundKeys.has(key)) {
+        continue;
+      }
+      await this.tagIndex.remove(key);
+      this.ttlResolver.deleteProfile(key);
+      this.circuitBreakerManager.delete(key);
+    }
+    this.metricsCollector.increment("invalidations");
+    this.logger.debug?.("expire", { keys });
+    this.emit("expire", { keys });
+  }
+  async expireKeysInLayers(keys, layers) {
+    if (keys.length === 0) {
+      return /* @__PURE__ */ new Set();
+    }
+    return this.invalidation.expireKeysInLayers(layers, keys);
+  }
   async publishInvalidation(message) {
     if (!this.options.invalidationBus) {
       return;
@@ -3457,6 +3786,10 @@ var CacheStack = class extends import_node_events.EventEmitter {
     }
     const keys = message.keys ?? [];
     this.maintenance.bumpKeyEpochs(keys);
+    if (message.operation === "expire") {
+      await this.expireKeysInLayers(keys, localLayers);
+      return;
+    }
     await this.invalidation.deleteKeysFromLayers(localLayers, keys);
     if (message.operation !== "write") {
       for (const key of keys) {
@@ -3654,6 +3987,9 @@ var CacheStack = class extends import_node_events.EventEmitter {
     validateCircuitBreakerOptions(options.circuitBreaker);
     validateRateLimitOptions("options.fetcherRateLimit", options.fetcherRateLimit);
     validateTags(options.tags);
+    if (options.contextOptions && typeof options.contextOptions !== "function") {
+      throw new Error("options.contextOptions must be a function.");
+    }
   }
   assertActive(operation) {
     if (this.isDisconnecting) {
@@ -3665,29 +4001,14 @@ var CacheStack = class extends import_node_events.EventEmitter {
     await this.startup;
     this.assertActive(operation);
   }
+  async readLayerEntry(layer, key) {
+    return this.reader.readLayerEntry(layer, key);
+  }
+  scheduleBackgroundRefresh(key, fetcher, options, fetcherContext) {
+    this.reader.runScheduleBackgroundRefresh(key, fetcher, options, fetcherContext);
+  }
   async applyFreshReadPolicies(key, hit, options, fetcher) {
-    const plan = planFreshReadPolicies({
-      stored: hit.stored,
-      hasFetcher: Boolean(fetcher),
-      slidingTtl: options?.slidingTtl ?? false,
-      refreshAheadSeconds: this.resolveLayerSeconds(hit.layerName, options?.refreshAhead, this.options.refreshAhead, 0) ?? 0
-    });
-    if (plan.refreshedStored) {
-      for (let index = 0; index <= hit.layerIndex; index += 1) {
-        const layer = this.layers[index];
-        if (!layer || this.shouldSkipLayer(layer)) {
-          continue;
-        }
-        try {
-          await layer.set(key, plan.refreshedStored, plan.refreshedStoredTtl);
-        } catch (error) {
-          await this.handleLayerFailure(layer, "sliding-ttl", error);
-        }
-      }
-    }
-    if (fetcher && plan.shouldScheduleBackgroundRefresh) {
-      this.scheduleBackgroundRefresh(key, fetcher, options);
-    }
+    return this.reader.runApplyFreshReadPolicies(key, hit, options, fetcher);
   }
   shouldSkipLayer(layer) {
     const degradedUntil = this.layerDegradedUntil.get(layer.name);
@@ -3729,9 +4050,6 @@ var CacheStack = class extends import_node_events.EventEmitter {
     }
     this.emitError("fetch", { key, error: this.formatError(error) });
   }
-  isNegativeStoredValue(stored) {
-    return isStoredValueEnvelope(stored) && stored.kind === "empty";
-  }
   emitError(operation, context) {
     this.logger.error?.(operation, context);
     if (this.listenerCount("error") > 0) {
@@ -3831,7 +4149,7 @@ var RedisInvalidationBus = class {
     }
     const candidate = value;
     const validScope = candidate.scope === "key" || candidate.scope === "keys" || candidate.scope === "clear";
-    const validOperation = candidate.operation === void 0 || candidate.operation === "write" || candidate.operation === "delete" || candidate.operation === "invalidate" || candidate.operation === "clear";
+    const validOperation = candidate.operation === void 0 || candidate.operation === "write" || candidate.operation === "delete" || candidate.operation === "invalidate" || candidate.operation === "expire" || candidate.operation === "clear";
     const validKeys = candidate.keys === void 0 || Array.isArray(candidate.keys) && candidate.keys.every((key) => typeof key === "string");
     return validScope && typeof candidate.sourceId === "string" && candidate.sourceId.length > 0 && validOperation && validKeys;
   }
@@ -4354,7 +4672,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()
     });
@@ -4385,7 +4703,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();
@@ -4575,7 +4893,7 @@ var RedisLayer = class {
       const payload = await this.encodePayload(serialized);
       const normalizedKey = this.withPrefix(entry.key);
       if (entry.ttl && entry.ttl > 0) {
-        pipeline.set(normalizedKey, payload, "EX", entry.ttl);
+        pipeline.set(normalizedKey, payload, "PX", entry.ttl);
       } else {
         pipeline.set(normalizedKey, payload);
       }
@@ -4590,7 +4908,7 @@ var RedisLayer = class {
     if (ttl && ttl > 0) {
       await this.runCommand(
         `set(${this.displayKey(key)})`,
-        () => this.client.set(normalizedKey, payload, "EX", ttl)
+        () => this.client.set(normalizedKey, payload, "PX", ttl)
       );
       return;
     }
@@ -4619,7 +4937,10 @@ var RedisLayer = class {
   }
   async ttl(key) {
     this.validateKey(key);
-    const remaining = await this.runCommand(`ttl(${this.displayKey(key)})`, () => this.client.ttl(this.withPrefix(key)));
+    const remaining = await this.runCommand(
+      `ttl(${this.displayKey(key)})`,
+      () => this.client.pttl(this.withPrefix(key))
+    );
     if (remaining < 0) {
       return null;
     }
@@ -4770,12 +5091,12 @@ var RedisLayer = class {
     const payload = await this.encodePayload(serialized);
     const ttl = await this.runCommand(
       `rewrite-ttl(${this.displayKey(key)})`,
-      () => this.client.ttl(this.withPrefix(key))
+      () => this.client.pttl(this.withPrefix(key))
     );
     if (ttl > 0) {
       await this.runCommand(
         `rewrite-set(${this.displayKey(key)})`,
-        () => this.client.set(this.withPrefix(key), payload, "EX", ttl)
+        () => this.client.set(this.withPrefix(key), payload, "PX", ttl)
       );
       return;
     }
@@ -5086,7 +5407,7 @@ var DiskLayer = class {
       const entry = {
         key,
         value,
-        expiresAt: ttl && ttl > 0 ? Date.now() + ttl * 1e3 : null
+        expiresAt: ttl && ttl > 0 ? Date.now() + ttl : null
       };
       const payload = this.serializer.serialize(entry);
       const raw = Buffer.isBuffer(payload) ? payload : Buffer.from(payload, "utf8");
@@ -5131,7 +5452,7 @@ var DiskLayer = class {
     if (entry.expiresAt === null) {
       return null;
     }
-    const remaining = Math.ceil((entry.expiresAt - Date.now()) / 1e3);
+    const remaining = Math.ceil(entry.expiresAt - Date.now());
     if (remaining <= 0) {
       return null;
     }
@@ -5421,7 +5742,7 @@ var MemcachedLayer = class {
     this.validateKey(key);
     const payload = this.serializer.serialize(value);
     await this.client.set(this.withPrefix(key), payload, {
-      expires: ttl && ttl > 0 ? ttl : void 0
+      expires: ttl && ttl > 0 ? Math.ceil(ttl / 1e3) : void 0
     });
   }
   async has(key) {