layercache 1.1.0 → 1.2.0

package/dist/index.cjs

@@ -20,6 +20,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  CacheMissError: () => CacheMissError,
   CacheNamespace: () => CacheNamespace,
   CacheStack: () => CacheStack,
   DiskLayer: () => DiskLayer,
@@ -37,6 +38,7 @@ __export(index_exports, {
   cacheGraphqlResolver: () => cacheGraphqlResolver,
   createCacheStatsHandler: () => createCacheStatsHandler,
   createCachedMethodDecorator: () => createCachedMethodDecorator,
+  createExpressCacheMiddleware: () => createExpressCacheMiddleware,
   createFastifyLayercachePlugin: () => createFastifyLayercachePlugin,
   createPrometheusMetricsExporter: () => createPrometheusMetricsExporter,
   createTrpcCacheMiddleware: () => createTrpcCacheMiddleware
@@ -49,7 +51,7 @@ var import_node_events = require("events");
 var import_node_fs = require("fs");
 
 // src/CacheNamespace.ts
-var CacheNamespace = class {
+var CacheNamespace = class _CacheNamespace {
   constructor(cache, prefix) {
     this.cache = cache;
     this.prefix = prefix;
@@ -62,6 +64,12 @@ var CacheNamespace = class {
   async getOrSet(key, fetcher, options) {
     return this.cache.getOrSet(this.qualify(key), fetcher, options);
   }
+  /**
+   * Like `get()`, but throws `CacheMissError` instead of returning `null`.
+   */
+  async getOrThrow(key, fetcher, options) {
+    return this.cache.getOrThrow(this.qualify(key), fetcher, options);
+  }
   async has(key) {
     return this.cache.has(this.qualify(key));
   }
@@ -102,6 +110,12 @@ var CacheNamespace = class {
   async invalidateByPattern(pattern) {
     await this.cache.invalidateByPattern(this.qualify(pattern));
   }
+  /**
+   * 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);
   }
@@ -120,6 +134,18 @@ var CacheNamespace = class {
   getHitRate() {
     return this.cache.getHitRate();
   }
+  /**
+   * 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}`;
   }
@@ -221,7 +247,12 @@ var CircuitBreakerManager = class {
 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) {
     ;
@@ -230,6 +261,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();
   }
@@ -264,6 +311,7 @@ var MetricsCollector = class {
       degradedOperations: 0,
       hitsByLayer: {},
       missesByLayer: {},
+      latencyByLayer: {},
       resetAt: Date.now()
     };
   }
@@ -501,11 +549,17 @@ var TagIndex = class {
   tagToKeys = /* @__PURE__ */ new Map();
   keyToTags = /* @__PURE__ */ new Map();
   knownKeys = /* @__PURE__ */ new Set();
+  maxKnownKeys;
+  constructor(options = {}) {
+    this.maxKnownKeys = options.maxKnownKeys;
+  }
   async touch(key) {
     this.knownKeys.add(key);
+    this.pruneKnownKeysIfNeeded();
   }
   async track(key, tags) {
     this.knownKeys.add(key);
+    this.pruneKnownKeysIfNeeded();
     if (tags.length === 0) {
       return;
     }
@@ -544,6 +598,9 @@ var TagIndex = class {
   async keysForTag(tag) {
     return [...this.tagToKeys.get(tag) ?? /* @__PURE__ */ new Set()];
   }
+  async tagsForKey(key) {
+    return [...this.keyToTags.get(key) ?? /* @__PURE__ */ new Set()];
+  }
   async matchPattern(pattern) {
     return [...this.knownKeys].filter((key) => PatternMatcher.matches(pattern, key));
   }
@@ -552,6 +609,21 @@ var TagIndex = class {
     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.knownKeys.delete(key);
+      this.keyToTags.delete(key);
+      removed += 1;
+    }
+  }
 };
 
 // src/stampede/StampedeGuard.ts
@@ -580,6 +652,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;
@@ -706,6 +788,18 @@ var CacheStack = class extends import_node_events.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.
    */
@@ -979,6 +1073,46 @@ var CacheStack = class extends import_node_events.EventEmitter {
   getHitRate() {
     return this.metricsCollector.hitRate();
   }
+  /**
+   * 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 normalizedKey = this.validateCacheKey(key);
+    await this.startup;
+    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: normalizedKey, foundInLayers, freshTtlSeconds, staleTtlSeconds, errorTtlSeconds, isStale, tags };
+  }
   async exportState() {
     await this.startup;
     const exported = /* @__PURE__ */ new Map();
@@ -1115,6 +1249,9 @@ var CacheStack = class extends import_node_events.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;
   }
@@ -1137,7 +1274,10 @@ var CacheStack = class extends import_node_events.EventEmitter {
     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;
@@ -1339,6 +1479,12 @@ var CacheStack = class extends import_node_events.EventEmitter {
       }
     }
   }
+  async getTagsForKey(key) {
+    if (this.tagIndex.tagsForKey) {
+      return this.tagIndex.tagsForKey(key);
+    }
+    return [];
+  }
   formatError(error) {
     if (error instanceof Error) {
       return error.message;
@@ -1559,35 +1705,36 @@ var RedisInvalidationBus = class {
   channel;
   publisher;
   subscriber;
-  activeListener;
+  handlers = /* @__PURE__ */ new Set();
+  sharedListener;
   constructor(options) {
     this.publisher = options.publisher;
     this.subscriber = options.subscriber ?? options.publisher.duplicate();
     this.channel = options.channel ?? "layercache:invalidation";
   }
   async subscribe(handler) {
-    if (this.activeListener) {
-      throw new Error("RedisInvalidationBus already has an active subscription.");
+    if (this.handlers.size === 0) {
+      const listener = (_channel, payload) => {
+        void this.dispatchToHandlers(payload);
+      };
+      this.sharedListener = listener;
+      this.subscriber.on("message", listener);
+      await this.subscriber.subscribe(this.channel);
     }
-    const listener = (_channel, payload) => {
-      void this.handleMessage(payload, handler);
-    };
-    this.activeListener = listener;
-    this.subscriber.on("message", listener);
-    await this.subscriber.subscribe(this.channel);
+    this.handlers.add(handler);
     return async () => {
-      if (this.activeListener !== listener) {
-        return;
+      this.handlers.delete(handler);
+      if (this.handlers.size === 0 && this.sharedListener) {
+        this.subscriber.off("message", this.sharedListener);
+        this.sharedListener = void 0;
+        await this.subscriber.unsubscribe(this.channel);
       }
-      this.activeListener = void 0;
-      this.subscriber.off("message", listener);
-      await this.subscriber.unsubscribe(this.channel);
     };
   }
   async publish(message) {
     await this.publisher.publish(this.channel, JSON.stringify(message));
   }
-  async handleMessage(payload, handler) {
+  async dispatchToHandlers(payload) {
     let message;
     try {
       const parsed = JSON.parse(payload);
@@ -1599,11 +1746,15 @@ var RedisInvalidationBus = class {
       this.reportError("invalid invalidation payload", error);
       return;
     }
-    try {
-      await handler(message);
-    } catch (error) {
-      this.reportError("invalidation handler failed", error);
-    }
+    await Promise.all(
+      [...this.handlers].map(async (handler) => {
+        try {
+          await handler(message);
+        } catch (error) {
+          this.reportError("invalidation handler failed", error);
+        }
+      })
+    );
   }
   isInvalidationMessage(value) {
     if (!value || typeof value !== "object") {
@@ -1664,6 +1815,9 @@ var RedisTagIndex = class {
   async keysForTag(tag) {
     return this.client.smembers(this.tagKeysKey(tag));
   }
+  async tagsForKey(key) {
+    return this.client.smembers(this.keyTagsKey(key));
+  }
   async matchPattern(pattern) {
     const matches = [];
     let cursor = "0";
@@ -1754,6 +1908,39 @@ function createFastifyLayercachePlugin(cache, options = {}) {
   };
 }
 
+// src/integrations/express.ts
+function createExpressCacheMiddleware(cache, options = {}) {
+  const allowedMethods = new Set((options.methods ?? ["GET"]).map((m) => m.toUpperCase()));
+  return async (req, res, next) => {
+    const method = (req.method ?? "GET").toUpperCase();
+    if (!allowedMethods.has(method)) {
+      next();
+      return;
+    }
+    const key = options.keyResolver ? options.keyResolver(req) : `${method}:${req.originalUrl ?? req.url ?? "/"}`;
+    const cached = await cache.get(key, void 0, options);
+    if (cached !== null) {
+      res.setHeader?.("content-type", "application/json; charset=utf-8");
+      res.setHeader?.("x-cache", "HIT");
+      if (res.json) {
+        res.json(cached);
+      } else {
+        res.end?.(JSON.stringify(cached));
+      }
+      return;
+    }
+    const originalJson = res.json?.bind(res);
+    if (originalJson) {
+      res.json = (body) => {
+        res.setHeader?.("x-cache", "MISS");
+        void cache.set(key, body, options);
+        return originalJson(body);
+      };
+    }
+    next();
+  };
+}
+
 // src/integrations/graphql.ts
 function cacheGraphqlResolver(cache, prefix, resolver, options = {}) {
   const wrapped = cache.wrap(prefix, resolver, {
@@ -1817,10 +2004,10 @@ var MemoryLayer = class {
     }
     if (this.evictionPolicy === "lru") {
       this.entries.delete(key);
-      entry.frequency += 1;
+      entry.accessCount += 1;
       this.entries.set(key, entry);
-    } else {
-      entry.frequency += 1;
+    } else if (this.evictionPolicy === "lfu") {
+      entry.accessCount += 1;
     }
     return entry.value;
   }
@@ -1836,7 +2023,7 @@ var MemoryLayer = class {
     this.entries.set(key, {
       value,
       expiresAt: ttl && ttl > 0 ? Date.now() + ttl * 1e3 : null,
-      frequency: 0,
+      accessCount: 0,
       insertedAt: Date.now()
     });
     while (this.entries.size > this.maxSize) {
@@ -1903,7 +2090,7 @@ var MemoryLayer = class {
       this.entries.set(entry.key, {
         value: entry.value,
         expiresAt: entry.expiresAt,
-        frequency: 0,
+        accessCount: 0,
         insertedAt: Date.now()
       });
     }
@@ -1920,11 +2107,11 @@ var MemoryLayer = class {
       return;
     }
     let victimKey;
-    let minFreq = Number.POSITIVE_INFINITY;
+    let minCount = Number.POSITIVE_INFINITY;
     let minInsertedAt = Number.POSITIVE_INFINITY;
     for (const [key, entry] of this.entries.entries()) {
-      if (entry.frequency < minFreq || entry.frequency === minFreq && entry.insertedAt < minInsertedAt) {
-        minFreq = entry.frequency;
+      if (entry.accessCount < minCount || entry.accessCount === minCount && entry.insertedAt < minInsertedAt) {
+        minCount = entry.accessCount;
         minInsertedAt = entry.insertedAt;
         victimKey = key;
       }
@@ -1946,6 +2133,7 @@ var MemoryLayer = class {
 };
 
 // src/layers/RedisLayer.ts
+var import_node_util = require("util");
 var import_node_zlib = require("zlib");
 
 // src/serialization/JsonSerializer.ts
@@ -1961,6 +2149,10 @@ var JsonSerializer = class {
 
 // src/layers/RedisLayer.ts
 var BATCH_DELETE_SIZE = 500;
+var gzipAsync = (0, import_node_util.promisify)(import_node_zlib.gzip);
+var gunzipAsync = (0, import_node_util.promisify)(import_node_zlib.gunzip);
+var brotliCompressAsync = (0, import_node_util.promisify)(import_node_zlib.brotliCompress);
+var brotliDecompressAsync = (0, import_node_util.promisify)(import_node_zlib.brotliDecompress);
 var RedisLayer = class {
   name;
   defaultTtl;
@@ -2017,7 +2209,8 @@ var RedisLayer = class {
     );
   }
   async set(key, value, ttl = this.defaultTtl) {
-    const payload = this.encodePayload(this.serializer.serialize(value));
+    const serialized = this.serializer.serialize(value);
+    const payload = await this.encodePayload(serialized);
     const normalizedKey = this.withPrefix(key);
     if (ttl && ttl > 0) {
       await this.client.set(normalizedKey, payload, "EX", ttl);
@@ -2096,7 +2289,7 @@ var RedisLayer = class {
   }
   async deserializeOrDelete(key, payload) {
     try {
-      return this.serializer.deserialize(this.decodePayload(payload));
+      return this.serializer.deserialize(await this.decodePayload(payload));
     } catch {
       await this.client.del(this.withPrefix(key)).catch(() => void 0);
       return null;
@@ -2105,7 +2298,11 @@ var RedisLayer = class {
   isSerializablePayload(payload) {
     return typeof payload === "string" || Buffer.isBuffer(payload);
   }
-  encodePayload(payload) {
+  /**
+   * Compresses the payload asynchronously if compression is enabled and the
+   * payload exceeds the threshold. This avoids blocking the event loop.
+   */
+  async encodePayload(payload) {
     if (!this.compression) {
       return payload;
     }
@@ -2114,18 +2311,21 @@ var RedisLayer = class {
       return payload;
     }
     const header = Buffer.from(`LCZ1:${this.compression}:`);
-    const compressed = this.compression === "gzip" ? (0, import_node_zlib.gzipSync)(source) : (0, import_node_zlib.brotliCompressSync)(source);
+    const compressed = this.compression === "gzip" ? await gzipAsync(source) : await brotliCompressAsync(source);
     return Buffer.concat([header, compressed]);
   }
-  decodePayload(payload) {
+  /**
+   * Decompresses the payload asynchronously if a compression header is present.
+   */
+  async decodePayload(payload) {
     if (!Buffer.isBuffer(payload)) {
       return payload;
     }
     if (payload.subarray(0, 10).toString() === "LCZ1:gzip:") {
-      return (0, import_node_zlib.gunzipSync)(payload.subarray(10));
+      return gunzipAsync(payload.subarray(10));
     }
     if (payload.subarray(0, 12).toString() === "LCZ1:brotli:") {
-      return (0, import_node_zlib.brotliDecompressSync)(payload.subarray(12));
+      return brotliDecompressAsync(payload.subarray(12));
     }
     return payload;
   }
@@ -2141,11 +2341,13 @@ var DiskLayer = class {
   isLocal = true;
   directory;
   serializer;
+  maxFiles;
   constructor(options) {
     this.directory = options.directory;
     this.defaultTtl = options.ttl;
     this.name = options.name ?? "disk";
     this.serializer = options.serializer ?? new JsonSerializer();
+    this.maxFiles = options.maxFiles;
   }
   async get(key) {
     return unwrapStoredValue(await this.getEntry(key));
@@ -2174,11 +2376,15 @@ var DiskLayer = class {
   async set(key, value, ttl = this.defaultTtl) {
     await import_node_fs2.promises.mkdir(this.directory, { recursive: true });
     const entry = {
+      key,
       value,
       expiresAt: ttl && ttl > 0 ? Date.now() + ttl * 1e3 : null
     };
     const payload = this.serializer.serialize(entry);
     await import_node_fs2.promises.writeFile(this.keyToPath(key), payload);
+    if (this.maxFiles !== void 0) {
+      await this.enforceMaxFiles();
+    }
   }
   async has(key) {
     const value = await this.getEntry(key);
@@ -2224,6 +2430,10 @@ var DiskLayer = class {
       entries.filter((name) => name.endsWith(".lc")).map((name) => this.safeDelete((0, import_node_path.join)(this.directory, name)))
     );
   }
+  /**
+   * Returns the original cache key strings stored on disk.
+   * Expired entries are skipped and cleaned up during the scan.
+   */
   async keys() {
     let entries;
     try {
@@ -2231,7 +2441,32 @@ var DiskLayer = class {
     } catch {
       return [];
     }
-    return entries.filter((name) => name.endsWith(".lc")).map((name) => name.slice(0, -3));
+    const lcFiles = entries.filter((name) => name.endsWith(".lc"));
+    const keys = [];
+    await Promise.all(
+      lcFiles.map(async (name) => {
+        const filePath = (0, import_node_path.join)(this.directory, name);
+        let raw;
+        try {
+          raw = await import_node_fs2.promises.readFile(filePath);
+        } catch {
+          return;
+        }
+        let entry;
+        try {
+          entry = this.serializer.deserialize(raw);
+        } catch {
+          await this.safeDelete(filePath);
+          return;
+        }
+        if (entry.expiresAt !== null && entry.expiresAt <= Date.now()) {
+          await this.safeDelete(filePath);
+          return;
+        }
+        keys.push(entry.key);
+      })
+    );
+    return keys;
   }
   async size() {
     const keys = await this.keys();
@@ -2247,6 +2482,38 @@ var DiskLayer = class {
     } catch {
     }
   }
+  /**
+   * Removes the oldest files (by mtime) when the directory exceeds maxFiles.
+   */
+  async enforceMaxFiles() {
+    if (this.maxFiles === void 0) {
+      return;
+    }
+    let entries;
+    try {
+      entries = await import_node_fs2.promises.readdir(this.directory);
+    } catch {
+      return;
+    }
+    const lcFiles = entries.filter((name) => name.endsWith(".lc"));
+    if (lcFiles.length <= this.maxFiles) {
+      return;
+    }
+    const withStats = await Promise.all(
+      lcFiles.map(async (name) => {
+        const filePath = (0, import_node_path.join)(this.directory, name);
+        try {
+          const stat = await import_node_fs2.promises.stat(filePath);
+          return { filePath, mtimeMs: stat.mtimeMs };
+        } catch {
+          return { filePath, mtimeMs: 0 };
+        }
+      })
+    );
+    withStats.sort((a, b) => a.mtimeMs - b.mtimeMs);
+    const toEvict = withStats.slice(0, lcFiles.length - this.maxFiles);
+    await Promise.all(toEvict.map(({ filePath }) => this.safeDelete(filePath)));
+  }
 };
 
 // src/layers/MemcachedLayer.ts
@@ -2256,29 +2523,41 @@ var MemcachedLayer = class {
   isLocal = false;
   client;
   keyPrefix;
+  serializer;
   constructor(options) {
     this.client = options.client;
     this.defaultTtl = options.ttl;
     this.name = options.name ?? "memcached";
     this.keyPrefix = options.keyPrefix ?? "";
+    this.serializer = options.serializer ?? new JsonSerializer();
   }
   async get(key) {
+    return unwrapStoredValue(await this.getEntry(key));
+  }
+  async getEntry(key) {
     const result = await this.client.get(this.withPrefix(key));
     if (!result || result.value === null) {
       return null;
     }
     try {
-      return JSON.parse(result.value.toString("utf8"));
+      return this.serializer.deserialize(result.value);
     } catch {
       return null;
     }
   }
+  async getMany(keys) {
+    return Promise.all(keys.map((key) => this.getEntry(key)));
+  }
   async set(key, value, ttl = this.defaultTtl) {
-    const payload = JSON.stringify(value);
+    const payload = this.serializer.serialize(value);
     await this.client.set(this.withPrefix(key), payload, {
       expires: ttl && ttl > 0 ? ttl : void 0
     });
   }
+  async has(key) {
+    const result = await this.client.get(this.withPrefix(key));
+    return result !== null && result.value !== null;
+  }
   async delete(key) {
     await this.client.delete(this.withPrefix(key));
   }
@@ -2372,6 +2651,12 @@ function createPrometheusMetricsExporter(stacks) {
     lines.push("# TYPE layercache_hits_by_layer_total counter");
     lines.push("# HELP layercache_misses_by_layer_total Misses broken down by layer");
     lines.push("# TYPE layercache_misses_by_layer_total counter");
+    lines.push("# HELP layercache_layer_latency_avg_ms Average read latency per layer in milliseconds");
+    lines.push("# TYPE layercache_layer_latency_avg_ms gauge");
+    lines.push("# HELP layercache_layer_latency_max_ms Maximum read latency per layer in milliseconds");
+    lines.push("# TYPE layercache_layer_latency_max_ms gauge");
+    lines.push("# HELP layercache_layer_latency_count Number of read latency samples per layer");
+    lines.push("# TYPE layercache_layer_latency_count counter");
     for (const { stack, name } of entries) {
       const m = stack.getMetrics();
       const hr = stack.getHitRate();
@@ -2395,6 +2680,12 @@ function createPrometheusMetricsExporter(stacks) {
       for (const [layerName, count] of Object.entries(m.missesByLayer)) {
         lines.push(`layercache_misses_by_layer_total{${label},layer="${sanitizeLabel(layerName)}"} ${count}`);
       }
+      for (const [layerName, latency] of Object.entries(m.latencyByLayer)) {
+        const layerLabel = `${label},layer="${sanitizeLabel(layerName)}"`;
+        lines.push(`layercache_layer_latency_avg_ms{${layerLabel}} ${latency.avgMs.toFixed(4)}`);
+        lines.push(`layercache_layer_latency_max_ms{${layerLabel}} ${latency.maxMs.toFixed(4)}`);
+        lines.push(`layercache_layer_latency_count{${layerLabel}} ${latency.count}`);
+      }
     }
     lines.push("");
     return lines.join("\n");
@@ -2405,6 +2696,7 @@ function sanitizeLabel(value) {
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  CacheMissError,
   CacheNamespace,
   CacheStack,
   DiskLayer,
@@ -2422,6 +2714,7 @@ function sanitizeLabel(value) {
   cacheGraphqlResolver,
   createCacheStatsHandler,
   createCachedMethodDecorator,
+  createExpressCacheMiddleware,
   createFastifyLayercachePlugin,
   createPrometheusMetricsExporter,
   createTrpcCacheMiddleware