@ls-stack/utils 3.46.0 → 3.47.0

package/dist/cache.cjs

@@ -139,7 +139,26 @@ function createCache({
       return new WithExpiration(value, expiration);
     }
   };
+  function refreshEntry(key, now) {
+    const entry = cache.get(key);
+    if (entry && !isExpired(entry, now)) {
+      cache.delete(key);
+      cache.set(key, entry);
+    }
+  }
   return {
+    /**
+     * Gets a value from the cache or computes and stores it if not present.
+     * This is the primary method for synchronous caching operations.
+     *
+     * @param cacheKey - Unique key to identify the cached value
+     * @param val - Function that computes the value if not cached. Receives
+     *   utility functions for advanced features.
+     * @param options - Optional configuration for this specific get operation
+     * @returns The cached or newly computed value
+     * @throws Error if the cached value is a promise (use getOrInsertAsync
+     *   instead)
+     */
     getOrInsert(cacheKey, val, options) {
       const now = Date.now();
       const entry = cache.get(cacheKey);
@@ -162,8 +181,20 @@ function createCache({
           "Cache value is a promise, use getOrInsertAsync instead"
         );
       }
+      refreshEntry(cacheKey, now);
       return entry.value;
     },
+    /**
+     * Gets a value from the cache or computes and stores it asynchronously.
+     * Provides promise deduplication - concurrent calls with the same key will
+     * share the same promise.
+     *
+     * @param cacheKey - Unique key to identify the cached value
+     * @param val - Async function that computes the value if not cached.
+     *   Receives utility functions for advanced features.
+     * @param options - Optional configuration for this specific get operation
+     * @returns Promise that resolves to the cached or newly computed value
+     */
     async getOrInsertAsync(cacheKey, val, options) {
       const entry = cache.get(cacheKey);
       if (entry && isPromise2(entry.value)) {
@@ -171,6 +202,7 @@ function createCache({
       }
       const now = Date.now();
       if (entry && !isExpired(entry, now)) {
+        refreshEntry(cacheKey, now);
         return entry.value;
       }
       const promise = val(utils).then((result) => {
@@ -204,31 +236,67 @@ function createCache({
       cleanExpiredItems();
       return promise;
     },
+    /** Removes all items from the cache. */
     clear() {
       cache.clear();
     },
+    /**
+     * Gets a value from the cache without computing it if missing. Returns
+     * undefined if the key doesn't exist or has expired.
+     *
+     * @param cacheKey - Key to look up in the cache
+     * @returns The cached value or undefined if not found/expired
+     * @throws Error if the cached value is a promise (use getAsync instead)
+     */
     get(cacheKey) {
       const entry = cache.get(cacheKey);
-      if (!entry || isExpired(entry, Date.now())) {
+      const now = Date.now();
+      if (!entry || isExpired(entry, now)) {
         return void 0;
       }
       if (isPromise2(entry.value)) {
         throw new Error("Cache value is a promise, use getAsync instead");
       }
+      refreshEntry(cacheKey, now);
       return entry.value;
     },
+    /**
+     * Manually sets a value in the cache.
+     *
+     * @param cacheKey - Key to store the value under
+     * @param value - Value to store, or WithExpiration wrapper for custom
+     *   expiration
+     */
     set(cacheKey, value) {
       cache.set(cacheKey, unwrapValue(value, Date.now()));
       trimToSize();
       cleanExpiredItems();
     },
+    /**
+     * Gets a value from the cache without computing it if missing. Works with
+     * both sync and async cached values.
+     *
+     * @param cacheKey - Key to look up in the cache
+     * @returns Promise that resolves to the cached value or undefined if not
+     *   found/expired
+     */
     async getAsync(cacheKey) {
       const entry = cache.get(cacheKey);
-      if (!entry || isExpired(entry, Date.now())) {
+      const now = Date.now();
+      if (!entry || isExpired(entry, now)) {
         return void 0;
       }
+      refreshEntry(cacheKey, now);
       return entry.value;
     },
+    /**
+     * Manually sets an async value in the cache. The promise will be stored
+     * immediately and shared with concurrent requests.
+     *
+     * @param cacheKey - Key to store the value under
+     * @param value - Async function that returns the value to cache
+     * @returns Promise that resolves to the computed value
+     */
     async setAsync(cacheKey, value) {
       const promise = value(utils).then((result) => {
         if (result instanceof SkipCaching) {
@@ -254,6 +322,10 @@ function createCache({
       cleanExpiredItems();
       return promise;
     },
+    /**
+     * Manually triggers cleanup of expired items. Normally this happens
+     * automatically during cache operations.
+     */
     cleanExpiredItems,
     /** @internal */
     " cache": { map: cache }
@@ -272,12 +344,18 @@ function fastCache({ maxCacheSize = 1e3 } = {}) {
   }
   function getOrInsert(cacheKey, val) {
     if (!cache.has(cacheKey)) {
-      cache.set(cacheKey, val());
+      const value = val();
+      cache.set(cacheKey, value);
       trimCache();
+      return cache.get(cacheKey) ?? value;
     }
     return cache.get(cacheKey);
   }
-  return { getOrInsert, clear: () => cache.clear() };
+  return {
+    getOrInsert,
+    /** Clears all cached values */
+    clear: () => cache.clear()
+  };
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {

package/dist/cache.d.cts

@@ -1,5 +1,23 @@
 import { DurationObj } from './time.cjs';
 
+/**
+ * Creates a cached getter that only calls the provided function once. The first
+ * access computes and caches the value; subsequent accesses return the cached
+ * result. This is useful for lazy initialization of expensive computations.
+ *
+ * @example
+ *   const expensive = cachedGetter(() => {
+ *     console.log('Computing...');
+ *     return heavyComputation();
+ *   });
+ *
+ *   console.log(expensive.value); // Logs "Computing..." and returns result
+ *   console.log(expensive.value); // Returns cached result without logging
+ *   console.log(expensive.value); // Returns cached result without logging
+ *
+ * @param getter - Function that computes the value to cache
+ * @returns Object with a `value` property that caches the result
+ */
 declare function cachedGetter<T>(getter: () => T): {
     value: T;
 };
@@ -20,10 +38,44 @@ type Options = {
      */
     expirationThrottle?: number;
 };
+/**
+ * Wrapper class that prevents a value from being cached. When returned from a
+ * cache computation function, the value will be returned to the caller but not
+ * stored in the cache.
+ *
+ * @example
+ *   const cache = createCache<string>();
+ *   const result = cache.getOrInsert('dynamic', ({ skipCaching }) => {
+ *     const data = generateData();
+ *     if (data.isTemporary) {
+ *       return skipCaching(data); // Won't be cached
+ *     }
+ *     return data; // Will be cached
+ *   });
+ */
 declare class SkipCaching<T> {
     value: T;
     constructor(value: T);
 }
+/**
+ * Wrapper class that sets a custom expiration time for a cached value. Allows
+ * individual cache entries to have different expiration times than the default
+ * cache expiration.
+ *
+ * @example
+ *   const cache = createCache<string>({ maxItemAge: { hours: 1 } }); // Default 1 hour
+ *
+ *   const result = cache.getOrInsert('short-lived', ({ withExpiration }) => {
+ *     return withExpiration('temporary data', { minutes: 5 }); // Expires in 5 minutes
+ *   });
+ *
+ *   const longLived = cache.getOrInsert(
+ *     'long-lived',
+ *     ({ withExpiration }) => {
+ *       return withExpiration('persistent data', { days: 1 }); // Expires in 1 day
+ *     },
+ *   );
+ */
 declare class WithExpiration<T> {
     value: T;
     expiration: number;
@@ -73,12 +125,103 @@ type Cache<T> = {
         }>;
     };
 };
+/**
+ * Creates a full-featured cache with time-based expiration, async support, and
+ * advanced features. This is a more powerful alternative to `fastCache` when
+ * you need expiration, async operations, or advanced caching strategies.
+ *
+ * @example
+ *   // Basic usage with expiration
+ *   const cache = createCache<string>({
+ *     maxCacheSize: 100,
+ *     maxItemAge: { minutes: 5 },
+ *   });
+ *
+ *   // Simple caching
+ *   const result = cache.getOrInsert('user:123', () => {
+ *     return fetchUserFromDatabase('123');
+ *   });
+ *
+ *   // Async caching with promise deduplication
+ *   const asyncResult = await cache.getOrInsertAsync(
+ *     'api:data',
+ *     async () => {
+ *       return await fetchFromApi('/data');
+ *     },
+ *   );
+ *
+ *   // Skip caching for certain values
+ *   const value = cache.getOrInsert('dynamic', ({ skipCaching }) => {
+ *     const data = generateDynamicData();
+ *     if (data.shouldNotCache) {
+ *       return skipCaching(data); // Won't be cached
+ *     }
+ *     return data;
+ *   });
+ *
+ *   // Custom expiration per item
+ *   const shortLivedValue = cache.getOrInsert(
+ *     'temp',
+ *     ({ withExpiration }) => {
+ *       return withExpiration('temporary data', { seconds: 30 });
+ *     },
+ *   );
+ *
+ *   // Conditional caching based on the computed value
+ *   const result = cache.getOrInsert(
+ *     'conditional',
+ *     () => {
+ *       return computeValue();
+ *     },
+ *     {
+ *       skipCachingWhen: (value) => value === null || value.error,
+ *     },
+ *   );
+ *
+ * @param options - Configuration options for the cache
+ * @param options.maxCacheSize - Maximum number of items to store. When
+ *   exceeded, oldest items are removed first. Defaults to 1000.
+ * @param options.maxItemAge - Default expiration time for all cached items.
+ *   Items older than this will be automatically removed.
+ * @param options.expirationThrottle - Minimum time in milliseconds between
+ *   expiration cleanup runs. Prevents excessive cleanup operations. Defaults to
+ *   10,000ms.
+ * @returns A cache instance with various methods for storing and retrieving
+ *   values
+ */
 declare function createCache<T>({ maxCacheSize, maxItemAge, expirationThrottle, }?: Options): Cache<T>;
 type FastCacheOptions = {
     maxCacheSize?: number;
 };
+/**
+ * Creates a simple, fast cache with FIFO (First In, First Out) eviction policy.
+ * This is a lightweight alternative to `createCache` for basic caching needs
+ * without expiration, async support, or advanced features.
+ *
+ * @example
+ *   const cache = fastCache<string>({ maxCacheSize: 100 });
+ *
+ *   // Cache expensive computation
+ *   const result = cache.getOrInsert('user:123', () => {
+ *     return fetchUserFromDatabase('123');
+ *   });
+ *
+ *   // Subsequent calls return cached value without re-computation
+ *   const cachedResult = cache.getOrInsert('user:123', () => {
+ *     return fetchUserFromDatabase('123'); // Won't be called
+ *   });
+ *
+ *   // Clear all cached values
+ *   cache.clear();
+ *
+ * @param options - Configuration options for the cache
+ * @param options.maxCacheSize - Maximum number of items to store in the cache.
+ *   When exceeded, oldest items are removed first. Defaults to 1000.
+ * @returns An object with cache methods
+ */
 declare function fastCache<T>({ maxCacheSize }?: FastCacheOptions): {
     getOrInsert: (cacheKey: string, val: () => T) => T;
+    /** Clears all cached values */
     clear: () => void;
 };
 

package/dist/cache.d.ts

@@ -1,5 +1,23 @@
 import { DurationObj } from './time.js';
 
+/**
+ * Creates a cached getter that only calls the provided function once. The first
+ * access computes and caches the value; subsequent accesses return the cached
+ * result. This is useful for lazy initialization of expensive computations.
+ *
+ * @example
+ *   const expensive = cachedGetter(() => {
+ *     console.log('Computing...');
+ *     return heavyComputation();
+ *   });
+ *
+ *   console.log(expensive.value); // Logs "Computing..." and returns result
+ *   console.log(expensive.value); // Returns cached result without logging
+ *   console.log(expensive.value); // Returns cached result without logging
+ *
+ * @param getter - Function that computes the value to cache
+ * @returns Object with a `value` property that caches the result
+ */
 declare function cachedGetter<T>(getter: () => T): {
     value: T;
 };
@@ -20,10 +38,44 @@ type Options = {
      */
     expirationThrottle?: number;
 };
+/**
+ * Wrapper class that prevents a value from being cached. When returned from a
+ * cache computation function, the value will be returned to the caller but not
+ * stored in the cache.
+ *
+ * @example
+ *   const cache = createCache<string>();
+ *   const result = cache.getOrInsert('dynamic', ({ skipCaching }) => {
+ *     const data = generateData();
+ *     if (data.isTemporary) {
+ *       return skipCaching(data); // Won't be cached
+ *     }
+ *     return data; // Will be cached
+ *   });
+ */
 declare class SkipCaching<T> {
     value: T;
     constructor(value: T);
 }
+/**
+ * Wrapper class that sets a custom expiration time for a cached value. Allows
+ * individual cache entries to have different expiration times than the default
+ * cache expiration.
+ *
+ * @example
+ *   const cache = createCache<string>({ maxItemAge: { hours: 1 } }); // Default 1 hour
+ *
+ *   const result = cache.getOrInsert('short-lived', ({ withExpiration }) => {
+ *     return withExpiration('temporary data', { minutes: 5 }); // Expires in 5 minutes
+ *   });
+ *
+ *   const longLived = cache.getOrInsert(
+ *     'long-lived',
+ *     ({ withExpiration }) => {
+ *       return withExpiration('persistent data', { days: 1 }); // Expires in 1 day
+ *     },
+ *   );
+ */
 declare class WithExpiration<T> {
     value: T;
     expiration: number;
@@ -73,12 +125,103 @@ type Cache<T> = {
         }>;
     };
 };
+/**
+ * Creates a full-featured cache with time-based expiration, async support, and
+ * advanced features. This is a more powerful alternative to `fastCache` when
+ * you need expiration, async operations, or advanced caching strategies.
+ *
+ * @example
+ *   // Basic usage with expiration
+ *   const cache = createCache<string>({
+ *     maxCacheSize: 100,
+ *     maxItemAge: { minutes: 5 },
+ *   });
+ *
+ *   // Simple caching
+ *   const result = cache.getOrInsert('user:123', () => {
+ *     return fetchUserFromDatabase('123');
+ *   });
+ *
+ *   // Async caching with promise deduplication
+ *   const asyncResult = await cache.getOrInsertAsync(
+ *     'api:data',
+ *     async () => {
+ *       return await fetchFromApi('/data');
+ *     },
+ *   );
+ *
+ *   // Skip caching for certain values
+ *   const value = cache.getOrInsert('dynamic', ({ skipCaching }) => {
+ *     const data = generateDynamicData();
+ *     if (data.shouldNotCache) {
+ *       return skipCaching(data); // Won't be cached
+ *     }
+ *     return data;
+ *   });
+ *
+ *   // Custom expiration per item
+ *   const shortLivedValue = cache.getOrInsert(
+ *     'temp',
+ *     ({ withExpiration }) => {
+ *       return withExpiration('temporary data', { seconds: 30 });
+ *     },
+ *   );
+ *
+ *   // Conditional caching based on the computed value
+ *   const result = cache.getOrInsert(
+ *     'conditional',
+ *     () => {
+ *       return computeValue();
+ *     },
+ *     {
+ *       skipCachingWhen: (value) => value === null || value.error,
+ *     },
+ *   );
+ *
+ * @param options - Configuration options for the cache
+ * @param options.maxCacheSize - Maximum number of items to store. When
+ *   exceeded, oldest items are removed first. Defaults to 1000.
+ * @param options.maxItemAge - Default expiration time for all cached items.
+ *   Items older than this will be automatically removed.
+ * @param options.expirationThrottle - Minimum time in milliseconds between
+ *   expiration cleanup runs. Prevents excessive cleanup operations. Defaults to
+ *   10,000ms.
+ * @returns A cache instance with various methods for storing and retrieving
+ *   values
+ */
 declare function createCache<T>({ maxCacheSize, maxItemAge, expirationThrottle, }?: Options): Cache<T>;
 type FastCacheOptions = {
     maxCacheSize?: number;
 };
+/**
+ * Creates a simple, fast cache with FIFO (First In, First Out) eviction policy.
+ * This is a lightweight alternative to `createCache` for basic caching needs
+ * without expiration, async support, or advanced features.
+ *
+ * @example
+ *   const cache = fastCache<string>({ maxCacheSize: 100 });
+ *
+ *   // Cache expensive computation
+ *   const result = cache.getOrInsert('user:123', () => {
+ *     return fetchUserFromDatabase('123');
+ *   });
+ *
+ *   // Subsequent calls return cached value without re-computation
+ *   const cachedResult = cache.getOrInsert('user:123', () => {
+ *     return fetchUserFromDatabase('123'); // Won't be called
+ *   });
+ *
+ *   // Clear all cached values
+ *   cache.clear();
+ *
+ * @param options - Configuration options for the cache
+ * @param options.maxCacheSize - Maximum number of items to store in the cache.
+ *   When exceeded, oldest items are removed first. Defaults to 1000.
+ * @returns An object with cache methods
+ */
 declare function fastCache<T>({ maxCacheSize }?: FastCacheOptions): {
     getOrInsert: (cacheKey: string, val: () => T) => T;
+    /** Clears all cached values */
     clear: () => void;
 };
 

package/dist/cache.js

@@ -4,7 +4,7 @@ import {
   cachedGetter,
   createCache,
   fastCache
-} from "./chunk-OIAGLRII.js";
+} from "./chunk-AULH7VMS.js";
 import "./chunk-5MNYPLZI.js";
 import "./chunk-HTCYUMDR.js";
 import "./chunk-II4R3VVX.js";

package/dist/{chunk-OIAGLRII.js → chunk-AULH7VMS.js}

@@ -86,7 +86,26 @@ function createCache({
       return new WithExpiration(value, expiration);
     }
   };
+  function refreshEntry(key, now) {
+    const entry = cache.get(key);
+    if (entry && !isExpired(entry, now)) {
+      cache.delete(key);
+      cache.set(key, entry);
+    }
+  }
   return {
+    /**
+     * Gets a value from the cache or computes and stores it if not present.
+     * This is the primary method for synchronous caching operations.
+     *
+     * @param cacheKey - Unique key to identify the cached value
+     * @param val - Function that computes the value if not cached. Receives
+     *   utility functions for advanced features.
+     * @param options - Optional configuration for this specific get operation
+     * @returns The cached or newly computed value
+     * @throws Error if the cached value is a promise (use getOrInsertAsync
+     *   instead)
+     */
     getOrInsert(cacheKey, val, options) {
       const now = Date.now();
       const entry = cache.get(cacheKey);
@@ -109,8 +128,20 @@ function createCache({
           "Cache value is a promise, use getOrInsertAsync instead"
         );
       }
+      refreshEntry(cacheKey, now);
       return entry.value;
     },
+    /**
+     * Gets a value from the cache or computes and stores it asynchronously.
+     * Provides promise deduplication - concurrent calls with the same key will
+     * share the same promise.
+     *
+     * @param cacheKey - Unique key to identify the cached value
+     * @param val - Async function that computes the value if not cached.
+     *   Receives utility functions for advanced features.
+     * @param options - Optional configuration for this specific get operation
+     * @returns Promise that resolves to the cached or newly computed value
+     */
     async getOrInsertAsync(cacheKey, val, options) {
       const entry = cache.get(cacheKey);
       if (entry && isPromise(entry.value)) {
@@ -118,6 +149,7 @@ function createCache({
       }
       const now = Date.now();
       if (entry && !isExpired(entry, now)) {
+        refreshEntry(cacheKey, now);
         return entry.value;
       }
       const promise = val(utils).then((result) => {
@@ -151,31 +183,67 @@ function createCache({
       cleanExpiredItems();
       return promise;
     },
+    /** Removes all items from the cache. */
     clear() {
       cache.clear();
     },
+    /**
+     * Gets a value from the cache without computing it if missing. Returns
+     * undefined if the key doesn't exist or has expired.
+     *
+     * @param cacheKey - Key to look up in the cache
+     * @returns The cached value or undefined if not found/expired
+     * @throws Error if the cached value is a promise (use getAsync instead)
+     */
     get(cacheKey) {
       const entry = cache.get(cacheKey);
-      if (!entry || isExpired(entry, Date.now())) {
+      const now = Date.now();
+      if (!entry || isExpired(entry, now)) {
         return void 0;
       }
       if (isPromise(entry.value)) {
         throw new Error("Cache value is a promise, use getAsync instead");
       }
+      refreshEntry(cacheKey, now);
       return entry.value;
     },
+    /**
+     * Manually sets a value in the cache.
+     *
+     * @param cacheKey - Key to store the value under
+     * @param value - Value to store, or WithExpiration wrapper for custom
+     *   expiration
+     */
     set(cacheKey, value) {
       cache.set(cacheKey, unwrapValue(value, Date.now()));
       trimToSize();
       cleanExpiredItems();
     },
+    /**
+     * Gets a value from the cache without computing it if missing. Works with
+     * both sync and async cached values.
+     *
+     * @param cacheKey - Key to look up in the cache
+     * @returns Promise that resolves to the cached value or undefined if not
+     *   found/expired
+     */
     async getAsync(cacheKey) {
       const entry = cache.get(cacheKey);
-      if (!entry || isExpired(entry, Date.now())) {
+      const now = Date.now();
+      if (!entry || isExpired(entry, now)) {
         return void 0;
       }
+      refreshEntry(cacheKey, now);
       return entry.value;
     },
+    /**
+     * Manually sets an async value in the cache. The promise will be stored
+     * immediately and shared with concurrent requests.
+     *
+     * @param cacheKey - Key to store the value under
+     * @param value - Async function that returns the value to cache
+     * @returns Promise that resolves to the computed value
+     */
     async setAsync(cacheKey, value) {
       const promise = value(utils).then((result) => {
         if (result instanceof SkipCaching) {
@@ -201,6 +269,10 @@ function createCache({
       cleanExpiredItems();
       return promise;
     },
+    /**
+     * Manually triggers cleanup of expired items. Normally this happens
+     * automatically during cache operations.
+     */
     cleanExpiredItems,
     /** @internal */
     " cache": { map: cache }
@@ -219,12 +291,18 @@ function fastCache({ maxCacheSize = 1e3 } = {}) {
   }
   function getOrInsert(cacheKey, val) {
     if (!cache.has(cacheKey)) {
-      cache.set(cacheKey, val());
+      const value = val();
+      cache.set(cacheKey, value);
       trimCache();
+      return cache.get(cacheKey) ?? value;
     }
     return cache.get(cacheKey);
   }
-  return { getOrInsert, clear: () => cache.clear() };
+  return {
+    getOrInsert,
+    /** Clears all cached values */
+    clear: () => cache.clear()
+  };
 }
 
 export {

package/dist/chunk-PUKVXYYL.js

@@ -0,0 +1,52 @@
+import {
+  isPlainObject
+} from "./chunk-JF2MDHOJ.js";
+
+// src/deepReplaceValues.ts
+function applyValueReplacements(value, replaceValues, visited, currentPath) {
+  function processValue(val, path) {
+    const replacement = replaceValues(val, path);
+    if (replacement !== false) {
+      return replacement.newValue;
+    }
+    if (Array.isArray(val)) {
+      if (visited.has(val)) {
+        throw new Error("Circular reference detected in array");
+      }
+      visited.add(val);
+      try {
+        return val.map((item, index) => {
+          const itemPath = path ? `${path}[${index}]` : `[${index}]`;
+          return processValue(item, itemPath);
+        });
+      } finally {
+        visited.delete(val);
+      }
+    }
+    if (isPlainObject(val)) {
+      if (visited.has(val)) {
+        throw new Error("Circular reference detected in object");
+      }
+      visited.add(val);
+      try {
+        const result = {};
+        for (const [key, itemValue] of Object.entries(val)) {
+          const itemPath = path ? `${path}.${key}` : key;
+          result[key] = processValue(itemValue, itemPath);
+        }
+        return result;
+      } finally {
+        visited.delete(val);
+      }
+    }
+    return val;
+  }
+  return processValue(value, currentPath);
+}
+function deepReplaceValues(value, replaceValues) {
+  return applyValueReplacements(value, replaceValues, /* @__PURE__ */ new Set(), "");
+}
+
+export {
+  deepReplaceValues
+};

package/dist/deepReplaceValues.cjs

@@ -0,0 +1,87 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/deepReplaceValues.ts
+var deepReplaceValues_exports = {};
+__export(deepReplaceValues_exports, {
+  deepReplaceValues: () => deepReplaceValues
+});
+module.exports = __toCommonJS(deepReplaceValues_exports);
+
+// src/typeGuards.ts
+function isPlainObject(value) {
+  if (!value || typeof value !== "object") return false;
+  const proto = Object.getPrototypeOf(value);
+  if (proto === null) {
+    return true;
+  }
+  const Ctor = Object.hasOwnProperty.call(proto, "constructor") && proto.constructor;
+  if (Ctor === Object) return true;
+  const objectCtorString = Object.prototype.constructor.toString();
+  return typeof Ctor == "function" && Function.toString.call(Ctor) === objectCtorString;
+}
+
+// src/deepReplaceValues.ts
+function applyValueReplacements(value, replaceValues, visited, currentPath) {
+  function processValue(val, path) {
+    const replacement = replaceValues(val, path);
+    if (replacement !== false) {
+      return replacement.newValue;
+    }
+    if (Array.isArray(val)) {
+      if (visited.has(val)) {
+        throw new Error("Circular reference detected in array");
+      }
+      visited.add(val);
+      try {
+        return val.map((item, index) => {
+          const itemPath = path ? `${path}[${index}]` : `[${index}]`;
+          return processValue(item, itemPath);
+        });
+      } finally {
+        visited.delete(val);
+      }
+    }
+    if (isPlainObject(val)) {
+      if (visited.has(val)) {
+        throw new Error("Circular reference detected in object");
+      }
+      visited.add(val);
+      try {
+        const result = {};
+        for (const [key, itemValue] of Object.entries(val)) {
+          const itemPath = path ? `${path}.${key}` : key;
+          result[key] = processValue(itemValue, itemPath);
+        }
+        return result;
+      } finally {
+        visited.delete(val);
+      }
+    }
+    return val;
+  }
+  return processValue(value, currentPath);
+}
+function deepReplaceValues(value, replaceValues) {
+  return applyValueReplacements(value, replaceValues, /* @__PURE__ */ new Set(), "");
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  deepReplaceValues
+});

package/dist/deepReplaceValues.d.cts

@@ -0,0 +1,27 @@
+/**
+ * Recursively traverses an object or array and allows conditional replacement of values
+ * based on a provided callback function. The callback receives each value and its path
+ * within the data structure.
+ *
+ * @param value - The input value to process (object, array, or primitive)
+ * @param replaceValues - Callback function that receives each value and its path.
+ *   Return `false` to keep the original value, or `{ newValue: unknown }` to replace it.
+ *   The path uses dot notation for objects (e.g., "user.name") and bracket notation for arrays (e.g., "items[0]")
+ * @returns A new structure with replaced values. The original structure is not modified.
+ * @throws Error if circular references are detected
+ *
+ * @example
+ * const data = { user: { id: 1, name: "Alice" }, scores: [85, 92] };
+ * const result = deepReplaceValues(data, (value, path) => {
+ *   if (typeof value === "number") {
+ *     return { newValue: value * 2 };
+ *   }
+ *   return false;
+ * });
+ * // Result: { user: { id: 2, name: "Alice" }, scores: [170, 184] }
+ */
+declare function deepReplaceValues<T, R = T>(value: T, replaceValues: (value: unknown, path: string) => false | {
+    newValue: unknown;
+}): R;
+
+export { deepReplaceValues };

package/dist/deepReplaceValues.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Recursively traverses an object or array and allows conditional replacement of values
+ * based on a provided callback function. The callback receives each value and its path
+ * within the data structure.
+ *
+ * @param value - The input value to process (object, array, or primitive)
+ * @param replaceValues - Callback function that receives each value and its path.
+ *   Return `false` to keep the original value, or `{ newValue: unknown }` to replace it.
+ *   The path uses dot notation for objects (e.g., "user.name") and bracket notation for arrays (e.g., "items[0]")
+ * @returns A new structure with replaced values. The original structure is not modified.
+ * @throws Error if circular references are detected
+ *
+ * @example
+ * const data = { user: { id: 1, name: "Alice" }, scores: [85, 92] };
+ * const result = deepReplaceValues(data, (value, path) => {
+ *   if (typeof value === "number") {
+ *     return { newValue: value * 2 };
+ *   }
+ *   return false;
+ * });
+ * // Result: { user: { id: 2, name: "Alice" }, scores: [170, 184] }
+ */
+declare function deepReplaceValues<T, R = T>(value: T, replaceValues: (value: unknown, path: string) => false | {
+    newValue: unknown;
+}): R;
+
+export { deepReplaceValues };

package/dist/deepReplaceValues.js

@@ -0,0 +1,7 @@
+import {
+  deepReplaceValues
+} from "./chunk-PUKVXYYL.js";
+import "./chunk-JF2MDHOJ.js";
+export {
+  deepReplaceValues
+};

package/dist/matchPath.cjs

@@ -39,12 +39,18 @@ function fastCache({ maxCacheSize = 1e3 } = {}) {
   }
   function getOrInsert(cacheKey, val) {
     if (!cache2.has(cacheKey)) {
-      cache2.set(cacheKey, val());
+      const value = val();
+      cache2.set(cacheKey, value);
       trimCache();
+      return cache2.get(cacheKey) ?? value;
     }
     return cache2.get(cacheKey);
   }
-  return { getOrInsert, clear: () => cache2.clear() };
+  return {
+    getOrInsert,
+    /** Clears all cached values */
+    clear: () => cache2.clear()
+  };
 }
 
 // src/matchPath.ts

package/dist/matchPath.js

@@ -1,6 +1,6 @@
 import {
   fastCache
-} from "./chunk-OIAGLRII.js";
+} from "./chunk-AULH7VMS.js";
 import "./chunk-5MNYPLZI.js";
 import "./chunk-HTCYUMDR.js";
 import "./chunk-II4R3VVX.js";

package/dist/testUtils.cjs

@@ -155,6 +155,51 @@ function deepEqual(foo, bar, maxDepth = 20) {
   return foo !== foo && bar !== bar;
 }
 
+// src/deepReplaceValues.ts
+function applyValueReplacements(value, replaceValues, visited, currentPath) {
+  function processValue(val, path) {
+    const replacement = replaceValues(val, path);
+    if (replacement !== false) {
+      return replacement.newValue;
+    }
+    if (Array.isArray(val)) {
+      if (visited.has(val)) {
+        throw new Error("Circular reference detected in array");
+      }
+      visited.add(val);
+      try {
+        return val.map((item, index) => {
+          const itemPath = path ? `${path}[${index}]` : `[${index}]`;
+          return processValue(item, itemPath);
+        });
+      } finally {
+        visited.delete(val);
+      }
+    }
+    if (isPlainObject(val)) {
+      if (visited.has(val)) {
+        throw new Error("Circular reference detected in object");
+      }
+      visited.add(val);
+      try {
+        const result = {};
+        for (const [key, itemValue] of Object.entries(val)) {
+          const itemPath = path ? `${path}.${key}` : key;
+          result[key] = processValue(itemValue, itemPath);
+        }
+        return result;
+      } finally {
+        visited.delete(val);
+      }
+    }
+    return val;
+  }
+  return processValue(value, currentPath);
+}
+function deepReplaceValues(value, replaceValues) {
+  return applyValueReplacements(value, replaceValues, /* @__PURE__ */ new Set(), "");
+}
+
 // src/filterObjectOrArrayKeys.ts
 var ID_PROP_REGEXP = /^(id_|key_|id-|key-)|(_id|_key|-id|-key)$/i;
 function filterObjectOrArrayKeys(objOrArray, {
@@ -1368,7 +1413,7 @@ function compactSnapshot(value, {
     }
   }
   if (replaceValues) {
-    processedValue = applyValueReplacements(processedValue, replaceValues);
+    processedValue = deepReplaceValues(processedValue, replaceValues);
   }
   processedValue = showBooleansAs ? replaceBooleansWithEmoji(processedValue, showBooleansAs) : processedValue;
   return `
@@ -1379,46 +1424,6 @@ ${yamlStringify(processedValue, {
     ...options
   })}`;
 }
-function applyValueReplacements(value, replaceValues, visited = /* @__PURE__ */ new Set(), currentPath = "") {
-  function processValue(val, path) {
-    const replacement = replaceValues(val, path);
-    if (replacement !== false) {
-      return replacement.newValue;
-    }
-    if (Array.isArray(val)) {
-      if (visited.has(val)) {
-        throw new Error("Circular reference detected in array");
-      }
-      visited.add(val);
-      try {
-        return val.map((item, index) => {
-          const itemPath = path ? `${path}[${index}]` : `[${index}]`;
-          return processValue(item, itemPath);
-        });
-      } finally {
-        visited.delete(val);
-      }
-    }
-    if (isPlainObject(val)) {
-      if (visited.has(val)) {
-        throw new Error("Circular reference detected in object");
-      }
-      visited.add(val);
-      try {
-        const result = {};
-        for (const [key, itemValue] of Object.entries(val)) {
-          const itemPath = path ? `${path}.${key}` : key;
-          result[key] = processValue(itemValue, itemPath);
-        }
-        return result;
-      } finally {
-        visited.delete(val);
-      }
-    }
-    return val;
-  }
-  return processValue(value, currentPath);
-}
 function replaceBooleansWithEmoji(value, showBooleansAs, visited = /* @__PURE__ */ new Set()) {
   if (showBooleansAs === false) {
     return value;

package/dist/testUtils.js

@@ -6,13 +6,16 @@ import {
   pick
 } from "./chunk-Y45CE75W.js";
 import "./chunk-GMJTLFM6.js";
+import {
+  filterObjectOrArrayKeys
+} from "./chunk-6CG6JZKB.js";
 import "./chunk-IATIXMCE.js";
 import {
   deepEqual
 } from "./chunk-JQFUKJU5.js";
 import {
-  filterObjectOrArrayKeys
-} from "./chunk-6CG6JZKB.js";
+  deepReplaceValues
+} from "./chunk-PUKVXYYL.js";
 import {
   defer
 } from "./chunk-DFXNVEH6.js";
@@ -281,7 +284,7 @@ function compactSnapshot(value, {
     }
   }
   if (replaceValues) {
-    processedValue = applyValueReplacements(processedValue, replaceValues);
+    processedValue = deepReplaceValues(processedValue, replaceValues);
   }
   processedValue = showBooleansAs ? replaceBooleansWithEmoji(processedValue, showBooleansAs) : processedValue;
   return `
@@ -292,46 +295,6 @@ ${yamlStringify(processedValue, {
     ...options
   })}`;
 }
-function applyValueReplacements(value, replaceValues, visited = /* @__PURE__ */ new Set(), currentPath = "") {
-  function processValue(val, path) {
-    const replacement = replaceValues(val, path);
-    if (replacement !== false) {
-      return replacement.newValue;
-    }
-    if (Array.isArray(val)) {
-      if (visited.has(val)) {
-        throw new Error("Circular reference detected in array");
-      }
-      visited.add(val);
-      try {
-        return val.map((item, index) => {
-          const itemPath = path ? `${path}[${index}]` : `[${index}]`;
-          return processValue(item, itemPath);
-        });
-      } finally {
-        visited.delete(val);
-      }
-    }
-    if (isPlainObject(val)) {
-      if (visited.has(val)) {
-        throw new Error("Circular reference detected in object");
-      }
-      visited.add(val);
-      try {
-        const result = {};
-        for (const [key, itemValue] of Object.entries(val)) {
-          const itemPath = path ? `${path}.${key}` : key;
-          result[key] = processValue(itemValue, itemPath);
-        }
-        return result;
-      } finally {
-        visited.delete(val);
-      }
-    }
-    return val;
-  }
-  return processValue(value, currentPath);
-}
 function replaceBooleansWithEmoji(value, showBooleansAs, visited = /* @__PURE__ */ new Set()) {
   if (showBooleansAs === false) {
     return value;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ls-stack/utils",
   "description": "Universal TypeScript utilities for browser and Node.js",
-  "version": "3.46.0",
+  "version": "3.47.0",
   "license": "MIT",
   "files": [
     "dist",
@@ -76,6 +76,10 @@
       "import": "./dist/deepEqual.js",
       "require": "./dist/deepEqual.cjs"
     },
+    "./deepReplaceValues": {
+      "import": "./dist/deepReplaceValues.js",
+      "require": "./dist/deepReplaceValues.cjs"
+    },
     "./enhancedMap": {
       "import": "./dist/enhancedMap.js",
       "require": "./dist/enhancedMap.cjs"