@ls-stack/utils 3.18.0 → 3.20.0

package/lib/getCompositeKey.js

@@ -1,8 +1,8 @@
 import {
   getCompositeKey
-} from "./chunk-NH2LCAQS.js";
-import "./chunk-WS4WEVHU.js";
-import "./chunk-SSKW673U.js";
+} from "./chunk-6FIBVC2P.js";
+import "./chunk-C2SVCIWE.js";
+import "./chunk-JF2MDHOJ.js";
 export {
   getCompositeKey
 };

package/lib/getValueStableKey.js

@@ -1,8 +1,8 @@
 import {
   getCompositeKey
-} from "./chunk-NH2LCAQS.js";
-import "./chunk-WS4WEVHU.js";
-import "./chunk-SSKW673U.js";
+} from "./chunk-6FIBVC2P.js";
+import "./chunk-C2SVCIWE.js";
+import "./chunk-JF2MDHOJ.js";
 
 // src/getValueStableKey.ts
 var getValueStableKey = getCompositeKey;

package/lib/interpolate.js

@@ -5,8 +5,8 @@ import {
 } from "./chunk-HTCYUMDR.js";
 import {
   invariant
-} from "./chunk-WS4WEVHU.js";
-import "./chunk-SSKW673U.js";
+} from "./chunk-C2SVCIWE.js";
+import "./chunk-JF2MDHOJ.js";
 
 // src/interpolate.ts
 function mod(n, m) {

package/lib/parallelAsyncCalls.js

@@ -4,8 +4,8 @@ import {
 import {
   invariant,
   isObject
-} from "./chunk-WS4WEVHU.js";
-import "./chunk-SSKW673U.js";
+} from "./chunk-C2SVCIWE.js";
+import "./chunk-JF2MDHOJ.js";
 
 // src/parallelAsyncCalls.ts
 import { Result, unknownToError } from "t-result";

package/lib/runShellCmd.d.cts

@@ -12,12 +12,62 @@ type RunCmdOptions = {
     throwOnError?: boolean;
     noCiColorForce?: boolean;
 };
+/**
+ * @deprecated This utility has been moved to @ls-stack/node-utils. Please update your imports:
+ * ```
+ * // Old (deprecated)
+ * import { runCmd } from '@ls-stack/utils/runShellCmd';
+ *
+ * // New (preferred)
+ * import { runCmd } from '@ls-stack/node-utils/runShellCmd';
+ * ```
+ */
 declare function runCmd(label: string | null, command: string | string[], { mock, silent, throwOnError, cwd, noCiColorForce, }?: RunCmdOptions): Promise<CmdResult>;
+/**
+ * @deprecated This utility has been moved to @ls-stack/node-utils. Please update your imports:
+ * ```
+ * // Old (deprecated)
+ * import { concurrentCmd } from '@ls-stack/utils/runShellCmd';
+ *
+ * // New (preferred)
+ * import { concurrentCmd } from '@ls-stack/node-utils/runShellCmd';
+ * ```
+ */
 declare function concurrentCmd(label: string, cmd: string | string[], onResult: (result: CmdResult) => void): Promise<() => void>;
+/**
+ * @deprecated This utility has been moved to @ls-stack/node-utils. Please update your imports:
+ * ```
+ * // Old (deprecated)
+ * import { runCmdUnwrap } from '@ls-stack/utils/runShellCmd';
+ *
+ * // New (preferred)
+ * import { runCmdUnwrap } from '@ls-stack/node-utils/runShellCmd';
+ * ```
+ */
 declare function runCmdUnwrap(label: string | null, command: string | string[], { silent, }?: {
     silent?: boolean | 'timeOnly';
 }): Promise<string>;
+/**
+ * @deprecated This utility has been moved to @ls-stack/node-utils. Please update your imports:
+ * ```
+ * // Old (deprecated)
+ * import { runCmdSilent } from '@ls-stack/utils/runShellCmd';
+ *
+ * // New (preferred)
+ * import { runCmdSilent } from '@ls-stack/node-utils/runShellCmd';
+ * ```
+ */
 declare function runCmdSilent(command: string | string[]): Promise<CmdResult>;
+/**
+ * @deprecated This utility has been moved to @ls-stack/node-utils. Please update your imports:
+ * ```
+ * // Old (deprecated)
+ * import { runCmdSilentUnwrap } from '@ls-stack/utils/runShellCmd';
+ *
+ * // New (preferred)
+ * import { runCmdSilentUnwrap } from '@ls-stack/node-utils/runShellCmd';
+ * ```
+ */
 declare function runCmdSilentUnwrap(command: string | string[]): Promise<string>;
 
 export { concurrentCmd, runCmd, runCmdSilent, runCmdSilentUnwrap, runCmdUnwrap };

package/lib/runShellCmd.d.ts

@@ -12,12 +12,62 @@ type RunCmdOptions = {
     throwOnError?: boolean;
     noCiColorForce?: boolean;
 };
+/**
+ * @deprecated This utility has been moved to @ls-stack/node-utils. Please update your imports:
+ * ```
+ * // Old (deprecated)
+ * import { runCmd } from '@ls-stack/utils/runShellCmd';
+ *
+ * // New (preferred)
+ * import { runCmd } from '@ls-stack/node-utils/runShellCmd';
+ * ```
+ */
 declare function runCmd(label: string | null, command: string | string[], { mock, silent, throwOnError, cwd, noCiColorForce, }?: RunCmdOptions): Promise<CmdResult>;
+/**
+ * @deprecated This utility has been moved to @ls-stack/node-utils. Please update your imports:
+ * ```
+ * // Old (deprecated)
+ * import { concurrentCmd } from '@ls-stack/utils/runShellCmd';
+ *
+ * // New (preferred)
+ * import { concurrentCmd } from '@ls-stack/node-utils/runShellCmd';
+ * ```
+ */
 declare function concurrentCmd(label: string, cmd: string | string[], onResult: (result: CmdResult) => void): Promise<() => void>;
+/**
+ * @deprecated This utility has been moved to @ls-stack/node-utils. Please update your imports:
+ * ```
+ * // Old (deprecated)
+ * import { runCmdUnwrap } from '@ls-stack/utils/runShellCmd';
+ *
+ * // New (preferred)
+ * import { runCmdUnwrap } from '@ls-stack/node-utils/runShellCmd';
+ * ```
+ */
 declare function runCmdUnwrap(label: string | null, command: string | string[], { silent, }?: {
     silent?: boolean | 'timeOnly';
 }): Promise<string>;
+/**
+ * @deprecated This utility has been moved to @ls-stack/node-utils. Please update your imports:
+ * ```
+ * // Old (deprecated)
+ * import { runCmdSilent } from '@ls-stack/utils/runShellCmd';
+ *
+ * // New (preferred)
+ * import { runCmdSilent } from '@ls-stack/node-utils/runShellCmd';
+ * ```
+ */
 declare function runCmdSilent(command: string | string[]): Promise<CmdResult>;
+/**
+ * @deprecated This utility has been moved to @ls-stack/node-utils. Please update your imports:
+ * ```
+ * // Old (deprecated)
+ * import { runCmdSilentUnwrap } from '@ls-stack/utils/runShellCmd';
+ *
+ * // New (preferred)
+ * import { runCmdSilentUnwrap } from '@ls-stack/node-utils/runShellCmd';
+ * ```
+ */
 declare function runCmdSilentUnwrap(command: string | string[]): Promise<string>;
 
 export { concurrentCmd, runCmd, runCmdSilent, runCmdSilentUnwrap, runCmdUnwrap };

package/lib/serializeXML.cjs

@@ -24,6 +24,11 @@ __export(serializeXML_exports, {
 });
 module.exports = __toCommonJS(serializeXML_exports);
 
+// src/typeGuards.ts
+function isTruthy(value) {
+  return !!value;
+}
+
 // src/arrayUtils.ts
 function filterAndMap(array, mapFilter) {
   const result = [];
@@ -52,12 +57,12 @@ var XML_ESCAPE_REGEX = /[&<>"']/g;
 function serializeXML(node, options) {
   if (Array.isArray(node)) {
     const EMPTY_LINE_MARKER = "\0EMPTY_LINE\0";
-    return node.map((n) => {
+    return node.filter(isTruthy).map((n) => {
       if (n.type === "emptyLine") {
         return EMPTY_LINE_MARKER;
       }
       return serializeWithLevel(n, options, 0);
-    }).filter(Boolean).join(options?.indent ? "\n" : "").replace(new RegExp(EMPTY_LINE_MARKER, "g"), "");
+    }).filter(isTruthy).join(options?.indent ? "\n" : "").replace(new RegExp(EMPTY_LINE_MARKER, "g"), "");
   }
   return serializeWithLevel(node, options, 0);
 }

package/lib/serializeXML.d.cts

@@ -17,6 +17,6 @@ type SerializeOptions = {
     validateTagName?: boolean;
     invalidNodes?: 'throw' | 'reject';
 };
-declare function serializeXML(node: XMLNode | XMLNode[], options?: SerializeOptions): string;
+declare function serializeXML(node: XMLNode | (XMLNode | null | undefined | false)[], options?: SerializeOptions): string;
 
 export { type SerializeOptions, type XMLNode, serializeXML };

package/lib/serializeXML.d.ts

@@ -17,6 +17,6 @@ type SerializeOptions = {
     validateTagName?: boolean;
     invalidNodes?: 'throw' | 'reject';
 };
-declare function serializeXML(node: XMLNode | XMLNode[], options?: SerializeOptions): string;
+declare function serializeXML(node: XMLNode | (XMLNode | null | undefined | false)[], options?: SerializeOptions): string;
 
 export { type SerializeOptions, type XMLNode, serializeXML };

package/lib/serializeXML.js

@@ -1,8 +1,10 @@
 import {
   filterAndMap
-} from "./chunk-DMW5Q4T2.js";
-import "./chunk-WS4WEVHU.js";
-import "./chunk-SSKW673U.js";
+} from "./chunk-SRVMMYSW.js";
+import "./chunk-C2SVCIWE.js";
+import {
+  isTruthy
+} from "./chunk-JF2MDHOJ.js";
 
 // src/serializeXML.ts
 var XML_TAG_NAME_REGEX = /^[a-zA-Z_][a-zA-Z0-9._-]*$/;
@@ -18,12 +20,12 @@ var XML_ESCAPE_REGEX = /[&<>"']/g;
 function serializeXML(node, options) {
   if (Array.isArray(node)) {
     const EMPTY_LINE_MARKER = "\0EMPTY_LINE\0";
-    return node.map((n) => {
+    return node.filter(isTruthy).map((n) => {
       if (n.type === "emptyLine") {
         return EMPTY_LINE_MARKER;
       }
       return serializeWithLevel(n, options, 0);
-    }).filter(Boolean).join(options?.indent ? "\n" : "").replace(new RegExp(EMPTY_LINE_MARKER, "g"), "");
+    }).filter(isTruthy).join(options?.indent ? "\n" : "").replace(new RegExp(EMPTY_LINE_MARKER, "g"), "");
   }
   return serializeWithLevel(node, options, 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 };