@ezez/utils 2.1.0 → 3.0.0

package/src/index.ts

@@ -38,16 +38,20 @@ export * from "./replaceDeep.js";
 export * from "./rethrow.js";
 export * from "./round.js";
 export * from "./safe.js";
+export * from "./sample.js";
+export * from "./samples.js";
 export * from "./scale.js";
 export * from "./seq.js";
 export * from "./serialize.js";
 export * from "./set.js";
 export * from "./setImmutable.js";
+export * from "./shuffle.js";
 export * from "./sortBy.js";
 export * from "./sortProps.js";
 export * from "./stripPrefix.js";
 export * from "./stripSuffix.js";
 export * from "./throttle.js";
+export * from "./toggle.js";
 export * from "./truthy.js";
 export * from "./unique.js";
 export * from "./wait.js";

package/src/replace.ts

@@ -12,7 +12,6 @@ const replace = (source: string, replaceMap: Record<string, string>) => {
     if (keys.length === 0) {
         return source;
     }
-    /* eslint-enable max-len */
     const regex = new RegExp(keys.map(escapeRegExp).join("|"), "g");
     return source.replace(regex, (matched) => replaceMap[matched]!);
 };

package/src/safe.ts

@@ -11,7 +11,6 @@ function safe<T, Y>(fn: () => T, def: Y): T | Y;
  * safe(() => trySomethingComplicated(), defaultValue); // if trySomethingComplicated throws, defaultValue will be returned
  */
 function safe<T, Y>(fn: () => T, def?: Y) { // eslint-disable-line func-style
-    /* eslint-enable max-len */
     try {
         return fn();
     }

package/src/sample.spec.ts

@@ -0,0 +1,31 @@
+// eslint-disable-next-line @typescript-eslint/no-shadow
+import must from "must";
+
+import { sample } from "./sample";
+
+describe("sample", () => {
+    it("should return any random item of an array", async () => {
+        const array = [1, 2, 3, 4, 5];
+        const pickSet = new Set<number>();
+        for (let i = 0; i < 1000; i++) {
+            const item = sample(array);
+            must(array).include(item);
+            pickSet.add(item);
+        }
+        must(pickSet.size).equal(5);
+    });
+
+    it("should work with 1 item array", async () => {
+        const array = [1];
+        for (let i = 0; i < 1000; i++) {
+            const item = sample(array);
+            must(item).equal(1);
+        }
+    });
+
+    it("should work with 0 items array", async () => {
+        const array: never[] = [];
+        const item = sample(array);
+        must(item).equal(undefined);
+    });
+});

package/src/sample.ts

@@ -0,0 +1,11 @@
+/**
+ * Picks a random element from an array.
+ * @param array - source array
+ */
+const sample = <T>(array: T[]): T => {
+    return array[Math.floor(Math.random() * array.length)]!;
+};
+
+export {
+    sample,
+};

package/src/samples.spec.ts

@@ -0,0 +1,50 @@
+// eslint-disable-next-line @typescript-eslint/no-shadow
+import must from "must";
+
+import { samples } from "./samples";
+
+describe("samples", () => {
+    it("must pick random elements", async () => {
+        const elements = [1, 2, 3];
+
+        const result = samples(elements, 2);
+        must(result).have.length(2);
+
+        for (const item of result) {
+            must(elements).include(item);
+        }
+        must([...new Set(result)]).have.length(2);
+    });
+
+    it("should be able to pick one element", async () => {
+        const elements = [1, 2, 3];
+        const result = samples(elements, 1);
+        must(result).have.length(1);
+        must(elements).include(result[0]);
+    });
+
+    it("should return empty array if no elements to pick", async () => {
+        const elements = [1, 2, 3];
+        const result = samples(elements, 0);
+        must(result).be.empty();
+    });
+
+    it("should return all elements if elements to pick is greater than array length", async () => {
+        const elements = [1, 2, 3];
+        const result = samples(elements, 5);
+        must(result).have.length(3);
+        must(result).eql(elements);
+    });
+
+    it("should return all elements if elements to pick is equal to array length", async () => {
+        const elements = [1, 2, 3];
+        const result = samples(elements, 3);
+        must(result).have.length(3);
+        must(result).eql(elements);
+    });
+
+    it("should throw if elements to pick is negative", async () => {
+        const elements = [1, 2, 3];
+        must(() => samples(elements, -1)).throw();
+    });
+});

package/src/samples.ts

@@ -0,0 +1,41 @@
+/**
+ * Picks a given number of random elements from the array. It won't pick the same element twice (unless the array has
+ * duplicates).
+ *
+ * If the number of elements to pick is greater than the array length, it will return the original array.
+ *
+ * @param array - source array
+ * @param elementsToPick - number of elements to pick
+ * @param allowShuffle - if true, it will shuffle the values if elementsToPick is greater or equal to array length instead of returning the original array
+ */
+const samples = <T>(array: T[], elementsToPick: number, allowShuffle = false): T[] => { // eslint-disable-line max-statements,max-len
+    if (elementsToPick < 0) {
+        throw new Error("elementsToPick must be a positive number");
+    }
+    if (elementsToPick === 0) {
+        return [];
+    }
+
+    if (!allowShuffle && elementsToPick >= array.length) {
+        return array;
+    }
+
+    const keys = Object.keys(array);
+    let picked = 0;
+    const result: T[] = [];
+
+    while (picked < elementsToPick) {
+        const indexOfKey = Math.floor(Math.random() * keys.length);
+        const indexOfArray = Number(keys[indexOfKey]);
+        const element = array[indexOfArray]!;
+        result.push(element);
+        keys.splice(indexOfKey, 1);
+        picked++;
+    }
+
+    return result;
+};
+
+export {
+    samples,
+};

package/src/shuffle.spec.ts

@@ -0,0 +1,39 @@
+// eslint-disable-next-line @typescript-eslint/no-shadow
+import must from "must";
+
+import { shuffle } from "./shuffle";
+
+describe("shuffle", () => {
+    it("should shuffle the array", async () => {
+        for (let i = 0; i < 100; i++) {
+            {
+                const elements = [1, 2, 3];
+
+                const result = shuffle(elements);
+                must(result).have.length(3);
+
+                for (const item of result) {
+                    must(elements).include(item);
+                }
+                must([...new Set(result)]).have.length(3);
+            }
+        }
+    });
+
+    it("should shuffle the array with duplicates", async () => {
+        for (let i = 0; i < 100; i++) {
+            {
+                const elements = [1, 2, 2, 3];
+
+                const result = shuffle(elements);
+                must(result).have.length(4);
+
+                for (const item of result) {
+                    must(elements).include(item);
+                }
+                must([...new Set(result)]).have.length(3);
+                must(result.filter(r => r === 2).length).equal(2);
+            }
+        }
+    });
+});

package/src/shuffle.ts

@@ -0,0 +1,13 @@
+import { samples } from "./samples.js";
+
+/**
+ * Shuffles an array, returning a new array.
+ * @param array source array
+ */
+const shuffle = <T>(array: T[]): T[] => {
+    return samples(array, array.length, true);
+};
+
+export {
+    shuffle,
+};

package/src/toggle.spec.ts

@@ -0,0 +1,43 @@
+import { toggle } from "./toggle.js";
+
+describe("toggle", () => {
+    it("adds the value if it doesn't exist", async () => {
+        must(toggle([1], 2)).eql([1, 2]);
+    });
+
+    it("removes the value if it exists", async () => {
+        must(toggle([1, 2], 2)).eql([1]);
+    });
+
+    it("removes only one occurrence", async () => {
+        must(toggle([1, 2, 2], 2)).eql([1, 2]);
+    });
+
+    it("modifies the original array when adding", async () => {
+        const array = [1];
+        toggle(array, 2);
+        must(array).eql([1, 2]);
+    });
+
+    it("modifies the original array when removing", async () => {
+        const array = [1, 2];
+        toggle(array, 2);
+        must(array).eql([1]);
+    });
+
+    it("returns the original array", async () => {
+        const array = [1];
+        // adding
+        must(toggle(array, 2)).equal(array);
+        // removing
+        must(toggle(array, 2)).equal(array);
+    });
+
+    it("adds NaN values correctly", async () => {
+        must(toggle([1], NaN)).eql([1, NaN]);
+    });
+
+    it("removes NaN values correctly", async () => {
+        must(toggle([1, NaN], NaN)).eql([1]);
+    });
+});

package/src/toggle.ts

@@ -0,0 +1,22 @@
+/**
+ * Toggles an item in an array. If it exists, remove it. If it doesn't exist, add it.
+ * If the array contains the given value more than once, this function will remove only one occurrence.
+ *
+ * @param array - source array
+ * @param item - item to toggle
+ */
+const toggle = <T>(array: T[], item: T): T[] => {
+    const index = array.findIndex((i) => Object.is(i, item));
+    // eslint-disable-next-line @typescript-eslint/no-magic-numbers
+    if (index === -1) {
+        array.push(item);
+    }
+    else {
+        array.splice(index, 1);
+    }
+    return array;
+};
+
+export {
+    toggle,
+};

package/src/waitFor.spec.ts

@@ -0,0 +1,141 @@
+// eslint-disable-next-line @typescript-eslint/no-shadow
+import must from "must";
+
+import createSpy from "../test/createSpy";
+
+import { waitFor } from "./waitFor";
+
+describe("waitFor", () => {
+    it("calls function multiple times until it returns truthy value", async () => {
+        let calls = 0;
+        const spy = createSpy(() => {
+            calls++;
+            return calls === 3;
+        });
+
+        const start = Date.now();
+        await waitFor(spy);
+
+        must(calls).equal(3);
+        // waited for 3 tries, should be 100ms (0 for first try) in total
+        must(Date.now() - start).be.gte(100);
+    });
+
+    it("returns value if check passes", async () => {
+        const x = await waitFor(() => 5);
+        must(x).equal(5);
+    });
+
+    it("returns value if check passes in non-first try", async () => {
+        let calls = 0;
+        const spy = createSpy(() => {
+            calls++;
+            return calls === 3;
+        });
+
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+        const res = await waitFor(spy);
+        must(res).equal(true);
+    });
+
+    it("allows to adjust interval", async () => {
+        let calls = 0;
+        const spy = createSpy(() => {
+            calls++;
+            return calls === 3;
+        });
+
+        const start = Date.now();
+        await waitFor(spy, { interval: 150 });
+
+        must(calls).equal(3);
+        must(Date.now() - start).be.gte(300);
+    });
+
+    it("time outs after given time", async () => {
+        // eslint-disable-next-line @typescript-eslint/await-thenable
+        await must(waitFor(() => null, {
+            interval: 40,
+            timeout: 300,
+        })).reject.to.instanceOf(Error);
+    });
+
+    it("time outs after given amout of retries", async () => {
+        const spy = createSpy(() => false);
+
+        // eslint-disable-next-line @typescript-eslint/await-thenable
+        await must(waitFor(spy, {
+            interval: 40,
+            maxTries: 3,
+        })).reject.to.instanceOf(Error);
+
+        must(spy.__spy.calls).have.length(3);
+    });
+
+    it("validates max tries", async () => {
+        // eslint-disable-next-line @typescript-eslint/await-thenable
+        await must(waitFor(() => null, {
+            maxTries: 0,
+        })).reject.to.instanceOf(TypeError);
+
+        // eslint-disable-next-line @typescript-eslint/await-thenable
+        await must(waitFor(() => null, {
+            maxTries: -666,
+        })).reject.to.instanceOf(TypeError);
+    });
+
+    it("crashes if check function crashes", async () => {
+        await waitFor(() => {
+            throw new Error(5);
+        }, 40).then(() => {
+            throw new Error("Should not resolve");
+        }, (e) => {
+            must(e).instanceOf(Error);
+            must(e.message).equal("[waitFor] check function threw an error");
+        });
+    });
+
+    describe("treats most falsy values as succeeded check", () => {
+        it("numeric zero", async () => {
+            const result = await waitFor(() => 0);
+            must(result).equal(0);
+        });
+
+        it("empty string", async () => {
+            const result = await waitFor(() => "");
+            must(result).equal("");
+        });
+    });
+
+    describe("supports promises", () => {
+        it("truthy value", async () => {
+            const result = await waitFor(() => true);
+            must(result).be.true();
+        });
+
+        it("by retrying if Promise returns false", async () => {
+            let calls = 0;
+            const spy = createSpy(() => {
+                calls++;
+                return calls === 3;
+            });
+
+            // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+            const result = await waitFor(spy);
+            must(result).be.true();
+            must(calls).equal(3);
+        });
+
+        it("by crashing if check function returns rejected promise", async () => {
+            await waitFor(() => {
+                return Promise.reject(new Error("oops"));
+            }, 40).then(() => {
+                throw new Error("Should not resolve");
+            }, (e) => {
+                must(e).instanceOf(Error);
+                must(e.message).equal("[waitFor] check function threw an error");
+            });
+        });
+    });
+});
+

package/src/waitFor.ts

@@ -1,46 +1,97 @@
+import { noop } from "./noop.js";
+
 const DEFAULT_INTERVAL = 50;
 
 type TTimeout = ReturnType<typeof setTimeout>;
-type TInterval = ReturnType<typeof setInterval>;
+type MaybePromise<T> = T | Promise<T>;
+
+type Options = {
+    /**
+     * Interval between checks in milliseconds
+     */
+    interval?: number;
+    /**
+     * Timeout in milliseconds
+     */
+    timeout?: number;
+    /**
+     * Maximum number of tries, 1 means no retry!
+     */
+    maxTries?: number;
+};
+
+const defaultOptions: Required<Options> = {
+    interval: DEFAULT_INTERVAL,
+    timeout: Infinity,
+    maxTries: Infinity,
+};
 
 /**
  * Runs the callback function every specified interval and returns a Promise that resolves when the callback returns
- * truthy value.
- * Pro-tip: Value returned from the callback is returned via resolved Promise. If you want to pass back falsy value then
- * wrap your potential return value with an object or array.
- * @param {function} fn - callback function
- * @param {number} interval - interval between checks
- * @param {number} timeout - optional timeout
+ * any other value than `null`, `undefined` or `false`.
+ * If your callback throws (or Promise rejects) it will stop the interval and reject the returned Promise.
+ * To avoid that use:
+ * ```typescript
+ * waitFor(() => promiseReturningFunction().catch(() => null));
+ * // or
+ * waitFor(() => safe(() => functionThatThrows()));
+ * ```
+ * @param fn - callback function
+ * @param options - options object
  */
-const waitFor = <T>(fn: () => T, interval = DEFAULT_INTERVAL, timeout = Infinity) => {
+const waitFor = <T>(fn: () => MaybePromise<T>, options: Options = defaultOptions) => {
     return new Promise<T>((resolve, reject) => {
-        let intervalTimer: TInterval, failTimer: TTimeout;
+        let intervalTimer: TTimeout, failTimer: TTimeout;
 
-        if (isFinite(timeout)) {
+        const opts = { ...defaultOptions, ...options };
+        if (typeof opts.maxTries === "number" && opts.maxTries < 1) {
+            reject(new TypeError("[waitFor] maxTries must be greater than 0"));
+            return;
+        }
+
+        if (Number.isFinite(opts.timeout)) {
             failTimer = setTimeout(() => {
                 reject(new Error("[waitFor] Timeout"));
-                clearInterval(intervalTimer);
-            }, timeout);
+                clearTimeout(intervalTimer);
+            }, opts.timeout);
         }
 
-        intervalTimer = setInterval(() => {
+        let tries = 0;
+
+        // eslint-disable-next-line max-statements
+        const tryFn = (async () => {
             try {
-                const result = fn();
-                if (result) {
+                tries++;
+                const result = await fn();
+                // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+                if (result != null && result !== false) {
                     clearTimeout(failTimer);
-                    clearInterval(intervalTimer);
+                    clearTimeout(intervalTimer);
                     resolve(result);
                 }
+                else {
+                    if (Number.isFinite(opts.maxTries) && tries >= opts.maxTries) {
+                        clearTimeout(failTimer);
+                        clearTimeout(intervalTimer);
+                        reject(new Error("[waitFor] Max tries reached"));
+                        return;
+                    }
+
+                    setTimeout(() => {
+                        tryFn().catch(noop);
+                    }, options.interval);
+                }
             }
             catch (error: unknown) {
                 clearTimeout(failTimer);
-                clearInterval(intervalTimer);
+                clearTimeout(intervalTimer);
 
                 const e: Error & { details?: unknown } = new Error("[waitFor] check function threw an error");
                 e.details = { error };
                 reject(e);
             }
-        }, interval);
+        });
+        tryFn().catch(noop);
     });
 };