layercache 1.2.6 → 1.2.7

package/dist/index.js

@@ -22,6 +22,127 @@ import { EventEmitter } from "events";
 
 // src/CacheNamespace.ts
 import { Mutex } from "async-mutex";
+
+// src/internal/CacheNamespaceMetrics.ts
+function createEmptyNamespaceMetrics(resetAt = Date.now()) {
+  return {
+    hits: 0,
+    misses: 0,
+    fetches: 0,
+    sets: 0,
+    deletes: 0,
+    backfills: 0,
+    invalidations: 0,
+    staleHits: 0,
+    refreshes: 0,
+    refreshErrors: 0,
+    writeFailures: 0,
+    singleFlightWaits: 0,
+    negativeCacheHits: 0,
+    circuitBreakerTrips: 0,
+    degradedOperations: 0,
+    hitsByLayer: {},
+    missesByLayer: {},
+    latencyByLayer: {},
+    resetAt
+  };
+}
+function cloneNamespaceMetrics(metrics) {
+  return {
+    ...metrics,
+    hitsByLayer: { ...metrics.hitsByLayer },
+    missesByLayer: { ...metrics.missesByLayer },
+    latencyByLayer: Object.fromEntries(
+      Object.entries(metrics.latencyByLayer).map(([key, value]) => [key, { ...value }])
+    )
+  };
+}
+function diffNamespaceMetrics(before, after) {
+  const latencyByLayer = Object.fromEntries(
+    Object.entries(after.latencyByLayer).map(([layer, value]) => [
+      layer,
+      {
+        avgMs: value.avgMs,
+        maxMs: value.maxMs,
+        count: Math.max(0, value.count - (before.latencyByLayer[layer]?.count ?? 0))
+      }
+    ])
+  );
+  return {
+    hits: after.hits - before.hits,
+    misses: after.misses - before.misses,
+    fetches: after.fetches - before.fetches,
+    sets: after.sets - before.sets,
+    deletes: after.deletes - before.deletes,
+    backfills: after.backfills - before.backfills,
+    invalidations: after.invalidations - before.invalidations,
+    staleHits: after.staleHits - before.staleHits,
+    refreshes: after.refreshes - before.refreshes,
+    refreshErrors: after.refreshErrors - before.refreshErrors,
+    writeFailures: after.writeFailures - before.writeFailures,
+    singleFlightWaits: after.singleFlightWaits - before.singleFlightWaits,
+    negativeCacheHits: after.negativeCacheHits - before.negativeCacheHits,
+    circuitBreakerTrips: after.circuitBreakerTrips - before.circuitBreakerTrips,
+    degradedOperations: after.degradedOperations - before.degradedOperations,
+    hitsByLayer: diffMetricMap(before.hitsByLayer, after.hitsByLayer),
+    missesByLayer: diffMetricMap(before.missesByLayer, after.missesByLayer),
+    latencyByLayer,
+    resetAt: after.resetAt
+  };
+}
+function addNamespaceMetrics(base, delta) {
+  return {
+    hits: base.hits + delta.hits,
+    misses: base.misses + delta.misses,
+    fetches: base.fetches + delta.fetches,
+    sets: base.sets + delta.sets,
+    deletes: base.deletes + delta.deletes,
+    backfills: base.backfills + delta.backfills,
+    invalidations: base.invalidations + delta.invalidations,
+    staleHits: base.staleHits + delta.staleHits,
+    refreshes: base.refreshes + delta.refreshes,
+    refreshErrors: base.refreshErrors + delta.refreshErrors,
+    writeFailures: base.writeFailures + delta.writeFailures,
+    singleFlightWaits: base.singleFlightWaits + delta.singleFlightWaits,
+    negativeCacheHits: base.negativeCacheHits + delta.negativeCacheHits,
+    circuitBreakerTrips: base.circuitBreakerTrips + delta.circuitBreakerTrips,
+    degradedOperations: base.degradedOperations + delta.degradedOperations,
+    hitsByLayer: addMetricMap(base.hitsByLayer, delta.hitsByLayer),
+    missesByLayer: addMetricMap(base.missesByLayer, delta.missesByLayer),
+    latencyByLayer: cloneNamespaceMetrics(delta).latencyByLayer,
+    resetAt: base.resetAt
+  };
+}
+function computeNamespaceHitRate(metrics) {
+  const total = metrics.hits + metrics.misses;
+  const overall = total === 0 ? 0 : metrics.hits / total;
+  const byLayer = {};
+  const layers = /* @__PURE__ */ new Set([...Object.keys(metrics.hitsByLayer), ...Object.keys(metrics.missesByLayer)]);
+  for (const layer of layers) {
+    const hits = metrics.hitsByLayer[layer] ?? 0;
+    const misses = metrics.missesByLayer[layer] ?? 0;
+    byLayer[layer] = hits + misses === 0 ? 0 : hits / (hits + misses);
+  }
+  return { overall, byLayer };
+}
+function diffMetricMap(before, after) {
+  const keys = /* @__PURE__ */ new Set([...Object.keys(before), ...Object.keys(after)]);
+  const result = {};
+  for (const key of keys) {
+    result[key] = (after[key] ?? 0) - (before[key] ?? 0);
+  }
+  return result;
+}
+function addMetricMap(base, delta) {
+  const keys = /* @__PURE__ */ new Set([...Object.keys(base), ...Object.keys(delta)]);
+  const result = {};
+  for (const key of keys) {
+    result[key] = (base[key] ?? 0) + (delta[key] ?? 0);
+  }
+  return result;
+}
+
+// src/CacheNamespace.ts
 var CacheNamespace = class _CacheNamespace {
   constructor(cache, prefix) {
     this.cache = cache;
@@ -31,7 +152,7 @@ var CacheNamespace = class _CacheNamespace {
   cache;
   prefix;
   static metricsMutexes = /* @__PURE__ */ new WeakMap();
-  metrics = emptyMetrics();
+  metrics = createEmptyNamespaceMetrics();
   async get(key, fetcher, options) {
     return this.trackMetrics(() => this.cache.get(this.qualify(key), fetcher, this.qualifyGetOptions(options)));
   }
@@ -128,19 +249,10 @@ var CacheNamespace = class _CacheNamespace {
     );
   }
   getMetrics() {
-    return cloneMetrics(this.metrics);
+    return cloneNamespaceMetrics(this.metrics);
   }
   getHitRate() {
-    const total = this.metrics.hits + this.metrics.misses;
-    const overall = total === 0 ? 0 : this.metrics.hits / total;
-    const byLayer = {};
-    const layers = /* @__PURE__ */ new Set([...Object.keys(this.metrics.hitsByLayer), ...Object.keys(this.metrics.missesByLayer)]);
-    for (const layer of layers) {
-      const hits = this.metrics.hitsByLayer[layer] ?? 0;
-      const misses = this.metrics.missesByLayer[layer] ?? 0;
-      byLayer[layer] = hits + misses === 0 ? 0 : hits / (hits + misses);
-    }
-    return { overall, byLayer };
+    return computeNamespaceHitRate(this.metrics);
   }
   /**
    * Creates a nested namespace. Keys are prefixed with `parentPrefix:childPrefix:`.
@@ -181,7 +293,7 @@ var CacheNamespace = class _CacheNamespace {
       const before = this.cache.getMetrics();
       const result = await operation();
       const after = this.cache.getMetrics();
-      this.metrics = addMetrics(this.metrics, diffMetrics(before, after));
+      this.metrics = addNamespaceMetrics(this.metrics, diffNamespaceMetrics(before, after));
       return result;
     });
   }
@@ -195,111 +307,6 @@ var CacheNamespace = class _CacheNamespace {
     return mutex;
   }
 };
-function emptyMetrics() {
-  return {
-    hits: 0,
-    misses: 0,
-    fetches: 0,
-    sets: 0,
-    deletes: 0,
-    backfills: 0,
-    invalidations: 0,
-    staleHits: 0,
-    refreshes: 0,
-    refreshErrors: 0,
-    writeFailures: 0,
-    singleFlightWaits: 0,
-    negativeCacheHits: 0,
-    circuitBreakerTrips: 0,
-    degradedOperations: 0,
-    hitsByLayer: {},
-    missesByLayer: {},
-    latencyByLayer: {},
-    resetAt: Date.now()
-  };
-}
-function cloneMetrics(metrics) {
-  return {
-    ...metrics,
-    hitsByLayer: { ...metrics.hitsByLayer },
-    missesByLayer: { ...metrics.missesByLayer },
-    latencyByLayer: Object.fromEntries(
-      Object.entries(metrics.latencyByLayer).map(([key, value]) => [key, { ...value }])
-    )
-  };
-}
-function diffMetrics(before, after) {
-  const latencyByLayer = Object.fromEntries(
-    Object.entries(after.latencyByLayer).map(([layer, value]) => [
-      layer,
-      {
-        avgMs: value.avgMs,
-        maxMs: value.maxMs,
-        count: Math.max(0, value.count - (before.latencyByLayer[layer]?.count ?? 0))
-      }
-    ])
-  );
-  return {
-    hits: after.hits - before.hits,
-    misses: after.misses - before.misses,
-    fetches: after.fetches - before.fetches,
-    sets: after.sets - before.sets,
-    deletes: after.deletes - before.deletes,
-    backfills: after.backfills - before.backfills,
-    invalidations: after.invalidations - before.invalidations,
-    staleHits: after.staleHits - before.staleHits,
-    refreshes: after.refreshes - before.refreshes,
-    refreshErrors: after.refreshErrors - before.refreshErrors,
-    writeFailures: after.writeFailures - before.writeFailures,
-    singleFlightWaits: after.singleFlightWaits - before.singleFlightWaits,
-    negativeCacheHits: after.negativeCacheHits - before.negativeCacheHits,
-    circuitBreakerTrips: after.circuitBreakerTrips - before.circuitBreakerTrips,
-    degradedOperations: after.degradedOperations - before.degradedOperations,
-    hitsByLayer: diffMap(before.hitsByLayer, after.hitsByLayer),
-    missesByLayer: diffMap(before.missesByLayer, after.missesByLayer),
-    latencyByLayer,
-    resetAt: after.resetAt
-  };
-}
-function addMetrics(base, delta) {
-  return {
-    hits: base.hits + delta.hits,
-    misses: base.misses + delta.misses,
-    fetches: base.fetches + delta.fetches,
-    sets: base.sets + delta.sets,
-    deletes: base.deletes + delta.deletes,
-    backfills: base.backfills + delta.backfills,
-    invalidations: base.invalidations + delta.invalidations,
-    staleHits: base.staleHits + delta.staleHits,
-    refreshes: base.refreshes + delta.refreshes,
-    refreshErrors: base.refreshErrors + delta.refreshErrors,
-    writeFailures: base.writeFailures + delta.writeFailures,
-    singleFlightWaits: base.singleFlightWaits + delta.singleFlightWaits,
-    negativeCacheHits: base.negativeCacheHits + delta.negativeCacheHits,
-    circuitBreakerTrips: base.circuitBreakerTrips + delta.circuitBreakerTrips,
-    degradedOperations: base.degradedOperations + delta.degradedOperations,
-    hitsByLayer: addMap(base.hitsByLayer, delta.hitsByLayer),
-    missesByLayer: addMap(base.missesByLayer, delta.missesByLayer),
-    latencyByLayer: cloneMetrics(delta).latencyByLayer,
-    resetAt: base.resetAt
-  };
-}
-function diffMap(before, after) {
-  const keys = /* @__PURE__ */ new Set([...Object.keys(before), ...Object.keys(after)]);
-  const result = {};
-  for (const key of keys) {
-    result[key] = (after[key] ?? 0) - (before[key] ?? 0);
-  }
-  return result;
-}
-function addMap(base, delta) {
-  const keys = /* @__PURE__ */ new Set([...Object.keys(base), ...Object.keys(delta)]);
-  const result = {};
-  for (const key of keys) {
-    result[key] = (base[key] ?? 0) + (delta[key] ?? 0);
-  }
-  return result;
-}
 function validateNamespaceKey(key) {
   if (key.length === 0) {
     throw new Error("Namespace prefix must not be empty.");
@@ -557,6 +564,187 @@ async function readUtf8HandleWithLimit(handle, byteLimit) {
   return Buffer.concat(chunks).toString("utf8");
 }
 
+// src/internal/CacheStackGeneration.ts
+var DEFAULT_GENERATION_CLEANUP_BATCH_SIZE = 500;
+function generationPrefix(generation) {
+  return generation === void 0 ? "" : `v${generation}:`;
+}
+function qualifyGenerationKey(key, generation) {
+  const prefix = generationPrefix(generation);
+  return prefix ? `${prefix}${key}` : key;
+}
+function qualifyGenerationPattern(pattern, generation) {
+  return qualifyGenerationKey(pattern, generation);
+}
+function stripGenerationPrefix(key, generation) {
+  const prefix = generationPrefix(generation);
+  if (!prefix || !key.startsWith(prefix)) {
+    return key;
+  }
+  return key.slice(prefix.length);
+}
+function resolveGenerationCleanupTarget({
+  previousGeneration,
+  nextGeneration,
+  generationCleanup
+}) {
+  if (!generationCleanup || previousGeneration === void 0 || previousGeneration === nextGeneration) {
+    return null;
+  }
+  return previousGeneration;
+}
+function resolveGenerationCleanupBatchSize(generationCleanup) {
+  if (typeof generationCleanup !== "object" || generationCleanup === null) {
+    return DEFAULT_GENERATION_CLEANUP_BATCH_SIZE;
+  }
+  return generationCleanup.batchSize ?? DEFAULT_GENERATION_CLEANUP_BATCH_SIZE;
+}
+function planGenerationCleanupBatches(keys, generationCleanup) {
+  if (keys.length === 0) {
+    return [];
+  }
+  const batchSize = resolveGenerationCleanupBatchSize(generationCleanup);
+  const batches = [];
+  for (let index = 0; index < keys.length; index += batchSize) {
+    batches.push(keys.slice(index, index + batchSize));
+  }
+  return batches;
+}
+
+// src/internal/CacheStackMaintenance.ts
+var CacheStackMaintenance = class {
+  keyEpochs = /* @__PURE__ */ new Map();
+  writeBehindQueue = [];
+  writeBehindTimer;
+  writeBehindFlushPromise;
+  generationCleanupPromise;
+  clearEpoch = 0;
+  initializeWriteBehindTimer(writeStrategy, options, flush) {
+    if (writeStrategy !== "write-behind") {
+      return;
+    }
+    const flushIntervalMs = options?.flushIntervalMs;
+    if (!flushIntervalMs || flushIntervalMs <= 0) {
+      return;
+    }
+    this.disposeWriteBehindTimer();
+    this.writeBehindTimer = setInterval(() => {
+      void flush();
+    }, flushIntervalMs);
+    this.writeBehindTimer.unref?.();
+  }
+  disposeWriteBehindTimer() {
+    if (!this.writeBehindTimer) {
+      return;
+    }
+    clearInterval(this.writeBehindTimer);
+    this.writeBehindTimer = void 0;
+  }
+  beginClearEpoch() {
+    this.clearEpoch += 1;
+    this.keyEpochs.clear();
+    this.writeBehindQueue.length = 0;
+  }
+  currentClearEpoch() {
+    return this.clearEpoch;
+  }
+  currentKeyEpoch(key) {
+    return this.keyEpochs.get(key) ?? 0;
+  }
+  bumpKeyEpochs(keys) {
+    for (const key of keys) {
+      this.keyEpochs.set(key, this.currentKeyEpoch(key) + 1);
+    }
+  }
+  isWriteOutdated(key, expectedClearEpoch, expectedKeyEpoch) {
+    if (expectedClearEpoch !== void 0 && expectedClearEpoch !== this.clearEpoch) {
+      return true;
+    }
+    if (expectedKeyEpoch !== void 0 && expectedKeyEpoch !== this.currentKeyEpoch(key)) {
+      return true;
+    }
+    return false;
+  }
+  async enqueueWriteBehind(operation, options, flushBatch) {
+    this.writeBehindQueue.push(operation);
+    const batchSize = options?.batchSize ?? 100;
+    const maxQueueSize = options?.maxQueueSize ?? batchSize * 10;
+    if (this.writeBehindQueue.length >= batchSize) {
+      await this.flushWriteBehindQueue(options, flushBatch);
+      return;
+    }
+    if (this.writeBehindQueue.length >= maxQueueSize) {
+      await this.flushWriteBehindQueue(options, flushBatch);
+    }
+  }
+  async flushWriteBehindQueue(options, flushBatch) {
+    if (this.writeBehindFlushPromise || this.writeBehindQueue.length === 0) {
+      await this.writeBehindFlushPromise;
+      return;
+    }
+    const batchSize = options?.batchSize ?? 100;
+    const batch = this.writeBehindQueue.splice(0, batchSize);
+    this.writeBehindFlushPromise = flushBatch(batch);
+    try {
+      await this.writeBehindFlushPromise;
+    } finally {
+      this.writeBehindFlushPromise = void 0;
+    }
+    if (this.writeBehindQueue.length > 0) {
+      await this.flushWriteBehindQueue(options, flushBatch);
+    }
+  }
+  scheduleGenerationCleanup(generation, task, onError) {
+    const scheduledTask = (this.generationCleanupPromise ?? Promise.resolve()).then(() => task(generation)).catch((error) => {
+      onError(generation, error);
+    });
+    this.generationCleanupPromise = scheduledTask.finally(() => {
+      if (this.generationCleanupPromise === scheduledTask) {
+        this.generationCleanupPromise = void 0;
+      }
+    });
+  }
+  async waitForGenerationCleanup() {
+    await this.generationCleanupPromise;
+  }
+};
+
+// src/internal/CacheStackRuntimePolicy.ts
+function shouldSkipLayer(degradedUntil, now = Date.now()) {
+  return degradedUntil !== void 0 && degradedUntil > now;
+}
+function shouldStartBackgroundRefresh({
+  isDisconnecting,
+  hasRefreshInFlight
+}) {
+  return !isDisconnecting && !hasRefreshInFlight;
+}
+function resolveRecoverableLayerFailure(gracefulDegradation, now = Date.now()) {
+  if (!gracefulDegradation) {
+    return { degrade: false };
+  }
+  const retryAfterMs = typeof gracefulDegradation === "object" ? gracefulDegradation.retryAfterMs ?? 1e4 : 1e4;
+  return {
+    degrade: true,
+    degradedUntil: now + retryAfterMs
+  };
+}
+function planFreshReadPolicies({
+  stored,
+  hasFetcher,
+  slidingTtl,
+  refreshAheadSeconds
+}) {
+  const refreshedStored = slidingTtl && isStoredValueEnvelope(stored) ? refreshStoredEnvelope(stored) : void 0;
+  const refreshedStoredTtl = refreshedStored ? remainingStoredTtlSeconds(refreshedStored) ?? void 0 : void 0;
+  const remainingFreshTtl = remainingFreshTtlSeconds(stored) ?? 0;
+  return {
+    refreshedStored,
+    refreshedStoredTtl,
+    shouldScheduleBackgroundRefresh: hasFetcher && refreshAheadSeconds > 0 && remainingFreshTtl > 0 && remainingFreshTtl <= refreshAheadSeconds
+  };
+}
+
 // src/internal/CacheStackValidation.ts
 var MAX_CACHE_KEY_LENGTH = 1024;
 var MAX_PATTERN_LENGTH = 1024;
@@ -710,7 +898,6 @@ var CircuitBreakerManager = class {
     if (!options) {
       return;
     }
-    this.pruneIfNeeded();
     const failureThreshold = options.failureThreshold ?? 3;
     const cooldownMs = options.cooldownMs ?? 3e4;
     const state = this.breakers.get(key) ?? { failures: 0, openUntil: null, createdAt: Date.now() };
@@ -719,6 +906,7 @@ var CircuitBreakerManager = class {
       state.openUntil = Date.now() + cooldownMs;
     }
     this.breakers.set(key, state);
+    this.pruneIfNeeded();
   }
   recordSuccess(key) {
     this.breakers.delete(key);
@@ -1346,15 +1534,10 @@ var CacheStack = class extends EventEmitter {
   snapshotSerializer = new JsonSerializer();
   backgroundRefreshes = /* @__PURE__ */ new Map();
   layerDegradedUntil = /* @__PURE__ */ new Map();
-  keyEpochs = /* @__PURE__ */ new Map();
+  maintenance = new CacheStackMaintenance();
   ttlResolver;
   circuitBreakerManager;
   currentGeneration;
-  writeBehindQueue = [];
-  writeBehindTimer;
-  writeBehindFlushPromise;
-  generationCleanupPromise;
-  clearEpoch = 0;
   isDisconnecting = false;
   disconnectPromise;
   /**
@@ -1510,7 +1693,7 @@ var CacheStack = class extends EventEmitter {
   }
   async clear() {
     await this.awaitStartup("clear");
-    this.beginClearEpoch();
+    this.maintenance.beginClearEpoch();
     await Promise.all(this.layers.map((layer) => layer.clear()));
     await this.tagIndex.clear();
     this.ttlResolver.clearProfiles();
@@ -1768,9 +1951,15 @@ var CacheStack = class extends EventEmitter {
   bumpGeneration(nextGeneration) {
     const current = this.currentGeneration ?? 0;
     const previousGeneration = this.currentGeneration;
-    this.currentGeneration = nextGeneration ?? current + 1;
-    if (previousGeneration !== void 0 && previousGeneration !== this.currentGeneration && this.shouldCleanupGenerations()) {
-      this.scheduleGenerationCleanup(previousGeneration);
+    const updatedGeneration = nextGeneration ?? current + 1;
+    const generationToCleanup = resolveGenerationCleanupTarget({
+      previousGeneration,
+      nextGeneration: updatedGeneration,
+      generationCleanup: this.options.generationCleanup
+    });
+    this.currentGeneration = updatedGeneration;
+    if (generationToCleanup !== null) {
+      this.scheduleGenerationCleanup(generationToCleanup);
     }
     return this.currentGeneration;
   }
@@ -1914,12 +2103,9 @@ var CacheStack = class extends EventEmitter {
         await this.startup;
         await this.unsubscribeInvalidation?.();
         await this.flushWriteBehindQueue();
-        await this.generationCleanupPromise;
+        await this.maintenance.waitForGenerationCleanup();
         await Promise.allSettled([...this.backgroundRefreshes.values()]);
-        if (this.writeBehindTimer) {
-          clearInterval(this.writeBehindTimer);
-          this.writeBehindTimer = void 0;
-        }
+        this.maintenance.disposeWriteBehindTimer();
         await Promise.allSettled(this.layers.map((layer) => layer.dispose?.() ?? Promise.resolve()));
       })();
     }
@@ -1995,13 +2181,13 @@ var CacheStack = class extends EventEmitter {
       if (!this.shouldNegativeCache(options)) {
         return null;
       }
-      if (this.isWriteOutdated(key, expectedClearEpoch, expectedKeyEpoch)) {
+      if (this.maintenance.isWriteOutdated(key, expectedClearEpoch, expectedKeyEpoch)) {
         this.logger.debug?.("skip-negative-store-after-invalidation", {
           key,
           expectedClearEpoch,
-          clearEpoch: this.clearEpoch,
+          clearEpoch: this.maintenance.currentClearEpoch(),
           expectedKeyEpoch,
-          keyEpoch: this.currentKeyEpoch(key)
+          keyEpoch: this.maintenance.currentKeyEpoch(key)
         });
         return null;
       }
@@ -2017,13 +2203,13 @@ var CacheStack = class extends EventEmitter {
         this.logger.warn?.("shouldCache-error", { key, error: this.formatError(error) });
       }
     }
-    if (this.isWriteOutdated(key, expectedClearEpoch, expectedKeyEpoch)) {
+    if (this.maintenance.isWriteOutdated(key, expectedClearEpoch, expectedKeyEpoch)) {
       this.logger.debug?.("skip-store-after-invalidation", {
         key,
         expectedClearEpoch,
-        clearEpoch: this.clearEpoch,
+        clearEpoch: this.maintenance.currentClearEpoch(),
         expectedKeyEpoch,
-        keyEpoch: this.currentKeyEpoch(key)
+        keyEpoch: this.maintenance.currentKeyEpoch(key)
       });
       return fetched;
     }
@@ -2031,10 +2217,10 @@ var CacheStack = class extends EventEmitter {
     return fetched;
   }
   async storeEntry(key, kind, value, options) {
-    const clearEpoch = this.clearEpoch;
-    const keyEpoch = this.currentKeyEpoch(key);
+    const clearEpoch = this.maintenance.currentClearEpoch();
+    const keyEpoch = this.maintenance.currentKeyEpoch(key);
     await this.writeAcrossLayers(key, kind, value, options);
-    if (this.isWriteOutdated(key, clearEpoch, keyEpoch)) {
+    if (this.maintenance.isWriteOutdated(key, clearEpoch, keyEpoch)) {
       return;
     }
     if (options?.tags) {
@@ -2051,8 +2237,8 @@ var CacheStack = class extends EventEmitter {
   }
   async writeBatch(entries) {
     const now = Date.now();
-    const clearEpoch = this.clearEpoch;
-    const entryEpochs = new Map(entries.map((entry) => [entry.key, this.currentKeyEpoch(entry.key)]));
+    const clearEpoch = this.maintenance.currentClearEpoch();
+    const entryEpochs = new Map(entries.map((entry) => [entry.key, this.maintenance.currentKeyEpoch(entry.key)]));
     const entriesByLayer = /* @__PURE__ */ new Map();
     const immediateOperations = [];
     const deferredOperations = [];
@@ -2069,11 +2255,11 @@ var CacheStack = class extends EventEmitter {
     }
     for (const [layer, layerEntries] of entriesByLayer.entries()) {
       const operation = async () => {
-        if (clearEpoch !== this.clearEpoch) {
+        if (clearEpoch !== this.maintenance.currentClearEpoch()) {
           return;
         }
         const activeEntries = layerEntries.filter(
-          (entry) => (entryEpochs.get(entry.key) ?? 0) === this.currentKeyEpoch(entry.key)
+          (entry) => (entryEpochs.get(entry.key) ?? 0) === this.maintenance.currentKeyEpoch(entry.key)
         );
         if (activeEntries.length === 0) {
           return;
@@ -2096,11 +2282,11 @@ var CacheStack = class extends EventEmitter {
     }
     await this.executeLayerOperations(immediateOperations, { key: "batch", action: "mset" });
     await Promise.all(deferredOperations.map((operation) => this.enqueueWriteBehind(operation)));
-    if (clearEpoch !== this.clearEpoch) {
+    if (clearEpoch !== this.maintenance.currentClearEpoch()) {
       return;
     }
     for (const entry of entries) {
-      if (this.isWriteOutdated(entry.key, clearEpoch, entryEpochs.get(entry.key))) {
+      if (this.maintenance.isWriteOutdated(entry.key, clearEpoch, entryEpochs.get(entry.key))) {
         continue;
       }
       if (entry.options?.tags) {
@@ -2204,13 +2390,13 @@ var CacheStack = class extends EventEmitter {
   }
   async writeAcrossLayers(key, kind, value, options) {
     const now = Date.now();
-    const clearEpoch = this.clearEpoch;
-    const keyEpoch = this.currentKeyEpoch(key);
+    const clearEpoch = this.maintenance.currentClearEpoch();
+    const keyEpoch = this.maintenance.currentKeyEpoch(key);
     const immediateOperations = [];
     const deferredOperations = [];
     for (const layer of this.layers) {
       const operation = async () => {
-        if (this.isWriteOutdated(key, clearEpoch, keyEpoch)) {
+        if (this.maintenance.isWriteOutdated(key, clearEpoch, keyEpoch)) {
           return;
         }
         if (this.shouldSkipLayer(layer)) {
@@ -2273,11 +2459,14 @@ var CacheStack = class extends EventEmitter {
     return options?.negativeCache ?? this.options.negativeCaching ?? false;
   }
   scheduleBackgroundRefresh(key, fetcher, options) {
-    if (this.isDisconnecting || this.backgroundRefreshes.has(key)) {
+    if (!shouldStartBackgroundRefresh({
+      isDisconnecting: this.isDisconnecting,
+      hasRefreshInFlight: this.backgroundRefreshes.has(key)
+    })) {
       return;
     }
-    const clearEpoch = this.clearEpoch;
-    const keyEpoch = this.currentKeyEpoch(key);
+    const clearEpoch = this.maintenance.currentClearEpoch();
+    const keyEpoch = this.maintenance.currentKeyEpoch(key);
     const refresh = (async () => {
       this.metricsCollector.increment("refreshes");
       try {
@@ -2315,7 +2504,7 @@ var CacheStack = class extends EventEmitter {
     if (keys.length === 0) {
       return;
     }
-    this.bumpKeyEpochs(keys);
+    this.maintenance.bumpKeyEpochs(keys);
     await this.deleteKeysFromLayers(this.layers, keys);
     for (const key of keys) {
       await this.tagIndex.remove(key);
@@ -2339,7 +2528,7 @@ var CacheStack = class extends EventEmitter {
     }
     const localLayers = this.layers.filter((layer) => layer.isLocal);
     if (message.scope === "clear") {
-      this.beginClearEpoch();
+      this.maintenance.beginClearEpoch();
       await Promise.all(localLayers.map((layer) => layer.clear()));
       await this.tagIndex.clear();
       this.ttlResolver.clearProfiles();
@@ -2347,7 +2536,7 @@ var CacheStack = class extends EventEmitter {
       return;
     }
     const keys = message.keys ?? [];
-    this.bumpKeyEpochs(keys);
+    this.maintenance.bumpKeyEpochs(keys);
     await this.deleteKeysFromLayers(localLayers, keys);
     if (message.operation !== "write") {
       for (const key of keys) {
@@ -2405,35 +2594,22 @@ var CacheStack = class extends EventEmitter {
   shouldBroadcastL1Invalidation() {
     return this.options.broadcastL1Invalidation ?? this.options.publishSetInvalidation ?? false;
   }
-  shouldCleanupGenerations() {
-    return Boolean(this.options.generationCleanup);
-  }
-  generationCleanupBatchSize() {
-    const configured = typeof this.options.generationCleanup === "object" ? this.options.generationCleanup.batchSize : void 0;
-    return configured ?? 500;
-  }
   scheduleGenerationCleanup(generation) {
-    const task = (this.generationCleanupPromise ?? Promise.resolve()).then(() => this.cleanupGeneration(generation)).catch((error) => {
-      this.logger.warn?.("generation-cleanup-error", {
-        generation,
-        error: this.formatError(error)
-      });
-    });
-    this.generationCleanupPromise = task.finally(() => {
-      if (this.generationCleanupPromise === task) {
-        this.generationCleanupPromise = void 0;
+    this.maintenance.scheduleGenerationCleanup(
+      generation,
+      async (generationToClean) => this.cleanupGeneration(generationToClean),
+      (failedGeneration, error) => {
+        this.logger.warn?.("generation-cleanup-error", {
+          generation: failedGeneration,
+          error: this.formatError(error)
+        });
       }
-    });
+    );
   }
   async cleanupGeneration(generation) {
     const prefix = `v${generation}:`;
     const keys = await this.keyDiscovery.collectKeysWithPrefix(prefix);
-    if (keys.length === 0) {
-      return;
-    }
-    const batchSize = this.generationCleanupBatchSize();
-    for (let index = 0; index < keys.length; index += batchSize) {
-      const batch = keys.slice(index, index + batchSize);
+    for (const batch of planGenerationCleanupBatches(keys, this.options.generationCleanup)) {
       await this.deleteKeys(batch);
       await this.publishInvalidation({
         scope: "keys",
@@ -2444,80 +2620,34 @@ var CacheStack = class extends EventEmitter {
     }
   }
   initializeWriteBehind(options) {
-    if (this.options.writeStrategy !== "write-behind") {
-      return;
-    }
-    const flushIntervalMs = options?.flushIntervalMs;
-    if (!flushIntervalMs || flushIntervalMs <= 0) {
-      return;
-    }
-    this.writeBehindTimer = setInterval(() => {
-      void this.flushWriteBehindQueue();
-    }, flushIntervalMs);
-    this.writeBehindTimer.unref?.();
+    this.maintenance.initializeWriteBehindTimer(
+      this.options.writeStrategy,
+      options,
+      this.flushWriteBehindQueue.bind(this)
+    );
   }
   shouldWriteBehind(layer) {
     return this.options.writeStrategy === "write-behind" && !layer.isLocal;
   }
-  beginClearEpoch() {
-    this.clearEpoch += 1;
-    this.keyEpochs.clear();
-    this.writeBehindQueue.length = 0;
-  }
-  currentKeyEpoch(key) {
-    return this.keyEpochs.get(key) ?? 0;
-  }
-  bumpKeyEpochs(keys) {
-    for (const key of keys) {
-      this.keyEpochs.set(key, this.currentKeyEpoch(key) + 1);
-    }
-  }
-  isWriteOutdated(key, expectedClearEpoch, expectedKeyEpoch) {
-    if (expectedClearEpoch !== void 0 && expectedClearEpoch !== this.clearEpoch) {
-      return true;
-    }
-    if (expectedKeyEpoch !== void 0 && expectedKeyEpoch !== this.currentKeyEpoch(key)) {
-      return true;
-    }
-    return false;
-  }
   async enqueueWriteBehind(operation) {
-    this.writeBehindQueue.push(operation);
-    const batchSize = this.options.writeBehind?.batchSize ?? 100;
-    const maxQueueSize = this.options.writeBehind?.maxQueueSize ?? batchSize * 10;
-    if (this.writeBehindQueue.length >= batchSize) {
-      await this.flushWriteBehindQueue();
-      return;
-    }
-    if (this.writeBehindQueue.length >= maxQueueSize) {
-      await this.flushWriteBehindQueue();
-    }
+    await this.maintenance.enqueueWriteBehind(operation, this.options.writeBehind, this.runWriteBehindBatch.bind(this));
   }
   async flushWriteBehindQueue() {
-    if (this.writeBehindFlushPromise || this.writeBehindQueue.length === 0) {
-      await this.writeBehindFlushPromise;
+    await this.maintenance.flushWriteBehindQueue(this.options.writeBehind, this.runWriteBehindBatch.bind(this));
+  }
+  async runWriteBehindBatch(batch) {
+    const results = await Promise.allSettled(batch.map((operation) => operation()));
+    const failures = results.filter((result) => result.status === "rejected");
+    if (failures.length === 0) {
       return;
     }
-    const batchSize = this.options.writeBehind?.batchSize ?? 100;
-    const batch = this.writeBehindQueue.splice(0, batchSize);
-    this.writeBehindFlushPromise = (async () => {
-      const results = await Promise.allSettled(batch.map((operation) => operation()));
-      const failures = results.filter((result) => result.status === "rejected");
-      if (failures.length > 0) {
-        this.metricsCollector.increment("writeFailures", failures.length);
-        this.logger.error?.("write-behind-flush-failure", {
-          failed: failures.length,
-          total: batch.length,
-          errors: failures.map((failure) => this.formatError(failure.reason))
-        });
-        this.emitError("write-behind", { failed: failures.length, total: batch.length });
-      }
-    })();
-    await this.writeBehindFlushPromise;
-    this.writeBehindFlushPromise = void 0;
-    if (this.writeBehindQueue.length > 0) {
-      await this.flushWriteBehindQueue();
-    }
+    this.metricsCollector.increment("writeFailures", failures.length);
+    this.logger.error?.("write-behind-flush-failure", {
+      failed: failures.length,
+      total: batch.length,
+      errors: failures.map((failure) => this.formatError(failure.reason))
+    });
+    this.emitError("write-behind", { failed: failures.length, total: batch.length });
   }
   buildLayerSetEntry(layer, key, kind, value, options, now) {
     const freshTtl = this.resolveFreshTtl(key, layer.name, kind, options, layer.defaultTtl, value);
@@ -2547,32 +2677,17 @@ var CacheStack = class extends EventEmitter {
       return [];
     }
     const [firstGroup, ...rest] = groups;
-    if (!firstGroup) {
-      return [];
-    }
     const restSets = rest.map((group) => new Set(group));
     return [...new Set(firstGroup)].filter((key) => restSets.every((group) => group.has(key)));
   }
   qualifyKey(key) {
-    const prefix = this.generationPrefix();
-    return prefix ? `${prefix}${key}` : key;
+    return qualifyGenerationKey(key, this.currentGeneration);
   }
   qualifyPattern(pattern) {
-    const prefix = this.generationPrefix();
-    return prefix ? `${prefix}${pattern}` : pattern;
+    return qualifyGenerationPattern(pattern, this.currentGeneration);
   }
   stripQualifiedKey(key) {
-    const prefix = this.generationPrefix();
-    if (!prefix || !key.startsWith(prefix)) {
-      return key;
-    }
-    return key.slice(prefix.length);
-  }
-  generationPrefix() {
-    if (this.currentGeneration === void 0) {
-      return "";
-    }
-    return `v${this.currentGeneration}:`;
+    return stripGenerationPrefix(key, this.currentGeneration);
   }
   async deleteKeysFromLayers(layers, keys) {
     await Promise.all(
@@ -2663,37 +2778,38 @@ var CacheStack = class extends EventEmitter {
     this.assertActive(operation);
   }
   async applyFreshReadPolicies(key, hit, options, fetcher) {
-    const refreshAhead = this.resolveLayerSeconds(hit.layerName, options?.refreshAhead, this.options.refreshAhead, 0) ?? 0;
-    const remainingFreshTtl = remainingFreshTtlSeconds(hit.stored) ?? 0;
-    if ((options?.slidingTtl ?? false) && isStoredValueEnvelope(hit.stored)) {
-      const refreshed = refreshStoredEnvelope(hit.stored);
-      const ttl = remainingStoredTtlSeconds(refreshed);
+    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, refreshed, ttl);
+          await layer.set(key, plan.refreshedStored, plan.refreshedStoredTtl);
         } catch (error) {
           await this.handleLayerFailure(layer, "sliding-ttl", error);
         }
       }
     }
-    if (fetcher && refreshAhead > 0 && remainingFreshTtl > 0 && remainingFreshTtl <= refreshAhead) {
+    if (fetcher && plan.shouldScheduleBackgroundRefresh) {
       this.scheduleBackgroundRefresh(key, fetcher, options);
     }
   }
   shouldSkipLayer(layer) {
-    const degradedUntil = this.layerDegradedUntil.get(layer.name);
-    return degradedUntil !== void 0 && degradedUntil > Date.now();
+    return shouldSkipLayer(this.layerDegradedUntil.get(layer.name));
   }
   async handleLayerFailure(layer, operation, error) {
-    if (!this.isGracefulDegradationEnabled()) {
+    const recovery = resolveRecoverableLayerFailure(this.options.gracefulDegradation);
+    if (!recovery.degrade) {
       throw error;
     }
-    const retryAfterMs = typeof this.options.gracefulDegradation === "object" ? this.options.gracefulDegradation.retryAfterMs ?? 1e4 : 1e4;
-    this.layerDegradedUntil.set(layer.name, Date.now() + retryAfterMs);
+    this.layerDegradedUntil.set(layer.name, recovery.degradedUntil);
     this.metricsCollector.increment("degradedOperations");
     this.logger.warn?.("layer-degraded", { layer: layer.name, operation, error: this.formatError(error) });
     this.emitError(operation, { layer: layer.name, degraded: true, error: this.formatError(error) });
@@ -3897,7 +4013,7 @@ var MsgpackSerializer = class {
     return Buffer.from(encode(value));
   }
   deserialize(payload) {
-    const normalized = Buffer.isBuffer(payload) ? payload : Buffer.from(payload);
+    const normalized = Buffer.isBuffer(payload) ? payload : Buffer.from(payload, "latin1");
     return sanitizeMsgpackValue(decode(normalized), 0, { count: 0 });
   }
 };