@ls-stack/utils 3.46.0 → 3.48.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 {