layercache 1.1.0 → 1.2.1

package/packages/nestjs/dist/index.js

@@ -46,63 +46,260 @@ function Cacheable(options) {
 import { Global, Inject, Module } from "@nestjs/common";
 
 // ../../src/CacheStack.ts
-import { randomUUID } from "crypto";
 import { EventEmitter } from "events";
-import { promises as fs } from "fs";
+
+// ../../node_modules/async-mutex/index.mjs
+var E_TIMEOUT = new Error("timeout while waiting for mutex to become available");
+var E_ALREADY_LOCKED = new Error("mutex already locked");
+var E_CANCELED = new Error("request for lock canceled");
+var __awaiter$2 = function(thisArg, _arguments, P, generator) {
+  function adopt(value) {
+    return value instanceof P ? value : new P(function(resolve) {
+      resolve(value);
+    });
+  }
+  return new (P || (P = Promise))(function(resolve, reject) {
+    function fulfilled(value) {
+      try {
+        step(generator.next(value));
+      } catch (e) {
+        reject(e);
+      }
+    }
+    function rejected(value) {
+      try {
+        step(generator["throw"](value));
+      } catch (e) {
+        reject(e);
+      }
+    }
+    function step(result) {
+      result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected);
+    }
+    step((generator = generator.apply(thisArg, _arguments || [])).next());
+  });
+};
+var Semaphore = class {
+  constructor(_value, _cancelError = E_CANCELED) {
+    this._value = _value;
+    this._cancelError = _cancelError;
+    this._weightedQueues = [];
+    this._weightedWaiters = [];
+  }
+  acquire(weight = 1) {
+    if (weight <= 0)
+      throw new Error(`invalid weight ${weight}: must be positive`);
+    return new Promise((resolve, reject) => {
+      if (!this._weightedQueues[weight - 1])
+        this._weightedQueues[weight - 1] = [];
+      this._weightedQueues[weight - 1].push({ resolve, reject });
+      this._dispatch();
+    });
+  }
+  runExclusive(callback, weight = 1) {
+    return __awaiter$2(this, void 0, void 0, function* () {
+      const [value, release] = yield this.acquire(weight);
+      try {
+        return yield callback(value);
+      } finally {
+        release();
+      }
+    });
+  }
+  waitForUnlock(weight = 1) {
+    if (weight <= 0)
+      throw new Error(`invalid weight ${weight}: must be positive`);
+    return new Promise((resolve) => {
+      if (!this._weightedWaiters[weight - 1])
+        this._weightedWaiters[weight - 1] = [];
+      this._weightedWaiters[weight - 1].push(resolve);
+      this._dispatch();
+    });
+  }
+  isLocked() {
+    return this._value <= 0;
+  }
+  getValue() {
+    return this._value;
+  }
+  setValue(value) {
+    this._value = value;
+    this._dispatch();
+  }
+  release(weight = 1) {
+    if (weight <= 0)
+      throw new Error(`invalid weight ${weight}: must be positive`);
+    this._value += weight;
+    this._dispatch();
+  }
+  cancel() {
+    this._weightedQueues.forEach((queue) => queue.forEach((entry) => entry.reject(this._cancelError)));
+    this._weightedQueues = [];
+  }
+  _dispatch() {
+    var _a;
+    for (let weight = this._value; weight > 0; weight--) {
+      const queueEntry = (_a = this._weightedQueues[weight - 1]) === null || _a === void 0 ? void 0 : _a.shift();
+      if (!queueEntry)
+        continue;
+      const previousValue = this._value;
+      const previousWeight = weight;
+      this._value -= weight;
+      weight = this._value + 1;
+      queueEntry.resolve([previousValue, this._newReleaser(previousWeight)]);
+    }
+    this._drainUnlockWaiters();
+  }
+  _newReleaser(weight) {
+    let called = false;
+    return () => {
+      if (called)
+        return;
+      called = true;
+      this.release(weight);
+    };
+  }
+  _drainUnlockWaiters() {
+    for (let weight = this._value; weight > 0; weight--) {
+      if (!this._weightedWaiters[weight - 1])
+        continue;
+      this._weightedWaiters[weight - 1].forEach((waiter) => waiter());
+      this._weightedWaiters[weight - 1] = [];
+    }
+  }
+};
+var __awaiter$1 = function(thisArg, _arguments, P, generator) {
+  function adopt(value) {
+    return value instanceof P ? value : new P(function(resolve) {
+      resolve(value);
+    });
+  }
+  return new (P || (P = Promise))(function(resolve, reject) {
+    function fulfilled(value) {
+      try {
+        step(generator.next(value));
+      } catch (e) {
+        reject(e);
+      }
+    }
+    function rejected(value) {
+      try {
+        step(generator["throw"](value));
+      } catch (e) {
+        reject(e);
+      }
+    }
+    function step(result) {
+      result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected);
+    }
+    step((generator = generator.apply(thisArg, _arguments || [])).next());
+  });
+};
+var Mutex = class {
+  constructor(cancelError) {
+    this._semaphore = new Semaphore(1, cancelError);
+  }
+  acquire() {
+    return __awaiter$1(this, void 0, void 0, function* () {
+      const [, releaser] = yield this._semaphore.acquire();
+      return releaser;
+    });
+  }
+  runExclusive(callback) {
+    return this._semaphore.runExclusive(() => callback());
+  }
+  isLocked() {
+    return this._semaphore.isLocked();
+  }
+  waitForUnlock() {
+    return this._semaphore.waitForUnlock();
+  }
+  release() {
+    if (this._semaphore.isLocked())
+      this._semaphore.release();
+  }
+  cancel() {
+    return this._semaphore.cancel();
+  }
+};
 
 // ../../src/CacheNamespace.ts
-var CacheNamespace = class {
+var CacheNamespace = class _CacheNamespace {
   constructor(cache, prefix) {
     this.cache = cache;
     this.prefix = prefix;
   }
   cache;
   prefix;
+  static metricsMutexes = /* @__PURE__ */ new WeakMap();
+  metrics = emptyMetrics();
   async get(key, fetcher, options) {
-    return this.cache.get(this.qualify(key), fetcher, options);
+    return this.trackMetrics(() => this.cache.get(this.qualify(key), fetcher, options));
   }
   async getOrSet(key, fetcher, options) {
-    return this.cache.getOrSet(this.qualify(key), fetcher, options);
+    return this.trackMetrics(() => this.cache.getOrSet(this.qualify(key), fetcher, options));
+  }
+  /**
+   * Like `get()`, but throws `CacheMissError` instead of returning `null`.
+   */
+  async getOrThrow(key, fetcher, options) {
+    return this.trackMetrics(() => this.cache.getOrThrow(this.qualify(key), fetcher, options));
   }
   async has(key) {
-    return this.cache.has(this.qualify(key));
+    return this.trackMetrics(() => this.cache.has(this.qualify(key)));
   }
   async ttl(key) {
-    return this.cache.ttl(this.qualify(key));
+    return this.trackMetrics(() => this.cache.ttl(this.qualify(key)));
   }
   async set(key, value, options) {
-    await this.cache.set(this.qualify(key), value, options);
+    await this.trackMetrics(() => this.cache.set(this.qualify(key), value, options));
   }
   async delete(key) {
-    await this.cache.delete(this.qualify(key));
+    await this.trackMetrics(() => this.cache.delete(this.qualify(key)));
   }
   async mdelete(keys) {
-    await this.cache.mdelete(keys.map((k) => this.qualify(k)));
+    await this.trackMetrics(() => this.cache.mdelete(keys.map((k) => this.qualify(k))));
   }
   async clear() {
-    await this.cache.invalidateByPattern(`${this.prefix}:*`);
+    await this.trackMetrics(() => this.cache.invalidateByPrefix(this.prefix));
   }
   async mget(entries) {
-    return this.cache.mget(
-      entries.map((entry) => ({
-        ...entry,
-        key: this.qualify(entry.key)
-      }))
+    return this.trackMetrics(
+      () => this.cache.mget(
+        entries.map((entry) => ({
+          ...entry,
+          key: this.qualify(entry.key)
+        }))
+      )
     );
   }
   async mset(entries) {
-    await this.cache.mset(
-      entries.map((entry) => ({
-        ...entry,
-        key: this.qualify(entry.key)
-      }))
+    await this.trackMetrics(
+      () => this.cache.mset(
+        entries.map((entry) => ({
+          ...entry,
+          key: this.qualify(entry.key)
+        }))
+      )
     );
   }
   async invalidateByTag(tag) {
-    await this.cache.invalidateByTag(tag);
+    await this.trackMetrics(() => this.cache.invalidateByTag(tag));
+  }
+  async invalidateByTags(tags, mode = "any") {
+    await this.trackMetrics(() => this.cache.invalidateByTags(tags, mode));
   }
   async invalidateByPattern(pattern) {
-    await this.cache.invalidateByPattern(this.qualify(pattern));
+    await this.trackMetrics(() => this.cache.invalidateByPattern(this.qualify(pattern)));
+  }
+  async invalidateByPrefix(prefix) {
+    await this.trackMetrics(() => this.cache.invalidateByPrefix(this.qualify(prefix)));
+  }
+  /**
+   * Returns detailed metadata about a single cache key within this namespace.
+   */
+  async inspect(key) {
+    return this.cache.inspect(this.qualify(key));
   }
   wrap(keyPrefix, fetcher, options) {
     return this.cache.wrap(`${this.prefix}:${keyPrefix}`, fetcher, options);
@@ -117,15 +314,159 @@ var CacheNamespace = class {
     );
   }
   getMetrics() {
-    return this.cache.getMetrics();
+    return cloneMetrics(this.metrics);
   }
   getHitRate() {
-    return this.cache.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 };
+  }
+  /**
+   * Creates a nested namespace. Keys are prefixed with `parentPrefix:childPrefix:`.
+   *
+   * ```ts
+   * const tenant = cache.namespace('tenant:abc')
+   * const posts = tenant.namespace('posts')
+   * // keys become: "tenant:abc:posts:mykey"
+   * ```
+   */
+  namespace(childPrefix) {
+    return new _CacheNamespace(this.cache, `${this.prefix}:${childPrefix}`);
   }
   qualify(key) {
     return `${this.prefix}:${key}`;
   }
+  async trackMetrics(operation) {
+    return this.getMetricsMutex().runExclusive(async () => {
+      const before = this.cache.getMetrics();
+      const result = await operation();
+      const after = this.cache.getMetrics();
+      this.metrics = addMetrics(this.metrics, diffMetrics(before, after));
+      return result;
+    });
+  }
+  getMetricsMutex() {
+    const existing = _CacheNamespace.metricsMutexes.get(this.cache);
+    if (existing) {
+      return existing;
+    }
+    const mutex = new Mutex();
+    _CacheNamespace.metricsMutexes.set(this.cache, mutex);
+    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;
+}
 
 // ../../src/internal/CircuitBreakerManager.ts
 var CircuitBreakerManager = class {
@@ -219,11 +560,105 @@ var CircuitBreakerManager = class {
   }
 };
 
+// ../../src/internal/FetchRateLimiter.ts
+var FetchRateLimiter = class {
+  active = 0;
+  queue = [];
+  startedAt = [];
+  drainTimer;
+  async schedule(options, task) {
+    if (!options) {
+      return task();
+    }
+    const normalized = this.normalize(options);
+    if (!normalized) {
+      return task();
+    }
+    return new Promise((resolve, reject) => {
+      this.queue.push({ options: normalized, task, resolve, reject });
+      this.drain();
+    });
+  }
+  normalize(options) {
+    const maxConcurrent = options.maxConcurrent;
+    const intervalMs = options.intervalMs;
+    const maxPerInterval = options.maxPerInterval;
+    if (!maxConcurrent && !(intervalMs && maxPerInterval)) {
+      return void 0;
+    }
+    return {
+      maxConcurrent,
+      intervalMs,
+      maxPerInterval
+    };
+  }
+  drain() {
+    if (this.drainTimer) {
+      clearTimeout(this.drainTimer);
+      this.drainTimer = void 0;
+    }
+    while (this.queue.length > 0) {
+      const next = this.queue[0];
+      if (!next) {
+        return;
+      }
+      const waitMs = this.waitTime(next.options);
+      if (waitMs > 0) {
+        this.drainTimer = setTimeout(() => {
+          this.drainTimer = void 0;
+          this.drain();
+        }, waitMs);
+        this.drainTimer.unref?.();
+        return;
+      }
+      this.queue.shift();
+      this.active += 1;
+      this.startedAt.push(Date.now());
+      void next.task().then(next.resolve, next.reject).finally(() => {
+        this.active -= 1;
+        this.drain();
+      });
+    }
+  }
+  waitTime(options) {
+    const now = Date.now();
+    if (options.maxConcurrent && this.active >= options.maxConcurrent) {
+      return 1;
+    }
+    if (!options.intervalMs || !options.maxPerInterval) {
+      return 0;
+    }
+    this.prune(now, options.intervalMs);
+    if (this.startedAt.length < options.maxPerInterval) {
+      return 0;
+    }
+    const oldest = this.startedAt[0];
+    if (!oldest) {
+      return 0;
+    }
+    return Math.max(1, options.intervalMs - (now - oldest));
+  }
+  prune(now, intervalMs) {
+    while (this.startedAt.length > 0) {
+      const startedAt = this.startedAt[0];
+      if (startedAt === void 0 || now - startedAt < intervalMs) {
+        break;
+      }
+      this.startedAt.shift();
+    }
+  }
+};
+
 // ../../src/internal/MetricsCollector.ts
 var MetricsCollector = class {
   data = this.empty();
   get snapshot() {
-    return { ...this.data };
+    return {
+      ...this.data,
+      hitsByLayer: { ...this.data.hitsByLayer },
+      missesByLayer: { ...this.data.missesByLayer },
+      latencyByLayer: Object.fromEntries(Object.entries(this.data.latencyByLayer).map(([k, v]) => [k, { ...v }]))
+    };
   }
   increment(field, amount = 1) {
     ;
@@ -232,6 +667,22 @@ var MetricsCollector = class {
   incrementLayer(map, layerName) {
     this.data[map][layerName] = (this.data[map][layerName] ?? 0) + 1;
   }
+  /**
+   * Records a read latency sample for the given layer.
+   * Maintains a rolling average and max using Welford's online algorithm.
+   */
+  recordLatency(layerName, durationMs) {
+    const existing = this.data.latencyByLayer[layerName];
+    if (!existing) {
+      this.data.latencyByLayer[layerName] = { avgMs: durationMs, maxMs: durationMs, count: 1 };
+      return;
+    }
+    existing.count += 1;
+    existing.avgMs += (durationMs - existing.avgMs) / existing.count;
+    if (durationMs > existing.maxMs) {
+      existing.maxMs = durationMs;
+    }
+  }
   reset() {
     this.data = this.empty();
   }
@@ -266,6 +717,7 @@ var MetricsCollector = class {
       degradedOperations: 0,
       hitsByLayer: {},
       missesByLayer: {},
+      latencyByLayer: {},
       resetAt: Date.now()
     };
   }
@@ -393,13 +845,14 @@ var TtlResolver = class {
   clearProfiles() {
     this.accessProfiles.clear();
   }
-  resolveFreshTtl(key, layerName, kind, options, fallbackTtl, globalNegativeTtl, globalTtl) {
+  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(
       layerName,
       options?.negativeTtl,
       globalNegativeTtl,
-      this.resolveLayerSeconds(layerName, options?.ttl, globalTtl, fallbackTtl) ?? DEFAULT_NEGATIVE_TTL_SECONDS
-    ) : this.resolveLayerSeconds(layerName, options?.ttl, globalTtl, fallbackTtl);
+      this.resolveLayerSeconds(layerName, options?.ttl, globalTtl, policyTtl ?? fallbackTtl) ?? DEFAULT_NEGATIVE_TTL_SECONDS
+    ) : this.resolveLayerSeconds(layerName, options?.ttl, globalTtl, policyTtl ?? fallbackTtl);
     const adaptiveTtl = this.applyAdaptiveTtl(key, layerName, baseTtl, options?.adaptiveTtl);
     const jitter = this.resolveLayerSeconds(layerName, options?.ttlJitter, void 0);
     return this.applyJitter(adaptiveTtl, jitter);
@@ -438,6 +891,29 @@ var TtlResolver = class {
     const delta = (Math.random() * 2 - 1) * jitter;
     return Math.max(1, Math.round(ttl + delta));
   }
+  resolvePolicyTtl(key, value, policy) {
+    if (!policy) {
+      return void 0;
+    }
+    if (typeof policy === "function") {
+      return policy({ key, value });
+    }
+    const now = /* @__PURE__ */ new Date();
+    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));
+    }
+    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));
+    }
+    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);
+  }
   readLayerNumber(layerName, value) {
     if (typeof value === "number") {
       return value;
@@ -465,269 +941,133 @@ var PatternMatcher = class _PatternMatcher {
   /**
    * Tests whether a glob-style pattern matches a value.
    * Supports `*` (any sequence of characters) and `?` (any single character).
-   * Uses a linear-time algorithm to avoid ReDoS vulnerabilities.
+   * Uses a two-pointer algorithm to avoid ReDoS vulnerabilities and
+   * quadratic memory usage on long patterns/keys.
    */
   static matches(pattern, value) {
     return _PatternMatcher.matchLinear(pattern, value);
   }
   /**
-   * Linear-time glob matching using dynamic programming.
-   * Avoids catastrophic backtracking that RegExp-based glob matching can cause.
+   * Linear-time glob matching with O(1) extra memory.
    */
   static matchLinear(pattern, value) {
-    const m = pattern.length;
-    const n = value.length;
-    const dp = Array.from({ length: m + 1 }, () => new Array(n + 1).fill(false));
-    dp[0][0] = true;
-    for (let i = 1; i <= m; i++) {
-      if (pattern[i - 1] === "*") {
-        dp[i][0] = dp[i - 1]?.[0];
-      }
-    }
-    for (let i = 1; i <= m; i++) {
-      for (let j = 1; j <= n; j++) {
-        const pc = pattern[i - 1];
-        if (pc === "*") {
-          dp[i][j] = dp[i - 1]?.[j] || dp[i]?.[j - 1];
-        } else if (pc === "?" || pc === value[j - 1]) {
-          dp[i][j] = dp[i - 1]?.[j - 1];
-        }
-      }
-    }
-    return dp[m]?.[n];
-  }
-};
-
-// ../../src/invalidation/TagIndex.ts
-var TagIndex = class {
-  tagToKeys = /* @__PURE__ */ new Map();
-  keyToTags = /* @__PURE__ */ new Map();
-  knownKeys = /* @__PURE__ */ new Set();
-  async touch(key) {
-    this.knownKeys.add(key);
-  }
-  async track(key, tags) {
-    this.knownKeys.add(key);
-    if (tags.length === 0) {
-      return;
-    }
-    const existingTags = this.keyToTags.get(key);
-    if (existingTags) {
-      for (const tag of existingTags) {
-        this.tagToKeys.get(tag)?.delete(key);
-      }
-    }
-    const tagSet = new Set(tags);
-    this.keyToTags.set(key, tagSet);
-    for (const tag of tagSet) {
-      const keys = this.tagToKeys.get(tag) ?? /* @__PURE__ */ new Set();
-      keys.add(key);
-      this.tagToKeys.set(tag, keys);
-    }
-  }
-  async remove(key) {
-    this.knownKeys.delete(key);
-    const tags = this.keyToTags.get(key);
-    if (!tags) {
-      return;
-    }
-    for (const tag of tags) {
-      const keys = this.tagToKeys.get(tag);
-      if (!keys) {
+    let patternIndex = 0;
+    let valueIndex = 0;
+    let starIndex = -1;
+    let backtrackValueIndex = 0;
+    while (valueIndex < value.length) {
+      const patternChar = pattern[patternIndex];
+      const valueChar = value[valueIndex];
+      if (patternChar === "*" && patternIndex < pattern.length) {
+        starIndex = patternIndex;
+        patternIndex += 1;
+        backtrackValueIndex = valueIndex;
         continue;
       }
-      keys.delete(key);
-      if (keys.size === 0) {
-        this.tagToKeys.delete(tag);
-      }
-    }
-    this.keyToTags.delete(key);
-  }
-  async keysForTag(tag) {
-    return [...this.tagToKeys.get(tag) ?? /* @__PURE__ */ new Set()];
-  }
-  async matchPattern(pattern) {
-    return [...this.knownKeys].filter((key) => PatternMatcher.matches(pattern, key));
-  }
-  async clear() {
-    this.tagToKeys.clear();
-    this.keyToTags.clear();
-    this.knownKeys.clear();
-  }
-};
-
-// ../../node_modules/async-mutex/index.mjs
-var E_TIMEOUT = new Error("timeout while waiting for mutex to become available");
-var E_ALREADY_LOCKED = new Error("mutex already locked");
-var E_CANCELED = new Error("request for lock canceled");
-var __awaiter$2 = function(thisArg, _arguments, P, generator) {
-  function adopt(value) {
-    return value instanceof P ? value : new P(function(resolve) {
-      resolve(value);
-    });
-  }
-  return new (P || (P = Promise))(function(resolve, reject) {
-    function fulfilled(value) {
-      try {
-        step(generator.next(value));
-      } catch (e) {
-        reject(e);
-      }
-    }
-    function rejected(value) {
-      try {
-        step(generator["throw"](value));
-      } catch (e) {
-        reject(e);
-      }
-    }
-    function step(result) {
-      result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected);
-    }
-    step((generator = generator.apply(thisArg, _arguments || [])).next());
-  });
-};
-var Semaphore = class {
-  constructor(_value, _cancelError = E_CANCELED) {
-    this._value = _value;
-    this._cancelError = _cancelError;
-    this._weightedQueues = [];
-    this._weightedWaiters = [];
-  }
-  acquire(weight = 1) {
-    if (weight <= 0)
-      throw new Error(`invalid weight ${weight}: must be positive`);
-    return new Promise((resolve, reject) => {
-      if (!this._weightedQueues[weight - 1])
-        this._weightedQueues[weight - 1] = [];
-      this._weightedQueues[weight - 1].push({ resolve, reject });
-      this._dispatch();
-    });
-  }
-  runExclusive(callback, weight = 1) {
-    return __awaiter$2(this, void 0, void 0, function* () {
-      const [value, release] = yield this.acquire(weight);
-      try {
-        return yield callback(value);
-      } finally {
-        release();
-      }
-    });
-  }
-  waitForUnlock(weight = 1) {
-    if (weight <= 0)
-      throw new Error(`invalid weight ${weight}: must be positive`);
-    return new Promise((resolve) => {
-      if (!this._weightedWaiters[weight - 1])
-        this._weightedWaiters[weight - 1] = [];
-      this._weightedWaiters[weight - 1].push(resolve);
-      this._dispatch();
-    });
-  }
-  isLocked() {
-    return this._value <= 0;
-  }
-  getValue() {
-    return this._value;
-  }
-  setValue(value) {
-    this._value = value;
-    this._dispatch();
-  }
-  release(weight = 1) {
-    if (weight <= 0)
-      throw new Error(`invalid weight ${weight}: must be positive`);
-    this._value += weight;
-    this._dispatch();
-  }
-  cancel() {
-    this._weightedQueues.forEach((queue) => queue.forEach((entry) => entry.reject(this._cancelError)));
-    this._weightedQueues = [];
-  }
-  _dispatch() {
-    var _a;
-    for (let weight = this._value; weight > 0; weight--) {
-      const queueEntry = (_a = this._weightedQueues[weight - 1]) === null || _a === void 0 ? void 0 : _a.shift();
-      if (!queueEntry)
+      if (patternChar === "?" || patternChar === valueChar) {
+        patternIndex += 1;
+        valueIndex += 1;
         continue;
-      const previousValue = this._value;
-      const previousWeight = weight;
-      this._value -= weight;
-      weight = this._value + 1;
-      queueEntry.resolve([previousValue, this._newReleaser(previousWeight)]);
-    }
-    this._drainUnlockWaiters();
-  }
-  _newReleaser(weight) {
-    let called = false;
-    return () => {
-      if (called)
-        return;
-      called = true;
-      this.release(weight);
-    };
-  }
-  _drainUnlockWaiters() {
-    for (let weight = this._value; weight > 0; weight--) {
-      if (!this._weightedWaiters[weight - 1])
+      }
+      if (starIndex !== -1) {
+        patternIndex = starIndex + 1;
+        backtrackValueIndex += 1;
+        valueIndex = backtrackValueIndex;
         continue;
-      this._weightedWaiters[weight - 1].forEach((waiter) => waiter());
-      this._weightedWaiters[weight - 1] = [];
+      }
+      return false;
     }
+    while (patternIndex < pattern.length && pattern[patternIndex] === "*") {
+      patternIndex += 1;
+    }
+    return patternIndex === pattern.length;
   }
 };
-var __awaiter$1 = function(thisArg, _arguments, P, generator) {
-  function adopt(value) {
-    return value instanceof P ? value : new P(function(resolve) {
-      resolve(value);
-    });
+
+// ../../src/invalidation/TagIndex.ts
+var TagIndex = class {
+  tagToKeys = /* @__PURE__ */ new Map();
+  keyToTags = /* @__PURE__ */ new Map();
+  knownKeys = /* @__PURE__ */ new Set();
+  maxKnownKeys;
+  constructor(options = {}) {
+    this.maxKnownKeys = options.maxKnownKeys;
   }
-  return new (P || (P = Promise))(function(resolve, reject) {
-    function fulfilled(value) {
-      try {
-        step(generator.next(value));
-      } catch (e) {
-        reject(e);
-      }
+  async touch(key) {
+    this.knownKeys.add(key);
+    this.pruneKnownKeysIfNeeded();
+  }
+  async track(key, tags) {
+    this.knownKeys.add(key);
+    this.pruneKnownKeysIfNeeded();
+    if (tags.length === 0) {
+      return;
     }
-    function rejected(value) {
-      try {
-        step(generator["throw"](value));
-      } catch (e) {
-        reject(e);
+    const existingTags = this.keyToTags.get(key);
+    if (existingTags) {
+      for (const tag of existingTags) {
+        this.tagToKeys.get(tag)?.delete(key);
       }
     }
-    function step(result) {
-      result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected);
+    const tagSet = new Set(tags);
+    this.keyToTags.set(key, tagSet);
+    for (const tag of tagSet) {
+      const keys = this.tagToKeys.get(tag) ?? /* @__PURE__ */ new Set();
+      keys.add(key);
+      this.tagToKeys.set(tag, keys);
     }
-    step((generator = generator.apply(thisArg, _arguments || [])).next());
-  });
-};
-var Mutex = class {
-  constructor(cancelError) {
-    this._semaphore = new Semaphore(1, cancelError);
   }
-  acquire() {
-    return __awaiter$1(this, void 0, void 0, function* () {
-      const [, releaser] = yield this._semaphore.acquire();
-      return releaser;
-    });
+  async remove(key) {
+    this.removeKey(key);
   }
-  runExclusive(callback) {
-    return this._semaphore.runExclusive(() => callback());
+  async keysForTag(tag) {
+    return [...this.tagToKeys.get(tag) ?? /* @__PURE__ */ new Set()];
   }
-  isLocked() {
-    return this._semaphore.isLocked();
+  async keysForPrefix(prefix) {
+    return [...this.knownKeys].filter((key) => key.startsWith(prefix));
   }
-  waitForUnlock() {
-    return this._semaphore.waitForUnlock();
+  async tagsForKey(key) {
+    return [...this.keyToTags.get(key) ?? /* @__PURE__ */ new Set()];
   }
-  release() {
-    if (this._semaphore.isLocked())
-      this._semaphore.release();
+  async matchPattern(pattern) {
+    return [...this.knownKeys].filter((key) => PatternMatcher.matches(pattern, key));
   }
-  cancel() {
-    return this._semaphore.cancel();
+  async clear() {
+    this.tagToKeys.clear();
+    this.keyToTags.clear();
+    this.knownKeys.clear();
+  }
+  pruneKnownKeysIfNeeded() {
+    if (this.maxKnownKeys === void 0 || this.knownKeys.size <= this.maxKnownKeys) {
+      return;
+    }
+    const toRemove = Math.ceil(this.maxKnownKeys * 0.1);
+    let removed = 0;
+    for (const key of this.knownKeys) {
+      if (removed >= toRemove) {
+        break;
+      }
+      this.removeKey(key);
+      removed += 1;
+    }
+  }
+  removeKey(key) {
+    this.knownKeys.delete(key);
+    const tags = this.keyToTags.get(key);
+    if (!tags) {
+      return;
+    }
+    for (const tag of tags) {
+      const keys = this.tagToKeys.get(tag);
+      if (!keys) {
+        continue;
+      }
+      keys.delete(key);
+      if (keys.size === 0) {
+        this.tagToKeys.delete(tag);
+      }
+    }
+    this.keyToTags.delete(key);
   }
 };
 
@@ -756,6 +1096,16 @@ var StampedeGuard = class {
   }
 };
 
+// ../../src/types.ts
+var CacheMissError = class extends Error {
+  key;
+  constructor(key) {
+    super(`Cache miss for key "${key}".`);
+    this.name = "CacheMissError";
+    this.key = key;
+  }
+};
+
 // ../../src/CacheStack.ts
 var DEFAULT_SINGLE_FLIGHT_LEASE_MS = 3e4;
 var DEFAULT_SINGLE_FLIGHT_TIMEOUT_MS = 5e3;
@@ -799,6 +1149,7 @@ var CacheStack = class extends EventEmitter {
     const maxProfileEntries = options.maxProfileEntries ?? DEFAULT_MAX_PROFILE_ENTRIES;
     this.ttlResolver = new TtlResolver({ maxProfileEntries });
     this.circuitBreakerManager = new CircuitBreakerManager({ maxEntries: maxProfileEntries });
+    this.currentGeneration = options.generation;
     if (options.publishSetInvalidation !== void 0) {
       console.warn(
         "[layercache] CacheStackOptions.publishSetInvalidation is deprecated. Use broadcastL1Invalidation instead."
@@ -807,21 +1158,27 @@ var CacheStack = class extends EventEmitter {
     const debugEnv = process.env.DEBUG?.split(",").includes("layercache:debug") ?? false;
     this.logger = typeof options.logger === "object" ? options.logger : new DebugLogger(Boolean(options.logger) || debugEnv);
     this.tagIndex = options.tagIndex ?? new TagIndex();
+    this.initializeWriteBehind(options.writeBehind);
     this.startup = this.initialize();
   }
   layers;
   options;
   stampedeGuard = new StampedeGuard();
   metricsCollector = new MetricsCollector();
-  instanceId = randomUUID();
+  instanceId = createInstanceId();
   startup;
   unsubscribeInvalidation;
   logger;
   tagIndex;
+  fetchRateLimiter = new FetchRateLimiter();
   backgroundRefreshes = /* @__PURE__ */ new Map();
   layerDegradedUntil = /* @__PURE__ */ new Map();
   ttlResolver;
   circuitBreakerManager;
+  currentGeneration;
+  writeBehindQueue = [];
+  writeBehindTimer;
+  writeBehindFlushPromise;
   isDisconnecting = false;
   disconnectPromise;
   /**
@@ -831,9 +1188,9 @@ var CacheStack = class extends EventEmitter {
    * and no `fetcher` is provided.
    */
   async get(key, fetcher, options) {
-    const normalizedKey = this.validateCacheKey(key);
+    const normalizedKey = this.qualifyKey(this.validateCacheKey(key));
     this.validateWriteOptions(options);
-    await this.startup;
+    await this.awaitStartup("get");
     const hit = await this.readFromLayers(normalizedKey, options, "allow-stale");
     if (hit.found) {
       this.ttlResolver.recordAccess(normalizedKey);
@@ -882,12 +1239,24 @@ var CacheStack = class extends EventEmitter {
   async getOrSet(key, fetcher, options) {
     return this.get(key, fetcher, options);
   }
+  /**
+   * Like `get()`, but throws `CacheMissError` instead of returning `null`.
+   * Useful when the value is expected to exist or the fetcher is expected to
+   * return non-null.
+   */
+  async getOrThrow(key, fetcher, options) {
+    const value = await this.get(key, fetcher, options);
+    if (value === null) {
+      throw new CacheMissError(key);
+    }
+    return value;
+  }
   /**
    * Returns true if the given key exists and is not expired in any layer.
    */
   async has(key) {
-    const normalizedKey = this.validateCacheKey(key);
-    await this.startup;
+    const normalizedKey = this.qualifyKey(this.validateCacheKey(key));
+    await this.awaitStartup("has");
     for (const layer of this.layers) {
       if (this.shouldSkipLayer(layer)) {
         continue;
@@ -917,8 +1286,8 @@ var CacheStack = class extends EventEmitter {
    * that has it, or null if the key is not found / has no TTL.
    */
   async ttl(key) {
-    const normalizedKey = this.validateCacheKey(key);
-    await this.startup;
+    const normalizedKey = this.qualifyKey(this.validateCacheKey(key));
+    await this.awaitStartup("ttl");
     for (const layer of this.layers) {
       if (this.shouldSkipLayer(layer)) {
         continue;
@@ -939,17 +1308,17 @@ var CacheStack = class extends EventEmitter {
    * Stores a value in all cache layers. Overwrites any existing value.
    */
   async set(key, value, options) {
-    const normalizedKey = this.validateCacheKey(key);
+    const normalizedKey = this.qualifyKey(this.validateCacheKey(key));
     this.validateWriteOptions(options);
-    await this.startup;
+    await this.awaitStartup("set");
     await this.storeEntry(normalizedKey, "value", value, options);
   }
   /**
    * Deletes the key from all layers and publishes an invalidation message.
    */
   async delete(key) {
-    const normalizedKey = this.validateCacheKey(key);
-    await this.startup;
+    const normalizedKey = this.qualifyKey(this.validateCacheKey(key));
+    await this.awaitStartup("delete");
     await this.deleteKeys([normalizedKey]);
     await this.publishInvalidation({
       scope: "key",
@@ -959,7 +1328,7 @@ var CacheStack = class extends EventEmitter {
     });
   }
   async clear() {
-    await this.startup;
+    await this.awaitStartup("clear");
     await Promise.all(this.layers.map((layer) => layer.clear()));
     await this.tagIndex.clear();
     this.ttlResolver.clearProfiles();
@@ -975,23 +1344,25 @@ var CacheStack = class extends EventEmitter {
     if (keys.length === 0) {
       return;
     }
-    await this.startup;
+    await this.awaitStartup("mdelete");
     const normalizedKeys = keys.map((k) => this.validateCacheKey(k));
-    await this.deleteKeys(normalizedKeys);
+    const cacheKeys = normalizedKeys.map((key) => this.qualifyKey(key));
+    await this.deleteKeys(cacheKeys);
     await this.publishInvalidation({
       scope: "keys",
-      keys: normalizedKeys,
+      keys: cacheKeys,
       sourceId: this.instanceId,
       operation: "delete"
     });
   }
   async mget(entries) {
+    this.assertActive("mget");
     if (entries.length === 0) {
       return [];
     }
     const normalizedEntries = entries.map((entry) => ({
       ...entry,
-      key: this.validateCacheKey(entry.key)
+      key: this.qualifyKey(this.validateCacheKey(entry.key))
     }));
     normalizedEntries.forEach((entry) => this.validateWriteOptions(entry.options));
     const canFastPath = normalizedEntries.every((entry) => entry.fetch === void 0 && entry.options === void 0);
@@ -1017,7 +1388,7 @@ var CacheStack = class extends EventEmitter {
         })
       );
     }
-    await this.startup;
+    await this.awaitStartup("mget");
     const pending = /* @__PURE__ */ new Set();
     const indexesByKey = /* @__PURE__ */ new Map();
     const resultsByKey = /* @__PURE__ */ new Map();
@@ -1065,14 +1436,17 @@ var CacheStack = class extends EventEmitter {
     return normalizedEntries.map((entry) => resultsByKey.get(entry.key) ?? null);
   }
   async mset(entries) {
+    this.assertActive("mset");
     const normalizedEntries = entries.map((entry) => ({
       ...entry,
-      key: this.validateCacheKey(entry.key)
+      key: this.qualifyKey(this.validateCacheKey(entry.key))
     }));
     normalizedEntries.forEach((entry) => this.validateWriteOptions(entry.options));
-    await Promise.all(normalizedEntries.map((entry) => this.set(entry.key, entry.value, entry.options)));
+    await this.awaitStartup("mset");
+    await this.writeBatch(normalizedEntries);
   }
   async warm(entries, options = {}) {
+    this.assertActive("warm");
     const concurrency = Math.max(1, options.concurrency ?? 4);
     const total = entries.length;
     let completed = 0;
@@ -1121,14 +1495,31 @@ var CacheStack = class extends EventEmitter {
     return new CacheNamespace(this, prefix);
   }
   async invalidateByTag(tag) {
-    await this.startup;
+    await this.awaitStartup("invalidateByTag");
     const keys = await this.tagIndex.keysForTag(tag);
     await this.deleteKeys(keys);
     await this.publishInvalidation({ scope: "keys", keys, sourceId: this.instanceId, operation: "invalidate" });
   }
+  async invalidateByTags(tags, mode = "any") {
+    if (tags.length === 0) {
+      return;
+    }
+    await this.awaitStartup("invalidateByTags");
+    const keysByTag = await Promise.all(tags.map((tag) => this.tagIndex.keysForTag(tag)));
+    const keys = mode === "all" ? this.intersectKeys(keysByTag) : [...new Set(keysByTag.flat())];
+    await this.deleteKeys(keys);
+    await this.publishInvalidation({ scope: "keys", keys, sourceId: this.instanceId, operation: "invalidate" });
+  }
   async invalidateByPattern(pattern) {
-    await this.startup;
-    const keys = await this.tagIndex.matchPattern(pattern);
+    await this.awaitStartup("invalidateByPattern");
+    const keys = await this.tagIndex.matchPattern(this.qualifyPattern(pattern));
+    await this.deleteKeys(keys);
+    await this.publishInvalidation({ scope: "keys", keys, sourceId: this.instanceId, operation: "invalidate" });
+  }
+  async invalidateByPrefix(prefix) {
+    await this.awaitStartup("invalidateByPrefix");
+    const qualifiedPrefix = this.qualifyKey(this.validateCacheKey(prefix));
+    const keys = this.tagIndex.keysForPrefix ? await this.tagIndex.keysForPrefix(qualifiedPrefix) : await this.tagIndex.matchPattern(`${qualifiedPrefix}*`);
     await this.deleteKeys(keys);
     await this.publishInvalidation({ scope: "keys", keys, sourceId: this.instanceId, operation: "invalidate" });
   }
@@ -1155,8 +1546,77 @@ var CacheStack = class extends EventEmitter {
   getHitRate() {
     return this.metricsCollector.hitRate();
   }
-  async exportState() {
+  async healthCheck() {
     await this.startup;
+    return Promise.all(
+      this.layers.map(async (layer) => {
+        const startedAt = performance.now();
+        try {
+          const healthy = layer.ping ? await layer.ping() : true;
+          return {
+            layer: layer.name,
+            healthy,
+            latencyMs: performance.now() - startedAt
+          };
+        } catch (error) {
+          return {
+            layer: layer.name,
+            healthy: false,
+            latencyMs: performance.now() - startedAt,
+            error: this.formatError(error)
+          };
+        }
+      })
+    );
+  }
+  bumpGeneration(nextGeneration) {
+    const current = this.currentGeneration ?? 0;
+    this.currentGeneration = nextGeneration ?? current + 1;
+    return this.currentGeneration;
+  }
+  /**
+   * Returns detailed metadata about a single cache key: which layers contain it,
+   * remaining fresh/stale/error TTLs, and associated tags.
+   * Returns `null` if the key does not exist in any layer.
+   */
+  async inspect(key) {
+    const userKey = this.validateCacheKey(key);
+    const normalizedKey = this.qualifyKey(userKey);
+    await this.awaitStartup("inspect");
+    const foundInLayers = [];
+    let freshTtlSeconds = null;
+    let staleTtlSeconds = null;
+    let errorTtlSeconds = null;
+    let isStale = false;
+    for (const layer of this.layers) {
+      if (this.shouldSkipLayer(layer)) {
+        continue;
+      }
+      const stored = await this.readLayerEntry(layer, normalizedKey);
+      if (stored === null) {
+        continue;
+      }
+      const resolved = resolveStoredValue(stored);
+      if (resolved.state === "expired") {
+        continue;
+      }
+      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;
+        isStale = resolved.state === "stale-while-revalidate" || resolved.state === "stale-if-error";
+      }
+    }
+    if (foundInLayers.length === 0) {
+      return null;
+    }
+    const tags = await this.getTagsForKey(normalizedKey);
+    return { key: userKey, foundInLayers, freshTtlSeconds, staleTtlSeconds, errorTtlSeconds, isStale, tags };
+  }
+  async exportState() {
+    await this.awaitStartup("exportState");
     const exported = /* @__PURE__ */ new Map();
     for (const layer of this.layers) {
       if (!layer.keys) {
@@ -1164,15 +1624,16 @@ var CacheStack = class extends EventEmitter {
       }
       const keys = await layer.keys();
       for (const key of keys) {
-        if (exported.has(key)) {
+        const exportedKey = this.stripQualifiedKey(key);
+        if (exported.has(exportedKey)) {
           continue;
         }
         const stored = await this.readLayerEntry(layer, key);
         if (stored === null) {
           continue;
         }
-        exported.set(key, {
-          key,
+        exported.set(exportedKey, {
+          key: exportedKey,
           value: stored,
           ttl: remainingStoredTtlSeconds(stored)
         });
@@ -1181,19 +1642,24 @@ var CacheStack = class extends EventEmitter {
     return [...exported.values()];
   }
   async importState(entries) {
-    await this.startup;
+    await this.awaitStartup("importState");
     await Promise.all(
       entries.map(async (entry) => {
-        await Promise.all(this.layers.map((layer) => layer.set(entry.key, entry.value, entry.ttl)));
-        await this.tagIndex.touch(entry.key);
+        const qualifiedKey = this.qualifyKey(entry.key);
+        await Promise.all(this.layers.map((layer) => layer.set(qualifiedKey, entry.value, entry.ttl)));
+        await this.tagIndex.touch(qualifiedKey);
       })
     );
   }
   async persistToFile(filePath) {
+    this.assertActive("persistToFile");
     const snapshot = await this.exportState();
+    const { promises: fs } = await import("fs");
     await fs.writeFile(filePath, JSON.stringify(snapshot, null, 2), "utf8");
   }
   async restoreFromFile(filePath) {
+    this.assertActive("restoreFromFile");
+    const { promises: fs } = await import("fs");
     const raw = await fs.readFile(filePath, "utf8");
     let parsed;
     try {
@@ -1217,7 +1683,13 @@ var CacheStack = class extends EventEmitter {
       this.disconnectPromise = (async () => {
         await this.startup;
         await this.unsubscribeInvalidation?.();
+        await this.flushWriteBehindQueue();
         await Promise.allSettled([...this.backgroundRefreshes.values()]);
+        if (this.writeBehindTimer) {
+          clearInterval(this.writeBehindTimer);
+          this.writeBehindTimer = void 0;
+        }
+        await Promise.allSettled(this.layers.map((layer) => layer.dispose?.() ?? Promise.resolve()));
       })();
     }
     await this.disconnectPromise;
@@ -1277,7 +1749,10 @@ var CacheStack = class extends EventEmitter {
     const fetchStart = Date.now();
     let fetched;
     try {
-      fetched = await fetcher();
+      fetched = await this.fetchRateLimiter.schedule(
+        options?.fetcherRateLimit ?? this.options.fetcherRateLimit,
+        fetcher
+      );
       this.circuitBreakerManager.recordSuccess(key);
       this.logger.debug?.("fetch", { key, durationMs: Date.now() - fetchStart });
     } catch (error) {
@@ -1291,6 +1766,9 @@ var CacheStack = class extends EventEmitter {
       await this.storeEntry(key, "empty", null, options);
       return null;
     }
+    if (options?.shouldCache && !options.shouldCache(fetched)) {
+      return fetched;
+    }
     await this.storeEntry(key, "value", fetched, options);
     return fetched;
   }
@@ -1308,12 +1786,70 @@ var CacheStack = class extends EventEmitter {
       await this.publishInvalidation({ scope: "key", keys: [key], sourceId: this.instanceId, operation: "write" });
     }
   }
+  async writeBatch(entries) {
+    const now = Date.now();
+    const entriesByLayer = /* @__PURE__ */ new Map();
+    const immediateOperations = [];
+    const deferredOperations = [];
+    for (const entry of entries) {
+      for (const layer of this.layers) {
+        if (this.shouldSkipLayer(layer)) {
+          continue;
+        }
+        const layerEntry = this.buildLayerSetEntry(layer, entry.key, "value", entry.value, entry.options, now);
+        const bucket = entriesByLayer.get(layer) ?? [];
+        bucket.push(layerEntry);
+        entriesByLayer.set(layer, bucket);
+      }
+    }
+    for (const [layer, layerEntries] of entriesByLayer.entries()) {
+      const operation = async () => {
+        try {
+          if (layer.setMany) {
+            await layer.setMany(layerEntries);
+            return;
+          }
+          await Promise.all(layerEntries.map((entry) => layer.set(entry.key, entry.value, entry.ttl)));
+        } catch (error) {
+          await this.handleLayerFailure(layer, "write", error);
+        }
+      };
+      if (this.shouldWriteBehind(layer)) {
+        deferredOperations.push(operation);
+      } else {
+        immediateOperations.push(operation);
+      }
+    }
+    await this.executeLayerOperations(immediateOperations, { key: "batch", action: "mset" });
+    await Promise.all(deferredOperations.map((operation) => this.enqueueWriteBehind(operation)));
+    for (const entry of entries) {
+      if (entry.options?.tags) {
+        await this.tagIndex.track(entry.key, entry.options.tags);
+      } else {
+        await this.tagIndex.touch(entry.key);
+      }
+      this.metricsCollector.increment("sets");
+      this.logger.debug?.("set", { key: entry.key, kind: "value", tags: entry.options?.tags });
+      this.emit("set", { key: entry.key, kind: "value", tags: entry.options?.tags });
+    }
+    if (this.shouldBroadcastL1Invalidation()) {
+      await this.publishInvalidation({
+        scope: "keys",
+        keys: entries.map((entry) => entry.key),
+        sourceId: this.instanceId,
+        operation: "write"
+      });
+    }
+  }
   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;
@@ -1388,33 +1924,28 @@ var CacheStack = class extends EventEmitter {
   }
   async writeAcrossLayers(key, kind, value, options) {
     const now = Date.now();
-    const operations = this.layers.map((layer) => async () => {
-      if (this.shouldSkipLayer(layer)) {
-        return;
-      }
-      const freshTtl = this.resolveFreshTtl(key, layer.name, kind, options, layer.defaultTtl);
-      const staleWhileRevalidate = this.resolveLayerSeconds(
-        layer.name,
-        options?.staleWhileRevalidate,
-        this.options.staleWhileRevalidate
-      );
-      const staleIfError = this.resolveLayerSeconds(layer.name, options?.staleIfError, this.options.staleIfError);
-      const payload = createStoredValueEnvelope({
-        kind,
-        value,
-        freshTtlSeconds: freshTtl,
-        staleWhileRevalidateSeconds: staleWhileRevalidate,
-        staleIfErrorSeconds: staleIfError,
-        now
-      });
-      const ttl = remainingStoredTtlSeconds(payload, now) ?? freshTtl;
-      try {
-        await layer.set(key, payload, ttl);
-      } catch (error) {
-        await this.handleLayerFailure(layer, "write", error);
+    const immediateOperations = [];
+    const deferredOperations = [];
+    for (const layer of this.layers) {
+      const operation = async () => {
+        if (this.shouldSkipLayer(layer)) {
+          return;
+        }
+        const entry = this.buildLayerSetEntry(layer, key, kind, value, options, now);
+        try {
+          await layer.set(entry.key, entry.value, entry.ttl);
+        } catch (error) {
+          await this.handleLayerFailure(layer, "write", error);
+        }
+      };
+      if (this.shouldWriteBehind(layer)) {
+        deferredOperations.push(operation);
+      } else {
+        immediateOperations.push(operation);
       }
-    });
-    await this.executeLayerOperations(operations, { key, action: kind === "empty" ? "negative-set" : "set" });
+    }
+    await this.executeLayerOperations(immediateOperations, { key, action: kind === "empty" ? "negative-set" : "set" });
+    await Promise.all(deferredOperations.map((operation) => this.enqueueWriteBehind(operation)));
   }
   async executeLayerOperations(operations, context) {
     if (this.options.writePolicy !== "best-effort") {
@@ -1438,8 +1969,17 @@ var CacheStack = class extends EventEmitter {
       );
     }
   }
-  resolveFreshTtl(key, layerName, kind, options, fallbackTtl) {
-    return this.ttlResolver.resolveFreshTtl(key, layerName, kind, options, fallbackTtl, this.options.negativeTtl);
+  resolveFreshTtl(key, layerName, kind, options, fallbackTtl, value) {
+    return this.ttlResolver.resolveFreshTtl(
+      key,
+      layerName,
+      kind,
+      options,
+      fallbackTtl,
+      this.options.negativeTtl,
+      void 0,
+      value
+    );
   }
   resolveLayerSeconds(layerName, override, globalDefault, fallback) {
     return this.ttlResolver.resolveLayerSeconds(layerName, override, globalDefault, fallback);
@@ -1515,6 +2055,12 @@ var CacheStack = class extends EventEmitter {
       }
     }
   }
+  async getTagsForKey(key) {
+    if (this.tagIndex.tagsForKey) {
+      return this.tagIndex.tagsForKey(key);
+    }
+    return [];
+  }
   formatError(error) {
     if (error instanceof Error) {
       return error.message;
@@ -1527,6 +2073,105 @@ var CacheStack = class extends EventEmitter {
   shouldBroadcastL1Invalidation() {
     return this.options.broadcastL1Invalidation ?? this.options.publishSetInvalidation ?? true;
   }
+  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?.();
+  }
+  shouldWriteBehind(layer) {
+    return this.options.writeStrategy === "write-behind" && !layer.isLocal;
+  }
+  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();
+    }
+  }
+  async flushWriteBehindQueue() {
+    if (this.writeBehindFlushPromise || this.writeBehindQueue.length === 0) {
+      await this.writeBehindFlushPromise;
+      return;
+    }
+    const batchSize = this.options.writeBehind?.batchSize ?? 100;
+    const batch = this.writeBehindQueue.splice(0, batchSize);
+    this.writeBehindFlushPromise = (async () => {
+      await Promise.allSettled(batch.map((operation) => operation()));
+    })();
+    await this.writeBehindFlushPromise;
+    this.writeBehindFlushPromise = void 0;
+    if (this.writeBehindQueue.length > 0) {
+      await this.flushWriteBehindQueue();
+    }
+  }
+  buildLayerSetEntry(layer, key, kind, value, options, now) {
+    const freshTtl = this.resolveFreshTtl(key, layer.name, kind, options, layer.defaultTtl, value);
+    const staleWhileRevalidate = this.resolveLayerSeconds(
+      layer.name,
+      options?.staleWhileRevalidate,
+      this.options.staleWhileRevalidate
+    );
+    const staleIfError = this.resolveLayerSeconds(layer.name, options?.staleIfError, this.options.staleIfError);
+    const payload = createStoredValueEnvelope({
+      kind,
+      value,
+      freshTtlSeconds: freshTtl,
+      staleWhileRevalidateSeconds: staleWhileRevalidate,
+      staleIfErrorSeconds: staleIfError,
+      now
+    });
+    const ttl = remainingStoredTtlSeconds(payload, now) ?? freshTtl;
+    return {
+      key,
+      value: payload,
+      ttl
+    };
+  }
+  intersectKeys(groups) {
+    if (groups.length === 0) {
+      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;
+  }
+  qualifyPattern(pattern) {
+    const prefix = this.generationPrefix();
+    return prefix ? `${prefix}${pattern}` : pattern;
+  }
+  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}:`;
+  }
   async deleteKeysFromLayers(layers, keys) {
     await Promise.all(
       layers.map(async (layer) => {
@@ -1570,6 +2215,9 @@ var CacheStack = class extends EventEmitter {
     this.validatePositiveNumber("singleFlightPollMs", this.options.singleFlightPollMs);
     this.validateAdaptiveTtlOptions(this.options.adaptiveTtl);
     this.validateCircuitBreakerOptions(this.options.circuitBreaker);
+    if (this.options.generation !== void 0) {
+      this.validateNonNegativeNumber("generation", this.options.generation);
+    }
   }
   validateWriteOptions(options) {
     if (!options) {
@@ -1581,6 +2229,7 @@ var CacheStack = class extends EventEmitter {
     this.validateLayerNumberOption("options.staleIfError", options.staleIfError);
     this.validateLayerNumberOption("options.ttlJitter", options.ttlJitter);
     this.validateLayerNumberOption("options.refreshAhead", options.refreshAhead);
+    this.validateTtlPolicy("options.ttlPolicy", options.ttlPolicy);
     this.validateAdaptiveTtlOptions(options.adaptiveTtl);
     this.validateCircuitBreakerOptions(options.circuitBreaker);
   }
@@ -1624,6 +2273,26 @@ var CacheStack = class extends EventEmitter {
     }
     return key;
   }
+  validateTtlPolicy(name, policy) {
+    if (!policy || typeof policy === "function" || policy === "until-midnight" || policy === "next-hour") {
+      return;
+    }
+    if ("alignTo" in policy) {
+      this.validatePositiveNumber(`${name}.alignTo`, policy.alignTo);
+      return;
+    }
+    throw new Error(`${name} is invalid.`);
+  }
+  assertActive(operation) {
+    if (this.isDisconnecting) {
+      throw new Error(`CacheStack is disconnecting; cannot perform ${operation}.`);
+    }
+  }
+  async awaitStartup(operation) {
+    this.assertActive(operation);
+    await this.startup;
+    this.assertActive(operation);
+  }
   serializeOptions(options) {
     return JSON.stringify(this.normalizeForSerialization(options) ?? null);
   }
@@ -1729,6 +2398,9 @@ var CacheStack = class extends EventEmitter {
     return value;
   }
 };
+function createInstanceId() {
+  return globalThis.crypto?.randomUUID?.() ?? `layercache-${Date.now()}-${Math.random().toString(36).slice(2)}`;
+}
 
 // src/module.ts
 var InjectCacheStack = () => Inject(CACHE_STACK);
@@ -1745,6 +2417,22 @@ var CacheStackModule = class {
       exports: [provider]
     };
   }
+  static forRootAsync(options) {
+    const provider = {
+      provide: CACHE_STACK,
+      inject: options.inject ?? [],
+      useFactory: async (...args) => {
+        const resolved = await options.useFactory(...args);
+        return new CacheStack(resolved.layers, resolved.bridgeOptions);
+      }
+    };
+    return {
+      global: true,
+      module: CacheStackModule,
+      providers: [provider],
+      exports: [provider]
+    };
+  }
 };
 CacheStackModule = __decorateClass([
   Global(),