@ls-stack/utils 3.17.1 → 3.19.0

package/lib/testUtils.js

@@ -14,11 +14,11 @@ import {
 import {
   arrayWithPrevAndIndex,
   filterAndMap
-} from "./chunk-DMW5Q4T2.js";
+} from "./chunk-SRVMMYSW.js";
 import {
   isObject
-} from "./chunk-WS4WEVHU.js";
-import "./chunk-SSKW673U.js";
+} from "./chunk-C2SVCIWE.js";
+import "./chunk-JF2MDHOJ.js";
 
 // src/testUtils.ts
 function createLoggerStore({

package/lib/throttle.cjs

@@ -0,0 +1,250 @@
+"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 lastArgs;
+  let lastThis;
+  let maxWait;
+  let result;
+  let timerId;
+  let lastCallTime;
+  let lastInvokeTime = 0;
+  let leading = false;
+  let maxing = false;
+  let trailing = true;
+  if (options) {
+    leading = !!options.leading;
+    maxing = "maxWait" in options;
+    maxWait = maxing ? Math.max(options.maxWait || 0, wait) : maxWait;
+    trailing = "trailing" in options ? !!options.trailing : trailing;
+  }
+  function invokeFunc(time) {
+    const args = lastArgs;
+    const thisArg = lastThis;
+    lastArgs = lastThis = void 0;
+    lastInvokeTime = time;
+    result = func.apply(thisArg, args);
+    return result;
+  }
+  function leadingEdge(time) {
+    lastInvokeTime = time;
+    timerId = setTimeout(timerExpired, wait);
+    return leading ? invokeFunc(time) : result;
+  }
+  function remainingWait(time) {
+    const timeSinceLastCall = time - (lastCallTime ?? 0);
+    const timeSinceLastInvoke = time - lastInvokeTime;
+    const timeWaiting = wait - 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 >= wait || 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 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, wait);
+        return invokeFunc(lastCallTime);
+      }
+    }
+    if (timerId === void 0) {
+      timerId = setTimeout(timerExpired, wait);
+    }
+    return result;
+  }
+  debounced.cancel = cancel;
+  debounced.flush = flush;
+  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/lib/throttle.d.cts

@@ -0,0 +1,89 @@
+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.
+ *
+ * @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
+ *
+ * @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 });
+ * ```
+ */
+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.
+ *
+ * @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
+ *
+ * @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)
+ * );
+ * ```
+ */
+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/lib/throttle.d.ts

@@ -0,0 +1,89 @@
+import { DebouncedFunc } from './debounce.js';
+import { __LEGIT_ANY_FUNCTION__ } from './saferTyping.js';
+
+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.
+ *
+ * @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
+ *
+ * @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 });
+ * ```
+ */
+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.
+ *
+ * @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
+ *
+ * @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)
+ * );
+ * ```
+ */
+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/lib/throttle.js

@@ -0,0 +1,38 @@
+import {
+  debounce
+} from "./chunk-NW5H5EW7.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/lib/timers.cjs

@@ -0,0 +1,93 @@
+"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/timers.ts
+var timers_exports = {};
+__export(timers_exports, {
+  createDebouncedTimeout: () => createDebouncedTimeout,
+  createInterval: () => createInterval,
+  createTimeout: () => createTimeout,
+  createWaitUntil: () => createWaitUntil
+});
+module.exports = __toCommonJS(timers_exports);
+function createTimeout(ms, callback) {
+  const timeoutId = setTimeout(callback, ms);
+  let isCleaned = false;
+  return () => {
+    if (isCleaned) return;
+    clearTimeout(timeoutId);
+    isCleaned = true;
+  };
+}
+function createInterval(ms, callback) {
+  const intervalId = setInterval(callback, ms);
+  let isCleaned = false;
+  return () => {
+    if (isCleaned) return;
+    clearInterval(intervalId);
+    isCleaned = true;
+  };
+}
+function createDebouncedTimeout(ms, callback) {
+  let cleanupTimer = null;
+  return {
+    clean: () => {
+      cleanupTimer?.();
+    },
+    call: () => {
+      cleanupTimer?.();
+      cleanupTimer = createTimeout(ms, () => {
+        callback();
+      });
+    }
+  };
+}
+function createWaitUntil({
+  condition,
+  maxWaitMs,
+  callback,
+  checkIntervalMs = 20
+}) {
+  let cleanCheckTimeout = null;
+  let cleanMaxWaitTimeout = null;
+  cleanMaxWaitTimeout = createTimeout(maxWaitMs, () => {
+    cleanCheckTimeout?.();
+  });
+  function check() {
+    const result = condition();
+    if (result) {
+      cleanMaxWaitTimeout?.();
+      callback(result);
+    } else {
+      cleanCheckTimeout = createTimeout(checkIntervalMs, check);
+    }
+  }
+  check();
+  return () => {
+    cleanMaxWaitTimeout();
+    cleanCheckTimeout?.();
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  createDebouncedTimeout,
+  createInterval,
+  createTimeout,
+  createWaitUntil
+});

package/lib/timers.d.cts

@@ -0,0 +1,110 @@
+type CleanupTimer = () => void;
+/**
+ * Creates a timeout with automatic cleanup capability.
+ *
+ * Returns a cleanup function that can be called to cancel the timeout.
+ * The cleanup function is idempotent - calling it multiple times is safe.
+ *
+ * @param ms - The timeout duration in milliseconds
+ * @param callback - The function to execute when the timeout completes
+ * @returns A cleanup function that cancels the timeout when called
+ *
+ * @example
+ * ```typescript
+ * const cleanup = createTimeout(1000, () => {
+ *   console.log('Timeout completed');
+ * });
+ *
+ * // Cancel the timeout before it completes
+ * cleanup();
+ * ```
+ */
+declare function createTimeout(ms: number, callback: () => void): CleanupTimer;
+/**
+ * Creates an interval with automatic cleanup capability.
+ *
+ * Returns a cleanup function that can be called to cancel the interval.
+ * The cleanup function is idempotent - calling it multiple times is safe.
+ *
+ * @param ms - The interval duration in milliseconds
+ * @param callback - The function to execute on each interval tick
+ * @returns A cleanup function that cancels the interval when called
+ *
+ * @example
+ * ```typescript
+ * const cleanup = createInterval(1000, () => {
+ *   console.log('Interval tick');
+ * });
+ *
+ * // Stop the interval
+ * cleanup();
+ * ```
+ */
+declare function createInterval(ms: number, callback: () => void): CleanupTimer;
+/**
+ * Creates a timeout that prevents concurrent executions.
+ *
+ * Each call to the `call` function will cancel any previous pending timeout
+ * and start a new one. This is useful for debouncing or ensuring only the
+ * last call executes after a delay.
+ *
+ * @param ms - The timeout duration in milliseconds
+ * @param callback - The function to execute when the timeout completes
+ * @returns An object with `call` to trigger the timeout and `clean` to cancel it
+ *
+ * @example
+ * ```typescript
+ * const { call, clean } = createDebouncedTimeout(1000, () => {
+ *   console.log('Only the last call executes');
+ * });
+ *
+ * call(); // This will be cancelled
+ * call(); // This will be cancelled
+ * call(); // Only this one will execute after 1000ms
+ *
+ * // Or cancel all pending timeouts
+ * clean();
+ * ```
+ */
+declare function createDebouncedTimeout(ms: number, callback: () => void): {
+    call: () => void;
+    clean: CleanupTimer;
+};
+/**
+ * Creates a timeout that waits for a condition to become true.
+ *
+ * Polls the condition function at regular intervals until it returns a truthy value,
+ * then calls the callback with that value. If the condition doesn't become true
+ * within the maximum wait time, the timeout expires without calling the callback.
+ *
+ * @template T - The type of value returned by the condition function when true
+ * @param options - Configuration options
+ * @param options.condition - Function that returns false or a truthy value when the condition is met
+ * @param options.maxWaitMs - Maximum time to wait for the condition in milliseconds
+ * @param options.callback - Function to call when the condition becomes true
+ * @param options.checkIntervalMs - How often to check the condition in milliseconds (default: 20)
+ * @returns A cleanup function that cancels the condition timeout
+ *
+ * @example
+ * ```typescript
+ * const cleanup = createWaitUntil({
+ *   condition: () => document.getElementById('myElement'),
+ *   maxWaitMs: 5000,
+ *   callback: (element) => {
+ *     console.log('Element found:', element);
+ *   },
+ *   checkIntervalMs: 50
+ * });
+ *
+ * // Cancel the condition check
+ * cleanup();
+ * ```
+ */
+declare function createWaitUntil<T extends NonNullable<unknown>>({ condition, maxWaitMs, callback, checkIntervalMs, }: {
+    condition: () => false | T;
+    maxWaitMs: number;
+    callback: (value: T) => void;
+    checkIntervalMs?: number;
+}): CleanupTimer;
+
+export { type CleanupTimer, createDebouncedTimeout, createInterval, createTimeout, createWaitUntil };