@sv443-network/userutils 6.1.0 → 6.3.0

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # @sv443-network/userutils
 
+## 6.3.0
+
+### Minor Changes
+
+- fa09004: Made `openInNewTab()` use `GM.openInTab` by default and fall back to the old behavior.
+  Also added `background` param to specify if the tab should get focus when opened.
+
+## 6.2.0
+
+### Minor Changes
+
+- 0173235: Add property to change the debounce edge in `SelectorObserver` instances
+
 ## 6.1.0
 
 ### Minor Changes

package/README.md

@@ -2,7 +2,7 @@
 
 <!-- #MARKER Description -->
 ## UserUtils
-Zero-dependency 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.  
+Zero-dependency library with various utilities for userscripts - register listeners for when CSS selectors exist, intercept events, create persistent & synchronous data stores, modify the DOM more easily and more.  
   
 Contains builtin TypeScript declarations. Fully web compatible and supports ESM and CJS imports and global declaration.  
 If you like using this library, please consider [supporting the development ❤️](https://github.com/sponsors/Sv443)
@@ -159,6 +159,7 @@ Additionally, there are the following extra options:
 - `disableOnNoListeners` - whether to disable the SelectorObserver when there are no listeners left (defaults to false)
 - `enableOnAddListener` - whether to enable the SelectorObserver when a new listener is added (defaults to true)
 - `defaultDebounce` - if set to a number, this debounce will be applied to every listener that doesn't have a custom debounce set (defaults to 0)
+- `defaultDebounceEdge` - can be set to "falling" (default) or "rising", to call the function at (rising) on the very first call and subsequent times after the given debounce time or (falling) the very last call after the debounce time passed with no new calls - [see `debounce()` for more info and a diagram](#debounce)
   
 ⚠️ Make sure to call `enable()` to actually start observing. This will need to be done after the DOM has loaded (when using `@run-at document-end` or after `DOMContentLoaded` has fired) **and** as soon as the `baseElement` or `baseElementSelector` is available.
 
@@ -177,16 +178,19 @@ The listener will be called immediately if the selector already exists in the DO
 > This will also include elements that were already found in a previous listener call.  
 > If set to false (default), querySelector() will be used and only the first matching element will be returned.
   
-> If `options.continuous` is set to true, the listener will not be deregistered after it was called once (defaults to false).  
+> If `options.continuous` is set to true, this listener will not be deregistered after it was called once (defaults to false).  
 >   
-> ⚠️ You should keep usage of this option to a minimum, as it will cause the listener to be called every time the selector is *checked for and found* and this can stack up quite quickly.  
+> ⚠️ You should keep usage of this option to a minimum, as it will cause this listener to be called every time the selector is *checked for and found* and this can stack up quite quickly.  
 > ⚠️ You should try to only use this option on SelectorObserver instances that are scoped really low in the DOM tree to prevent as many selector checks as possible from being triggered.  
 > ⚠️ I also recommend always setting a debounce time (see constructor or below) if you use this option.
   
-> If `options.debounce` is set to a number above 0, the listener will be debounced by that amount of milliseconds (defaults to 0).  
-> E.g. if the debounce time is set to 200 and the selector is found twice within 100ms, only the last call of the listener will be executed.
+> If `options.debounce` is set to a number above 0, this listener will be debounced by that amount of milliseconds (defaults to 0).  
+> E.g. if the debounce time is set to 200 and the selector is found twice within 100ms, only the last call of this listener will be executed.
+
+> `options.debounceEdge` is set to "falling" by default, which means the debounce timer will start after the last call of this listener.  
+> If set to "rising", the debounce timer will start after the first call of this listener.
   
-> When using TypeScript, the generic `TElement` can be used to specify the type of the element(s) that the listener will return.  
+> When using TypeScript, the generic `TElement` can be used to specify the type of the element(s) that this listener will return.  
 > It will default to HTMLElement if left undefined.
   
 <br>
@@ -262,6 +266,9 @@ document.addEventListener("DOMContentLoaded", () => {
     attributeFilter: ["class", "style", "data-whatever"],
     // debounce all listeners by 100ms unless specified otherwise:
     defaultDebounce: 100,
+    // "rising" means listeners are called immediately and use the debounce as a timeout between subsequent calls - see the debounce() function for a better explanation
+    defaultDebounceEdge: "rising",
+    // other settings from the MutationObserver API can be set here too - see https://developer.mozilla.org/en-US/docs/Web/API/MutationObserver/observe#options
   });
 
   barObserver.addListener("#my-element", {
@@ -273,6 +280,8 @@ document.addEventListener("DOMContentLoaded", () => {
   barObserver.addListener("#my-other-element", {
     // set the debounce higher than provided by the defaultDebounce property:
     debounce: 250,
+    // adjust the debounceEdge back to the default "falling" for this specific listener:
+    debounceEdge: "falling",
     listener: (element) => {
       console.log("Other element's attributes changed:", element);
     },
@@ -573,14 +582,14 @@ preloadImages([
 ### openInNewTab()
 Usage:  
 ```ts
-openInNewTab(url: string): void
+openInNewTab(url: string, background?: boolean): void
 ```
   
-Creates an invisible anchor with a `_blank` target and clicks it.  
-Contrary to `window.open()`, this has a lesser chance to get blocked by the browser's popup blocker and doesn't open the URL as a new window.  
-This function has to be run in response to a user interaction event, else the browser might reject it.  
+Tries to use `GM.openInTab` to open the given URL in a new tab, or as a fallback if the grant is not given, creates an invisible anchor element and clicks it.  
+If `background` is set to true, the tab will be opened in the background. Leave `undefined` to use the browser's default behavior.  
   
-⚠️ This function needs to be run after the DOM has loaded (when using `@run-at document-end` or after `DOMContentLoaded` has fired).  
+⚠️ Needs the `@grant GM.openInTab` directive, otherwise only the fallback behavior will be used and the warning below is extra important:  
+⚠️ For the fallback to work, this function needs to be run in response to a user interaction event, else the browser might reject it.  
   
 <details><summary><b>Example - click to view</b></summary>
 
@@ -588,7 +597,8 @@ This function has to be run in response to a user interaction event, else the br
 import { openInNewTab } from "@sv443-network/userutils";
 
 document.querySelector("#my-button").addEventListener("click", () => {
-  openInNewTab("https://example.org/");
+  // open in background:
+  openInNewTab("https://example.org/", true);
 });
 ```
 

package/dist/index.global.js

@@ -7,8 +7,8 @@
 
 // ==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.1.0
+// @description  Library with various utilities for userscripts - register listeners for when CSS selectors exist, intercept events, create persistent & synchronous data stores, modify the DOM more easily and more
+// @version      6.3.0
 // @license      MIT
 // @copyright    Sv443 (https://github.com/Sv443)
 
@@ -336,18 +336,22 @@ var UserUtils = (function (exports) {
     }));
     return Promise.allSettled(promises);
   }
-  function openInNewTab(href) {
-    const openElem = document.createElement("a");
-    Object.assign(openElem, {
-      className: "userutils-open-in-new-tab",
-      target: "_blank",
-      rel: "noopener noreferrer",
-      href
-    });
-    openElem.style.display = "none";
-    document.body.appendChild(openElem);
-    openElem.click();
-    setTimeout(openElem.remove, 50);
+  function openInNewTab(href, background) {
+    try {
+      GM.openInTab(href, background);
+    } catch (e) {
+      const openElem = document.createElement("a");
+      Object.assign(openElem, {
+        className: "userutils-open-in-new-tab",
+        target: "_blank",
+        rel: "noopener noreferrer",
+        href
+      });
+      openElem.style.display = "none";
+      document.body.appendChild(openElem);
+      openElem.click();
+      setTimeout(openElem.remove, 50);
+    }
   }
   function interceptEvent(eventObject, eventName, predicate = () => true) {
     Error.stackTraceLimit = Math.max(Error.stackTraceLimit, 100);
@@ -512,10 +516,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"
       ]);
@@ -525,6 +531,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
       };
@@ -564,12 +571,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}
@@ -585,7 +588,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

@@ -316,18 +316,22 @@ function preloadImages(srcUrls, rejects = false) {
   }));
   return Promise.allSettled(promises);
 }
-function openInNewTab(href) {
-  const openElem = document.createElement("a");
-  Object.assign(openElem, {
-    className: "userutils-open-in-new-tab",
-    target: "_blank",
-    rel: "noopener noreferrer",
-    href
-  });
-  openElem.style.display = "none";
-  document.body.appendChild(openElem);
-  openElem.click();
-  setTimeout(openElem.remove, 50);
+function openInNewTab(href, background) {
+  try {
+    GM.openInTab(href, background);
+  } catch (e) {
+    const openElem = document.createElement("a");
+    Object.assign(openElem, {
+      className: "userutils-open-in-new-tab",
+      target: "_blank",
+      rel: "noopener noreferrer",
+      href
+    });
+    openElem.style.display = "none";
+    document.body.appendChild(openElem);
+    openElem.click();
+    setTimeout(openElem.remove, 50);
+  }
 }
 function interceptEvent(eventObject, eventName, predicate = () => true) {
   Error.stackTraceLimit = Math.max(Error.stackTraceLimit, 100);
@@ -492,10 +496,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"
     ]);
@@ -505,6 +511,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
     };
@@ -544,12 +551,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}
@@ -565,7 +568,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

@@ -314,18 +314,22 @@ function preloadImages(srcUrls, rejects = false) {
   }));
   return Promise.allSettled(promises);
 }
-function openInNewTab(href) {
-  const openElem = document.createElement("a");
-  Object.assign(openElem, {
-    className: "userutils-open-in-new-tab",
-    target: "_blank",
-    rel: "noopener noreferrer",
-    href
-  });
-  openElem.style.display = "none";
-  document.body.appendChild(openElem);
-  openElem.click();
-  setTimeout(openElem.remove, 50);
+function openInNewTab(href, background) {
+  try {
+    GM.openInTab(href, background);
+  } catch (e) {
+    const openElem = document.createElement("a");
+    Object.assign(openElem, {
+      className: "userutils-open-in-new-tab",
+      target: "_blank",
+      rel: "noopener noreferrer",
+      href
+    });
+    openElem.style.display = "none";
+    document.body.appendChild(openElem);
+    openElem.click();
+    setTimeout(openElem.remove, 50);
+  }
 }
 function interceptEvent(eventObject, eventName, predicate = () => true) {
   Error.stackTraceLimit = Math.max(Error.stackTraceLimit, 100);
@@ -490,10 +494,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"
     ]);
@@ -503,6 +509,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
     };
@@ -542,12 +549,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}
@@ -563,7 +566,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/dom.d.ts

@@ -26,12 +26,12 @@ export declare function addGlobalStyle(style: string): HTMLStyleElement;
  */
 export declare function preloadImages(srcUrls: string[], rejects?: boolean): Promise<PromiseSettledResult<unknown>[]>;
 /**
- * Creates an invisible anchor with a `_blank` target and clicks it.
- * Contrary to `window.open()`, this has a lesser chance to get blocked by the browser's popup blocker and doesn't open the URL as a new window.
- *
- * This function has to be run in response to a user interaction event, else the browser might reject it.
+ * Tries to use `GM.openInTab` to open the given URL in a new tab, otherwise if the grant is not given, creates an invisible anchor element and clicks it.
+ * For the fallback to work, this function needs to be run in response to a user interaction event, else the browser might reject it.
+ * @param href The URL to open in a new tab
+ * @param background If set to `true`, the tab will be opened in the background - set to `undefined` (default) to use the browser's default behavior
  */
-export declare function openInNewTab(href: string): void;
+export declare function openInNewTab(href: string, background?: boolean): void;
 /**
  * Intercepts the specified event on the passed object and prevents it from being called if the called {@linkcode predicate} function returns a truthy value.
  * If no predicate is specified, all events will be discarded.

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@sv443-network/userutils",
   "libName": "UserUtils",
-  "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",
+  "version": "6.3.0",
+  "description": "Library with various utilities for userscripts - register listeners for when CSS selectors exist, intercept events, create persistent & synchronous data stores, modify the DOM more easily and more",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
   "types": "dist/lib/index.d.ts",