@ls-stack/utils 3.56.0 → 3.58.0

package/dist/debounce.d.ts

@@ -27,11 +27,20 @@ interface DebouncedFunc<T extends (...args: any[]) => void> {
      * debounced function was never invoked.
      */
     flush: () => ReturnType<T> | undefined;
+    /** Return true if the debounced function still has a scheduled run. */
+    pending: () => boolean;
+    /** Update the debounced function with a new callback. */
+    updateCb: (callback: T) => void;
+    /** Update the debounce wait and options while keeping scheduled runs. */
+    updateParams: (wait: number, options?: DebounceOptions) => void;
 }
 declare function debounce<T extends (...args: any[]) => void>(func: T, wait: number, options?: DebounceOptions): DebouncedFunc<T>;
 declare function isDebouncedFn<T extends (...args: any[]) => void>(fn: T): fn is T & {
     cancel: () => void;
     flush: () => ReturnType<T> | undefined;
+    pending: () => boolean;
+    updateCb: (callback: T) => void;
+    updateParams: (wait: number, options?: DebounceOptions) => void;
 };
 
 export { type DebounceOptions, type DebouncedFunc, debounce, isDebouncedFn };

package/dist/debounce.js

@@ -1,7 +1,7 @@
 import {
   debounce,
   isDebouncedFn
-} from "./chunk-NW5H5EW7.js";
+} from "./chunk-CCUPDGSZ.js";
 export {
   debounce,
   isDebouncedFn

package/dist/filterObjectOrArrayKeys.js

@@ -1,7 +1,7 @@
 import {
   filterObjectOrArrayKeys
-} from "./chunk-6CG6JZKB.js";
-import "./chunk-27AL66CH.js";
+} from "./chunk-LBBC55GE.js";
+import "./chunk-BT3UMATU.js";
 import "./chunk-C2SVCIWE.js";
 import "./chunk-JF2MDHOJ.js";
 export {

package/dist/interpolate.js

@@ -2,7 +2,7 @@ import {
   clampMax,
   clampMin,
   clampRange
-} from "./chunk-HTCYUMDR.js";
+} from "./chunk-DBOWTYR4.js";
 import {
   invariant
 } from "./chunk-C2SVCIWE.js";

package/dist/iteratorUtils.cjs

@@ -0,0 +1,73 @@
+"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/iteratorUtils.ts
+var iteratorUtils_exports = {};
+__export(iteratorUtils_exports, {
+  enumerate: () => enumerate,
+  range: () => range,
+  rangeArray: () => rangeArray,
+  withIsLast: () => withIsLast,
+  withPrevious: () => withPrevious
+});
+module.exports = __toCommonJS(iteratorUtils_exports);
+function* enumerate(iter, start = 0) {
+  let index = start;
+  for (const item of iter) {
+    yield [index, item];
+    index++;
+  }
+}
+function* withIsLast(array) {
+  let index = 0;
+  for (const item of array) {
+    const isLast = index === array.length - 1;
+    yield [isLast, item, index];
+    index++;
+  }
+}
+function* withPrevious(iter) {
+  let prev = void 0;
+  for (const current of iter) {
+    yield { prev, current };
+    prev = current;
+  }
+}
+function* range(start, end, step = 1) {
+  if (start > end) {
+    for (let i = start; i >= end; i -= step) {
+      yield i;
+    }
+  } else {
+    for (let i = start; i <= end; i += step) {
+      yield i;
+    }
+  }
+}
+function rangeArray(start, end, step = 1) {
+  return [...range(start, end, step)];
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  enumerate,
+  range,
+  rangeArray,
+  withIsLast,
+  withPrevious
+});

package/dist/iteratorUtils.d.cts

@@ -0,0 +1,10 @@
+declare function enumerate<T>(iter: Iterable<T>, start?: number): Generator<[number, T]>;
+declare function withIsLast<T>(array: T[]): Generator<[isLast: boolean, item: T, index: number]>;
+declare function withPrevious<T>(iter: Iterable<T>): Generator<{
+    prev: T | undefined;
+    current: T;
+}>;
+declare function range(start: number, end: number, step?: number): Generator<number>;
+declare function rangeArray(start: number, end: number, step?: number): number[];
+
+export { enumerate, range, rangeArray, withIsLast, withPrevious };

package/dist/iteratorUtils.d.ts

@@ -0,0 +1,10 @@
+declare function enumerate<T>(iter: Iterable<T>, start?: number): Generator<[number, T]>;
+declare function withIsLast<T>(array: T[]): Generator<[isLast: boolean, item: T, index: number]>;
+declare function withPrevious<T>(iter: Iterable<T>): Generator<{
+    prev: T | undefined;
+    current: T;
+}>;
+declare function range(start: number, end: number, step?: number): Generator<number>;
+declare function rangeArray(start: number, end: number, step?: number): number[];
+
+export { enumerate, range, rangeArray, withIsLast, withPrevious };

package/dist/iteratorUtils.js

@@ -0,0 +1,44 @@
+// src/iteratorUtils.ts
+function* enumerate(iter, start = 0) {
+  let index = start;
+  for (const item of iter) {
+    yield [index, item];
+    index++;
+  }
+}
+function* withIsLast(array) {
+  let index = 0;
+  for (const item of array) {
+    const isLast = index === array.length - 1;
+    yield [isLast, item, index];
+    index++;
+  }
+}
+function* withPrevious(iter) {
+  let prev = void 0;
+  for (const current of iter) {
+    yield { prev, current };
+    prev = current;
+  }
+}
+function* range(start, end, step = 1) {
+  if (start > end) {
+    for (let i = start; i >= end; i -= step) {
+      yield i;
+    }
+  } else {
+    for (let i = start; i <= end; i += step) {
+      yield i;
+    }
+  }
+}
+function rangeArray(start, end, step = 1) {
+  return [...range(start, end, step)];
+}
+export {
+  enumerate,
+  range,
+  rangeArray,
+  withIsLast,
+  withPrevious
+};

package/dist/matchPath.js

@@ -1,8 +1,8 @@
 import {
   fastCache
-} from "./chunk-AULH7VMS.js";
-import "./chunk-5MNYPLZI.js";
-import "./chunk-HTCYUMDR.js";
+} from "./chunk-DX2524CZ.js";
+import "./chunk-6FBIEPWU.js";
+import "./chunk-DBOWTYR4.js";
 import "./chunk-II4R3VVX.js";
 import "./chunk-C2SVCIWE.js";
 import "./chunk-JF2MDHOJ.js";

package/dist/mathUtils.cjs

@@ -20,11 +20,15 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/mathUtils.ts
 var mathUtils_exports = {};
 __export(mathUtils_exports, {
+  ceilToStep: () => ceilToStep,
   clamp: () => clamp,
   clampMax: () => clampMax,
   clampMin: () => clampMin,
   clampRange: () => clampRange,
-  fixFloatingPointNumber: () => fixFloatingPointNumber
+  fixFloatingPointNumber: () => fixFloatingPointNumber,
+  floorToStep: () => floorToStep,
+  round: () => round,
+  roundToStep: () => roundToStep
 });
 module.exports = __toCommonJS(mathUtils_exports);
 function clampMax(value, max) {
@@ -45,11 +49,33 @@ function clamp(num, min, max) {
 function fixFloatingPointNumber(value) {
   return Number(value.toPrecision(15));
 }
+function roundToStep(value, step, offset = 0) {
+  const inv = 1 / step;
+  const snapped = Math.round((value - offset) * inv) / inv + offset;
+  return Number(snapped.toFixed(12));
+}
+function floorToStep(value, step, offset = 0) {
+  const inv = 1 / step;
+  const snapped = Math.floor((value - offset) * inv) / inv + offset;
+  return Number(snapped.toFixed(12));
+}
+function ceilToStep(value, step, offset = 0) {
+  const inv = 1 / step;
+  const snapped = Math.ceil((value - offset) * inv) / inv + offset;
+  return Number(snapped.toFixed(12));
+}
+function round(num, precision) {
+  return Math.round(num * 10 ** precision) / 10 ** precision;
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  ceilToStep,
   clamp,
   clampMax,
   clampMin,
   clampRange,
-  fixFloatingPointNumber
+  fixFloatingPointNumber,
+  floorToStep,
+  round,
+  roundToStep
 });

package/dist/mathUtils.d.cts

@@ -3,5 +3,52 @@ declare function clampMin(value: number, min: number): number;
 declare function clampRange(num: number, v1: number, v2: number): number;
 declare function clamp(num: number, min: number, max: number): number;
 declare function fixFloatingPointNumber(value: number): number;
+/**
+ * Rounds a number to the nearest multiple of the specified step value.
+ *
+ * @param value - The number to round
+ * @param step - The step size to round to
+ * @param offset - Optional offset to shift the rounding grid
+ * @returns The rounded value
+ *
+ * @example
+ * roundToStep(23, 5) // 25 (nearest multiple of 5)
+ */
+declare function roundToStep(value: number, step: number, offset?: number): number;
+/**
+ * Floors a number down to the nearest multiple of the specified step value.
+ *
+ * @param value - The number to floor
+ * @param step - The step size to floor to
+ * @param offset - Optional offset to shift the flooring grid
+ * @returns The floored value
+ *
+ * @example
+ * floorToStep(23, 5) // 20 (largest multiple of 5 ≤ 23)
+ */
+declare function floorToStep(value: number, step: number, offset?: number): number;
+/**
+ * Ceils a number up to the nearest multiple of the specified step value.
+ *
+ * @param value - The number to ceil
+ * @param step - The step size to ceil to
+ * @param offset - Optional offset to shift the ceiling grid
+ * @returns The ceiled value
+ *
+ * @example
+ * ceilToStep(23, 5) // 25 (smallest multiple of 5 ≥ 23)
+ */
+declare function ceilToStep(value: number, step: number, offset?: number): number;
+/**
+ * Rounds a number to the specified number of decimal places.
+ *
+ * @param num - The number to round
+ * @param precision - Number of decimal places
+ * @returns The rounded number
+ *
+ * @example
+ * round(3.14159, 2) // 3.14
+ */
+declare function round(num: number, precision: number): number;
 
-export { clamp, clampMax, clampMin, clampRange, fixFloatingPointNumber };
+export { ceilToStep, clamp, clampMax, clampMin, clampRange, fixFloatingPointNumber, floorToStep, round, roundToStep };

package/dist/mathUtils.d.ts

@@ -3,5 +3,52 @@ declare function clampMin(value: number, min: number): number;
 declare function clampRange(num: number, v1: number, v2: number): number;
 declare function clamp(num: number, min: number, max: number): number;
 declare function fixFloatingPointNumber(value: number): number;
+/**
+ * Rounds a number to the nearest multiple of the specified step value.
+ *
+ * @param value - The number to round
+ * @param step - The step size to round to
+ * @param offset - Optional offset to shift the rounding grid
+ * @returns The rounded value
+ *
+ * @example
+ * roundToStep(23, 5) // 25 (nearest multiple of 5)
+ */
+declare function roundToStep(value: number, step: number, offset?: number): number;
+/**
+ * Floors a number down to the nearest multiple of the specified step value.
+ *
+ * @param value - The number to floor
+ * @param step - The step size to floor to
+ * @param offset - Optional offset to shift the flooring grid
+ * @returns The floored value
+ *
+ * @example
+ * floorToStep(23, 5) // 20 (largest multiple of 5 ≤ 23)
+ */
+declare function floorToStep(value: number, step: number, offset?: number): number;
+/**
+ * Ceils a number up to the nearest multiple of the specified step value.
+ *
+ * @param value - The number to ceil
+ * @param step - The step size to ceil to
+ * @param offset - Optional offset to shift the ceiling grid
+ * @returns The ceiled value
+ *
+ * @example
+ * ceilToStep(23, 5) // 25 (smallest multiple of 5 ≥ 23)
+ */
+declare function ceilToStep(value: number, step: number, offset?: number): number;
+/**
+ * Rounds a number to the specified number of decimal places.
+ *
+ * @param num - The number to round
+ * @param precision - Number of decimal places
+ * @returns The rounded number
+ *
+ * @example
+ * round(3.14159, 2) // 3.14
+ */
+declare function round(num: number, precision: number): number;
 
-export { clamp, clampMax, clampMin, clampRange, fixFloatingPointNumber };
+export { ceilToStep, clamp, clampMax, clampMin, clampRange, fixFloatingPointNumber, floorToStep, round, roundToStep };

package/dist/mathUtils.js

@@ -1,14 +1,22 @@
 import {
+  ceilToStep,
   clamp,
   clampMax,
   clampMin,
   clampRange,
-  fixFloatingPointNumber
-} from "./chunk-HTCYUMDR.js";
+  fixFloatingPointNumber,
+  floorToStep,
+  round,
+  roundToStep
+} from "./chunk-DBOWTYR4.js";
 export {
+  ceilToStep,
   clamp,
   clampMax,
   clampMin,
   clampRange,
-  fixFloatingPointNumber
+  fixFloatingPointNumber,
+  floorToStep,
+  round,
+  roundToStep
 };

package/dist/objUtils.js

@@ -9,9 +9,9 @@ import {
   pick,
   rejectObjUndefinedValues,
   sortObjectKeys
-} from "./chunk-Y76LZUOB.js";
+} from "./chunk-WNFRB7P6.js";
 import "./chunk-GMJTLFM6.js";
-import "./chunk-27AL66CH.js";
+import "./chunk-BT3UMATU.js";
 import "./chunk-C2SVCIWE.js";
 import "./chunk-JF2MDHOJ.js";
 export {

package/dist/serializeXML.js

@@ -1,6 +1,6 @@
 import {
   filterAndMap
-} from "./chunk-27AL66CH.js";
+} from "./chunk-BT3UMATU.js";
 import "./chunk-C2SVCIWE.js";
 import {
   isTruthy

package/dist/testUtils.js

@@ -4,11 +4,11 @@ import {
 import {
   omit,
   pick
-} from "./chunk-Y76LZUOB.js";
+} from "./chunk-WNFRB7P6.js";
 import "./chunk-GMJTLFM6.js";
 import {
   filterObjectOrArrayKeys
-} from "./chunk-6CG6JZKB.js";
+} from "./chunk-LBBC55GE.js";
 import "./chunk-IATIXMCE.js";
 import {
   deepEqual
@@ -21,12 +21,12 @@ import {
 } from "./chunk-DFXNVEH6.js";
 import {
   clampMin
-} from "./chunk-HTCYUMDR.js";
+} from "./chunk-DBOWTYR4.js";
 import "./chunk-BM4PYVOX.js";
 import {
   arrayWithPrevAndIndex,
   filterAndMap
-} from "./chunk-27AL66CH.js";
+} from "./chunk-BT3UMATU.js";
 import {
   isObject
 } from "./chunk-C2SVCIWE.js";

package/dist/throttle.cjs

@@ -27,6 +27,9 @@ 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;
@@ -37,35 +40,37 @@ function debounce(func, wait, options) {
   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 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 = func.apply(thisArg, args);
+    result = currentCallback.apply(thisArg, args);
     return result;
   }
   function leadingEdge(time) {
     lastInvokeTime = time;
-    timerId = setTimeout(timerExpired, wait);
+    timerId = setTimeout(timerExpired, waitMs);
     return leading ? invokeFunc(time) : result;
   }
   function remainingWait(time) {
     const timeSinceLastCall = time - (lastCallTime ?? 0);
     const timeSinceLastInvoke = time - lastInvokeTime;
-    const timeWaiting = wait - timeSinceLastCall;
+    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 >= wait || timeSinceLastCall < 0 || maxing && timeSinceLastInvoke >= (maxWait ?? 0);
+    return lastCallTime === void 0 || timeSinceLastCall >= waitMs || timeSinceLastCall < 0 || maxing && timeSinceLastInvoke >= (maxWait ?? 0);
   }
   function timerExpired() {
     const time = Date.now();
@@ -92,6 +97,30 @@ function debounce(func, wait, options) {
   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);
@@ -104,17 +133,20 @@ function debounce(func, wait, options) {
       }
       if (maxing) {
         clearTimeout(timerId);
-        timerId = setTimeout(timerExpired, wait);
+        timerId = setTimeout(timerExpired, waitMs);
         return invokeFunc(lastCallTime);
       }
     }
     if (timerId === void 0) {
-      timerId = setTimeout(timerExpired, wait);
+      timerId = setTimeout(timerExpired, waitMs);
     }
     return result;
   }
   debounced.cancel = cancel;
   debounced.flush = flush;
+  debounced.pending = pending;
+  debounced.updateCb = updateCb;
+  debounced.updateParams = updateParams;
   return debounced;
 }
 

package/dist/throttle.js

@@ -1,6 +1,6 @@
 import {
   debounce
-} from "./chunk-NW5H5EW7.js";
+} from "./chunk-CCUPDGSZ.js";
 import {
   EnhancedMap
 } from "./chunk-7CQPOM5I.js";

package/dist/time.js

@@ -15,8 +15,8 @@ import {
   getUnixSeconds,
   msToTimeString,
   parseTimeStringToMs
-} from "./chunk-5MNYPLZI.js";
-import "./chunk-HTCYUMDR.js";
+} from "./chunk-6FBIEPWU.js";
+import "./chunk-DBOWTYR4.js";
 import "./chunk-II4R3VVX.js";
 export {
   DAY_AS_MS,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ls-stack/utils",
   "description": "Universal TypeScript utilities for browser and Node.js",
-  "version": "3.56.0",
+  "version": "3.58.0",
   "license": "MIT",
   "files": [
     "dist",
@@ -112,6 +112,10 @@
       "import": "./dist/interpolate.js",
       "require": "./dist/interpolate.cjs"
     },
+    "./iteratorUtils": {
+      "import": "./dist/iteratorUtils.js",
+      "require": "./dist/iteratorUtils.cjs"
+    },
     "./keepPrevIfUnchanged": {
       "import": "./dist/keepPrevIfUnchanged.js",
       "require": "./dist/keepPrevIfUnchanged.cjs"

package/dist/chunk-HTCYUMDR.js

@@ -1,27 +0,0 @@
-// src/mathUtils.ts
-function clampMax(value, max) {
-  return value > max ? max : value;
-}
-function clampMin(value, min) {
-  return value < min ? min : value;
-}
-function clampRange(num, v1, v2) {
-  if (v2 > v1) {
-    return clamp(num, v1, v2);
-  }
-  return clamp(num, v2, v1);
-}
-function clamp(num, min, max) {
-  return num > max ? max : num < min ? min : num;
-}
-function fixFloatingPointNumber(value) {
-  return Number(value.toPrecision(15));
-}
-
-export {
-  clampMax,
-  clampMin,
-  clampRange,
-  clamp,
-  fixFloatingPointNumber
-};