layercache 1.1.0 → 1.2.0

package/packages/nestjs/dist/index.js

@@ -51,7 +51,7 @@ import { EventEmitter } from "events";
 import { promises as fs } from "fs";
 
 // ../../src/CacheNamespace.ts
-var CacheNamespace = class {
+var CacheNamespace = class _CacheNamespace {
   constructor(cache, prefix) {
     this.cache = cache;
     this.prefix = prefix;
@@ -64,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));
   }
@@ -104,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);
   }
@@ -122,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}`;
   }
@@ -223,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) {
     ;
@@ -232,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();
   }
@@ -266,6 +311,7 @@ var MetricsCollector = class {
       degradedOperations: 0,
       hitsByLayer: {},
       missesByLayer: {},
+      latencyByLayer: {},
       resetAt: Date.now()
     };
   }
@@ -503,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;
     }
@@ -546,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));
   }
@@ -554,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;
+    }
+  }
 };
 
 // ../../node_modules/async-mutex/index.mjs
@@ -756,6 +826,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;
@@ -882,6 +962,18 @@ 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.
    */
@@ -1155,6 +1247,46 @@ var CacheStack = class extends 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();
@@ -1291,6 +1423,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;
   }
@@ -1313,7 +1448,10 @@ var CacheStack = class extends 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;
@@ -1515,6 +1653,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;
@@ -1745,6 +1889,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(),