@sv443-network/userutils 2.0.0 → 3.0.0

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      2.0.0
+// @version      3.0.0
 // @license      MIT
 // @copyright    Sv443 (https://github.com/Sv443)
 
@@ -69,28 +69,36 @@ var UserUtils = (function (exports) {
   function clamp(value, min, max) {
     return Math.max(Math.min(value, max), min);
   }
-  function mapRange(value, range_1_min, range_1_max, range_2_min, range_2_max) {
-    if (Number(range_1_min) === 0 && Number(range_2_min) === 0)
-      return value * (range_2_max / range_1_max);
-    return (value - range_1_min) * ((range_2_max - range_2_min) / (range_1_max - range_1_min)) + range_2_min;
+  function mapRange(value, range1min, range1max, range2min, range2max) {
+    if (Number(range1min) === 0 && Number(range2min) === 0)
+      return value * (range2max / range1max);
+    return (value - range1min) * ((range2max - range2min) / (range1max - range1min)) + range2min;
   }
   function randRange(...args) {
     let min, max;
-    if (typeof args[0] === "number" && typeof args[1] === "number") {
+    if (typeof args[0] === "number" && typeof args[1] === "number")
       [min, max] = args;
-    } else if (typeof args[0] === "number" && typeof args[1] !== "number") {
+    else if (typeof args[0] === "number" && typeof args[1] !== "number") {
       min = 0;
-      max = args[0];
+      [max] = args;
     } else
       throw new TypeError(`Wrong parameter(s) provided - expected: "number" and "number|undefined", got: "${typeof args[0]}" and "${typeof args[1]}"`);
     min = Number(min);
     max = Number(max);
     if (isNaN(min) || isNaN(max))
-      throw new TypeError(`Parameters "min" and "max" can't be NaN`);
+      return NaN;
     if (min > max)
       throw new TypeError(`Parameter "min" can't be bigger than "max"`);
     return Math.floor(Math.random() * (max - min + 1)) + min;
   }
+  function randomId(length = 16, radix = 16) {
+    const arr = new Uint8Array(length);
+    crypto.getRandomValues(arr);
+    return Array.from(
+      arr,
+      (v) => mapRange(v, 0, 255, 0, radix).toString(radix).substring(0, 1)
+    ).join("");
+  }
 
   // lib/array.ts
   function randomItem(array) {
@@ -120,14 +128,14 @@ var UserUtils = (function (exports) {
     return retArray;
   }
 
-  // lib/config.ts
+  // lib/ConfigManager.ts
   var ConfigManager = class {
     /**
      * Creates an instance of ConfigManager to manage a user configuration 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.  
      *   
      * ⚠️ Requires the directives `@grant GM.getValue` and `@grant GM.setValue`  
-     * ⚠️ Make sure to call `loadData()` at least once after creating an instance, or the returned data will be the same as `options.defaultConfig`
+     * ⚠️ Make sure to call {@linkcode loadData()} at least once after creating an instance, or the returned data will be the same as `options.defaultConfig`
      * 
      * @template TData The type of the data that is saved in persistent storage (will be automatically inferred from `config.defaultConfig`) - this should also be the type of the data format associated with the current `options.formatVersion`
      * @param options The options for this ConfigManager instance
@@ -170,7 +178,10 @@ var UserUtils = (function (exports) {
         }
       });
     }
-    /** Returns a copy of the data from the in-memory cache. Use `loadData()` to get fresh data from persistent storage (usually not necessary since the cache should always exactly reflect persistent storage). */
+    /**
+     * Returns a copy of the data from the in-memory cache.  
+     * Use {@linkcode loadData()} to get fresh data from persistent storage (usually not necessary since the cache should always exactly reflect persistent storage).
+     */
     getData() {
       return this.deepCopy(this.cachedConfig);
     }
@@ -200,8 +211,8 @@ var UserUtils = (function (exports) {
     }
     /**
      * Call this method to clear all persistently stored data associated with this ConfigManager instance.  
-     * The in-memory cache will be left untouched, so you may still access the data with `getData()`.  
-     * Calling `loadData()` or `setData()` after this method was called will recreate persistent storage with the cached or default data.  
+     * The in-memory cache will be left untouched, so you may still access the data with {@linkcode getData()}  
+     * Calling {@linkcode loadData()} or {@linkcode setData()} after this method was called will recreate persistent storage with the cached or default data.  
      *   
      * ⚠️ This requires the additional directive `@grant GM.deleteValue`
      */
@@ -294,7 +305,7 @@ var UserUtils = (function (exports) {
     openElem.click();
     setTimeout(openElem.remove, 50);
   }
-  function interceptEvent(eventObject, eventName, predicate) {
+  function interceptEvent(eventObject, eventName, predicate = () => true) {
     if (typeof Error.stackTraceLimit === "number" && Error.stackTraceLimit < 1e3) {
       Error.stackTraceLimit = 1e3;
     }
@@ -312,54 +323,44 @@ var UserUtils = (function (exports) {
       };
     })(eventObject.__proto__.addEventListener);
   }
-  function interceptWindowEvent(eventName, predicate) {
+  function interceptWindowEvent(eventName, predicate = () => true) {
     return interceptEvent(getUnsafeWindow(), eventName, predicate);
   }
-  function amplifyMedia(mediaElement, initialMultiplier = 1) {
+  function amplifyMedia(mediaElement, initialGain = 1) {
     const context = new (window.AudioContext || window.webkitAudioContext)();
     const props = {
-      /** Sets the gain multiplier */
-      setGain(multiplier) {
-        props.gainNode.gain.setValueAtTime(multiplier, props.context.currentTime);
+      context,
+      sourceNode: context.createMediaElementSource(mediaElement),
+      gainNode: context.createGain(),
+      /** Sets the gain of the amplifying GainNode */
+      setGain(gain) {
+        props.gainNode.gain.value = gain;
       },
-      /** Returns the current gain multiplier */
+      /** Returns the current gain of the amplifying GainNode */
       getGain() {
         return props.gainNode.gain.value;
       },
+      /** Whether the amplification is currently enabled */
+      enabled: false,
       /** Enable the amplification for the first time or if it was disabled before */
       enable() {
-        props.source.connect(props.limiterNode);
-        props.limiterNode.connect(props.gainNode);
+        if (props.enabled)
+          return;
+        props.enabled = true;
+        props.sourceNode.connect(props.gainNode);
         props.gainNode.connect(props.context.destination);
       },
       /** Disable the amplification */
       disable() {
-        props.source.disconnect(props.limiterNode);
-        props.limiterNode.disconnect(props.gainNode);
+        if (!props.enabled)
+          return;
+        props.enabled = false;
+        props.sourceNode.disconnect(props.gainNode);
         props.gainNode.disconnect(props.context.destination);
-        props.source.connect(props.context.destination);
-      },
-      /**
-       * Set the options of the [limiter / DynamicsCompressorNode](https://developer.mozilla.org/en-US/docs/Web/API/DynamicsCompressorNode/DynamicsCompressorNode#options)  
-       * The default is `{ threshold: -2, knee: 40, ratio: 12, attack: 0.003, release: 0.25 }`
-       */
-      setLimiterOptions(options) {
-        for (const [key, val] of Object.entries(options))
-          props.limiterNode[key].setValueAtTime(val, props.context.currentTime);
-      },
-      context,
-      source: context.createMediaElementSource(mediaElement),
-      gainNode: context.createGain(),
-      limiterNode: context.createDynamicsCompressor()
+        props.sourceNode.connect(props.context.destination);
+      }
     };
-    props.setLimiterOptions({
-      threshold: -2,
-      knee: 40,
-      ratio: 12,
-      attack: 3e-3,
-      release: 0.25
-    });
-    props.setGain(initialMultiplier);
+    props.setGain(initialGain);
     return props;
   }
   function isScrollable(element) {
@@ -408,55 +409,146 @@ var UserUtils = (function (exports) {
     });
   }
 
-  // lib/onSelector.ts
-  var selectorMap = /* @__PURE__ */ new Map();
-  function onSelector(selector, options) {
-    let selectorMapItems = [];
-    if (selectorMap.has(selector))
-      selectorMapItems = selectorMap.get(selector);
-    selectorMapItems.push(options);
-    selectorMap.set(selector, selectorMapItems);
-    checkSelectorExists(selector, selectorMapItems);
-  }
-  function removeOnSelector(selector) {
-    return selectorMap.delete(selector);
-  }
-  function checkSelectorExists(selector, options) {
-    const deleteIndices = [];
-    options.forEach((option, i) => {
-      try {
-        const elements = option.all ? document.querySelectorAll(selector) : document.querySelector(selector);
-        if (elements !== null && elements instanceof NodeList && elements.length > 0 || elements !== null) {
-          option.listener(elements);
-          if (!option.continuous)
-            deleteIndices.push(i);
+  // lib/SelectorObserver.ts
+  var SelectorObserver = class {
+    constructor(baseElement, options = {}) {
+      __publicField(this, "enabled", false);
+      __publicField(this, "baseElement");
+      __publicField(this, "observer");
+      __publicField(this, "observerOptions");
+      __publicField(this, "listenerMap");
+      this.baseElement = baseElement;
+      this.listenerMap = /* @__PURE__ */ new Map();
+      this.observer = new MutationObserver(() => this.checkAllSelectors());
+      this.observerOptions = __spreadValues({
+        childList: true,
+        subtree: true
+      }, options);
+    }
+    checkAllSelectors() {
+      for (const [selector, listeners] of this.listenerMap.entries())
+        this.checkSelector(selector, listeners);
+    }
+    checkSelector(selector, listeners) {
+      var _a;
+      if (!this.enabled)
+        return;
+      const baseElement = typeof this.baseElement === "string" ? document.querySelector(this.baseElement) : this.baseElement;
+      if (!baseElement)
+        return;
+      const all = listeners.some((listener) => listener.all);
+      const one = listeners.some((listener) => !listener.all);
+      const allElements = all ? baseElement.querySelectorAll(selector) : null;
+      const oneElement = one ? baseElement.querySelector(selector) : null;
+      for (const options of listeners) {
+        if (options.all) {
+          if (allElements && allElements.length > 0) {
+            options.listener(allElements);
+            if (!options.continuous)
+              this.removeListener(selector, options);
+          }
+        } else {
+          if (oneElement) {
+            options.listener(oneElement);
+            if (!options.continuous)
+              this.removeListener(selector, options);
+          }
         }
-      } catch (err) {
-        console.error(`Couldn't call listener for selector '${selector}'`, err);
+        if (((_a = this.listenerMap.get(selector)) == null ? void 0 : _a.length) === 0)
+          this.listenerMap.delete(selector);
       }
-    });
-    if (deleteIndices.length > 0) {
-      const newOptsArray = options.filter((_, i) => !deleteIndices.includes(i));
-      if (newOptsArray.length === 0)
-        selectorMap.delete(selector);
-      else {
-        selectorMap.set(selector, newOptsArray);
+    }
+    debounce(func, time) {
+      let timeout;
+      return function(...args) {
+        clearTimeout(timeout);
+        timeout = setTimeout(() => func.apply(this, args), time);
+      };
+    }
+    /**
+     * Starts observing the children of the base element for changes to the given {@linkcode selector} according to the set {@linkcode options}
+     * @param selector The selector to observe
+     * @param options Options for the selector observation
+     * @param options.listener Gets called whenever the selector was found in the DOM
+     * @param [options.all] Whether to use `querySelectorAll()` instead - default is false
+     * @param [options.continuous] Whether to call the listener continuously instead of just once - default is false
+     * @param [options.debounce] Whether to debounce the listener to reduce calls to `querySelector` or `querySelectorAll` - set undefined or <=0 to disable (default)
+     */
+    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) {
+        options.listener = this.debounce(
+          options.listener,
+          options.debounce || this.observerOptions.defaultDebounce
+        );
       }
+      if (this.listenerMap.has(selector))
+        this.listenerMap.get(selector).push(options);
+      else
+        this.listenerMap.set(selector, [options]);
+      this.checkSelector(selector, [options]);
     }
-  }
-  function initOnSelector(options = {}) {
-    const observer = new MutationObserver(() => {
-      for (const [selector, options2] of selectorMap.entries())
-        checkSelectorExists(selector, options2);
-    });
-    observer.observe(document.body, __spreadValues({
-      subtree: true,
-      childList: true
-    }, options));
-  }
-  function getSelectorMap() {
-    return selectorMap;
-  }
+    /** Disables the observation of the child elements */
+    disable() {
+      if (!this.enabled)
+        return;
+      this.enabled = false;
+      this.observer.disconnect();
+    }
+    /**
+     * Enables or reenables the observation of the child elements.
+     * @param immediatelyCheckSelectors Whether to immediately check if all previously registered selectors exist (default is true)
+     * @returns Returns true when the observation was enabled, false otherwise (e.g. when the base element wasn't found)
+     */
+    enable(immediatelyCheckSelectors = true) {
+      const baseElement = typeof this.baseElement === "string" ? document.querySelector(this.baseElement) : this.baseElement;
+      if (this.enabled || !baseElement)
+        return false;
+      this.enabled = true;
+      this.observer.observe(baseElement, this.observerOptions);
+      if (immediatelyCheckSelectors)
+        this.checkAllSelectors();
+      return true;
+    }
+    /** Returns whether the observation of the child elements is currently enabled */
+    isEnabled() {
+      return this.enabled;
+    }
+    /** Removes all listeners that have been registered with {@linkcode addListener()} */
+    clearListeners() {
+      this.listenerMap.clear();
+    }
+    /**
+     * Removes all listeners for the given {@linkcode selector} that have been registered with {@linkcode addListener()}
+     * @returns Returns true when all listeners for the associated selector were found and removed, false otherwise
+     */
+    removeAllListeners(selector) {
+      return this.listenerMap.delete(selector);
+    }
+    /**
+     * Removes a single listener for the given {@linkcode selector} and {@linkcode options} that has been registered with {@linkcode addListener()}
+     * @returns Returns true when the listener was found and removed, false otherwise
+     */
+    removeListener(selector, options) {
+      const listeners = this.listenerMap.get(selector);
+      if (!listeners)
+        return false;
+      const index = listeners.indexOf(options);
+      if (index > -1) {
+        listeners.splice(index, 1);
+        return true;
+      }
+      return false;
+    }
+    /** Returns all listeners that have been registered with {@linkcode addListener()} */
+    getAllListeners() {
+      return this.listenerMap;
+    }
+    /** Returns all listeners for the given {@linkcode selector} that have been registered with {@linkcode addListener()} */
+    getListeners(selector) {
+      return this.listenerMap.get(selector);
+    }
+  };
 
   // lib/translation.ts
   var trans = {};
@@ -484,6 +576,7 @@ var UserUtils = (function (exports) {
   };
 
   exports.ConfigManager = ConfigManager;
+  exports.SelectorObserver = SelectorObserver;
   exports.addGlobalStyle = addGlobalStyle;
   exports.addParent = addParent;
   exports.amplifyMedia = amplifyMedia;
@@ -491,24 +584,21 @@ var UserUtils = (function (exports) {
   exports.clamp = clamp;
   exports.debounce = debounce;
   exports.fetchAdvanced = fetchAdvanced;
-  exports.getSelectorMap = getSelectorMap;
   exports.getUnsafeWindow = getUnsafeWindow;
-  exports.initOnSelector = initOnSelector;
   exports.insertAfter = insertAfter;
   exports.insertValues = insertValues;
   exports.interceptEvent = interceptEvent;
   exports.interceptWindowEvent = interceptWindowEvent;
   exports.isScrollable = isScrollable;
   exports.mapRange = mapRange;
-  exports.onSelector = onSelector;
   exports.openInNewTab = openInNewTab;
   exports.pauseFor = pauseFor;
   exports.preloadImages = preloadImages;
   exports.randRange = randRange;
+  exports.randomId = randomId;
   exports.randomItem = randomItem;
   exports.randomItemIndex = randomItemIndex;
   exports.randomizeArray = randomizeArray;
-  exports.removeOnSelector = removeOnSelector;
   exports.takeRandomItem = takeRandomItem;
   exports.tr = tr;