@ezez/utils 4.8.0 → 4.8.2

package/esm/waitFor.js.map

@@ -1 +1 @@
-{"version":3,"file":"waitFor.js","sourceRoot":"","sources":["../src/waitFor.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEjC,MAAM,gBAAgB,GAAG,EAAE,CAAC;AAoB5B,MAAM,cAAc,GAAsB;IACtC,QAAQ,EAAE,gBAAgB;IAC1B,OAAO,EAAE,QAAQ;IACjB,QAAQ,EAAE,QAAQ;CACrB,CAAC;AAeF,MAAM,OAAO,GAAG,CAAI,EAAyB,EAAE,UAAmB,cAAc,EAAc,EAAE;IAC5F,OAAO,IAAI,OAAO,CAAI,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QACtC,IAAI,aAAuB,EAAE,SAAmB,CAAC;QAEjD,MAAM,IAAI,GAAG,EAAE,GAAG,cAAc,EAAE,GAAG,OAAO,EAAE,CAAC;QAC/C,IAAI,OAAO,IAAI,CAAC,QAAQ,KAAK,QAAQ,IAAI,IAAI,CAAC,QAAQ,GAAG,CAAC,EAAE,CAAC;YACzD,MAAM,CAAC,IAAI,SAAS,CAAC,2CAA2C,CAAC,CAAC,CAAC;YACnE,OAAO;QACX,CAAC;QAED,IAAI,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC;YAChC,SAAS,GAAG,UAAU,CAAC,GAAG,EAAE;gBACxB,MAAM,CAAC,IAAI,KAAK,CAAC,mBAAmB,CAAC,CAAC,CAAC;gBACvC,YAAY,CAAC,aAAa,CAAC,CAAC;YAChC,CAAC,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC;QACrB,CAAC;QAED,IAAI,KAAK,GAAG,CAAC,CAAC;QAGd,MAAM,KAAK,GAAG,CAAC,KAAK,IAAI,EAAE;YACtB,IAAI,CAAC;gBACD,KAAK,EAAE,CAAC;gBACR,MAAM,MAAM,GAAG,MAAM,EAAE,EAAE,CAAC;gBAE1B,IAAI,MAAM,IAAI,IAAI,IAAI,MAAM,KAAK,KAAK,EAAE,CAAC;oBACrC,YAAY,CAAC,SAAS,CAAC,CAAC;oBACxB,YAAY,CAAC,aAAa,CAAC,CAAC;oBAC5B,OAAO,CAAC,MAAM,CAAC,CAAC;gBACpB,CAAC;qBACI,CAAC;oBACF,IAAI,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,KAAK,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;wBAC3D,YAAY,CAAC,SAAS,CAAC,CAAC;wBACxB,YAAY,CAAC,aAAa,CAAC,CAAC;wBAC5B,MAAM,CAAC,IAAI,KAAK,CAAC,6BAA6B,CAAC,CAAC,CAAC;wBACjD,OAAO;oBACX,CAAC;oBAED,aAAa,GAAG,UAAU,CAAC,GAAG,EAAE;wBAC5B,KAAK,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;oBACxB,CAAC,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC;gBACzB,CAAC;YACL,CAAC;YACD,OAAO,KAAc,EAAE,CAAC;gBACpB,YAAY,CAAC,SAAS,CAAC,CAAC;gBACxB,YAAY,CAAC,aAAa,CAAC,CAAC;gBAE5B,MAAM,CAAC,GAAkC,IAAI,KAAK,CAAC,yCAAyC,CAAC,CAAC;gBAC9F,CAAC,CAAC,OAAO,GAAG,EAAE,KAAK,EAAE,CAAC;gBACtB,MAAM,CAAC,CAAC,CAAC,CAAC;YACd,CAAC;QACL,CAAC,CAAC,CAAC;QACH,KAAK,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IACxB,CAAC,CAAC,CAAC;AACP,CAAC,CAAC;AAEF,OAAO,EAAE,OAAO,EAAE,CAAC"}
+{"version":3,"file":"waitFor.js","sourceRoot":"","sources":["../src/waitFor.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEjC,MAAM,gBAAgB,GAAG,EAAE,CAAC;AAoB5B,MAAM,cAAc,GAAsB;IACtC,QAAQ,EAAE,gBAAgB;IAC1B,OAAO,EAAE,QAAQ;IACjB,QAAQ,EAAE,QAAQ;CACrB,CAAC;AAMF,MAAM,gBAAgB,GAAG,CAAC,KAAY,EAAE,QAAe,EAAQ,EAAE;IAC7D,MAAM,YAAY,GAAG,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC;IAC3D,IAAI,YAAY,EAAE,CAAC;QAEf,KAAK,CAAC,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC,KAAK,KAAK,YAAY,EAAE,CAAC,CAAC,CAAC,YAAY,CAAC;IACjF,CAAC;AACL,CAAC,CAAC;AAeF,MAAM,OAAO,GAAG,CAAI,EAAyB,EAAE,UAAmB,cAAc,EAAc,EAAE;IAI5F,MAAM,QAAQ,GAAG,IAAI,KAAK,EAAE,CAAC;IAE7B,OAAO,IAAI,OAAO,CAAI,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QACtC,IAAI,aAAuB,EAAE,SAAmB,CAAC;QAEjD,MAAM,IAAI,GAAG,CAAC,KAAY,EAAQ,EAAE;YAChC,gBAAgB,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;YAClC,YAAY,CAAC,SAAS,CAAC,CAAC;YACxB,YAAY,CAAC,aAAa,CAAC,CAAC;YAC5B,MAAM,CAAC,KAAK,CAAC,CAAC;QAClB,CAAC,CAAC;QAEF,MAAM,IAAI,GAAG,EAAE,GAAG,cAAc,EAAE,GAAG,OAAO,EAAE,CAAC;QAC/C,IAAI,OAAO,IAAI,CAAC,QAAQ,KAAK,QAAQ,IAAI,IAAI,CAAC,QAAQ,GAAG,CAAC,EAAE,CAAC;YACzD,IAAI,CAAC,IAAI,SAAS,CAAC,2CAA2C,CAAC,CAAC,CAAC;YACjE,OAAO;QACX,CAAC;QAED,IAAI,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC;YAChC,SAAS,GAAG,UAAU,CAAC,GAAG,EAAE;gBACxB,IAAI,CAAC,IAAI,KAAK,CAAC,mBAAmB,CAAC,CAAC,CAAC;YACzC,CAAC,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC;QACrB,CAAC;QAED,IAAI,KAAK,GAAG,CAAC,CAAC;QACd,MAAM,KAAK,GAAG,CAAC,KAAK,IAAI,EAAE;YACtB,IAAI,CAAC;gBACD,KAAK,EAAE,CAAC;gBACR,MAAM,MAAM,GAAG,MAAM,EAAE,EAAE,CAAC;gBAE1B,IAAI,MAAM,IAAI,IAAI,IAAI,MAAM,KAAK,KAAK,EAAE,CAAC;oBACrC,YAAY,CAAC,SAAS,CAAC,CAAC;oBACxB,YAAY,CAAC,aAAa,CAAC,CAAC;oBAC5B,OAAO,CAAC,MAAM,CAAC,CAAC;gBACpB,CAAC;qBACI,CAAC;oBACF,IAAI,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,KAAK,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;wBAC3D,IAAI,CAAC,IAAI,KAAK,CAAC,6BAA6B,CAAC,CAAC,CAAC;wBAC/C,OAAO;oBACX,CAAC;oBAED,aAAa,GAAG,UAAU,CAAC,GAAG,EAAE;wBAC5B,KAAK,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;oBACxB,CAAC,EAAE,IAAI,CAAC,QAAQ,CAAC,CAAC;gBACtB,CAAC;YACL,CAAC;YACD,OAAO,KAAc,EAAE,CAAC;gBACpB,MAAM,CAAC,GAAkC,IAAI,KAAK,CAC9C,yCAAyC,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,CAC9D,CAAC;gBACF,CAAC,CAAC,OAAO,GAAG,EAAE,KAAK,EAAE,CAAC;gBACtB,IAAI,CAAC,CAAC,CAAC,CAAC;YACZ,CAAC;QACL,CAAC,CAAC,CAAC;QACH,KAAK,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IACxB,CAAC,CAAC,CAAC;AACP,CAAC,CAAC;AAEF,OAAO,EAAE,OAAO,EAAE,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ezez/utils",
-  "version": "4.8.0",
+  "version": "4.8.2",
   "repository": "https://github.com/dzek69/bottom-line.git",
   "author": "Jacek Nowacki @dzek69 <git-public@dzek.eu>",
   "license": "MIT",
@@ -16,25 +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.14.168",
-    "@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": "^29.7.0",
-    "lodash": "^4.17.21",
+    "jest": "^30.4.2",
+    "lodash": "^4.18.1",
     "must": "^0.13.4",
-    "nodemon": "^3.1.9",
-    "prettier": "^3.4.2",
+    "prettier": "^3.8.4",
     "resolve-tspaths": "^0.8.23",
-    "ts-node": "^10.9.2",
     "typedoc": "0.27.6",
-    "typescript": "^5.7.3"
+    "typescript": "^5.9.3"
   },
   "husky": {
     "hooks": {
@@ -47,7 +45,6 @@
     "fixDefaultForCommonJS": false,
     "jsx": false
   },
-  "dependencies": {},
   "scripts": {
     "test": "NODE_ENV=test jest",
     "test:lodashImports": "node test/lodash-tree.cjs",
@@ -58,8 +55,6 @@
     "typecheck": "tsc --noEmit",
     "lint": "ezlint src",
     "lint:fix": "pnpm run lint --fix",
-    "start:dev": "nodemon",
-    "start:dev:compatibility": "TS_NODE_FILES=true pnpm run start:dev",
     "updates": "pnpm dlx npm-check-updates --dep prod",
     "updates:dev": "pnpm dlx npm-check-updates --dep dev",
     "updates:all": "pnpm dlx npm-check-updates"

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/serializeToBuffer/unserializeFromBuffer.spec.ts

@@ -60,4 +60,14 @@ describe("unserialize", () => {
             0x35, 0x6a, 0x00, 0x22, 0x6e, 0x3a, 0x31, 0x22, 0x00,
         ]))).eql([1]);
     });
+
+    it("unserializes multiple various arguments", async () => {
+        must(unserialize(Buffer.from([
+            0x35, 0x66, 0x00, 0x70, 0x69, 0x6e, 0x67, 0x32, 0x00,
+            0x35, 0x6a, 0x00, 0x22, 0x6e, 0x3a, 0x35, 0x22, 0x00,
+            0x35, 0x6a, 0x00, 0x22, 0x62, 0x3a, 0x31, 0x22, 0x00,
+            0x35, 0x6a, 0x00, 0x22, 0x6e, 0x3a, 0x36, 0x22, 0x00,
+            0x35, 0x6a, 0x00, 0x22, 0x6e, 0x3a, 0x39, 0x22, 0x00,
+        ]))).eql(["ping2", 5, true, 6, 9]);
+    });
 });

package/src/serializeToBuffer/unserializeFromBuffer.ts

@@ -1,8 +1,6 @@
 import { deserialize } from "../deserialize.js";
 import { BINARY_MARK_BIN, BINARY_MARK_MAP, BINARY_MARK_STRING } from "./const.js";
 
-const MAX_DATA_PARTS = 4;
-
 const NOT_FOUND = -1;
 const LAST_CHAR = -1;
 
@@ -29,8 +27,7 @@ const unserializeFromBuffer = <RT extends any[] = unknown[]>( // eslint-disable-
     let startPoint = 0;
     const result = [];
 
-    let i = 0;
-    while (i++ < MAX_DATA_PARTS) {
+    while (startPoint < intData.length) {
         const dataSplitPoint = intData.indexOf(0, startPoint); // find null
         if (dataSplitPoint === NOT_FOUND) { // no null found = no data
             break;

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);