feat(core utils): debouncer - Add postpone option for callback to be run after all debounce calls or in between.

If "postpone" is set to "true" (the default and previous behavior) the
callback will only be called after no more debouncer calls are done for
the given timeout.
If "postpone" is set to "false" the callback will be run after the
timeout has passed and calls to "debouncer" in between are ignored.

Author: thet

src/core/utils.js

@@ -516,7 +516,20 @@ const timeout = (ms) => {
     return new Promise((resolve) => setTimeout(resolve, ms));
 };
 
-const debounce = (func, ms, timer = { timer: null }) => {
+/**
+ * Returns a function, that, as long as it continues to be invoked, will not
+ * be triggered. The function will be called after it stops being called for
+ * N milliseconds.
+ * From: https://underscorejs.org/#debounce
+ *
+ * @param {Function} func - The function to debounce.
+ * @param {Number} ms - The time in milliseconds to debounce.
+ * @param {Object} timer - A module-global timer as an object.
+ * @param {Boolean} postpone - If true, the function will be called after it stops being called for N milliseconds.
+ *
+ * @returns {Function} - The debounced function.
+ */
+const debounce = (func, ms, timer = { timer: null }, postpone = true) => {
     // Returns a function, that, as long as it continues to be invoked, will not
     // be triggered. The function will be called after it stops being called for
     // N milliseconds.
@@ -528,11 +541,17 @@ const debounce = (func, ms, timer = { timer: null }) => {
     //
     // Pass a module-global timer as an object ``{ timer: null }`` if you want
     // to also cancel debounced functions from other pattern-invocations.
-    //
+    timer.last_run = 0;
     return function () {
-        clearTimeout(timer.timer);
         const args = arguments;
-        timer.timer = setTimeout(() => func.apply(this, args), ms);
+        if (!postpone && timer.timer && Date.now() - timer.last_run <= ms) {
+            return;
+        }
+        clearTimeout(timer.timer);
+        timer.last_run = Date.now();
+        timer.timer = setTimeout(() => {
+            func.apply(this, args);
+        }, ms);
     };
 };
 

src/core/utils.test.js

@@ -630,6 +630,25 @@ describe("debounce ...", function () {
         await utils.timeout(1);
         expect(test_func).toHaveBeenCalledTimes(1);
     });
+    it("ensures to be called every x ms", async () => {
+        const test_func = jest.fn();
+        const debouncer = utils.debounce(test_func, 2, { timer: null }, false);
+        debouncer();
+        await utils.timeout(1);
+        debouncer();
+        await utils.timeout(1);
+        debouncer();
+        await utils.timeout(1);
+        debouncer();
+        await utils.timeout(1);
+        debouncer();
+        await utils.timeout(1);
+        await utils.timeout(1);
+
+        // There should be 2 or 3 calls, depending on timing corner cases.
+        const calls = test_func.mock.calls.length;
+        expect(calls >= 2 && calls < 4).toBe(true);
+    });
     it("incorrect usage by multi instantiation won't cancel previous runs", async () => {
         const test_func = jest.fn();
         utils.debounce(test_func, 1)();