@ls-stack/utils 3.65.0 → 3.67.0

package/dist/cache.d.cts

@@ -1,228 +0,0 @@
-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;
-};
-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;
-};
-/**
- * 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;
-    /**
-     * @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>;
-};
-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;
-};
-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;
-        }>;
-    };
-};
-/**
- * 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;
-};
-
-export { type Cache, SkipCaching, WithExpiration, cachedGetter, createCache, fastCache };

package/dist/cache.js

@@ -1,19 +0,0 @@
-import {
-  SkipCaching,
-  WithExpiration,
-  cachedGetter,
-  createCache,
-  fastCache
-} from "./chunk-DX2524CZ.js";
-import "./chunk-6FBIEPWU.js";
-import "./chunk-DBOWTYR4.js";
-import "./chunk-II4R3VVX.js";
-import "./chunk-C2SVCIWE.js";
-import "./chunk-JF2MDHOJ.js";
-export {
-  SkipCaching,
-  WithExpiration,
-  cachedGetter,
-  createCache,
-  fastCache
-};

package/dist/castValues.cjs

@@ -1,50 +0,0 @@
-"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/castValues.ts
-var castValues_exports = {};
-__export(castValues_exports, {
-  castToNumber: () => castToNumber,
-  castToString: () => castToString
-});
-module.exports = __toCommonJS(castValues_exports);
-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;
-  }
-}
-// Annotate the CommonJS export names for ESM import in node:
-0 && (module.exports = {
-  castToNumber,
-  castToString
-});

package/dist/castValues.d.ts

@@ -1,4 +0,0 @@
-declare function castToString(value: unknown): string | null;
-declare function castToNumber(value: unknown): number | null;
-
-export { castToNumber, castToString };

package/dist/castValues.js

@@ -1,8 +0,0 @@
-import {
-  castToNumber,
-  castToString
-} from "./chunk-II4R3VVX.js";
-export {
-  castToNumber,
-  castToString
-};

package/dist/chunk-5DZT3Z5Z.js

@@ -1,8 +0,0 @@
-// src/sleep.ts
-function sleep(ms) {
-  return new Promise((resolve) => setTimeout(resolve, ms));
-}
-
-export {
-  sleep
-};

package/dist/chunk-6FBIEPWU.js

@@ -1,96 +0,0 @@
-import {
-  clampMax
-} from "./chunk-DBOWTYR4.js";
-import {
-  castToNumber
-} from "./chunk-II4R3VVX.js";
-
-// src/time.ts
-var MINUTE_AS_MS = 60 * 1e3;
-var HOUR_AS_MS = 60 * MINUTE_AS_MS;
-var DAY_AS_MS = 24 * HOUR_AS_MS;
-var WEEK_AS_MS = 7 * DAY_AS_MS;
-var MONTH_AS_MS = 30 * DAY_AS_MS;
-var YEAR_AS_MS = 365 * DAY_AS_MS;
-var HOUR_AS_SECS = 60 * 60;
-var DAY_AS_SECS = 24 * HOUR_AS_SECS;
-var WEEK_AS_SECS = 7 * DAY_AS_SECS;
-var MONTH_AS_SECS = 30 * DAY_AS_SECS;
-var YEAR_AS_SECS = 365 * DAY_AS_SECS;
-function dateStringOrNullToUnixMs(isoString) {
-  if (!isoString) return null;
-  const unixMs = new Date(isoString).getTime();
-  if (isNaN(unixMs)) return null;
-  return unixMs;
-}
-function msToTimeString(ms, format, hoursMinLength = 2) {
-  const { hours, minutes, seconds, milliseconds } = msToDurationObj(ms);
-  const hoursString = padTimeVal(hours, hoursMinLength);
-  const minutesString = padTimeVal(minutes);
-  if (format === "minutes") {
-    return `${hoursString}:${minutesString}`;
-  }
-  const secondsString = padTimeVal(seconds);
-  if (format === "seconds") {
-    return `${hoursString}:${minutesString}:${secondsString}`;
-  }
-  return `${hoursString}:${minutesString}:${secondsString}:${padTimeVal(
-    milliseconds,
-    3
-  )}`;
-}
-function padTimeVal(val, maxLength = 2) {
-  return val.toString().padStart(maxLength, "0");
-}
-function parseTimeStringToMs(timeString) {
-  if (!timeString.trim()) return 0;
-  const [hours, minutes, seconds, ms] = timeString.split(":");
-  return getTimeStringPartToInt(hours) * HOUR_AS_MS + clampMax(getTimeStringPartToInt(minutes), 59) * MINUTE_AS_MS + clampMax(getTimeStringPartToInt(seconds), 59) * 1e3 + getTimeStringPartToInt(ms, 3);
-}
-function getTimeStringPartToInt(timeStringPart, length) {
-  if (!timeStringPart?.trim()) return 0;
-  let string = timeStringPart.replaceAll("_", "0");
-  string = string.replaceAll("-", "");
-  if (length) {
-    string = string.padEnd(length, "0");
-    if (string.length > length) {
-      string = string.slice(0, length);
-    }
-  }
-  const num = castToNumber(string);
-  if (!num) return 0;
-  return Math.floor(num);
-}
-function msToDurationObj(ms) {
-  return {
-    milliseconds: ms % 1e3,
-    seconds: Math.floor(ms / 1e3) % 60,
-    minutes: Math.floor(ms / 1e3 / 60) % 60,
-    hours: Math.floor(ms / 1e3 / 60 / 60)
-  };
-}
-function getUnixSeconds() {
-  return Math.floor(Date.now() / 1e3);
-}
-function durationObjToMs(durationObj) {
-  return (durationObj.hours ?? 0) * HOUR_AS_MS + (durationObj.minutes ?? 0) * MINUTE_AS_MS + (durationObj.seconds ?? 0) * 1e3 + (durationObj.ms ?? 0) + (durationObj.days ?? 0) * DAY_AS_MS;
-}
-
-export {
-  MINUTE_AS_MS,
-  HOUR_AS_MS,
-  DAY_AS_MS,
-  WEEK_AS_MS,
-  MONTH_AS_MS,
-  YEAR_AS_MS,
-  HOUR_AS_SECS,
-  DAY_AS_SECS,
-  WEEK_AS_SECS,
-  MONTH_AS_SECS,
-  YEAR_AS_SECS,
-  dateStringOrNullToUnixMs,
-  msToTimeString,
-  parseTimeStringToMs,
-  getUnixSeconds,
-  durationObjToMs
-};

package/dist/chunk-6FIBVC2P.js

@@ -1,56 +0,0 @@
-import {
-  isObject
-} from "./chunk-C2SVCIWE.js";
-
-// src/getCompositeKey.ts
-function getCompositeKey(input, maxSortingDepth = 3) {
-  if (typeof input === "string") return `"${input}`;
-  if (!input || typeof input !== "object") return `$${input}`;
-  return stringifyCompact(input, maxSortingDepth, 0, /* @__PURE__ */ new WeakSet());
-}
-function stringifyCompact(input, maxSortingDepth, depth, refs) {
-  const isJsObj = input && typeof input === "object";
-  if (isJsObj) {
-    if (refs.has(input)) {
-      throw new Error("Circular reference detected");
-    }
-    refs.add(input);
-  }
-  let result;
-  if (Array.isArray(input)) {
-    result = "[";
-    for (const v of input) {
-      if (result.length > 1) result += ",";
-      result += stringifyCompact(v, maxSortingDepth, depth + 1, refs);
-    }
-    result += "]";
-  } else if (isObject(input)) {
-    let entries = Object.entries(input);
-    if (entries.length === 0) {
-      result = "{}";
-    } else {
-      if (depth < maxSortingDepth) {
-        entries = entries.sort(
-          ([a], [b]) => a < b ? -1 : a > b ? 1 : 0
-        );
-      }
-      result = "{";
-      for (const [k, v] of entries) {
-        if (v === void 0) continue;
-        if (result.length > 1) result += ",";
-        result += `${k}:${stringifyCompact(v, maxSortingDepth, depth + 1, refs)}`;
-      }
-      result += "}";
-    }
-  } else {
-    result = JSON.stringify(input);
-  }
-  if (isJsObj) {
-    refs.delete(input);
-  }
-  return result;
-}
-
-export {
-  getCompositeKey
-};

package/dist/chunk-7CQPOM5I.js

@@ -1,100 +0,0 @@
-import {
-  isFunction
-} from "./chunk-C2SVCIWE.js";
-
-// src/enhancedMap.ts
-var enhancedMapReject = Symbol();
-var EnhancedMap = class _EnhancedMap extends Map {
-  find(predicate) {
-    for (const [key, value] of this) {
-      if (predicate(value, key)) {
-        return { key, value };
-      }
-    }
-    return void 0;
-  }
-  setMultiple(...values) {
-    if (Array.isArray(values[0])) {
-      for (const [key, value] of values) {
-        this.set(key, value);
-      }
-    } else {
-      for (const [key, value] of Object.entries(values[0])) {
-        this.set(key, value);
-      }
-    }
-    return this;
-  }
-  getOrThrow(key) {
-    const value = this.get(key);
-    if (value === void 0) {
-      throw new Error(`Key ${key} not found in EnhancedMap`);
-    }
-    return value;
-  }
-  getOrInsert(key, fallback) {
-    if (!this.has(key)) {
-      this.set(key, fallback());
-    }
-    return this.getOrThrow(key);
-  }
-  toFilteredValues(predicate) {
-    const values = [];
-    for (const [key, value] of this) {
-      if (predicate(value, key)) {
-        values.push(value);
-      }
-    }
-    return values;
-  }
-  toMap(mapFunction) {
-    const values = [];
-    for (const [key, value] of this) {
-      const result = mapFunction(value, key, enhancedMapReject);
-      if (result !== enhancedMapReject) {
-        values.push(result);
-      }
-    }
-    return values;
-  }
-  toObjMap(mapFunction) {
-    const values = {};
-    for (const [key, value] of this) {
-      const result = mapFunction(value, key);
-      if (result) {
-        values[result[0]] = result[1];
-      }
-    }
-    return values;
-  }
-  toValues() {
-    return [...this.values()];
-  }
-  toKeys() {
-    return [...this.keys()];
-  }
-  static from(array, mapFunction) {
-    const map = new _EnhancedMap();
-    if (!array) return map;
-    const isFn = isFunction(mapFunction);
-    for (const item of array) {
-      if (isFn) {
-        const result = mapFunction(item);
-        if (result) {
-          map.set(result[0], result[1]);
-        }
-      } else {
-        const key = item[mapFunction];
-        if (key !== void 0) {
-          map.set(key, item);
-        }
-      }
-    }
-    return map;
-  }
-};
-
-export {
-  enhancedMapReject,
-  EnhancedMap
-};