@ls-stack/utils 3.18.0 → 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/tsResult.js

@@ -5,8 +5,8 @@ import {
   isFunction,
   isObject,
   isPromise
-} from "./chunk-WS4WEVHU.js";
-import "./chunk-SSKW673U.js";
+} from "./chunk-C2SVCIWE.js";
+import "./chunk-JF2MDHOJ.js";
 
 // src/tsResult.ts
 function okUnwrapOr() {

package/lib/typeGuards.cjs

@@ -25,7 +25,8 @@ __export(typeGuards_exports, {
   isNonEmptyArray: () => isNonEmptyArray,
   isObject: () => isObject,
   isPlainObject: () => isPlainObject,
-  isPromise: () => isPromise
+  isPromise: () => isPromise,
+  isTruthy: () => isTruthy
 });
 module.exports = __toCommonJS(typeGuards_exports);
 function isObject(value) {
@@ -54,6 +55,9 @@ function isNonEmptyArray(value) {
 function arrayHasAtLeastXItems(array, minLength) {
   return array.length >= minLength;
 }
+function isTruthy(value) {
+  return !!value;
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   arrayHasAtLeastXItems,
@@ -61,5 +65,6 @@ function arrayHasAtLeastXItems(array, minLength) {
   isNonEmptyArray,
   isObject,
   isPlainObject,
-  isPromise
+  isPromise,
+  isTruthy
 });

package/lib/typeGuards.d.cts

@@ -105,5 +105,6 @@ declare function arrayHasAtLeastXItems<T>(array: T[], minLength: 2): array is [T
 declare function arrayHasAtLeastXItems<T>(array: T[], minLength: 3): array is [T, T, T, ...T[]];
 declare function arrayHasAtLeastXItems<T>(array: T[], minLength: 4): array is [T, T, T, T, ...T[]];
 declare function arrayHasAtLeastXItems<T>(array: T[], minLength: 5): array is [T, T, T, T, T, ...T[]];
+declare function isTruthy<T>(value: T): value is Exclude<T, null | undefined | false | 0 | '' | 0n>;
 
-export { type NonEmptyArray, arrayHasAtLeastXItems, isFunction, isNonEmptyArray, isObject, isPlainObject, isPromise };
+export { type NonEmptyArray, arrayHasAtLeastXItems, isFunction, isNonEmptyArray, isObject, isPlainObject, isPromise, isTruthy };

package/lib/typeGuards.d.ts

@@ -105,5 +105,6 @@ declare function arrayHasAtLeastXItems<T>(array: T[], minLength: 2): array is [T
 declare function arrayHasAtLeastXItems<T>(array: T[], minLength: 3): array is [T, T, T, ...T[]];
 declare function arrayHasAtLeastXItems<T>(array: T[], minLength: 4): array is [T, T, T, T, ...T[]];
 declare function arrayHasAtLeastXItems<T>(array: T[], minLength: 5): array is [T, T, T, T, T, ...T[]];
+declare function isTruthy<T>(value: T): value is Exclude<T, null | undefined | false | 0 | '' | 0n>;
 
-export { type NonEmptyArray, arrayHasAtLeastXItems, isFunction, isNonEmptyArray, isObject, isPlainObject, isPromise };
+export { type NonEmptyArray, arrayHasAtLeastXItems, isFunction, isNonEmptyArray, isObject, isPlainObject, isPromise, isTruthy };

package/lib/typeGuards.js

@@ -4,13 +4,15 @@ import {
   isNonEmptyArray,
   isObject,
   isPlainObject,
-  isPromise
-} from "./chunk-SSKW673U.js";
+  isPromise,
+  isTruthy
+} from "./chunk-JF2MDHOJ.js";
 export {
   arrayHasAtLeastXItems,
   isFunction,
   isNonEmptyArray,
   isObject,
   isPlainObject,
-  isPromise
+  isPromise,
+  isTruthy
 };

package/lib/typingFnUtils.cjs

@@ -44,7 +44,11 @@ function asType(value) {
   return value;
 }
 function narrowStringToUnion(key, union) {
-  if (key && union.includes(key)) {
+  if (!key) return void 0;
+  if (union instanceof Set) {
+    return union.has(key) ? key : void 0;
+  }
+  if (union.includes(key)) {
     return key;
   }
   return void 0;

package/lib/typingFnUtils.d.cts

@@ -10,7 +10,7 @@ declare function typedObjectKeys<T extends Record<string, unknown>>(obj: T): (ke
 /** a safe way to cast types, use to substitute the `as Type` */
 declare function asType<T = unknown>(value: T): T;
 /** narrow a string to a union of strings */
-declare function narrowStringToUnion<const T extends string>(key: string | undefined | null, union: T[]): T | undefined;
+declare function narrowStringToUnion<const T extends string>(key: string | undefined | null, union: T[] | readonly T[] | Set<T>): T | undefined;
 /**
  * Type helper to check if a type is a subtype of another type.
  *

package/lib/typingFnUtils.d.ts

@@ -10,7 +10,7 @@ declare function typedObjectKeys<T extends Record<string, unknown>>(obj: T): (ke
 /** a safe way to cast types, use to substitute the `as Type` */
 declare function asType<T = unknown>(value: T): T;
 /** narrow a string to a union of strings */
-declare function narrowStringToUnion<const T extends string>(key: string | undefined | null, union: T[]): T | undefined;
+declare function narrowStringToUnion<const T extends string>(key: string | undefined | null, union: T[] | readonly T[] | Set<T>): T | undefined;
 /**
  * Type helper to check if a type is a subtype of another type.
  *

package/lib/typingFnUtils.js

@@ -12,7 +12,11 @@ function asType(value) {
   return value;
 }
 function narrowStringToUnion(key, union) {
-  if (key && union.includes(key)) {
+  if (!key) return void 0;
+  if (union instanceof Set) {
+    return union.has(key) ? key : void 0;
+  }
+  if (union.includes(key)) {
     return key;
   }
   return void 0;

package/lib/yamlStringify.js

@@ -1,14 +1,14 @@
+import {
+  bytesToHumanReadable
+} from "./chunk-IATIXMCE.js";
 import {
   truncateString
 } from "./chunk-4REIIZQY.js";
 import {
   isObject,
   isPlainObject
-} from "./chunk-WS4WEVHU.js";
-import "./chunk-SSKW673U.js";
-import {
-  bytesToHumanReadable
-} from "./chunk-IATIXMCE.js";
+} from "./chunk-C2SVCIWE.js";
+import "./chunk-JF2MDHOJ.js";
 
 // src/yamlStringify.ts
 function yamlStringify(obj, {