@sv443-network/userutils 6.0.1 → 6.2.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @sv443-network/userutils
 
+## 6.2.0
+
+### Minor Changes
+
+- 0173235: Add property to change the debounce edge in `SelectorObserver` instances
+
+## 6.1.0
+
+### Minor Changes
+
+- a11ed77: Added parameter to switch `debounce()` to trigger on the rising edge, instead of just the falling edge [(see docs)](https://github.com/Sv443-Network/UserUtils#debounce)
+
 ## 6.0.1
 
 ### Patch Changes

package/README.md

@@ -47,7 +47,7 @@ View the documentation of previous major releases:
     - [DataStore](#datastore) - class that manages a sync & async persistent JSON database, including data migration
     - [autoPlural()](#autoplural) - automatically pluralize a string
     - [pauseFor()](#pausefor) - pause the execution of a function for a given amount of time
-    - [debounce()](#debounce) - call a function only once, after a given amount of time
+    - [debounce()](#debounce) - call a function only once in a series of calls, after or before a given timeout
     - [fetchAdvanced()](#fetchadvanced) - wrapper around the fetch API with a timeout option
     - [insertValues()](#insertvalues) - insert values into a string at specified placeholders
     - [compress()](#compress) - compress a string with Gzip or Deflate
@@ -1180,22 +1180,43 @@ async function run() {
 ### debounce()
 Usage:  
 ```ts
-debounce(func: Function, timeout?: number): Function
+debounce(func: Function, timeout?: number, edge?: "falling" | "rising"): Function
 ```
   
-Debounces a function, meaning that it will only be called once after a given amount of time.  
-This is very useful for functions that are called repeatedly, like event listeners, to remove extraneous calls.  
-All passed properties will be passed down to the debounced function.  
-The timeout will default to 300ms if left undefined.  
+Returns a debounced wrapper function, meaning that the given `func` will only be called once after or before a given amount of time.  
+This is very useful for functions that are called repeatedly, like event listeners, to remove a substantial amount of unnecessary calls.  
+All parameters passed to the returned function will be passed along to the input `func`  
+  
+The `timeout` will default to 300ms if left undefined.  
+  
+The `edge` ("falling" by default) determines if the function should be called after the timeout has passed or before it.  
+In simpler terms, this results in "falling" edge functions being called once at the very end of a sequence of calls, and "rising" edge functions being called once at the beginning and possibly multiple times following that, but at the very least they're spaced apart by what's passed in `timeout`.  
+  
+This diagram can hopefully help bring the difference across:  
+<details><summary><b>Click to view the diagram</b></summary>
+
+![debounce function edge diagram](./.github/assets/debounce.png)
+
+</details>
+
+<br>
   
 <details><summary><b>Example - click to view</b></summary>
 
 ```ts
 import { debounce } from "@sv443-network/userutils";
 
+// uses "falling" edge by default:
 window.addEventListener("resize", debounce((event) => {
   console.log("Window was resized:", event);
 }, 500)); // 500ms timeout
+
+// using "rising" edge:
+const myFunc = debounce((event) => {
+  console.log("Body was scrolled:", event);
+}, 100, "rising"); // 100ms timeout
+
+document.body.addEventListener("scroll", myFunc);
 ```
 
 </details>

package/dist/index.global.js

@@ -8,7 +8,7 @@
 // ==UserLibrary==
 // @name         UserUtils
 // @description  Library with various utilities for userscripts - register listeners for when CSS selectors exist, intercept events, manage persistent user configurations, modify the DOM more easily and more
-// @version      6.0.1
+// @version      6.2.0
 // @license      MIT
 // @copyright    Sv443 (https://github.com/Sv443)
 
@@ -432,11 +432,18 @@ var UserUtils = (function (exports) {
       setTimeout(() => res(), time);
     });
   }
-  function debounce(func, timeout = 300) {
+  function debounce(func, timeout = 300, edge = "falling") {
     let timer;
     return function(...args) {
-      clearTimeout(timer);
-      timer = setTimeout(() => func.apply(this, args), timeout);
+      if (edge === "rising") {
+        if (!timer) {
+          func.apply(this, args);
+          timer = setTimeout(() => timer = void 0, timeout);
+        }
+      } else {
+        clearTimeout(timer);
+        timer = setTimeout(() => func.apply(this, args), timeout);
+      }
     };
   }
   function fetchAdvanced(_0) {
@@ -505,10 +512,12 @@ var UserUtils = (function (exports) {
       this.observer = new MutationObserver(() => this.checkAllSelectors());
       const _a = options, {
         defaultDebounce,
+        defaultDebounceEdge,
         disableOnNoListeners,
         enableOnAddListener
       } = _a, observerOptions = __objRest(_a, [
         "defaultDebounce",
+        "defaultDebounceEdge",
         "disableOnNoListeners",
         "enableOnAddListener"
       ]);
@@ -518,6 +527,7 @@ var UserUtils = (function (exports) {
       }, observerOptions);
       this.customOptions = {
         defaultDebounce: defaultDebounce != null ? defaultDebounce : 0,
+        defaultDebounceEdge: defaultDebounceEdge != null ? defaultDebounceEdge : "rising",
         disableOnNoListeners: disableOnNoListeners != null ? disableOnNoListeners : false,
         enableOnAddListener: enableOnAddListener != null ? enableOnAddListener : true
       };
@@ -557,12 +567,8 @@ var UserUtils = (function (exports) {
           this.disable();
       }
     }
-    debounce(func, time) {
-      let timeout;
-      return function(...args) {
-        clearTimeout(timeout);
-        timeout = setTimeout(() => func.apply(this, args), time);
-      };
+    debounce(func, time, edge = "falling") {
+      return debounce(func, time, edge);
     }
     /**
      * Starts observing the children of the base element for changes to the given {@linkcode selector} according to the set {@linkcode options}
@@ -578,7 +584,8 @@ var UserUtils = (function (exports) {
       if (options.debounce && options.debounce > 0 || this.customOptions.defaultDebounce && this.customOptions.defaultDebounce > 0) {
         options.listener = this.debounce(
           options.listener,
-          options.debounce || this.customOptions.defaultDebounce
+          options.debounce || this.customOptions.defaultDebounce,
+          options.debounceEdge || this.customOptions.defaultDebounceEdge
         );
       }
       if (this.listenerMap.has(selector))

package/dist/index.js

@@ -412,11 +412,18 @@ function pauseFor(time) {
     setTimeout(() => res(), time);
   });
 }
-function debounce(func, timeout = 300) {
+function debounce(func, timeout = 300, edge = "falling") {
   let timer;
   return function(...args) {
-    clearTimeout(timer);
-    timer = setTimeout(() => func.apply(this, args), timeout);
+    if (edge === "rising") {
+      if (!timer) {
+        func.apply(this, args);
+        timer = setTimeout(() => timer = void 0, timeout);
+      }
+    } else {
+      clearTimeout(timer);
+      timer = setTimeout(() => func.apply(this, args), timeout);
+    }
   };
 }
 function fetchAdvanced(_0) {
@@ -485,10 +492,12 @@ var SelectorObserver = class {
     this.observer = new MutationObserver(() => this.checkAllSelectors());
     const _a = options, {
       defaultDebounce,
+      defaultDebounceEdge,
       disableOnNoListeners,
       enableOnAddListener
     } = _a, observerOptions = __objRest(_a, [
       "defaultDebounce",
+      "defaultDebounceEdge",
       "disableOnNoListeners",
       "enableOnAddListener"
     ]);
@@ -498,6 +507,7 @@ var SelectorObserver = class {
     }, observerOptions);
     this.customOptions = {
       defaultDebounce: defaultDebounce != null ? defaultDebounce : 0,
+      defaultDebounceEdge: defaultDebounceEdge != null ? defaultDebounceEdge : "rising",
       disableOnNoListeners: disableOnNoListeners != null ? disableOnNoListeners : false,
       enableOnAddListener: enableOnAddListener != null ? enableOnAddListener : true
     };
@@ -537,12 +547,8 @@ var SelectorObserver = class {
         this.disable();
     }
   }
-  debounce(func, time) {
-    let timeout;
-    return function(...args) {
-      clearTimeout(timeout);
-      timeout = setTimeout(() => func.apply(this, args), time);
-    };
+  debounce(func, time, edge = "falling") {
+    return debounce(func, time, edge);
   }
   /**
    * Starts observing the children of the base element for changes to the given {@linkcode selector} according to the set {@linkcode options}
@@ -558,7 +564,8 @@ var SelectorObserver = class {
     if (options.debounce && options.debounce > 0 || this.customOptions.defaultDebounce && this.customOptions.defaultDebounce > 0) {
       options.listener = this.debounce(
         options.listener,
-        options.debounce || this.customOptions.defaultDebounce
+        options.debounce || this.customOptions.defaultDebounce,
+        options.debounceEdge || this.customOptions.defaultDebounceEdge
       );
     }
     if (this.listenerMap.has(selector))

package/dist/index.mjs

@@ -410,11 +410,18 @@ function pauseFor(time) {
     setTimeout(() => res(), time);
   });
 }
-function debounce(func, timeout = 300) {
+function debounce(func, timeout = 300, edge = "falling") {
   let timer;
   return function(...args) {
-    clearTimeout(timer);
-    timer = setTimeout(() => func.apply(this, args), timeout);
+    if (edge === "rising") {
+      if (!timer) {
+        func.apply(this, args);
+        timer = setTimeout(() => timer = void 0, timeout);
+      }
+    } else {
+      clearTimeout(timer);
+      timer = setTimeout(() => func.apply(this, args), timeout);
+    }
   };
 }
 function fetchAdvanced(_0) {
@@ -483,10 +490,12 @@ var SelectorObserver = class {
     this.observer = new MutationObserver(() => this.checkAllSelectors());
     const _a = options, {
       defaultDebounce,
+      defaultDebounceEdge,
       disableOnNoListeners,
       enableOnAddListener
     } = _a, observerOptions = __objRest(_a, [
       "defaultDebounce",
+      "defaultDebounceEdge",
       "disableOnNoListeners",
       "enableOnAddListener"
     ]);
@@ -496,6 +505,7 @@ var SelectorObserver = class {
     }, observerOptions);
     this.customOptions = {
       defaultDebounce: defaultDebounce != null ? defaultDebounce : 0,
+      defaultDebounceEdge: defaultDebounceEdge != null ? defaultDebounceEdge : "rising",
       disableOnNoListeners: disableOnNoListeners != null ? disableOnNoListeners : false,
       enableOnAddListener: enableOnAddListener != null ? enableOnAddListener : true
     };
@@ -535,12 +545,8 @@ var SelectorObserver = class {
         this.disable();
     }
   }
-  debounce(func, time) {
-    let timeout;
-    return function(...args) {
-      clearTimeout(timeout);
-      timeout = setTimeout(() => func.apply(this, args), time);
-    };
+  debounce(func, time, edge = "falling") {
+    return debounce(func, time, edge);
   }
   /**
    * Starts observing the children of the base element for changes to the given {@linkcode selector} according to the set {@linkcode options}
@@ -556,7 +562,8 @@ var SelectorObserver = class {
     if (options.debounce && options.debounce > 0 || this.customOptions.defaultDebounce && this.customOptions.defaultDebounce > 0) {
       options.listener = this.debounce(
         options.listener,
-        options.debounce || this.customOptions.defaultDebounce
+        options.debounce || this.customOptions.defaultDebounce,
+        options.debounceEdge || this.customOptions.defaultDebounceEdge
       );
     }
     if (this.listenerMap.has(selector))

package/dist/lib/SelectorObserver.d.ts

@@ -17,10 +17,17 @@ type SelectorOptionsCommon = {
     continuous?: boolean;
     /** Whether to debounce the listener to reduce calls to `querySelector` or `querySelectorAll` - set undefined or <=0 to disable (default) */
     debounce?: number;
+    /** Whether to call the function at the very first call ("rising" edge) or the very last call ("falling" edge, default) */
+    debounceEdge?: "rising" | "falling";
 };
 export type SelectorObserverOptions = {
     /** If set, applies this debounce in milliseconds to all listeners that don't have their own debounce set */
     defaultDebounce?: number;
+    /**
+     * If set, applies this debounce edge to all listeners that don't have their own set.
+     * Edge = Whether to call the function at the very first call ("rising" edge) or the very last call ("falling" edge, default)
+     */
+    defaultDebounceEdge?: "rising" | "falling";
     /** Whether to disable the observer when no listeners are present - default is true */
     disableOnNoListeners?: boolean;
     /** Whether to ensure the observer is enabled when a new listener is added - default is true */

package/dist/lib/misc.d.ts

@@ -26,8 +26,11 @@ export declare function pauseFor(time: number): Promise<void>;
 /**
  * Calls the passed {@linkcode func} after the specified {@linkcode timeout} in ms (defaults to 300).
  * Any subsequent calls to this function will reset the timer and discard all previous calls.
+ * @param func The function to call after the timeout
+ * @param timeout The time in ms to wait before calling the function
+ * @param edge Whether to call the function at the very first call ("rising" edge) or the very last call ("falling" edge, default)
  */
-export declare function debounce<TFunc extends (...args: TArgs[]) => void, TArgs = any>(func: TFunc, timeout?: number): (...args: TArgs[]) => void;
+export declare function debounce<TFunc extends (...args: TArgs[]) => void, TArgs = any>(func: TFunc, timeout?: number, edge?: "rising" | "falling"): (...args: TArgs[]) => void;
 /** Options for the `fetchAdvanced()` function */
 export type FetchAdvancedOpts = Omit<RequestInit & Partial<{
     /** Timeout in milliseconds after which the fetch call will be canceled with an AbortController signal */

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@sv443-network/userutils",
   "libName": "UserUtils",
-  "version": "6.0.1",
+  "version": "6.2.0",
   "description": "Library with various utilities for userscripts - register listeners for when CSS selectors exist, intercept events, manage persistent user configurations, modify the DOM more easily and more",
   "main": "dist/index.js",
   "module": "dist/index.mjs",