@sv443-network/userutils 6.0.0 → 6.1.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @sv443-network/userutils
 
+## 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
+
+- 08248c1: Fixed terminology in JSDoc comments of the `DataStore` class
+
 ## 6.0.0
 
 ### Major Changes

package/README.md

@@ -8,9 +8,12 @@ Contains builtin TypeScript declarations. Fully web compatible and supports ESM
 If you like using this library, please consider [supporting the development ❤️](https://github.com/sponsors/Sv443)
 
 <br>
+<sup>
+View the documentation of previous major releases:
+</sup>
 <sub>
 
-View the documentation of previous major releases: [4.2.1](https://github.com/Sv443-Network/UserUtils/blob/v4.2.1/README.md), [3.0.0](https://github.com/Sv443-Network/UserUtils/blob/v3.0.0/README.md), [2.0.1](https://github.com/Sv443-Network/UserUtils/blob/v2.0.1/README.md), [1.2.0](https://github.com/Sv443-Network/UserUtils/blob/v1.2.0/README.md), [0.5.3](https://github.com/Sv443-Network/UserUtils/blob/v0.5.3/README.md)
+<a href="https://github.com/Sv443-Network/UserUtils/blob/v5.0.1/README.md" rel="noopener noreferrer">5.0.1</a>, <a href="https://github.com/Sv443-Network/UserUtils/blob/v4.2.1/README.md" rel="noopener noreferrer">4.2.1</a>, <a href="https://github.com/Sv443-Network/UserUtils/blob/v3.0.0/README.md" rel="noopener noreferrer">3.0.0</a>, <a href="https://github.com/Sv443-Network/UserUtils/blob/v2.0.1/README.md" rel="noopener noreferrer">2.0.1</a>, <a href="https://github.com/Sv443-Network/UserUtils/blob/v1.2.0/README.md" rel="noopener noreferrer">1.2.0</a>, <a href="https://github.com/Sv443-Network/UserUtils/blob/v0.5.3/README.md" rel="noopener noreferrer">0.5.3</a>
 
 </sub>
 </div>
@@ -44,7 +47,7 @@ View the documentation of previous major releases: [4.2.1](https://github.com/Sv
     - [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
@@ -1177,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.0
+// @version      6.1.0
 // @license      MIT
 // @copyright    Sv443 (https://github.com/Sv443)
 
@@ -145,7 +145,7 @@ var UserUtils = (function (exports) {
      * ⚠️ Requires the directives `@grant GM.getValue` and `@grant GM.setValue`  
      * ⚠️ Make sure to call {@linkcode loadData()} at least once after creating an instance, or the returned data will be the same as `options.defaultData`
      * 
-     * @template TData The type of the data that is saved in persistent storage (will be automatically inferred from `config.defaultData`) - this should also be the type of the data format associated with the current `options.formatVersion`
+     * @template TData The type of the data that is saved in persistent storage (will be automatically inferred from `options.defaultData`) - this should also be the type of the data format associated with the current `options.formatVersion`
      * @param options The options for this DataStore instance
     */
     constructor(options) {
@@ -212,7 +212,7 @@ var UserUtils = (function (exports) {
         resolve();
       }));
     }
-    /** Saves the default configuration data passed in the constructor synchronously to the in-memory cache and asynchronously to persistent storage */
+    /** Saves the default data passed in the constructor synchronously to the in-memory cache and asynchronously to persistent storage */
     saveDefaultData() {
       return __async(this, null, function* () {
         this.cachedData = this.defaultData;
@@ -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) {

package/dist/index.js

@@ -125,7 +125,7 @@ var DataStore = class {
    * ⚠️ Requires the directives `@grant GM.getValue` and `@grant GM.setValue`  
    * ⚠️ Make sure to call {@linkcode loadData()} at least once after creating an instance, or the returned data will be the same as `options.defaultData`
    * 
-   * @template TData The type of the data that is saved in persistent storage (will be automatically inferred from `config.defaultData`) - this should also be the type of the data format associated with the current `options.formatVersion`
+   * @template TData The type of the data that is saved in persistent storage (will be automatically inferred from `options.defaultData`) - this should also be the type of the data format associated with the current `options.formatVersion`
    * @param options The options for this DataStore instance
   */
   constructor(options) {
@@ -192,7 +192,7 @@ var DataStore = class {
       resolve();
     }));
   }
-  /** Saves the default configuration data passed in the constructor synchronously to the in-memory cache and asynchronously to persistent storage */
+  /** Saves the default data passed in the constructor synchronously to the in-memory cache and asynchronously to persistent storage */
   saveDefaultData() {
     return __async(this, null, function* () {
       this.cachedData = this.defaultData;
@@ -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) {

package/dist/index.mjs

@@ -123,7 +123,7 @@ var DataStore = class {
    * ⚠️ Requires the directives `@grant GM.getValue` and `@grant GM.setValue`  
    * ⚠️ Make sure to call {@linkcode loadData()} at least once after creating an instance, or the returned data will be the same as `options.defaultData`
    * 
-   * @template TData The type of the data that is saved in persistent storage (will be automatically inferred from `config.defaultData`) - this should also be the type of the data format associated with the current `options.formatVersion`
+   * @template TData The type of the data that is saved in persistent storage (will be automatically inferred from `options.defaultData`) - this should also be the type of the data format associated with the current `options.formatVersion`
    * @param options The options for this DataStore instance
   */
   constructor(options) {
@@ -190,7 +190,7 @@ var DataStore = class {
       resolve();
     }));
   }
-  /** Saves the default configuration data passed in the constructor synchronously to the in-memory cache and asynchronously to persistent storage */
+  /** Saves the default data passed in the constructor synchronously to the in-memory cache and asynchronously to persistent storage */
   saveDefaultData() {
     return __async(this, null, function* () {
       this.cachedData = this.defaultData;
@@ -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) {

package/dist/lib/DataStore.d.ts

@@ -1,7 +1,7 @@
 /** Function that takes the data in the old format and returns the data in the new format. Also supports an asynchronous migration. */
 type MigrationFunc = (oldData: any) => any | Promise<any>;
 /** Dictionary of format version numbers and the function that migrates to them from the previous whole integer */
-export type ConfigMigrationsDict = Record<number, MigrationFunc>;
+export type DataMigrationsDict = Record<number, MigrationFunc>;
 /** Options for the DataStore instance */
 export type DataStoreOptions<TData> = {
     /** A unique internal ID for this data store - choose wisely as changing it is not supported yet. */
@@ -27,7 +27,7 @@ export type DataStoreOptions<TData> = {
      * The functions will be run in order from the oldest to the newest version.
      * If the current format version is not in the dictionary, no migrations will be run.
      */
-    migrations?: ConfigMigrationsDict;
+    migrations?: DataMigrationsDict;
 } & ({
     /**
      * Function to use to encode the data prior to saving it in persistent storage.
@@ -51,7 +51,7 @@ export type DataStoreOptions<TData> = {
 });
 /**
  * Manages a sync & async persistent JSON database that is cached in memory and persistently saved across sessions.
- * Supports migrating data from older versions of the configuration to newer ones and populating the cache with default data if no persistent data is found.
+ * Supports migrating data from older format versions to newer ones and populating the cache with default data if no persistent data is found.
  *
  * ⚠️ Requires the directives `@grant GM.getValue` and `@grant GM.setValue`
  * ⚠️ Make sure to call {@linkcode loadData()} at least once after creating an instance, or the returned data will be the same as `options.defaultData`
@@ -73,7 +73,7 @@ export declare class DataStore<TData = any> {
      * ⚠️ Requires the directives `@grant GM.getValue` and `@grant GM.setValue`
      * ⚠️ Make sure to call {@linkcode loadData()} at least once after creating an instance, or the returned data will be the same as `options.defaultData`
      *
-     * @template TData The type of the data that is saved in persistent storage (will be automatically inferred from `config.defaultData`) - this should also be the type of the data format associated with the current `options.formatVersion`
+     * @template TData The type of the data that is saved in persistent storage (will be automatically inferred from `options.defaultData`) - this should also be the type of the data format associated with the current `options.formatVersion`
      * @param options The options for this DataStore instance
     */
     constructor(options: DataStoreOptions<TData>);
@@ -90,7 +90,7 @@ export declare class DataStore<TData = any> {
     getData(): TData;
     /** Saves the data synchronously to the in-memory cache and asynchronously to the persistent storage */
     setData(data: TData): Promise<void>;
-    /** Saves the default configuration data passed in the constructor synchronously to the in-memory cache and asynchronously to persistent storage */
+    /** Saves the default data passed in the constructor synchronously to the in-memory cache and asynchronously to persistent storage */
     saveDefaultData(): Promise<void>;
     /**
      * Call this method to clear all persistently stored data associated with this DataStore instance.

package/dist/lib/dom.d.ts

@@ -67,7 +67,7 @@ export declare function observeElementProp<TElem extends Element = HTMLElement,
  * @param siblingAmount The amount of siblings to return
  * @param refElementAlignment Can be set to `center-top` (default), `center-bottom`, `top`, or `bottom`, which will determine where the relative location of the provided {@linkcode refElement} is in the returned array
  * @param includeRef If set to `true` (default), the provided {@linkcode refElement} will be included in the returned array at the corresponding position
- * @template TSiblingType The type of the sibling elements that are returned
+ * @template TSibling The type of the sibling elements that are returned
  * @returns An array of sibling elements
  */
-export declare function getSiblingsFrame<TSiblingType extends Element = HTMLElement>(refElement: Element, siblingAmount: number, refElementAlignment?: "center-top" | "center-bottom" | "top" | "bottom", includeRef?: boolean): TSiblingType[];
+export declare function getSiblingsFrame<TSibling extends Element = HTMLElement>(refElement: Element, siblingAmount: number, refElementAlignment?: "center-top" | "center-bottom" | "top" | "bottom", includeRef?: boolean): TSibling[];

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.0",
+  "version": "6.1.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",
@@ -10,7 +10,7 @@
     "lint": "tsc --noEmit && eslint .",
     "build-types": "tsc --emitDeclarationOnly --declaration --outDir dist",
     "build-common": "tsup lib/index.ts --format cjs,esm --clean --treeshake",
-    "build-global": "tsup lib/index.ts --format cjs,esm,iife --treeshake --onSuccess \"npm run post-build-global && echo Finished building.\"",
+    "build-all": "tsup lib/index.ts --format cjs,esm,iife --treeshake --onSuccess \"npm run post-build-global && echo Finished building.\"",
     "build": "npm run build-common -- && npm run build-types",
     "post-build-global": "npm run node-ts -- ./tools/post-build-global.mts",
     "dev": "npm run build-common -- --sourcemap --watch --onSuccess \"npm run build-types && echo Finished building.\"",