@ls-stack/utils 3.63.0 → 3.66.0

package/dist/throttle.cjs

@@ -1,282 +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/throttle.ts
-var throttle_exports = {};
-__export(throttle_exports, {
-  createThrottledFunctionFactory: () => createThrottledFunctionFactory,
-  throttle: () => throttle
-});
-module.exports = __toCommonJS(throttle_exports);
-
-// src/debounce.ts
-function debounce(func, wait, options) {
-  let currentCallback = func;
-  let waitMs = wait;
-  let currentOptions = options;
-  let lastArgs;
-  let lastThis;
-  let maxWait;
-  let result;
-  let timerId;
-  let lastCallTime;
-  let lastInvokeTime = 0;
-  let leading = false;
-  let maxing = false;
-  let trailing = true;
-  function applyOptions() {
-    const opts = currentOptions;
-    leading = !!opts?.leading;
-    trailing = opts && "trailing" in opts ? !!opts.trailing : true;
-    maxing = !!(opts && "maxWait" in opts);
-    maxWait = maxing ? Math.max(opts?.maxWait ?? 0, waitMs) : void 0;
-  }
-  applyOptions();
-  function invokeFunc(time) {
-    const args = lastArgs;
-    const thisArg = lastThis;
-    lastArgs = lastThis = void 0;
-    lastInvokeTime = time;
-    result = currentCallback.apply(thisArg, args);
-    return result;
-  }
-  function leadingEdge(time) {
-    lastInvokeTime = time;
-    timerId = setTimeout(timerExpired, waitMs);
-    return leading ? invokeFunc(time) : result;
-  }
-  function remainingWait(time) {
-    const timeSinceLastCall = time - (lastCallTime ?? 0);
-    const timeSinceLastInvoke = time - lastInvokeTime;
-    const timeWaiting = waitMs - timeSinceLastCall;
-    return maxing ? Math.min(timeWaiting, (maxWait ?? 0) - timeSinceLastInvoke) : timeWaiting;
-  }
-  function shouldInvoke(time) {
-    const timeSinceLastCall = time - (lastCallTime ?? 0);
-    const timeSinceLastInvoke = time - lastInvokeTime;
-    return lastCallTime === void 0 || timeSinceLastCall >= waitMs || timeSinceLastCall < 0 || maxing && timeSinceLastInvoke >= (maxWait ?? 0);
-  }
-  function timerExpired() {
-    const time = Date.now();
-    if (shouldInvoke(time)) {
-      return trailingEdge(time);
-    }
-    timerId = setTimeout(timerExpired, remainingWait(time));
-  }
-  function trailingEdge(time) {
-    timerId = void 0;
-    if (trailing && lastArgs) {
-      return invokeFunc(time);
-    }
-    lastArgs = lastThis = void 0;
-    return result;
-  }
-  function cancel() {
-    if (timerId !== void 0) {
-      clearTimeout(timerId);
-    }
-    lastInvokeTime = 0;
-    lastArgs = lastCallTime = lastThis = timerId = void 0;
-  }
-  function flush() {
-    return timerId === void 0 ? result : trailingEdge(Date.now());
-  }
-  function pending() {
-    return timerId !== void 0;
-  }
-  function updateCb(callback) {
-    currentCallback = callback;
-  }
-  function updateParams(newWait, newOptions) {
-    waitMs = newWait;
-    if (newOptions !== void 0) {
-      currentOptions = newOptions;
-    }
-    applyOptions();
-    if (timerId !== void 0) {
-      const time = Date.now();
-      const shouldRun = shouldInvoke(time);
-      clearTimeout(timerId);
-      if (shouldRun) {
-        timerId = setTimeout(timerExpired, 0);
-      } else {
-        const delay = remainingWait(time);
-        timerId = setTimeout(timerExpired, delay > 0 ? delay : 0);
-      }
-    }
-  }
-  function debounced() {
-    const time = Date.now();
-    const isInvoking = shouldInvoke(time);
-    lastArgs = arguments;
-    lastThis = this;
-    lastCallTime = time;
-    if (isInvoking) {
-      if (timerId === void 0) {
-        return leadingEdge(lastCallTime);
-      }
-      if (maxing) {
-        clearTimeout(timerId);
-        timerId = setTimeout(timerExpired, waitMs);
-        return invokeFunc(lastCallTime);
-      }
-    }
-    if (timerId === void 0) {
-      timerId = setTimeout(timerExpired, waitMs);
-    }
-    return result;
-  }
-  debounced.cancel = cancel;
-  debounced.flush = flush;
-  debounced.pending = pending;
-  debounced.updateCb = updateCb;
-  debounced.updateParams = updateParams;
-  return debounced;
-}
-
-// src/typeGuards.ts
-function isFunction(value) {
-  return typeof value === "function";
-}
-
-// src/assertions.ts
-var isFunction2 = isFunction;
-
-// 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 = isFunction2(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;
-  }
-};
-
-// src/throttle.ts
-function throttle(func, wait, options) {
-  let leading = true;
-  let trailing = true;
-  if (options) {
-    leading = "leading" in options ? !!options.leading : leading;
-    trailing = "trailing" in options ? !!options.trailing : trailing;
-  }
-  return debounce(func, wait, { leading, maxWait: wait, trailing });
-}
-function createThrottledFunctionFactory(wait, callback, options) {
-  const cache = new EnhancedMap();
-  return {
-    call: (...args) => {
-      const key = args.map(
-        (arg) => arg === void 0 ? "__UNDEFINED__" : JSON.stringify(arg)
-      ).join(",");
-      const cachedFunction = cache.getOrInsert(
-        key,
-        () => throttle(callback, wait, options)
-      );
-      return cachedFunction(...args);
-    }
-  };
-}
-// Annotate the CommonJS export names for ESM import in node:
-0 && (module.exports = {
-  createThrottledFunctionFactory,
-  throttle
-});

package/dist/throttle.d.cts

@@ -1,98 +0,0 @@
-import { DebouncedFunc } from './debounce.cjs';
-import { __LEGIT_ANY_FUNCTION__ } from './saferTyping.cjs';
-
-interface ThrottleSettings {
-    /**
-     * Specify invoking on the leading edge of the timeout.
-     *
-     * @default true
-     */
-    leading?: boolean;
-    /**
-     * Specify invoking on the trailing edge of the timeout.
-     *
-     * @default true
-     */
-    trailing?: boolean;
-}
-/**
- * Creates a throttled function that only invokes the provided function at most
- * once per every `wait` milliseconds. The throttled function comes with a
- * `cancel` method to cancel delayed invocations and a `flush` method to
- * immediately invoke them.
- *
- * Throttling is useful for rate-limiting events that fire frequently, like
- * scroll or resize handlers. Unlike debouncing, throttling guarantees the
- * function is called at regular intervals.
- *
- * @example
- *   ```ts
- *   const throttledSave = throttle(saveData, 1000);
- *
- *   // Will only call saveData at most once per second
- *   throttledSave();
- *   throttledSave();
- *   throttledSave();
- *   ```;
- *
- * @example
- *   ```ts
- *   // Only invoke on trailing edge
- *   const throttledHandler = throttle(handleScroll, 100, { leading: false });
- *   ```;
- *
- * @template T - The type of the function to throttle
- * @param func - The function to throttle
- * @param wait - The number of milliseconds to throttle invocations to
- * @param options - The options object
- * @param options.leading - Specify invoking on the leading edge of the timeout
- *   (default: true)
- * @param options.trailing - Specify invoking on the trailing edge of the
- *   timeout (default: true)
- * @returns Returns the new throttled function
- */
-declare function throttle<T extends __LEGIT_ANY_FUNCTION__>(func: T, wait: number, options?: ThrottleSettings): DebouncedFunc<T>;
-/**
- * Creates a factory for throttled functions that caches throttled instances
- * based on function arguments. Each unique set of arguments gets its own
- * throttled function instance, allowing for fine-grained throttling control per
- * argument combination.
- *
- * This is useful when you want to throttle calls to the same function but with
- * different parameters independently. For example, throttling API calls per
- * user ID or throttling UI updates per component.
- *
- * @example
- *   ```ts
- *   const apiThrottle = createThrottledFunctionFactory(
- *     1000,
- *     (userId: string, action: string) => callAPI(userId, action)
- *   );
- *
- *   // Each user gets their own throttled instance
- *   apiThrottle.call('user1', 'update'); // Executes immediately
- *   apiThrottle.call('user2', 'update'); // Executes immediately (different user)
- *   apiThrottle.call('user1', 'update'); // Throttled (same user)
- *   ```;
- *
- * @example
- *   ```ts
- *   // Throttle UI updates per component
- *   const updateThrottle = createThrottledFunctionFactory(
- *     100,
- *     (componentId: string, data: any) => updateComponent(componentId, data)
- *   );
- *   ```;
- *
- * @template T - The type of arguments the callback function accepts
- * @template R - The return type of the callback function
- * @param wait - The number of milliseconds to throttle invocations to
- * @param callback - The function to throttle
- * @param options - The throttle options (leading/trailing behavior)
- * @returns An object with a `call` method that accepts the callback arguments
- */
-declare function createThrottledFunctionFactory<T extends string | number | null | undefined | boolean, R>(wait: number, callback: (...args: T[]) => R, options?: ThrottleSettings): {
-    call: (...args: T[]) => R | undefined;
-};
-
-export { createThrottledFunctionFactory, throttle };

package/dist/throttle.js

@@ -1,38 +0,0 @@
-import {
-  debounce
-} from "./chunk-CCUPDGSZ.js";
-import {
-  EnhancedMap
-} from "./chunk-7CQPOM5I.js";
-import "./chunk-C2SVCIWE.js";
-import "./chunk-JF2MDHOJ.js";
-
-// src/throttle.ts
-function throttle(func, wait, options) {
-  let leading = true;
-  let trailing = true;
-  if (options) {
-    leading = "leading" in options ? !!options.leading : leading;
-    trailing = "trailing" in options ? !!options.trailing : trailing;
-  }
-  return debounce(func, wait, { leading, maxWait: wait, trailing });
-}
-function createThrottledFunctionFactory(wait, callback, options) {
-  const cache = new EnhancedMap();
-  return {
-    call: (...args) => {
-      const key = args.map(
-        (arg) => arg === void 0 ? "__UNDEFINED__" : JSON.stringify(arg)
-      ).join(",");
-      const cachedFunction = cache.getOrInsert(
-        key,
-        () => throttle(callback, wait, options)
-      );
-      return cachedFunction(...args);
-    }
-  };
-}
-export {
-  createThrottledFunctionFactory,
-  throttle
-};

package/dist/time.cjs

@@ -1,152 +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/time.ts
-var time_exports = {};
-__export(time_exports, {
-  DAY_AS_MS: () => DAY_AS_MS,
-  DAY_AS_SECS: () => DAY_AS_SECS,
-  HOUR_AS_MS: () => HOUR_AS_MS,
-  HOUR_AS_SECS: () => HOUR_AS_SECS,
-  MINUTE_AS_MS: () => MINUTE_AS_MS,
-  MONTH_AS_MS: () => MONTH_AS_MS,
-  MONTH_AS_SECS: () => MONTH_AS_SECS,
-  WEEK_AS_MS: () => WEEK_AS_MS,
-  WEEK_AS_SECS: () => WEEK_AS_SECS,
-  YEAR_AS_MS: () => YEAR_AS_MS,
-  YEAR_AS_SECS: () => YEAR_AS_SECS,
-  dateStringOrNullToUnixMs: () => dateStringOrNullToUnixMs,
-  durationObjToMs: () => durationObjToMs,
-  getUnixSeconds: () => getUnixSeconds,
-  msToTimeString: () => msToTimeString,
-  parseTimeStringToMs: () => parseTimeStringToMs
-});
-module.exports = __toCommonJS(time_exports);
-
-// src/castValues.ts
-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;
-  }
-}
-
-// src/mathUtils.ts
-function clampMax(value, max) {
-  return value > max ? max : value;
-}
-
-// 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;
-}
-// Annotate the CommonJS export names for ESM import in node:
-0 && (module.exports = {
-  DAY_AS_MS,
-  DAY_AS_SECS,
-  HOUR_AS_MS,
-  HOUR_AS_SECS,
-  MINUTE_AS_MS,
-  MONTH_AS_MS,
-  MONTH_AS_SECS,
-  WEEK_AS_MS,
-  WEEK_AS_SECS,
-  YEAR_AS_MS,
-  YEAR_AS_SECS,
-  dateStringOrNullToUnixMs,
-  durationObjToMs,
-  getUnixSeconds,
-  msToTimeString,
-  parseTimeStringToMs
-});

package/dist/time.d.cts

@@ -1,25 +0,0 @@
-declare const MINUTE_AS_MS: number;
-declare const HOUR_AS_MS: number;
-declare const DAY_AS_MS: number;
-declare const WEEK_AS_MS: number;
-declare const MONTH_AS_MS: number;
-declare const YEAR_AS_MS: number;
-declare const HOUR_AS_SECS: number;
-declare const DAY_AS_SECS: number;
-declare const WEEK_AS_SECS: number;
-declare const MONTH_AS_SECS: number;
-declare const YEAR_AS_SECS: number;
-declare function dateStringOrNullToUnixMs(isoString: string | null | undefined): number | null;
-declare function msToTimeString(ms: number, format: 'minutes' | 'seconds' | 'milliseconds', hoursMinLength?: number): string;
-declare function parseTimeStringToMs(timeString: string): number;
-declare function getUnixSeconds(): number;
-type DurationObj = {
-    ms?: number;
-    seconds?: number;
-    minutes?: number;
-    hours?: number;
-    days?: number;
-};
-declare function durationObjToMs(durationObj: DurationObj): number;
-
-export { DAY_AS_MS, DAY_AS_SECS, type DurationObj, HOUR_AS_MS, HOUR_AS_SECS, MINUTE_AS_MS, MONTH_AS_MS, MONTH_AS_SECS, WEEK_AS_MS, WEEK_AS_SECS, YEAR_AS_MS, YEAR_AS_SECS, dateStringOrNullToUnixMs, durationObjToMs, getUnixSeconds, msToTimeString, parseTimeStringToMs };

package/dist/time.js

@@ -1,38 +0,0 @@
-import {
-  DAY_AS_MS,
-  DAY_AS_SECS,
-  HOUR_AS_MS,
-  HOUR_AS_SECS,
-  MINUTE_AS_MS,
-  MONTH_AS_MS,
-  MONTH_AS_SECS,
-  WEEK_AS_MS,
-  WEEK_AS_SECS,
-  YEAR_AS_MS,
-  YEAR_AS_SECS,
-  dateStringOrNullToUnixMs,
-  durationObjToMs,
-  getUnixSeconds,
-  msToTimeString,
-  parseTimeStringToMs
-} from "./chunk-6FBIEPWU.js";
-import "./chunk-DBOWTYR4.js";
-import "./chunk-II4R3VVX.js";
-export {
-  DAY_AS_MS,
-  DAY_AS_SECS,
-  HOUR_AS_MS,
-  HOUR_AS_SECS,
-  MINUTE_AS_MS,
-  MONTH_AS_MS,
-  MONTH_AS_SECS,
-  WEEK_AS_MS,
-  WEEK_AS_SECS,
-  YEAR_AS_MS,
-  YEAR_AS_SECS,
-  dateStringOrNullToUnixMs,
-  durationObjToMs,
-  getUnixSeconds,
-  msToTimeString,
-  parseTimeStringToMs
-};