@ezez/utils 1.0.0

package/src/throttle.ts

@@ -0,0 +1,153 @@
+interface Opts {
+    /**
+     * Should function be invoked immediately on first call to throttled function
+     */
+    leading?: boolean;
+    /**
+     * Should function be called after given time
+     */
+    trailing?: boolean;
+}
+
+interface Extras {
+    /**
+     * Stops any planned calls (and resets the `time` array progress)
+     */
+    cancel: () => void;
+    /**
+     * Immediately runs planned call.
+     */
+    flush: () => void;
+}
+
+const defaultOptions: Required<Opts> = {
+    leading: true,
+    trailing: true,
+};
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type CanReturnUndefined<F extends (...args: any[]) => any> = (...args: Parameters<F>) => ReturnType<F> | undefined;
+
+/**
+ * Creates a throttled function that calls given function only once every given time. Throttled function takes the same
+ * arguments, returns "cached" value of last "real" call to the given function.
+ * Time (in ms) can be specified as an array - each "real" call to the function will then pick next value of that array
+ * as a time to wait for the next "real" call. This is useful for throttled notifications or auto-retries. Last value of
+ * the array will be used if no more values.
+ * Returned function also includes `cancel` property - call it to stop any planned calls (and reset the `time` array
+ * progress) and `flush` property - call it to immediately run planned call.
+ *
+ * You can provide options to specify if function should be invoked immediately on first call to throttled function
+ * (`leading` property) and if it should be called after given time (`trailing` property).
+ *
+ * If (this is default) both `leading` and `trailing` property are true then it's required to call throttled function at
+ * least twice.
+ * @param {function} fn - function to throttle
+ * @param {number | number[]} time - throttle time as number or array of numbers (min 1 element)
+ * @param {Opts} options
+ */
+const throttle = <RT, F extends (...args: any[]) => RT>( // eslint-disable-line max-lines-per-function, @typescript-eslint/no-explicit-any, max-len
+    fn: F, time: number | [number, ...number[]] = 0, options?: Opts,
+): CanReturnUndefined<F> & Extras => {
+    const opts: Required<Opts> = {
+        leading: options?.leading ?? defaultOptions.leading,
+        trailing: options?.trailing ?? defaultOptions.trailing,
+    };
+
+    if (!opts.trailing && !opts.leading) {
+        throw new TypeError("Throttle with trailing & leading options `false` won't do anything.");
+    }
+    if (typeof time !== "number" && !time.length) {
+        throw new TypeError("`time` must be an array with at least one number.");
+    }
+
+    const finalTime = typeof time === "number" ? time : time[time.length - 1];
+
+    let lastRun = 0,
+        timeoutId: ReturnType<typeof setTimeout> | null = null,
+        lastResult: RT | undefined,
+        lastArgs: Parameters<F>,
+        lastTime = typeof time === "number" ? time : time[0],
+        leadingCalled = false;
+
+    const times = typeof time === "number" ? [time] : [...time];
+
+    // eslint-disable-next-line max-statements
+    const throttledFn = ((...args: Parameters<F>) => {
+        lastArgs = args;
+        if (timeoutId !== null) { // if timer goes on, then we shouldn't do anything
+            return lastResult;
+        }
+
+        if (!opts.trailing) { // we don't want a timer
+            if (Date.now() - lastRun < lastTime) { // it's not yet the time to call the func
+                return lastResult;
+            }
+            lastTime = times.shift() ?? finalTime;
+            lastRun = Date.now();
+            lastResult = fn(...args);
+            return lastResult;
+        }
+
+        // we want timers here!
+        const diffLastRun = Date.now() - lastRun;
+        if (opts.leading && (!leadingCalled || typeof time === "number") && diffLastRun >= (times[0] ?? finalTime)) {
+            // we want initial run and last run was long time ago
+            lastRun = Date.now();
+            lastResult = fn(...args);
+            leadingCalled = true;
+            return lastResult;
+        }
+
+        if (lastRun || !opts.leading) {
+            lastTime = times.shift() ?? finalTime;
+        }
+        timeoutId = setTimeout(() => {
+            timeoutId = null;
+            lastRun = Date.now();
+            lastResult = fn(...args);
+        }, lastRun ? (lastTime - diffLastRun + 1) : lastTime);
+
+        return lastResult;
+    }) as (CanReturnUndefined<F> & Extras);
+
+    throttledFn.cancel = () => {
+        timeoutId !== null && clearTimeout(timeoutId);
+        timeoutId = null;
+        lastRun = 0;
+        lastResult = undefined;
+
+        // we can't replace `times` with different instance - throttledFn already has one, so we clear the array
+        // and refill it
+        times.length = 0;
+        if (typeof time === "number") {
+            times.push(time);
+        }
+        else {
+            times.push(...time);
+        }
+        lastTime = typeof time === "number" ? time : time[0];
+    };
+    throttledFn.flush = () => {
+        if (timeoutId !== null) {
+            lastRun = Date.now();
+            lastResult = fn(...lastArgs);
+            clearTimeout(timeoutId);
+            timeoutId = null;
+            return throttledFn(...lastArgs);
+        }
+        return lastResult;
+    };
+
+    return throttledFn;
+};
+
+export {
+    throttle,
+};
+
+export type {
+    Extras as ThrottledFunctionExtras,
+    Opts as ThrottleOptions,
+    CanReturnUndefined as ThrottledFunction,
+};

package/src/truthy.spec.ts

@@ -0,0 +1,21 @@
+import { truthy } from "./truthy.js";
+
+describe("truthy", function() {
+    it("returns true on truthy values", function() {
+        truthy(true).must.be.true();
+        truthy(() => {}).must.be.true();
+        truthy(1).must.be.true();
+        truthy("a").must.be.true();
+        truthy([]).must.be.true();
+        truthy({}).must.be.true();
+    });
+
+    it("returns false on falsy values", function() {
+        truthy(false).must.be.false();
+        truthy(null).must.be.false();
+        truthy(0).must.be.false();
+        truthy("").must.be.false();
+        truthy(NaN).must.be.false();
+        truthy(undefined).must.be.false();
+    });
+});

package/src/truthy.ts

@@ -0,0 +1,13 @@
+/**
+ * Returns true if value is truthy, useful with `Array.prototype.filter` and TypeScript (`[].filter(Boolean)` won't
+ * filter out falsy values from the types)
+ * @param {*} val - test value
+ * @returns {boolean} - is value truthy
+ */
+const truthy = <T>(val: T | null | undefined | "" | false | 0): val is T => {
+    return Boolean(val);
+};
+
+export {
+    truthy,
+};

package/src/wait.spec.ts

@@ -0,0 +1,21 @@
+import { wait } from "./wait.js";
+
+describe("wait", () => {
+    it("returns a promise", () => {
+        wait(0).must.be.instanceof(Promise);
+    });
+
+    it("waits given time", async () => {
+        const start1 = Date.now();
+        await wait(5);
+        const end1 = Date.now();
+        (end1 - start1).must.be.gte(5);
+
+        const start2 = Date.now();
+        await wait(100);
+        const end2 = Date.now();
+        (end2 - start2).must.be.gte(100);
+    });
+
+    // @TODO does not block test
+});

package/src/wait.ts

@@ -0,0 +1,14 @@
+/**
+ * Returns a promise that resolves after given time
+ * @param {number} timeMs - time to wait
+ * @returns {Promise<void>}
+ */
+const wait = (timeMs = 0) => {
+    return new Promise<void>((resolve) => {
+        setTimeout(() => { resolve(); }, timeMs);
+    });
+};
+
+export {
+    wait,
+};

package/src/waitFor.ts

@@ -0,0 +1,47 @@
+const DEFAULT_INTERVAL = 50;
+
+type TTimeout = ReturnType<typeof setTimeout>;
+type TInterval = ReturnType<typeof setInterval>;
+
+/**
+ * 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
+ */
+const waitFor = <T>(fn: () => T, interval = DEFAULT_INTERVAL, timeout = Infinity) => {
+    return new Promise<T>((resolve, reject) => {
+        let intervalTimer: TInterval, failTimer: TTimeout;
+
+        if (isFinite(timeout)) {
+            failTimer = setTimeout(() => {
+                reject(new Error("[waitFor] Timeout"));
+                clearInterval(intervalTimer);
+            }, timeout);
+        }
+
+        intervalTimer = setInterval(() => {
+            try {
+                const result = fn();
+                if (result) {
+                    clearTimeout(failTimer);
+                    clearInterval(intervalTimer);
+                    resolve(result);
+                }
+            }
+            catch (error: unknown) {
+                clearTimeout(failTimer);
+                clearInterval(intervalTimer);
+
+                const e: Error & { details?: unknown } = new Error("[waitFor] check function threw an error");
+                e.details = { error };
+                reject(e);
+            }
+        }, interval);
+    });
+};
+
+export { waitFor };

package/src/waitSync.spec.ts

@@ -0,0 +1,21 @@
+import { waitSync } from "./waitSync.js";
+
+describe("wait", () => {
+    it("doesn't return value", () => {
+        must(waitSync(0)).be.equal(undefined); // eslint-disable-line @typescript-eslint/no-confusing-void-expression
+    });
+
+    it("waits given time", () => {
+        const start1 = Date.now();
+        waitSync(5);
+        const end1 = Date.now();
+        (end1 - start1).must.be.gte(5);
+
+        const start2 = Date.now();
+        waitSync(100);
+        const end2 = Date.now();
+        (end2 - start2).must.be.gte(100);
+    });
+
+    // @TODO test that nothing else could happen during wait
+});

package/src/waitSync.ts

@@ -0,0 +1,14 @@
+/**
+ * Synchronously wait for a given time, blocking the event loop [!]
+ * @param {number} timeMs - time to wait
+ * @returns {Promise<void>}
+ */
+const waitSync = (timeMs = 0) => {
+    const s = Date.now();
+    // eslint-disable-next-line no-empty
+    while (Date.now() - s < timeMs) {}
+};
+
+export {
+    waitSync,
+};

package/tutorials/Introduction.md

@@ -0,0 +1 @@
+WIP.