@ezez/utils 4.8.1 → 4.8.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ezez/utils",
-  "version": "4.8.1",
+  "version": "4.8.2",
   "repository": "https://github.com/dzek69/bottom-line.git",
   "author": "Jacek Nowacki @dzek69 <git-public@dzek.eu>",
   "license": "MIT",
@@ -16,23 +16,23 @@
   "module": "./esm/index.js",
   "type": "module",
   "devDependencies": {
-    "@babel/core": "^7.26.0",
-    "@babel/preset-env": "^7.26.0",
-    "@babel/preset-typescript": "^7.26.0",
-    "@ezez/eslint": "^9.39.3",
+    "@babel/core": "^7.29.7",
+    "@babel/preset-env": "^7.29.7",
+    "@babel/preset-typescript": "^7.29.7",
+    "@ezez/eslint": "^9.39.4",
     "@types/jest": "^29.5.14",
-    "@types/lodash": "^4.17.20",
-    "@types/node": "^20.8.3",
+    "@types/lodash": "^4.17.24",
+    "@types/node": "^20.19.43",
     "babel-plugin-module-extension": "^0.1.3",
-    "fs-extra": "^11.3.0",
+    "fs-extra": "^11.3.5",
     "husky": "^8.0.3",
-    "jest": "^30.2.0",
-    "lodash": "^4.17.23",
+    "jest": "^30.4.2",
+    "lodash": "^4.18.1",
     "must": "^0.13.4",
-    "prettier": "^3.4.2",
+    "prettier": "^3.8.4",
     "resolve-tspaths": "^0.8.23",
     "typedoc": "0.27.6",
-    "typescript": "^5.7.3"
+    "typescript": "^5.9.3"
   },
   "husky": {
     "hooks": {
@@ -45,7 +45,6 @@
     "fixDefaultForCommonJS": false,
     "jsx": false
   },
-  "dependencies": {},
   "scripts": {
     "test": "NODE_ENV=test jest",
     "test:lodashImports": "node test/lodash-tree.cjs",

package/pnpm-workspace.yaml

@@ -0,0 +1,2 @@
+allowBuilds:
+  unrs-resolver: false

package/src/get.ts

@@ -30,7 +30,7 @@ interface Source { [key: string]: unknown }
  * // else `5` will be returned
  * @returns {*} - found value or default value
  */
-const get = (source: Source, property: string | string[], defaultValue: unknown = undefined): unknown => {
+const get = (source: Source, property: string | string[], defaultValue?: unknown): unknown => {
     const properties = typeof property === "string" ? property.split(".") : [...property];
 
     let result: unknown = source;

package/src/mostFrequent.spec.ts

@@ -16,7 +16,8 @@ describe("mostFrequent", () => {
     });
 
     it("returns undefined if array empty", () => {
-        must(mostFrequent([])).equal(undefined);
+        const result = mostFrequent<number>([]);
+        must(result).equal(undefined);
     });
 
     it("compares strictly", () => {

package/src/mostFrequent.ts

@@ -2,24 +2,20 @@
  * Finds most frequent value in array
  * @param {Array} array
  */
-const mostFrequent = <T>(array: T[]): T => {
+const mostFrequent = <T>(array: T[]): T | undefined => {
     let top = 0,
         topValue = array[0];
 
     const map = new Map<T, number>();
     array.forEach(value => {
-        if (!map.has(value)) {
-            map.set(value, 0);
-        }
-        const next = map.get(value)! + 1;
-        map.set(value, map.get(value)! + 1);
+        const next = (map.get(value) ?? 0) + 1;
+        map.set(value, next);
         if (next > top) {
             top = next;
             topValue = value;
         }
     });
 
-    // @ts-expect-error - idk if there is a good workaround for this with `noUncheckedIndexedAccess`
     return topValue;
 };
 

package/src/race.spec.ts

@@ -0,0 +1,42 @@
+import must from "must"; // eslint-disable-line @typescript-eslint/no-shadow
+
+import { race } from "./race";
+import { wait } from "./wait";
+
+describe("race", () => {
+    it("resolves with the promise value when it settles before the timeout", async () => {
+        const start = Date.now();
+        const result = await race(Promise.resolve(42), 100);
+        must(result).equal(42);
+        must(Date.now() - start).be.below(90);
+    });
+
+    it("rejects with the promise error when it rejects before the timeout", async () => {
+        const start = Date.now();
+        await race(Promise.reject(new Error("boom")), 100).then(() => {
+            throw new Error("Should not resolve");
+        }, (e: unknown) => {
+            must((e as Error).message).equal("boom");
+            must(Date.now() - start).be.below(90);
+        });
+    });
+
+    it("rejects with a timeout error when the promise is too slow", async () => {
+        const slow = wait(200).then(() => "late");
+        await race(slow, 50).then(() => {
+            throw new Error("Should not resolve");
+        }, (e: unknown) => {
+            must(e).instanceOf(Error);
+            must((e as Error).message).equal("Race: Timeout");
+        });
+    });
+
+    it("uses a custom timeout message", async () => {
+        const slow = wait(200).then(() => "late");
+        await race(slow, 50, "too slow").then(() => {
+            throw new Error("Should not resolve");
+        }, (e: unknown) => {
+            must((e as Error).message).equal("too slow");
+        });
+    });
+});

package/src/race.ts

@@ -26,5 +26,3 @@ const race = <T>(promise: Promise<T>, timeout: number, message = "Race: Timeout"
 export {
     race,
 };
-
-// TODO unit tests

package/src/retry.spec.ts

@@ -0,0 +1,87 @@
+import must from "must"; // eslint-disable-line @typescript-eslint/no-shadow
+
+import { retry } from "./retry";
+
+describe("retry", () => {
+    it("returns the result on first success without retrying", async () => {
+        let calls = 0;
+        const result = await retry(async () => {
+            calls++;
+            return "ok";
+        });
+        must(result).equal("ok");
+        must(calls).equal(1);
+    });
+
+    it("retries until the function succeeds", async () => {
+        let calls = 0;
+        const result = await retry(async () => {
+            calls++;
+            if (calls < 3) {
+                throw new Error("fail");
+            }
+            return calls;
+        });
+        must(result).equal(3);
+        must(calls).equal(3);
+    });
+
+    it("with maxRetries 0 runs once and rethrows the error", async () => {
+        let calls = 0;
+        await retry(async () => {
+            calls++;
+            throw new Error("nope");
+        }, { maxRetries: 0 }).then(() => {
+            throw new Error("Should not resolve");
+        }, (e: unknown) => {
+            must((e as Error).message).equal("nope");
+        });
+        must(calls).equal(1);
+    });
+
+    it("with maxRetries N runs N+1 times before giving up", async () => {
+        let calls = 0;
+        await retry(async () => {
+            calls++;
+            throw new Error("nope");
+        }, { maxRetries: 2 }).catch(() => { /* expected to reject */ });
+        must(calls).equal(3);
+    });
+
+    it("stops early when earlyBreak returns true", async () => {
+        let calls = 0;
+        const seenCounts: number[] = [];
+        await retry(async () => {
+            calls++;
+            throw new Error("stop");
+        }, {
+            maxRetries: 10,
+            earlyBreak: (_e, count) => {
+                seenCounts.push(count);
+                return calls === 2;
+            },
+        }).catch(() => { /* expected to reject */ });
+        must(calls).equal(2);
+        must(seenCounts).eql([0, 1]);
+    });
+
+    it("waits between retries, passing the retry count to the wait function", async () => {
+        let calls = 0;
+        const waitCounts: number[] = [];
+        const result = await retry(async () => {
+            calls++;
+            if (calls < 3) {
+                throw new Error("fail");
+            }
+            return "done";
+        }, {
+            waitBetween: (count) => {
+                waitCounts.push(count);
+                return 10;
+            },
+        });
+        must(result).equal("done");
+        must(calls).equal(3);
+        must(waitCounts).eql([1, 2]);
+    });
+});

package/src/retry.ts

@@ -49,5 +49,3 @@ const retry = async <T>(fn: () => Promise<T>, options?: Options): Promise<T> =>
 export {
     retry,
 };
-
-// TODO unit tests

package/src/samples.spec.ts

@@ -47,4 +47,13 @@ describe("samples", () => {
         const elements = [1, 2, 3];
         must(() => samples(elements, -1)).throw();
     });
+
+    it("should not pad with undefined when allowShuffle and elementsToPick exceed length", async () => {
+        const elements = [1, 2, 3];
+        // BUG: with allowShuffle the early-return is skipped and the loop runs `elementsToPick`
+        // times; once the keys are exhausted it pushes `array[NaN]` (undefined) as padding.
+        const result = samples(elements, 5, true);
+        must(result).have.length(3);
+        must(result).not.include(undefined);
+    });
 });

package/src/samples.ts

@@ -21,10 +21,13 @@ const samples = <T>(array: T[], elementsToPick: number, allowShuffle = false): T
     }
 
     const keys = Object.keys(array);
+    // when shuffling we may be asked for more than we have - never pick more than exists, or we'd
+    // run out of keys and pad the result with `undefined`
+    const toPick = Math.min(elementsToPick, keys.length);
     let picked = 0;
     const result: T[] = [];
 
-    while (picked < elementsToPick) {
+    while (picked < toPick) {
         const indexOfKey = Math.floor(Math.random() * keys.length);
         const indexOfArray = Number(keys[indexOfKey]);
         const element = array[indexOfArray]!;

package/src/scale.spec.ts

@@ -0,0 +1,18 @@
+import must from "must"; // eslint-disable-line @typescript-eslint/no-shadow
+
+import { scale } from "./scale";
+
+describe("scale", () => {
+    it("maps a value from one range to another", async () => {
+        must(scale(0, 10, 0, 100, 5)).equal(50);
+        must(scale(10, 20, 0, 200, 15)).equal(100);
+    });
+
+    it("handles inverted target ranges", async () => {
+        must(scale(0, 10, 100, 0, 5)).equal(50);
+    });
+
+    it("throws when fromMin equals fromMax", async () => {
+        must(() => scale(5, 5, 0, 100, 5)).throw(/fromMin and fromMax must not be equal/u);
+    });
+});

package/src/scale.ts

@@ -8,8 +8,12 @@
  * @param {number} toMin
  * @param {number} toMax
  * @param {number} number
+ * @throws {Error} when `fromMin` equals `fromMax` (the source range has zero width)
  */
 const scale = (fromMin: number, fromMax: number, toMin: number, toMax: number, number: number): number => {
+    if (fromMin === fromMax) {
+        throw new Error("[scale] fromMin and fromMax must not be equal");
+    }
     return toMin + ((number - fromMin) / (fromMax - fromMin) * (toMax - toMin));
 };
 

package/src/sortByMultiple.ts

@@ -23,6 +23,7 @@
  *   { height: 480, bitrate: 300 },
  *   { height: 720, bitrate: 200 },
  *   { height: 720 }, // bitrate assumed to be 150
+ *   { height: 720, bitrate: undefined }, // bitrate assumed to be 150
  *   { height: 720, bitrate: 100 },
  * ]
  * ```

package/src/throttle.spec.ts

@@ -133,4 +133,39 @@ describe("throttle", function() {
         diffs[2].must.be.gte(300);
         diffs[2].must.be.lt(350);
     });
+
+    describe("flush", function() {
+        it("runs the pending trailing call immediately and only once", async function() {
+            let calls = 0;
+            const fn = () => {
+                calls++;
+                return calls;
+            };
+
+            const throttled = throttle(fn, 100, { leading: false, trailing: true });
+            throttled(); // schedules a trailing call ~100ms from now
+            throttled.flush(); // should run that planned call right now
+
+            calls.must.equal(1);
+
+            // flush must NOT leave (or schedule) another planned call behind
+            await wait(200);
+            calls.must.equal(1);
+        });
+
+        it("is a no-op returning the last result when nothing is pending", async function() {
+            let calls = 0;
+            const fn = () => {
+                calls++;
+                return calls;
+            };
+
+            const throttled = throttle(fn, 100, { leading: true, trailing: true });
+            throttled(); // leading call runs immediately, nothing is pending afterwards
+            calls.must.equal(1);
+
+            throttled.flush();
+            calls.must.equal(1); // flush did not call fn again
+        });
+    });
 });

package/src/throttle.ts

@@ -9,15 +9,15 @@ interface Opts {
     trailing?: boolean;
 }
 
-interface Extras {
+interface Extras<R = unknown> {
     /**
      * Stops any planned calls (and resets the `time` array progress)
      */
     cancel: () => void;
     /**
-     * Immediately runs planned call.
+     * Immediately runs planned call, returning its result (or the last cached result if nothing is planned).
      */
-    flush: () => void;
+    flush: () => R | undefined;
 }
 
 const defaultOptions: Required<Opts> = {
@@ -48,7 +48,7 @@ type CanReturnUndefined<F extends (...args: any[]) => any> = (...args: Parameter
  */
 const throttle = <RT, F extends (...args: any[]) => RT>( // eslint-disable-line max-lines-per-function, @typescript-eslint/no-explicit-any
     fn: F, time: number | [number, ...number[]] = 0, options?: Opts,
-): CanReturnUndefined<F> & Extras => {
+): CanReturnUndefined<F> & Extras<RT> => {
     const opts: Required<Opts> = {
         leading: options?.leading ?? defaultOptions.leading,
         trailing: options?.trailing ?? defaultOptions.trailing,
@@ -109,7 +109,7 @@ const throttle = <RT, F extends (...args: any[]) => RT>( // eslint-disable-line
         }, lastRun ? (lastTime - diffLastRun + 1) : lastTime);
 
         return lastResult;
-    }) as (CanReturnUndefined<F> & Extras);
+    }) as (CanReturnUndefined<F> & Extras<RT>);
 
     throttledFn.cancel = () => {
         timeoutId !== null && clearTimeout(timeoutId);
@@ -130,11 +130,10 @@ const throttle = <RT, F extends (...args: any[]) => RT>( // eslint-disable-line
     };
     throttledFn.flush = () => {
         if (timeoutId !== null) {
-            lastRun = Date.now();
-            lastResult = fn(...lastArgs);
             clearTimeout(timeoutId);
             timeoutId = null;
-            return throttledFn(...lastArgs);
+            lastRun = Date.now();
+            lastResult = fn(...lastArgs);
         }
         return lastResult;
     };

package/src/trimEnd.spec.ts

@@ -19,4 +19,9 @@ describe("trimEnd", () => {
         must(trimEnd("abc", "abc")).equal("");
         must(trimEnd("a", "a")).equal("");
     });
+
+    it("should return the source unchanged when characters is empty", async () => {
+        must(trimEnd("hello", "")).equal("hello");
+        must(trimEnd("", "")).equal("");
+    });
 });

package/src/trimEnd.ts

@@ -10,6 +10,9 @@
  * trimEnd("!aaa!!", "!"); // "!aaa"
  */
 const trimEnd = (source: string, characters: string): string => {
+    if (characters === "") {
+        return source;
+    }
     let s = source;
     while (s.endsWith(characters)) {
         s = s.slice(0, -characters.length);

package/src/trimStart.spec.ts

@@ -19,4 +19,9 @@ describe("trimStart", () => {
         must(trimStart("abc", "abc")).equal("");
         must(trimStart("aaa", "a")).equal("");
     });
+
+    it("should return the source unchanged when characters is empty", async () => {
+        must(trimStart("hello", "")).equal("hello");
+        must(trimStart("", "")).equal("");
+    });
 });

package/src/trimStart.ts

@@ -10,6 +10,9 @@
  * trimStart("!!aaa!", "!"); // "aaa!"
  */
 const trimStart = (source: string, characters: string): string => {
+    if (characters === "") {
+        return source;
+    }
     let s = source;
     while (s.startsWith(characters)) {
         s = s.slice(characters.length);

package/src/waitFor.spec.ts

@@ -53,6 +53,19 @@ describe("waitFor", () => {
         must(Date.now() - start).be.gte(300);
     });
 
+    it("falls back to the default interval when other options are given without `interval`", async () => {
+        const spy = createSpy(() => false);
+
+        // only `timeout` is provided, `interval` is omitted -> should still use the 50ms default.
+        // BUG: implementation reads the raw `options.interval` (undefined) instead of the merged
+        // `opts.interval`, so setTimeout fires at 0ms and the check busy-loops.
+        waitFor(spy, { timeout: 250 }).catch(() => { /* expected to reject on timeout */ });
+        await wait(120);
+
+        // with the default 50ms interval checks land at ~0/50/100ms => ~3 calls by now
+        must(spy.__spy.calls.length).be.lte(4);
+    });
+
     it("time outs after given time", async () => {
         const spy = createSpy(() => false);
         // eslint-disable-next-line @typescript-eslint/await-thenable
@@ -100,6 +113,54 @@ describe("waitFor", () => {
         });
     });
 
+    describe("error stack traces point at the caller", () => {
+        // Helper with a recognizable name so we can assert it appears in the stack.
+        const callerOfWaitFor = <T>(...args: Parameters<typeof waitFor<T>>): Promise<T> => {
+            return waitFor<T>(...args);
+        };
+
+        it("on timeout", async () => {
+            await callerOfWaitFor(() => false, { interval: 40, timeout: 100 }).then(() => {
+                throw new Error("Should not resolve");
+            }, (e: unknown) => {
+                must((e as Error).message).equal("[waitFor] Timeout");
+                must((e as Error).stack).include("callerOfWaitFor");
+            });
+        });
+
+        it("on max tries reached", async () => {
+            await callerOfWaitFor(() => false, { interval: 40, maxTries: 2 }).then(() => {
+                throw new Error("Should not resolve");
+            }, (e: unknown) => {
+                must((e as Error).message).equal("[waitFor] Max tries reached");
+                must((e as Error).stack).include("callerOfWaitFor");
+            });
+        });
+
+        it("on invalid maxTries", async () => {
+            await callerOfWaitFor(() => null, { maxTries: 0 }).then(() => {
+                throw new Error("Should not resolve");
+            }, (e: unknown) => {
+                must(e).instanceOf(TypeError);
+                must((e as Error).stack).include("callerOfWaitFor");
+            });
+        });
+
+        it("on check function throwing, and preserves original error as cause", async () => {
+            const original = new Error("boom");
+            await callerOfWaitFor(() => {
+                throw original;
+            }, { interval: 40 }).then(() => {
+                throw new Error("Should not resolve");
+            }, (e: unknown) => {
+                must((e as Error).message).equal("[waitFor] check function threw an error");
+                must((e as Error).stack).include("callerOfWaitFor");
+                must((e as Error & { cause?: unknown }).cause).equal(original);
+                must((e as Error & { details?: { error?: unknown } }).details!.error).equal(original);
+            });
+        });
+    });
+
     describe("treats most falsy values as succeeded check", () => {
         it("numeric zero", async () => {
             const result = await waitFor(() => 0);

package/src/waitFor.ts

@@ -26,6 +26,18 @@ const defaultOptions: Required<Options> = {
     maxTries: Infinity,
 };
 
+/**
+ * Appends the synchronously-captured caller frames onto an error created later (on a timer or
+ * microtask), so its stack trace points at whoever called `waitFor` instead of just node internals.
+ */
+const graftCallerStack = (error: Error, callSite: Error): void => {
+    const callerFrames = callSite.stack?.replace(/^.*\n/u, "");
+    if (callerFrames) {
+        // eslint-disable-next-line no-param-reassign
+        error.stack = error.stack ? `${error.stack}\n${callerFrames}` : callerFrames;
+    }
+};
+
 /**
  * Runs the callback function every specified interval and returns a Promise that resolves when the callback returns
  * any other value than `null`, `undefined` or `false`.
@@ -39,26 +51,35 @@ const defaultOptions: Required<Options> = {
  * @param fn - callback function
  * @param options - options object
  */
-const waitFor = <T>(fn: () => MaybePromise<T>, options: Options = defaultOptions): Promise<T> => {
+const waitFor = <T>(fn: () => MaybePromise<T>, options: Options = defaultOptions): Promise<T> => { // eslint-disable-line max-lines-per-function
+    // Captured synchronously on the caller's stack: once execution hops onto a timer or
+    // microtask those frames are gone, so we graft them back onto any rejected error (see
+    // `graftCallerStack`) to keep production stack traces pointing at the actual caller.
+    const callSite = new Error();
+
     return new Promise<T>((resolve, reject) => {
         let intervalTimer: TTimeout, failTimer: TTimeout;
 
+        const fail = (error: Error): void => {
+            graftCallerStack(error, callSite);
+            clearTimeout(failTimer);
+            clearTimeout(intervalTimer);
+            reject(error);
+        };
+
         const opts = { ...defaultOptions, ...options };
         if (typeof opts.maxTries === "number" && opts.maxTries < 1) {
-            reject(new TypeError("[waitFor] maxTries must be greater than 0"));
+            fail(new TypeError("[waitFor] maxTries must be greater than 0"));
             return;
         }
 
         if (Number.isFinite(opts.timeout)) {
             failTimer = setTimeout(() => {
-                reject(new Error("[waitFor] Timeout"));
-                clearTimeout(intervalTimer);
+                fail(new Error("[waitFor] Timeout"));
             }, opts.timeout);
         }
 
         let tries = 0;
-
-        // eslint-disable-next-line max-statements
         const tryFn = (async () => {
             try {
                 tries++;
@@ -71,24 +92,21 @@ const waitFor = <T>(fn: () => MaybePromise<T>, options: Options = defaultOptions
                 }
                 else {
                     if (Number.isFinite(opts.maxTries) && tries >= opts.maxTries) {
-                        clearTimeout(failTimer);
-                        clearTimeout(intervalTimer);
-                        reject(new Error("[waitFor] Max tries reached"));
+                        fail(new Error("[waitFor] Max tries reached"));
                         return;
                     }
 
                     intervalTimer = setTimeout(() => {
                         tryFn().catch(noop);
-                    }, options.interval);
+                    }, opts.interval);
                 }
             }
             catch (error: unknown) {
-                clearTimeout(failTimer);
-                clearTimeout(intervalTimer);
-
-                const e: Error & { details?: unknown } = new Error("[waitFor] check function threw an error");
+                const e: Error & { details?: unknown } = new Error(
+                    "[waitFor] check function threw an error", { cause: error },
+                );
                 e.details = { error };
-                reject(e);
+                fail(e);
             }
         });
         tryFn().catch(noop);

package/src/waitSync.ts

@@ -1,7 +1,7 @@
 /**
  * Synchronously wait for a given time, blocking the event loop [!]
- * @param {number} timeMs - time to wait
- * @returns {Promise<void>}
+ * @param timeMs - time to wait
+ * @returns
  */
 const waitSync = (timeMs = 0): void => {
     const s = Date.now();