@sv443-network/userutils 4.0.0 → 4.2.0

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # @sv443-network/userutils
 
+## 4.2.0
+
+### Minor Changes
+
+- 47639f0: Added SelectorObserver options `disableOnNoListeners` and `enableOnAddListener`
+- 4a58caa: `addGlobalStyle` now returns the created style element
+- 5038967: `fetchAdvanced` is now a drop-in replacement and timeout can now optionally be disabled
+
+### Patch Changes
+
+- 17a6ad5: `randomizeArray` now returns a copy if an empty array is passed as well
+
+## 4.1.0
+
+### Minor Changes
+
+- 885323d: Added function `observeElementProp` to allow observing element property changes
+
 ## 4.0.0
 
 ### Major Changes

package/README.md

@@ -33,6 +33,7 @@ View the documentation of previous major releases: [3.0.0](https://github.com/Sv
     - [interceptEvent()](#interceptevent) - conditionally intercepts events registered by `addEventListener()` on any given EventTarget object
     - [interceptWindowEvent()](#interceptwindowevent) - conditionally intercepts events registered by `addEventListener()` on the window object
     - [isScrollable()](#isscrollable) - check if an element has a horizontal or vertical scroll bar
+    - [observeElementProp()](#observeelementprop) - observe changes to an element's property that can't be observed with MutationObserver
   - [**Math:**](#math)
     - [clamp()](#clamp) - constrain a number between a min and max value
     - [mapRange()](#maprange) - map a number from one range to the same spot in another range
@@ -83,7 +84,7 @@ View the documentation of previous major releases: [3.0.0](https://github.com/Sv
 
 <br>
 
-- If you are not using a bundler, you can include the latest release from GreasyFork by adding this directive to the userscript header:
+- If you are not using a bundler, you can include the latest release by adding one of these directives to the userscript header, depending on your preferred CDN:
   ```
   // @require https://greasyfork.org/scripts/472956-userutils/code/UserUtils.js
   ```
@@ -99,7 +100,7 @@ View the documentation of previous major releases: [3.0.0](https://github.com/Sv
   // or using object destructuring:
 
   const { clamp } = UserUtils;
-  console.log(clamp(1, 5, 10); // 5
+  console.log(clamp(1, 5, 10)); // 5
   ```
 
 <br><br>
@@ -147,9 +148,12 @@ If a selector string is passed instead, it will be used to find the element.
 If you want to observe the entire document, you can pass `document.body`  
 
 The `options` parameter is optional and will be passed to the MutationObserver that is used internally.  
-The default options are `{ childList: true, subtree: true }` - you may see the [MutationObserver.observe() documentation](https://developer.mozilla.org/en-US/docs/Web/API/MutationObserver/observe#options) for more information and a list of options.  
-For example, if you want to trigger the listeners when certain attributes change, pass `{ attributes: true, attributeFilter: ["class", "data-my-attribute"] }`  
+The MutationObserver options present by default are `{ childList: true, subtree: true }` - you may see the [MutationObserver.observe() documentation](https://developer.mozilla.org/en-US/docs/Web/API/MutationObserver/observe#options) for more information and a list of options.  
+For example, if you want to trigger the listeners when certain attributes change, pass `{ attributeFilter: ["class", "data-my-attribute"] }`  
+  
 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)
   
 ⚠️ 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.
@@ -505,10 +509,11 @@ addParent(element, newParent);
 ### addGlobalStyle()
 Usage:  
 ```ts
-addGlobalStyle(css: string): void
+addGlobalStyle(css: string): HTMLStyleElement
 ```
   
 Adds a global style to the page in form of a `<style>` element that's inserted into the `<head>`.  
+Returns the style element that was just created.  
 ⚠️ This function needs to be run after the DOM has loaded (when using `@run-at document-end` or after `DOMContentLoaded` has fired).  
   
 <details><summary><b>Example - click to view</b></summary>
@@ -675,6 +680,59 @@ console.log("Element has a vertical scroll bar:", vertical);
 
 </details>
 
+<br>
+
+### observeElementProp()
+Usage:  
+```ts
+observeElementProp(
+  element: Element,
+  property: string,
+  callback: (oldValue: any, newValue: any) => void
+): void
+```
+  
+This function observes changes to the given property of a given element.  
+While regular HTML attributes can be observed using a MutationObserver, this is not always possible for properties that are assigned on the JS object.  
+This function shims the setter of the provided property and calls the callback function whenever it is changed through any means.  
+  
+When using TypeScript, the types for `element`, `property` and the arguments for `callback` will be automatically inferred.  
+  
+<details><summary><b>Example - click to view</b></summary>
+
+```ts
+import { observeElementProp } from "@sv443-network/userutils";
+
+const myInput = document.querySelector("input#my-input");
+
+let value = 0;
+
+setInterval(() => {
+  value += 1;
+  myInput.value = String(value);
+}, 1000);
+
+
+const observer = new MutationObserver((mutations) => {
+  // will never be called:
+  console.log("MutationObserver mutation:", mutations);
+});
+
+// one would think this should work, but "value" is a JS object *property*, not a DOM *attribute*
+observer.observe(myInput, {
+  attributes: true,
+  attributeFilter: ["value"],
+});
+
+
+observeElementProp(myInput, "value", (oldValue, newValue) => {
+  // will be called every time the value changes:
+  console.log("Value changed from", oldValue, "to", newValue);
+});
+```
+
+</details>
+
 <br><br>
 
 <!-- #SECTION Math -->
@@ -769,6 +827,9 @@ randomId(length?: number, radix?: number): string
 ```
   
 Generates a cryptographically strong random ID of a given length and [radix (base).](https://en.wikipedia.org/wiki/Radix)  
+Uses the [Web Crypto API](https://developer.mozilla.org/en-US/docs/Web/API/Crypto/getRandomValues) for generating the random numbers.  
+⚠️ This is not intended for generating encryption keys, only for generating IDs with a decent amount of entropy!  
+  
 The default length is 16 and the default radix is 16 (hexadecimal).  
 You may change the radix to get digits from different numerical systems.  
 Use 2 for binary, 8 for octal, 10 for decimal, 16 for hexadecimal and 36 for alphanumeric.  
@@ -1004,14 +1065,15 @@ window.addEventListener("resize", debounce((event) => {
 ### fetchAdvanced()
 Usage:  
 ```ts
-fetchAdvanced(url: string, options?: {
+fetchAdvanced(input: string | Request | URL, options?: {
   timeout?: number,
   // any other options from fetch() except for signal
 }): Promise<Response>
 ```
   
-A wrapper around the native `fetch()` function that adds options like a timeout property.  
-The timeout will default to 10 seconds if left undefined.  
+A drop-in replacement for the native `fetch()` function that adds options like a timeout property.  
+The timeout will default to 10 seconds if left undefined. Set it to a negative number to disable the timeout.  
+Note that the `signal` option will be overwritten if passed.  
   
 <details><summary><b>Example - click to view</b></summary>
 
@@ -1022,10 +1084,12 @@ fetchAdvanced("https://jokeapi.dev/joke/Any?safe-mode", {
   timeout: 5000,
   // also accepts any other fetch options like headers:
   headers: {
-    "Accept": "application/json",
+    "Accept": "text/plain",
   },
 }).then(async (response) => {
-  console.log("Data:", await response.json());
+  console.log("Fetch data:", await response.text());
+}).catch((err) => {
+  console.error("Fetch error:", err);
 });
 ```
 
@@ -1215,7 +1279,7 @@ randomizeArray(array: Array): Array
 ```
   
 Returns a copy of an array with its items in a random order.  
-If the array is empty, the originally passed empty array will be returned without copying.  
+If the array is empty, a new, empty array will be returned.  
   
 <details><summary><b>Example - click to view</b></summary>
 

package/dist/index.global.js

@@ -9,7 +9,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      4.0.0
+// @version      4.2.0
 // @license      MIT
 // @copyright    Sv443 (https://github.com/Sv443)
 
@@ -22,8 +22,6 @@
 
 var UserUtils = (function (exports) {
   var __defProp = Object.defineProperty;
-  var __defProps = Object.defineProperties;
-  var __getOwnPropDescs = Object.getOwnPropertyDescriptors;
   var __getOwnPropSymbols = Object.getOwnPropertySymbols;
   var __hasOwnProp = Object.prototype.hasOwnProperty;
   var __propIsEnum = Object.prototype.propertyIsEnumerable;
@@ -39,7 +37,18 @@ var UserUtils = (function (exports) {
       }
     return a;
   };
-  var __spreadProps = (a, b) => __defProps(a, __getOwnPropDescs(b));
+  var __objRest = (source, exclude) => {
+    var target = {};
+    for (var prop in source)
+      if (__hasOwnProp.call(source, prop) && exclude.indexOf(prop) < 0)
+        target[prop] = source[prop];
+    if (source != null && __getOwnPropSymbols)
+      for (var prop of __getOwnPropSymbols(source)) {
+        if (exclude.indexOf(prop) < 0 && __propIsEnum.call(source, prop))
+          target[prop] = source[prop];
+      }
+    return target;
+  };
   var __publicField = (obj, key, value) => {
     __defNormalProp(obj, typeof key !== "symbol" ? key + "" : key, value);
     return value;
@@ -120,7 +129,7 @@ var UserUtils = (function (exports) {
   function randomizeArray(array) {
     const retArray = [...array];
     if (array.length === 0)
-      return array;
+      return retArray;
     for (let i = retArray.length - 1; i > 0; i--) {
       const j = Math.floor(randRange(0, 1e4) / 1e4 * (i + 1));
       [retArray[i], retArray[j]] = [retArray[j], retArray[i]];
@@ -282,6 +291,7 @@ var UserUtils = (function (exports) {
     const styleElem = document.createElement("style");
     styleElem.innerHTML = style;
     document.head.appendChild(styleElem);
+    return styleElem;
   }
   function preloadImages(srcUrls, rejects = false) {
     const promises = srcUrls.map((src) => new Promise((res, rej) => {
@@ -333,6 +343,28 @@ var UserUtils = (function (exports) {
       horizontal: (overflowX === "scroll" || overflowX === "auto") && element.scrollWidth > element.clientWidth
     };
   }
+  function observeElementProp(element, property, callback) {
+    const elementPrototype = Object.getPrototypeOf(element);
+    if (elementPrototype.hasOwnProperty(property)) {
+      const descriptor = Object.getOwnPropertyDescriptor(elementPrototype, property);
+      Object.defineProperty(element, property, {
+        get: function() {
+          var _a;
+          return (_a = descriptor == null ? void 0 : descriptor.get) == null ? void 0 : _a.apply(this, arguments);
+        },
+        set: function() {
+          var _a;
+          const oldValue = this[property];
+          (_a = descriptor == null ? void 0 : descriptor.set) == null ? void 0 : _a.apply(this, arguments);
+          const newValue = this[property];
+          if (typeof callback === "function") {
+            callback.bind(this, oldValue, newValue);
+          }
+          return newValue;
+        }
+      });
+    }
+  }
 
   // lib/misc.ts
   function autoPlural(word, num) {
@@ -353,13 +385,15 @@ var UserUtils = (function (exports) {
     };
   }
   function fetchAdvanced(_0) {
-    return __async(this, arguments, function* (url, options = {}) {
+    return __async(this, arguments, function* (input, options = {}) {
       const { timeout = 1e4 } = options;
-      const controller = new AbortController();
-      const id = setTimeout(() => controller.abort(), timeout);
-      const res = yield fetch(url, __spreadProps(__spreadValues({}, options), {
-        signal: controller.signal
-      }));
+      let signalOpts = {}, id = void 0;
+      if (timeout >= 0) {
+        const controller = new AbortController();
+        id = setTimeout(() => controller.abort(), timeout);
+        signalOpts = { signal: controller.signal };
+      }
+      const res = yield fetch(input, __spreadValues(__spreadValues({}, options), signalOpts));
       clearTimeout(id);
       return res;
     });
@@ -409,14 +443,29 @@ var UserUtils = (function (exports) {
       __publicField(this, "baseElement");
       __publicField(this, "observer");
       __publicField(this, "observerOptions");
+      __publicField(this, "customOptions");
       __publicField(this, "listenerMap");
       this.baseElement = baseElement;
       this.listenerMap = /* @__PURE__ */ new Map();
       this.observer = new MutationObserver(() => this.checkAllSelectors());
+      const _a = options, {
+        defaultDebounce,
+        disableOnNoListeners,
+        enableOnAddListener
+      } = _a, observerOptions = __objRest(_a, [
+        "defaultDebounce",
+        "disableOnNoListeners",
+        "enableOnAddListener"
+      ]);
       this.observerOptions = __spreadValues({
         childList: true,
         subtree: true
-      }, options);
+      }, observerOptions);
+      this.customOptions = {
+        defaultDebounce: defaultDebounce != null ? defaultDebounce : 0,
+        disableOnNoListeners: disableOnNoListeners != null ? disableOnNoListeners : false,
+        enableOnAddListener: enableOnAddListener != null ? enableOnAddListener : true
+      };
     }
     checkAllSelectors() {
       for (const [selector, listeners] of this.listenerMap.entries())
@@ -449,6 +498,8 @@ var UserUtils = (function (exports) {
         }
         if (((_a = this.listenerMap.get(selector)) == null ? void 0 : _a.length) === 0)
           this.listenerMap.delete(selector);
+        if (this.listenerMap.size === 0 && this.customOptions.disableOnNoListeners)
+          this.disable();
       }
     }
     debounce(func, time) {
@@ -469,16 +520,18 @@ var UserUtils = (function (exports) {
      */
     addListener(selector, options) {
       options = __spreadValues({ all: false, continuous: false, debounce: 0 }, options);
-      if (options.debounce && options.debounce > 0 || this.observerOptions.defaultDebounce && this.observerOptions.defaultDebounce > 0) {
+      if (options.debounce && options.debounce > 0 || this.customOptions.defaultDebounce && this.customOptions.defaultDebounce > 0) {
         options.listener = this.debounce(
           options.listener,
-          options.debounce || this.observerOptions.defaultDebounce
+          options.debounce || this.customOptions.defaultDebounce
         );
       }
       if (this.listenerMap.has(selector))
         this.listenerMap.get(selector).push(options);
       else
         this.listenerMap.set(selector, [options]);
+      if (this.enabled === false && this.customOptions.enableOnAddListener)
+        this.enable();
       this.checkSelector(selector, [options]);
     }
     /** Disables the observation of the child elements */
@@ -585,6 +638,7 @@ var UserUtils = (function (exports) {
   exports.interceptWindowEvent = interceptWindowEvent;
   exports.isScrollable = isScrollable;
   exports.mapRange = mapRange;
+  exports.observeElementProp = observeElementProp;
   exports.openInNewTab = openInNewTab;
   exports.pauseFor = pauseFor;
   exports.preloadImages = preloadImages;

package/dist/index.js

@@ -1,8 +1,6 @@
 'use strict';
 
 var __defProp = Object.defineProperty;
-var __defProps = Object.defineProperties;
-var __getOwnPropDescs = Object.getOwnPropertyDescriptors;
 var __getOwnPropSymbols = Object.getOwnPropertySymbols;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
 var __propIsEnum = Object.prototype.propertyIsEnumerable;
@@ -18,7 +16,18 @@ var __spreadValues = (a, b) => {
     }
   return a;
 };
-var __spreadProps = (a, b) => __defProps(a, __getOwnPropDescs(b));
+var __objRest = (source, exclude) => {
+  var target = {};
+  for (var prop in source)
+    if (__hasOwnProp.call(source, prop) && exclude.indexOf(prop) < 0)
+      target[prop] = source[prop];
+  if (source != null && __getOwnPropSymbols)
+    for (var prop of __getOwnPropSymbols(source)) {
+      if (exclude.indexOf(prop) < 0 && __propIsEnum.call(source, prop))
+        target[prop] = source[prop];
+    }
+  return target;
+};
 var __publicField = (obj, key, value) => {
   __defNormalProp(obj, typeof key !== "symbol" ? key + "" : key, value);
   return value;
@@ -99,7 +108,7 @@ function takeRandomItem(arr) {
 function randomizeArray(array) {
   const retArray = [...array];
   if (array.length === 0)
-    return array;
+    return retArray;
   for (let i = retArray.length - 1; i > 0; i--) {
     const j = Math.floor(randRange(0, 1e4) / 1e4 * (i + 1));
     [retArray[i], retArray[j]] = [retArray[j], retArray[i]];
@@ -261,6 +270,7 @@ function addGlobalStyle(style) {
   const styleElem = document.createElement("style");
   styleElem.innerHTML = style;
   document.head.appendChild(styleElem);
+  return styleElem;
 }
 function preloadImages(srcUrls, rejects = false) {
   const promises = srcUrls.map((src) => new Promise((res, rej) => {
@@ -312,6 +322,28 @@ function isScrollable(element) {
     horizontal: (overflowX === "scroll" || overflowX === "auto") && element.scrollWidth > element.clientWidth
   };
 }
+function observeElementProp(element, property, callback) {
+  const elementPrototype = Object.getPrototypeOf(element);
+  if (elementPrototype.hasOwnProperty(property)) {
+    const descriptor = Object.getOwnPropertyDescriptor(elementPrototype, property);
+    Object.defineProperty(element, property, {
+      get: function() {
+        var _a;
+        return (_a = descriptor == null ? void 0 : descriptor.get) == null ? void 0 : _a.apply(this, arguments);
+      },
+      set: function() {
+        var _a;
+        const oldValue = this[property];
+        (_a = descriptor == null ? void 0 : descriptor.set) == null ? void 0 : _a.apply(this, arguments);
+        const newValue = this[property];
+        if (typeof callback === "function") {
+          callback.bind(this, oldValue, newValue);
+        }
+        return newValue;
+      }
+    });
+  }
+}
 
 // lib/misc.ts
 function autoPlural(word, num) {
@@ -332,13 +364,15 @@ function debounce(func, timeout = 300) {
   };
 }
 function fetchAdvanced(_0) {
-  return __async(this, arguments, function* (url, options = {}) {
+  return __async(this, arguments, function* (input, options = {}) {
     const { timeout = 1e4 } = options;
-    const controller = new AbortController();
-    const id = setTimeout(() => controller.abort(), timeout);
-    const res = yield fetch(url, __spreadProps(__spreadValues({}, options), {
-      signal: controller.signal
-    }));
+    let signalOpts = {}, id = void 0;
+    if (timeout >= 0) {
+      const controller = new AbortController();
+      id = setTimeout(() => controller.abort(), timeout);
+      signalOpts = { signal: controller.signal };
+    }
+    const res = yield fetch(input, __spreadValues(__spreadValues({}, options), signalOpts));
     clearTimeout(id);
     return res;
   });
@@ -388,14 +422,29 @@ var SelectorObserver = class {
     __publicField(this, "baseElement");
     __publicField(this, "observer");
     __publicField(this, "observerOptions");
+    __publicField(this, "customOptions");
     __publicField(this, "listenerMap");
     this.baseElement = baseElement;
     this.listenerMap = /* @__PURE__ */ new Map();
     this.observer = new MutationObserver(() => this.checkAllSelectors());
+    const _a = options, {
+      defaultDebounce,
+      disableOnNoListeners,
+      enableOnAddListener
+    } = _a, observerOptions = __objRest(_a, [
+      "defaultDebounce",
+      "disableOnNoListeners",
+      "enableOnAddListener"
+    ]);
     this.observerOptions = __spreadValues({
       childList: true,
       subtree: true
-    }, options);
+    }, observerOptions);
+    this.customOptions = {
+      defaultDebounce: defaultDebounce != null ? defaultDebounce : 0,
+      disableOnNoListeners: disableOnNoListeners != null ? disableOnNoListeners : false,
+      enableOnAddListener: enableOnAddListener != null ? enableOnAddListener : true
+    };
   }
   checkAllSelectors() {
     for (const [selector, listeners] of this.listenerMap.entries())
@@ -428,6 +477,8 @@ var SelectorObserver = class {
       }
       if (((_a = this.listenerMap.get(selector)) == null ? void 0 : _a.length) === 0)
         this.listenerMap.delete(selector);
+      if (this.listenerMap.size === 0 && this.customOptions.disableOnNoListeners)
+        this.disable();
     }
   }
   debounce(func, time) {
@@ -448,16 +499,18 @@ var SelectorObserver = class {
    */
   addListener(selector, options) {
     options = __spreadValues({ all: false, continuous: false, debounce: 0 }, options);
-    if (options.debounce && options.debounce > 0 || this.observerOptions.defaultDebounce && this.observerOptions.defaultDebounce > 0) {
+    if (options.debounce && options.debounce > 0 || this.customOptions.defaultDebounce && this.customOptions.defaultDebounce > 0) {
       options.listener = this.debounce(
         options.listener,
-        options.debounce || this.observerOptions.defaultDebounce
+        options.debounce || this.customOptions.defaultDebounce
       );
     }
     if (this.listenerMap.has(selector))
       this.listenerMap.get(selector).push(options);
     else
       this.listenerMap.set(selector, [options]);
+    if (this.enabled === false && this.customOptions.enableOnAddListener)
+      this.enable();
     this.checkSelector(selector, [options]);
   }
   /** Disables the observation of the child elements */
@@ -564,6 +617,7 @@ exports.interceptEvent = interceptEvent;
 exports.interceptWindowEvent = interceptWindowEvent;
 exports.isScrollable = isScrollable;
 exports.mapRange = mapRange;
+exports.observeElementProp = observeElementProp;
 exports.openInNewTab = openInNewTab;
 exports.pauseFor = pauseFor;
 exports.preloadImages = preloadImages;

package/dist/index.mjs

@@ -1,6 +1,4 @@
 var __defProp = Object.defineProperty;
-var __defProps = Object.defineProperties;
-var __getOwnPropDescs = Object.getOwnPropertyDescriptors;
 var __getOwnPropSymbols = Object.getOwnPropertySymbols;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
 var __propIsEnum = Object.prototype.propertyIsEnumerable;
@@ -16,7 +14,18 @@ var __spreadValues = (a, b) => {
     }
   return a;
 };
-var __spreadProps = (a, b) => __defProps(a, __getOwnPropDescs(b));
+var __objRest = (source, exclude) => {
+  var target = {};
+  for (var prop in source)
+    if (__hasOwnProp.call(source, prop) && exclude.indexOf(prop) < 0)
+      target[prop] = source[prop];
+  if (source != null && __getOwnPropSymbols)
+    for (var prop of __getOwnPropSymbols(source)) {
+      if (exclude.indexOf(prop) < 0 && __propIsEnum.call(source, prop))
+        target[prop] = source[prop];
+    }
+  return target;
+};
 var __publicField = (obj, key, value) => {
   __defNormalProp(obj, typeof key !== "symbol" ? key + "" : key, value);
   return value;
@@ -97,7 +106,7 @@ function takeRandomItem(arr) {
 function randomizeArray(array) {
   const retArray = [...array];
   if (array.length === 0)
-    return array;
+    return retArray;
   for (let i = retArray.length - 1; i > 0; i--) {
     const j = Math.floor(randRange(0, 1e4) / 1e4 * (i + 1));
     [retArray[i], retArray[j]] = [retArray[j], retArray[i]];
@@ -259,6 +268,7 @@ function addGlobalStyle(style) {
   const styleElem = document.createElement("style");
   styleElem.innerHTML = style;
   document.head.appendChild(styleElem);
+  return styleElem;
 }
 function preloadImages(srcUrls, rejects = false) {
   const promises = srcUrls.map((src) => new Promise((res, rej) => {
@@ -310,6 +320,28 @@ function isScrollable(element) {
     horizontal: (overflowX === "scroll" || overflowX === "auto") && element.scrollWidth > element.clientWidth
   };
 }
+function observeElementProp(element, property, callback) {
+  const elementPrototype = Object.getPrototypeOf(element);
+  if (elementPrototype.hasOwnProperty(property)) {
+    const descriptor = Object.getOwnPropertyDescriptor(elementPrototype, property);
+    Object.defineProperty(element, property, {
+      get: function() {
+        var _a;
+        return (_a = descriptor == null ? void 0 : descriptor.get) == null ? void 0 : _a.apply(this, arguments);
+      },
+      set: function() {
+        var _a;
+        const oldValue = this[property];
+        (_a = descriptor == null ? void 0 : descriptor.set) == null ? void 0 : _a.apply(this, arguments);
+        const newValue = this[property];
+        if (typeof callback === "function") {
+          callback.bind(this, oldValue, newValue);
+        }
+        return newValue;
+      }
+    });
+  }
+}
 
 // lib/misc.ts
 function autoPlural(word, num) {
@@ -330,13 +362,15 @@ function debounce(func, timeout = 300) {
   };
 }
 function fetchAdvanced(_0) {
-  return __async(this, arguments, function* (url, options = {}) {
+  return __async(this, arguments, function* (input, options = {}) {
     const { timeout = 1e4 } = options;
-    const controller = new AbortController();
-    const id = setTimeout(() => controller.abort(), timeout);
-    const res = yield fetch(url, __spreadProps(__spreadValues({}, options), {
-      signal: controller.signal
-    }));
+    let signalOpts = {}, id = void 0;
+    if (timeout >= 0) {
+      const controller = new AbortController();
+      id = setTimeout(() => controller.abort(), timeout);
+      signalOpts = { signal: controller.signal };
+    }
+    const res = yield fetch(input, __spreadValues(__spreadValues({}, options), signalOpts));
     clearTimeout(id);
     return res;
   });
@@ -386,14 +420,29 @@ var SelectorObserver = class {
     __publicField(this, "baseElement");
     __publicField(this, "observer");
     __publicField(this, "observerOptions");
+    __publicField(this, "customOptions");
     __publicField(this, "listenerMap");
     this.baseElement = baseElement;
     this.listenerMap = /* @__PURE__ */ new Map();
     this.observer = new MutationObserver(() => this.checkAllSelectors());
+    const _a = options, {
+      defaultDebounce,
+      disableOnNoListeners,
+      enableOnAddListener
+    } = _a, observerOptions = __objRest(_a, [
+      "defaultDebounce",
+      "disableOnNoListeners",
+      "enableOnAddListener"
+    ]);
     this.observerOptions = __spreadValues({
       childList: true,
       subtree: true
-    }, options);
+    }, observerOptions);
+    this.customOptions = {
+      defaultDebounce: defaultDebounce != null ? defaultDebounce : 0,
+      disableOnNoListeners: disableOnNoListeners != null ? disableOnNoListeners : false,
+      enableOnAddListener: enableOnAddListener != null ? enableOnAddListener : true
+    };
   }
   checkAllSelectors() {
     for (const [selector, listeners] of this.listenerMap.entries())
@@ -426,6 +475,8 @@ var SelectorObserver = class {
       }
       if (((_a = this.listenerMap.get(selector)) == null ? void 0 : _a.length) === 0)
         this.listenerMap.delete(selector);
+      if (this.listenerMap.size === 0 && this.customOptions.disableOnNoListeners)
+        this.disable();
     }
   }
   debounce(func, time) {
@@ -446,16 +497,18 @@ var SelectorObserver = class {
    */
   addListener(selector, options) {
     options = __spreadValues({ all: false, continuous: false, debounce: 0 }, options);
-    if (options.debounce && options.debounce > 0 || this.observerOptions.defaultDebounce && this.observerOptions.defaultDebounce > 0) {
+    if (options.debounce && options.debounce > 0 || this.customOptions.defaultDebounce && this.customOptions.defaultDebounce > 0) {
       options.listener = this.debounce(
         options.listener,
-        options.debounce || this.observerOptions.defaultDebounce
+        options.debounce || this.customOptions.defaultDebounce
       );
     }
     if (this.listenerMap.has(selector))
       this.listenerMap.get(selector).push(options);
     else
       this.listenerMap.set(selector, [options]);
+    if (this.enabled === false && this.customOptions.enableOnAddListener)
+      this.enable();
     this.checkSelector(selector, [options]);
   }
   /** Disables the observation of the child elements */
@@ -545,4 +598,4 @@ tr.getLanguage = () => {
   return curLang;
 };
 
-export { ConfigManager, SelectorObserver, addGlobalStyle, addParent, autoPlural, clamp, compress, debounce, decompress, fetchAdvanced, getUnsafeWindow, insertAfter, insertValues, interceptEvent, interceptWindowEvent, isScrollable, mapRange, openInNewTab, pauseFor, preloadImages, randRange, randomId, randomItem, randomItemIndex, randomizeArray, takeRandomItem, tr };
+export { ConfigManager, SelectorObserver, addGlobalStyle, addParent, autoPlural, clamp, compress, debounce, decompress, fetchAdvanced, getUnsafeWindow, insertAfter, insertValues, interceptEvent, interceptWindowEvent, isScrollable, mapRange, observeElementProp, openInNewTab, pauseFor, preloadImages, randRange, randomId, randomItem, randomItemIndex, randomizeArray, takeRandomItem, tr };

package/dist/lib/SelectorObserver.d.ts

@@ -18,9 +18,13 @@ type SelectorOptionsCommon = {
     /** Whether to debounce the listener to reduce calls to `querySelector` or `querySelectorAll` - set undefined or <=0 to disable (default) */
     debounce?: number;
 };
-export type SelectorObserverOptions = MutationObserverInit & {
+export type SelectorObserverOptions = {
     /** If set, applies this debounce in milliseconds to all listeners that don't have their own debounce set */
     defaultDebounce?: number;
+    /** 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 */
+    enableOnAddListener?: boolean;
 };
 /** Observes the children of the given element for changes */
 export declare class SelectorObserver {
@@ -28,13 +32,14 @@ export declare class SelectorObserver {
     private baseElement;
     private observer;
     private observerOptions;
+    private customOptions;
     private listenerMap;
     /**
      * Creates a new SelectorObserver that will observe the children of the given base element selector for changes (only creation and deletion of elements by default)
      * @param baseElementSelector The selector of the element to observe
      * @param options Fine-tune what triggers the MutationObserver's checking function - `subtree` and `childList` are set to true by default
      */
-    constructor(baseElementSelector: string, options?: SelectorObserverOptions);
+    constructor(baseElementSelector: string, options?: SelectorObserverOptions & MutationObserverInit);
     /**
      * Creates a new SelectorObserver that will observe the children of the given base element for changes (only creation and deletion of elements by default)
      * @param baseElement The element to observe

package/dist/lib/dom.d.ts

@@ -16,8 +16,9 @@ export declare function addParent(element: Element, newParent: Element): Element
  * Adds global CSS style in the form of a `<style>` element in the document's `<head>`
  * This needs to be run after the `DOMContentLoaded` event has fired on the document object (or instantly if `@run-at document-end` is used).
  * @param style CSS string
+ * @returns Returns the created style element
  */
-export declare function addGlobalStyle(style: string): void;
+export declare function addGlobalStyle(style: string): HTMLStyleElement;
 /**
  * Preloads an array of image URLs so they can be loaded instantly from the browser cache later on
  * @param rejects If set to `true`, the returned PromiseSettledResults will contain rejections for any of the images that failed to load
@@ -50,3 +51,13 @@ export declare function isScrollable(element: Element): {
     vertical: boolean;
     horizontal: boolean;
 };
+/**
+ * Executes the callback when the passed element's property changes.
+ * Contrary to an element's attributes, properties can usually not be observed with a MutationObserver.
+ * This function shims the getter and setter of the property to invoke the callback.
+ *
+ * [Source](https://stackoverflow.com/a/61975440)
+ * @param property The name of the property to observe
+ * @param callback Callback to execute when the value is changed
+ */
+export declare function observeElementProp<TElem extends Element = HTMLElement, TPropKey extends keyof TElem = keyof TElem>(element: TElem, property: TPropKey, callback: (oldVal: TElem[TPropKey], newVal: TElem[TPropKey]) => void): void;

package/dist/lib/math.d.ts

@@ -12,6 +12,7 @@ export declare function randRange(max: number): number;
 /**
  * Generates a random ID with the specified length and radix (16 characters and hexadecimal by default)
  * Uses [`crypto.getRandomValues()`](https://developer.mozilla.org/en-US/docs/Web/API/Crypto/getRandomValues) for better cryptographic randomness
+ * ⚠️ Not suitable for generating encryption keys! Use [`crypto.subtle.generateKey()`](https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto/generateKey) for that.
  * @param length The length of the ID to generate (defaults to 16)
  * @param radix The [radix](https://en.wikipedia.org/wiki/Radix) of each digit (defaults to 16 which is hexadecimal. Use 2 for binary, 10 for decimal, 36 for alphanumeric, etc.)
  */

package/dist/lib/misc.d.ts

@@ -29,12 +29,12 @@ export declare function pauseFor(time: number): Promise<void>;
  */
 export declare function debounce<TFunc extends (...args: TArgs[]) => void, TArgs = any>(func: TFunc, timeout?: number): (...args: TArgs[]) => void;
 /** Options for the `fetchAdvanced()` function */
-export type FetchAdvancedOpts = RequestInit & Partial<{
+export type FetchAdvancedOpts = Omit<RequestInit & Partial<{
     /** Timeout in milliseconds after which the fetch call will be canceled with an AbortController signal */
     timeout: number;
-}>;
+}>, "signal">;
 /** Calls the fetch API with special options like a timeout */
-export declare function fetchAdvanced(url: string, options?: FetchAdvancedOpts): Promise<Response>;
+export declare function fetchAdvanced(input: RequestInfo | URL, options?: FetchAdvancedOpts): Promise<Response>;
 /**
  * Inserts the passed values into a string at the respective placeholders.
  * The placeholder format is `%n`, where `n` is the 1-indexed argument number.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sv443-network/userutils",
-  "version": "4.0.0",
+  "version": "4.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",