@ls-stack/utils 3.63.0 → 3.66.0

package/dist/{awaitDebounce.d.cts → awaitDebounce.d.mts}

@@ -1,4 +1,6 @@
-import { __LEGIT_ANY__ } from './saferTyping.cjs';
+import { __LEGIT_ANY__ } from "./saferTyping.mjs";
+
+//#region src/awaitDebounce.d.ts
 
 /**
  * Creates an awaitable debounce mechanism that allows you to debounce async
@@ -33,9 +35,12 @@ import { __LEGIT_ANY__ } from './saferTyping.cjs';
  * @returns Promise that resolves to 'continue' if this call should proceed, or
  *   'skip' if it was superseded
  */
-declare function awaitDebounce({ callId: _callId, debounce, }: {
-    callId: __LEGIT_ANY__;
-    debounce: number;
+declare function awaitDebounce({
+  callId: _callId,
+  debounce
+}: {
+  callId: __LEGIT_ANY__;
+  debounce: number;
 }): Promise<'continue' | 'skip'>;
-
-export { awaitDebounce };
+//#endregion
+export { awaitDebounce };

package/dist/awaitDebounce.mjs

@@ -0,0 +1,54 @@
+import { getCompositeKey } from "./getCompositeKey.mjs";
+
+//#region src/awaitDebounce.ts
+const resolvers = {};
+const debouncers = {};
+/**
+* Creates an awaitable debounce mechanism that allows you to debounce async
+* operations. When called multiple times with the same `callId`, only the last
+* call will resolve with 'continue', while all previous calls resolve with
+* 'skip'.
+*
+* This is useful for debouncing API calls, search operations, or any async work
+* where you want to ensure only the most recent request is processed.
+*
+* @example
+*   ```ts
+*   async function searchUsers(query: string) {
+*     const result = await awaitDebounce({ callId: 'search', debounce: 300 });
+*     if (result === 'skip') return; // This search was superseded
+*
+*     // Only the most recent search will reach here
+*     const users = await fetchUsers(query);
+*     updateUI(users);
+*   }
+*
+*   // Called rapidly - only the last call will execute
+*   searchUsers('a');
+*   searchUsers('ab');
+*   searchUsers('abc'); // Only this one will continue
+*   ```;
+*
+* @param options - Configuration object
+* @param options.callId - Unique identifier for the debounce group. Calls with
+*   the same ID are debounced together
+* @param options.debounce - Debounce delay in milliseconds
+* @returns Promise that resolves to 'continue' if this call should proceed, or
+*   'skip' if it was superseded
+*/
+async function awaitDebounce({ callId: _callId, debounce }) {
+	const callId = getCompositeKey(_callId);
+	if (debouncers[callId]) clearTimeout(debouncers[callId]);
+	debouncers[callId] = globalThis.setTimeout(() => {
+		const resolve = resolvers[callId];
+		resolvers[callId] = void 0;
+		resolve?.("continue");
+	}, debounce);
+	if (resolvers[callId]) resolvers[callId]("skip");
+	return new Promise((resolve) => {
+		resolvers[callId] = resolve;
+	});
+}
+
+//#endregion
+export { awaitDebounce };

package/dist/{cache.d.ts → cache.d.mts}

@@ -1,4 +1,6 @@
-import { DurationObj } from './time.js';
+import { DurationObj } from "./time.mjs";
+
+//#region src/cache.d.ts
 
 /**
  * Creates a cached getter that only calls the provided function once. The first
@@ -19,24 +21,24 @@ import { DurationObj } from './time.js';
  * @returns Object with a `value` property that caches the result
  */
 declare function cachedGetter<T>(getter: () => T): {
-    value: T;
+  value: T;
 };
 type Options = {
-    /**
-     * The maximum number of items in the cache.
-     *
-     * @default 1000
-     */
-    maxCacheSize?: number;
-    /** The maximum age of items in the cache. */
-    maxItemAge?: DurationObj;
-    /**
-     * The throttle for checking expired items in milliseconds.
-     *
-     * @default
-     * 10_000
-     */
-    expirationThrottle?: number;
+  /**
+   * The maximum number of items in the cache.
+   *
+   * @default 1000
+   */
+  maxCacheSize?: number;
+  /** The maximum age of items in the cache. */
+  maxItemAge?: DurationObj;
+  /**
+   * The throttle for checking expired items in milliseconds.
+   *
+   * @default
+   * 10_000
+   */
+  expirationThrottle?: number;
 };
 /**
  * Wrapper class that prevents a value from being cached. When returned from a
@@ -54,8 +56,8 @@ type Options = {
  *   });
  */
 declare class SkipCaching<T> {
-    value: T;
-    constructor(value: T);
+  value: T;
+  constructor(value: T);
 }
 /**
  * Wrapper class that sets a custom expiration time for a cached value. Allows
@@ -77,53 +79,53 @@ declare class SkipCaching<T> {
  *   );
  */
 declare class WithExpiration<T> {
-    value: T;
-    expiration: number;
-    /**
-     * @param value - The value to store in the cache.
-     * @param expiration - The expiration time of the value in seconds or a
-     *   duration object.
-     */
-    constructor(value: T, expiration: DurationObj);
+  value: T;
+  expiration: number;
+  /**
+   * @param value - The value to store in the cache.
+   * @param expiration - The expiration time of the value in seconds or a
+   *   duration object.
+   */
+  constructor(value: T, expiration: DurationObj);
 }
 type Utils<T> = {
-    skipCaching: (value: T) => SkipCaching<T>;
-    /**
-     * Create a new WithExpiration object with the given value and expiration
-     * time.
-     *
-     * @param value - The value to store in the cache.
-     * @param expiration - The expiration time of the value in seconds or a
-     *   duration object.
-     */
-    withExpiration: (value: T, expiration: DurationObj) => WithExpiration<T>;
+  skipCaching: (value: T) => SkipCaching<T>;
+  /**
+   * Create a new WithExpiration object with the given value and expiration
+   * time.
+   *
+   * @param value - The value to store in the cache.
+   * @param expiration - The expiration time of the value in seconds or a
+   *   duration object.
+   */
+  withExpiration: (value: T, expiration: DurationObj) => WithExpiration<T>;
 };
 type GetOptions<T> = {
-    /**
-     * A function that determines whether a value should be rejected from being
-     * cached. If the function returns true, the value will be returned but not
-     * cached.
-     *
-     * @param value The value to check
-     * @returns True if the value should be rejected, false otherwise
-     */
-    skipCachingWhen?: (value: T) => boolean;
+  /**
+   * A function that determines whether a value should be rejected from being
+   * cached. If the function returns true, the value will be returned but not
+   * cached.
+   *
+   * @param value The value to check
+   * @returns True if the value should be rejected, false otherwise
+   */
+  skipCachingWhen?: (value: T) => boolean;
 };
 type Cache<T> = {
-    getOrInsert: (cacheKey: string, val: (utils: Utils<T>) => T | SkipCaching<T>, options?: GetOptions<T>) => T;
-    getOrInsertAsync: (cacheKey: string, val: (utils: Utils<T>) => Promise<T | SkipCaching<T>>, options?: GetOptions<T>) => Promise<T>;
-    clear: () => void;
-    get: (cacheKey: string) => T | undefined;
-    set: (cacheKey: string, value: T | WithExpiration<T>) => void;
-    cleanExpiredItems: () => void;
-    getAsync: (cacheKey: string) => Promise<T | undefined>;
-    setAsync: (cacheKey: string, value: (utils: Utils<T>) => Promise<T | WithExpiration<T>>) => Promise<T>;
-    [' cache']: {
-        map: Map<string, {
-            value: T | Promise<T>;
-            timestamp: number;
-        }>;
-    };
+  getOrInsert: (cacheKey: string, val: (utils: Utils<T>) => T | SkipCaching<T>, options?: GetOptions<T>) => T;
+  getOrInsertAsync: (cacheKey: string, val: (utils: Utils<T>) => Promise<T | SkipCaching<T>>, options?: GetOptions<T>) => Promise<T>;
+  clear: () => void;
+  get: (cacheKey: string) => T | undefined;
+  set: (cacheKey: string, value: T | WithExpiration<T>) => void;
+  cleanExpiredItems: () => void;
+  getAsync: (cacheKey: string) => Promise<T | undefined>;
+  setAsync: (cacheKey: string, value: (utils: Utils<T>) => Promise<T | WithExpiration<T>>) => Promise<T>;
+  [' cache']: {
+    map: Map<string, {
+      value: T | Promise<T>;
+      timestamp: number;
+    }>;
+  };
 };
 /**
  * Creates a full-featured cache with time-based expiration, async support, and
@@ -189,9 +191,13 @@ type Cache<T> = {
  * @returns A cache instance with various methods for storing and retrieving
  *   values
  */
-declare function createCache<T>({ maxCacheSize, maxItemAge, expirationThrottle, }?: Options): Cache<T>;
+declare function createCache<T>({
+  maxCacheSize,
+  maxItemAge,
+  expirationThrottle
+}?: Options): Cache<T>;
 type FastCacheOptions = {
-    maxCacheSize?: number;
+  maxCacheSize?: number;
 };
 /**
  * Creates a simple, fast cache with FIFO (First In, First Out) eviction policy.
@@ -219,10 +225,12 @@ type FastCacheOptions = {
  *   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;
+declare function fastCache<T>({
+  maxCacheSize
+}?: FastCacheOptions): {
+  getOrInsert: (cacheKey: string, val: () => T) => T;
+  /** Clears all cached values */
+  clear: () => void;
 };
-
-export { type Cache, SkipCaching, WithExpiration, cachedGetter, createCache, fastCache };
+//#endregion
+export { Cache, SkipCaching, WithExpiration, cachedGetter, createCache, fastCache };

package/dist/cache.mjs

@@ -0,0 +1,355 @@
+import { c as isPromise } from "./assertions-qMxfVhSu.mjs";
+import { p as durationObjToMs } from "./time-sr2lhQRw.mjs";
+
+//#region src/cache.ts
+/**
+* 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
+*/
+function cachedGetter(getter) {
+	return { get value() {
+		const value = getter();
+		Object.defineProperty(this, "value", { value });
+		return value;
+	} };
+}
+/**
+* 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
+*   });
+*/
+var SkipCaching = class {
+	value;
+	constructor(value) {
+		this.value = value;
+	}
+};
+/**
+* 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
+*     },
+*   );
+*/
+var WithExpiration = class {
+	value;
+	expiration;
+	/**
+	* @param value - The value to store in the cache.
+	* @param expiration - The expiration time of the value in seconds or a
+	*   duration object.
+	*/
+	constructor(value, expiration) {
+		this.value = value;
+		this.expiration = durationObjToMs(expiration);
+	}
+};
+/**
+* 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
+*/
+function createCache({ maxCacheSize = 1e3, maxItemAge, expirationThrottle = 1e4 } = {}) {
+	const cache = /* @__PURE__ */ new Map();
+	let lastExpirationCheck = 0;
+	const defaultMaxItemAgeMs = maxItemAge && durationObjToMs(maxItemAge);
+	function cleanExpiredItems() {
+		const now = Date.now();
+		if (!defaultMaxItemAgeMs || now - lastExpirationCheck < expirationThrottle) return;
+		lastExpirationCheck = now;
+		for (const [key, item] of cache.entries()) if (isExpired(item, now)) cache.delete(key);
+	}
+	function trimToSize() {
+		const currentSize = cache.size;
+		if (currentSize > maxCacheSize) {
+			const keysToRemove = currentSize - maxCacheSize;
+			const iterator = cache.keys();
+			for (let i = 0; i < keysToRemove; i++) {
+				const { value: key } = iterator.next();
+				if (key) cache.delete(key);
+			}
+		}
+	}
+	function isExpired(entry, now) {
+		const maxItemAgeMs = entry.expiration ?? defaultMaxItemAgeMs;
+		return !!maxItemAgeMs && now - entry.timestamp > maxItemAgeMs;
+	}
+	function unwrapValue(value, now) {
+		if (value instanceof WithExpiration) return {
+			value: value.value,
+			timestamp: now,
+			expiration: value.expiration ? typeof value.expiration === "number" ? value.expiration : now + durationObjToMs(value.expiration) : void 0
+		};
+		return {
+			value,
+			timestamp: now,
+			expiration: void 0
+		};
+	}
+	const utils = {
+		skipCaching: (value) => new SkipCaching(value),
+		withExpiration: (value, expiration) => {
+			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 {
+		getOrInsert(cacheKey, val, options) {
+			const now = Date.now();
+			const entry = cache.get(cacheKey);
+			if (!entry || isExpired(entry, now)) {
+				const value = val(utils);
+				if (value instanceof SkipCaching) return value.value;
+				if (options?.skipCachingWhen?.(value)) return value;
+				const unwrappedValue = unwrapValue(value, now);
+				cache.set(cacheKey, unwrappedValue);
+				trimToSize();
+				cleanExpiredItems();
+				return unwrappedValue.value;
+			}
+			if (isPromise(entry.value)) throw new Error("Cache value is a promise, use getOrInsertAsync instead");
+			refreshEntry(cacheKey, now);
+			return entry.value;
+		},
+		async getOrInsertAsync(cacheKey, val, options) {
+			const entry = cache.get(cacheKey);
+			if (entry && isPromise(entry.value)) return entry.value;
+			const now = Date.now();
+			if (entry && !isExpired(entry, now)) {
+				refreshEntry(cacheKey, now);
+				return entry.value;
+			}
+			const promise = val(utils).then((result) => {
+				if (result instanceof SkipCaching) {
+					if (cache.get(cacheKey)?.value === promise) cache.delete(cacheKey);
+					return result.value;
+				}
+				if (options?.skipCachingWhen?.(result)) {
+					if (cache.get(cacheKey)?.value === promise) cache.delete(cacheKey);
+					return result;
+				}
+				const unwrappedValue = unwrapValue(result, Date.now());
+				cache.set(cacheKey, unwrappedValue);
+				return unwrappedValue.value;
+			}).catch((error) => {
+				cache.delete(cacheKey);
+				throw error;
+			});
+			cache.set(cacheKey, {
+				value: promise,
+				timestamp: now,
+				expiration: void 0
+			});
+			trimToSize();
+			cleanExpiredItems();
+			return promise;
+		},
+		clear() {
+			cache.clear();
+		},
+		get(cacheKey) {
+			const entry = cache.get(cacheKey);
+			const now = Date.now();
+			if (!entry || isExpired(entry, now)) return;
+			if (isPromise(entry.value)) throw new Error("Cache value is a promise, use getAsync instead");
+			refreshEntry(cacheKey, now);
+			return entry.value;
+		},
+		set(cacheKey, value) {
+			cache.set(cacheKey, unwrapValue(value, Date.now()));
+			trimToSize();
+			cleanExpiredItems();
+		},
+		async getAsync(cacheKey) {
+			const entry = cache.get(cacheKey);
+			const now = Date.now();
+			if (!entry || isExpired(entry, now)) return;
+			refreshEntry(cacheKey, now);
+			return entry.value;
+		},
+		async setAsync(cacheKey, value) {
+			const promise = value(utils).then((result) => {
+				if (result instanceof SkipCaching) {
+					if (cache.get(cacheKey)?.value === promise) cache.delete(cacheKey);
+					return result.value;
+				}
+				const unwrappedValue = unwrapValue(result, Date.now());
+				cache.set(cacheKey, unwrappedValue);
+				return unwrappedValue.value;
+			}).catch((error) => {
+				cache.delete(cacheKey);
+				throw error;
+			});
+			cache.set(cacheKey, {
+				value: promise,
+				timestamp: Date.now(),
+				expiration: void 0
+			});
+			trimToSize();
+			cleanExpiredItems();
+			return promise;
+		},
+		cleanExpiredItems,
+		" cache": { map: cache }
+	};
+}
+/**
+* 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
+*/
+function fastCache({ maxCacheSize = 1e3 } = {}) {
+	const cache = /* @__PURE__ */ new Map();
+	function trimCache() {
+		const cacheSize = cache.size;
+		if (cacheSize > maxCacheSize) {
+			const keys = Array.from(cache.keys());
+			for (let i = 0; i < cacheSize - maxCacheSize; i++) cache.delete(keys[i]);
+		}
+	}
+	/**
+	* Gets a value from the cache or computes and stores it if not present.
+	*
+	* @param cacheKey - The key to store/retrieve the value under
+	* @param val - Function that computes the value if not cached
+	* @returns The cached or newly computed value
+	*/
+	function getOrInsert(cacheKey, val) {
+		if (!cache.has(cacheKey)) {
+			const value = val();
+			cache.set(cacheKey, value);
+			trimCache();
+			return cache.get(cacheKey) ?? value;
+		}
+		return cache.get(cacheKey);
+	}
+	return {
+		getOrInsert,
+		clear: () => cache.clear()
+	};
+}
+
+//#endregion
+export { SkipCaching, WithExpiration, cachedGetter, createCache, fastCache };

package/dist/castValues-DfICShCc.mjs

@@ -0,0 +1,19 @@
+//#region src/castValues.ts
+function castToString(value) {
+	const valueType = typeof value;
+	return valueType === "string" || valueType === "number" || valueType === "boolean" || valueType === "bigint" ? String(value) : null;
+}
+function castToNumber(value) {
+	return isFiniteNumeric(value) ? Number(value) : null;
+}
+function isFiniteNumeric(num) {
+	switch (typeof num) {
+		case "number": return num - num === 0;
+		case "string": return num.trim() !== "" && Number.isFinite(+num);
+		case "bigint": return Number.isFinite(Number(num));
+		default: return false;
+	}
+}
+
+//#endregion
+export { castToString as n, castToNumber as t };

package/dist/{castValues.d.cts → castValues.d.mts}

@@ -1,4 +1,5 @@
+//#region src/castValues.d.ts
 declare function castToString(value: unknown): string | null;
 declare function castToNumber(value: unknown): number | null;
-
-export { castToNumber, castToString };
+//#endregion
+export { castToNumber, castToString };

package/dist/castValues.mjs

@@ -0,0 +1,3 @@
+import { n as castToString, t as castToNumber } from "./castValues-DfICShCc.mjs";
+
+export { castToNumber, castToString };