@adaptic/utils 0.0.1008 → 0.0.1010

package/dist/index.mjs

@@ -63616,6 +63616,15 @@ class StampedeProtectedCache {
             allowStale: true,
             updateAgeOnGet: false,
             updateAgeOnHas: false,
+            // LRU discard visibility for the onEvent observability hook. lru-cache
+            // invokes dispose for every removal; only capacity discards ("evict")
+            // are reported as evictions so deliberate delete()/invalidate() calls
+            // do not inflate the eviction signal.
+            dispose: (_value, key, reason) => {
+                if (reason === "evict") {
+                    this.emitEvent("eviction", key);
+                }
+            },
         });
         this.options.logger.info("StampedeProtectedCache initialized", {
             maxSize: this.options.maxSize,
@@ -63683,6 +63692,7 @@ class StampedeProtectedCache {
             if (now < jitteredExpiresAt) {
                 // Fresh hit
                 this.stats.hits++;
+                this.emitEvent("hit", key);
                 this.options.logger.debug("Cache hit (fresh)", {
                     key,
                     age: now - cached.createdAt,
@@ -63694,6 +63704,7 @@ class StampedeProtectedCache {
             if (now < staleExpiresAt && !cached.isRefreshing) {
                 // Serve stale and trigger background refresh
                 this.stats.staleHits++;
+                this.emitEvent("stale_hit", key);
                 this.options.logger.debug("Cache hit (stale-while-revalidate)", {
                     key,
                     age: now - cached.createdAt,
@@ -63707,6 +63718,7 @@ class StampedeProtectedCache {
         }
         // Cache miss or expired - need to load
         this.stats.misses++;
+        this.emitEvent("miss", key);
         this.options.logger.debug("Cache miss", { key, hadCached: !!cached });
         return this.loadWithCoalescing(key, loader, effectiveTtl);
     }
@@ -63767,6 +63779,29 @@ class StampedeProtectedCache {
     has(key) {
         return this.cache.has(key);
     }
+    /**
+     * Synchronous peek at a cached value without triggering a loader.
+     *
+     * @description Returns the cached value when present and FRESH (inside its
+     * per-entry TTL), `undefined` otherwise — never coalesces onto or starts a
+     * load, never serves stale-while-revalidate data, and counts a hit only
+     * when a fresh value is returned (mirroring the read-path hit semantics so
+     * hitRatio stays truthful). Added 2026-08-08 for the engine cache
+     * consolidation: its fork exposed peek() and consumers rely on the
+     * no-load contract on hot paths.
+     *
+     * @param key - Cache key to inspect.
+     * @returns The fresh cached value, or `undefined` when absent or expired.
+     */
+    peek(key) {
+        const entry = this.cache.get(key);
+        if (entry && Date.now() < entry.expiresAt) {
+            this.stats.hits++;
+            this.emitEvent("hit", key);
+            return entry.value;
+        }
+        return undefined;
+    }
     /**
      * Delete a specific key from the cache
      *
@@ -63784,6 +63819,25 @@ class StampedeProtectedCache {
      * cache.delete(`positions:${accountId}`);
      * ```
      */
+    /**
+     * Fire the {@link StampedeProtectedCacheOptions.onEvent} hook, never
+     * letting an observer failure propagate into the cache path.
+     */
+    emitEvent(event, key) {
+        const hook = this.options.onEvent;
+        if (!hook)
+            return;
+        try {
+            hook(event, key);
+        }
+        catch (err) {
+            this.options.logger.warn("cache onEvent observer threw — ignored", {
+                event,
+                key,
+                error: err instanceof Error ? err.message : String(err),
+            });
+        }
+    }
     delete(key) {
         const deleted = this.cache.delete(key);
         if (deleted) {
@@ -63916,6 +63970,7 @@ class StampedeProtectedCache {
         const existingPromise = this.pendingRefreshes.get(key);
         if (existingPromise) {
             this.stats.coalescedRequests++;
+            this.emitEvent("coalesced", key);
             this.options.logger.debug("Request coalesced", { key });
             return existingPromise;
         }
@@ -63949,6 +64004,7 @@ class StampedeProtectedCache {
         const timeoutPromise = new Promise((_, reject) => {
             timeoutHandle = setTimeout(() => {
                 this.stats.loadTimeouts++;
+                this.emitEvent("load_timeout", key);
                 // Mark the invocation abandoned BEFORE evicting the pin: a retry that
                 // starts now must never be overwritten by this loader's late result.
                 invocation.abandoned = true;
@@ -64005,6 +64061,7 @@ class StampedeProtectedCache {
         }
         catch (error) {
             this.stats.refreshErrors++;
+            this.emitEvent("refresh_error", key);
             const loadTime = Date.now() - startTime;
             this.options.logger.error("Failed to load data", {
                 key,
@@ -64037,6 +64094,7 @@ class StampedeProtectedCache {
         this.loadWithCoalescing(key, loader, ttl)
             .then(() => {
             this.stats.backgroundRefreshes++;
+            this.emitEvent("background_refresh", key);
             this.options.logger.debug("Background refresh completed", { key });
         })
             .catch((error) => {