feat: get betterSetInterval ready for 2025 (#496)

Historically, functions scheduled with `betterSetInterval` needed to
accept a callback and then call it when done, to schedule their next
invocation. This was because Promises were not a thing in 2015 when this
function was originally written. It's silly to have this requirement
now, almost ten years later, when async/await and Promises are a normal
feature.

This change adds support for scheduling any function, sync or async,
accepting or not accepting a callback, and having it just work.

```js
betterSetInterval(async () => {
    await myAsyncOperation();
}, 1000);
```

For backwards compatibility reasons, a dummy callback is still passed to
the invoked function as its first argument, otherwise the functions that
don't expect this change would break.

Author: fnesveda

packages/utilities/src/utilities.ts

@@ -117,24 +117,27 @@ export type BetterIntervalID = { _betterClearInterval: () => void };
  * Similar to setInterval() but with two important differences:
  * First, it assumes the function is asynchronous and only schedules its next invocation AFTER the asynchronous function finished.
  * Second, it invokes the function immediately.
- * @param func Asynchronous function to be periodically executed. It must take a single argument with a callback that
- * the function must invoke after it's done.
- * @param delay The number of milliseconds to wait to next invocation of the function.
+ * @param func Function to be periodically executed.
+ * For backwards compatibility reasons, it is passed a callback as its first argument during invocation, however that callback has no effect.
+ * @param delay The number of milliseconds to wait to next invocation of the function after the current invocation finishes.
  * @returns Object that can be passed to betterClearInterval()
  */
-export function betterSetInterval(func: (a: (...args: unknown[]) => unknown) => void, delay: number): BetterIntervalID {
-    let callback: (...a: unknown[]) => unknown;
-    let timeoutId: number;
+export function betterSetInterval(func: ((a: (...args: unknown[]) => unknown) => void) | ((...args: unknown[]) => unknown), delay: number): BetterIntervalID {
+    let scheduleNextRun: () => void;
+    let timeoutId: NodeJS.Timeout;
     let isRunning = true;
+
     const funcWrapper = function () {
-        func(callback);
+        // Historically, the function was passed a callback that it needed to call to signal it was done.
+        // We keep passing this callback for backwards compatibility, but it has no effect anymore.
+        void new Promise((resolve) => resolve(func(() => undefined))).finally(scheduleNextRun);
     };
-    callback = function () {
-        if (isRunning) timeoutId = setTimeout(funcWrapper, delay) as unknown as number;
+    scheduleNextRun = function () {
+        if (isRunning) timeoutId = setTimeout(funcWrapper, delay);
     };
     funcWrapper();
-    return {
 
+    return {
         _betterClearInterval() {
             isRunning = false;
             clearTimeout(timeoutId);

test/utilities.test.ts

@@ -342,3 +342,62 @@ describe('timeoutPromise()', () => {
         });
     });
 });
+
+describe('BetterSetInterval', () => {
+    it('works with normal function', async () => {
+        const fn = jest.fn();
+
+        const interval = utils.betterSetInterval(fn, 200);
+
+        // 3 x 200ms + some leeway
+        await utils.delayPromise(700);
+        utils.betterClearInterval(interval);
+
+        // 1st call is immediate, 3 more after 1, 2 and 3 intervals
+        expect(fn).toHaveBeenCalledTimes(4);
+
+        // No more calls after clearing the interval
+        await utils.delayPromise(500);
+        expect(fn).toHaveBeenCalledTimes(4);
+    });
+
+    it('works with async function', async () => {
+        const fn = jest.fn();
+
+        const interval = utils.betterSetInterval(async () => {
+            fn();
+            await utils.delayPromise(100);
+        }, 200);
+
+        // 3 x (200 + 100)ms + some leeway
+        await utils.delayPromise(1000);
+        utils.betterClearInterval(interval);
+
+        // 1st call is immediate, 3 more after 1, 2 and 3 intervals
+        expect(fn).toHaveBeenCalledTimes(4);
+
+        // No more calls after clearing the interval
+        await utils.delayPromise(500);
+        expect(fn).toHaveBeenCalledTimes(4);
+    });
+
+    it('works with function that accepts a callback (legacy)', async () => {
+        const fn = jest.fn();
+
+        const interval = utils.betterSetInterval((cb: () => void) => {
+            fn();
+            cb();
+        }, 200);
+
+        // 3 x 200ms + some leeway
+        await utils.delayPromise(700);
+        utils.betterClearInterval(interval);
+
+        // 1st call is immediate, 3 more after 1, 2 and 3 intervals
+        expect(fn).toHaveBeenCalledTimes(4);
+
+        // No more calls after clearing the interval
+        await utils.delayPromise(500);
+        expect(fn).toHaveBeenCalledTimes(4);
+    });
+});