@sv443-network/userutils 2.0.0 → 3.0.0

package/dist/index.mjs

@@ -46,28 +46,36 @@ var __async = (__this, __arguments, generator) => {
 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) {
@@ -97,14 +105,14 @@ function randomizeArray(array) {
   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
@@ -147,7 +155,10 @@ var ConfigManager = class {
       }
     });
   }
-  /** 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);
   }
@@ -177,8 +188,8 @@ var ConfigManager = class {
   }
   /**
    * 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`
    */
@@ -271,7 +282,7 @@ function openInNewTab(href) {
   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;
   }
@@ -289,54 +300,44 @@ function interceptEvent(eventObject, eventName, predicate) {
     };
   })(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) {
@@ -385,55 +386,146 @@ function insertValues(str, ...values) {
   });
 }
 
-// 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 = {};
@@ -460,4 +552,4 @@ tr.getLanguage = () => {
   return curLang;
 };
 
-export { ConfigManager, addGlobalStyle, addParent, amplifyMedia, autoPlural, clamp, debounce, fetchAdvanced, getSelectorMap, getUnsafeWindow, initOnSelector, insertAfter, insertValues, interceptEvent, interceptWindowEvent, isScrollable, mapRange, onSelector, openInNewTab, pauseFor, preloadImages, randRange, randomItem, randomItemIndex, randomizeArray, removeOnSelector, takeRandomItem, tr };
+export { ConfigManager, SelectorObserver, addGlobalStyle, addParent, amplifyMedia, autoPlural, clamp, debounce, fetchAdvanced, getUnsafeWindow, insertAfter, insertValues, interceptEvent, interceptWindowEvent, isScrollable, mapRange, openInNewTab, pauseFor, preloadImages, randRange, randomId, randomItem, randomItemIndex, randomizeArray, takeRandomItem, tr };

package/dist/lib/{config.d.ts → ConfigManager.d.ts}

@@ -34,7 +34,7 @@ export interface ConfigManagerOptions<TData> {
  * 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`
  */
@@ -49,7 +49,7 @@ export declare class ConfigManager<TData = any> {
      * 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
@@ -61,7 +61,10 @@ export declare class ConfigManager<TData = any> {
      * Also runs all necessary migration functions if the data format has changed since the last time the data was saved.
      */
     loadData(): Promise<TData>;
-    /** 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(): TData;
     /** Saves the data synchronously to the in-memory cache and asynchronously to the persistent storage */
     setData(data: TData): Promise<void>;
@@ -69,8 +72,8 @@ export declare class ConfigManager<TData = any> {
     saveDefaultData(): Promise<void>;
     /**
      * 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`
      */

package/dist/lib/SelectorObserver.d.ts

@@ -0,0 +1,84 @@
+/** Options for the `onSelector()` method of {@linkcode SelectorObserver} */
+export type SelectorListenerOptions<TElem extends Element = HTMLElement> = SelectorOptionsOne<TElem> | SelectorOptionsAll<TElem>;
+type SelectorOptionsOne<TElem extends Element> = SelectorOptionsCommon & {
+    /** Whether to use `querySelectorAll()` instead - default is false */
+    all?: false;
+    /** Gets called whenever the selector was found in the DOM */
+    listener: (element: TElem) => void;
+};
+type SelectorOptionsAll<TElem extends Element> = SelectorOptionsCommon & {
+    /** Whether to use `querySelectorAll()` instead - default is false */
+    all: true;
+    /** Gets called whenever the selector was found in the DOM */
+    listener: (elements: NodeListOf<TElem>) => void;
+};
+type SelectorOptionsCommon = {
+    /** Whether to call the listener continuously instead of once - default is false */
+    continuous?: boolean;
+    /** 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 & {
+    /** If set, applies this debounce in milliseconds to all listeners that don't have their own debounce set */
+    defaultDebounce?: number;
+};
+/** Observes the children of the given element for changes */
+export declare class SelectorObserver {
+    private enabled;
+    private baseElement;
+    private observer;
+    private observerOptions;
+    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);
+    /**
+     * 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
+     * @param options Fine-tune what triggers the MutationObserver's checking function - `subtree` and `childList` are set to true by default
+     */
+    constructor(baseElement: Element, options: SelectorObserverOptions);
+    private checkAllSelectors;
+    private checkSelector;
+    private debounce;
+    /**
+     * 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<TElem extends Element = HTMLElement>(selector: string, options: SelectorListenerOptions<TElem>): void;
+    /** Disables the observation of the child elements */
+    disable(): void;
+    /**
+     * 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?: boolean): boolean;
+    /** Returns whether the observation of the child elements is currently enabled */
+    isEnabled(): boolean;
+    /** Removes all listeners that have been registered with {@linkcode addListener()} */
+    clearListeners(): void;
+    /**
+     * 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: string): boolean;
+    /**
+     * 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: string, options: SelectorListenerOptions): boolean;
+    /** Returns all listeners that have been registered with {@linkcode addListener()} */
+    getAllListeners(): Map<string, SelectorListenerOptions<HTMLElement>[]>;
+    /** Returns all listeners for the given {@linkcode selector} that have been registered with {@linkcode addListener()} */
+    getListeners(selector: string): SelectorListenerOptions<HTMLElement>[] | undefined;
+}
+export {};

package/dist/lib/array.d.ts

@@ -1,3 +1,5 @@
+/** Describes an array with at least one item */
+export type NonEmptyArray<T = unknown> = [T, ...T[]];
 /** Returns a random item from the passed array */
 export declare function randomItem<T = unknown>(array: T[]): T | undefined;
 /**

package/dist/lib/dom.d.ts

@@ -3,8 +3,8 @@
  */
 export declare function getUnsafeWindow(): Window;
 /**
- * Inserts `afterElement` as a sibling just after the provided `beforeElement`
- * @returns Returns the `afterElement`
+ * Inserts {@linkcode afterElement} as a sibling just after the provided {@linkcode beforeElement}
+ * @returns Returns the {@linkcode afterElement}
  */
 export declare function insertAfter(beforeElement: Element, afterElement: Element): Element;
 /**
@@ -32,64 +32,66 @@ export declare function preloadImages(srcUrls: string[], rejects?: boolean): Pro
  */
 export declare function openInNewTab(href: string): void;
 /**
- * Intercepts the specified event on the passed object and prevents it from being called if the called `predicate` function returns a truthy value.
+ * 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.
  * This function should be called as soon as possible (I recommend using `@run-at document-start`), as it will only intercept events that are added after this function is called.
  * Calling this function will set the `Error.stackTraceLimit` to 1000 to ensure the stack trace is preserved.
  */
-export declare function interceptEvent<TEvtObj extends EventTarget, TPredicateEvt extends Event>(eventObject: TEvtObj, eventName: Parameters<TEvtObj["addEventListener"]>[0], predicate: (event: TPredicateEvt) => boolean): void;
+export declare function interceptEvent<TEvtObj extends EventTarget, TPredicateEvt extends Event>(eventObject: TEvtObj, eventName: Parameters<TEvtObj["addEventListener"]>[0], predicate?: (event: TPredicateEvt) => boolean): void;
 /**
- * Intercepts the specified event on the window object and prevents it from being called if the called `predicate` function returns a truthy value.
+ * Intercepts the specified event on the window 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.
  * This function should be called as soon as possible (I recommend using `@run-at document-start`), as it will only intercept events that are added after this function is called.
  * Calling this function will set the `Error.stackTraceLimit` to 1000 to ensure the stack trace is preserved.
  */
-export declare function interceptWindowEvent<TEvtKey extends keyof WindowEventMap>(eventName: TEvtKey, predicate: (event: WindowEventMap[TEvtKey]) => boolean): void;
+export declare function interceptWindowEvent<TEvtKey extends keyof WindowEventMap>(eventName: TEvtKey, predicate?: (event: WindowEventMap[TEvtKey]) => boolean): void;
+/** An object which contains the results of {@linkcode amplifyMedia()} */
+export type AmplifyMediaResult = ReturnType<typeof amplifyMedia>;
 /**
- * Amplifies the gain of the passed media element's audio by the specified multiplier.
- * Also applies a limiter to prevent clipping and distortion.
+ * Amplifies the gain of the passed media element's audio by the specified value.
  * This function supports any MediaElement instance like `<audio>` or `<video>`
  *
  * This is the audio processing workflow:
- * `MediaElement (source)` => `DynamicsCompressorNode (limiter)` => `GainNode` => `AudioDestinationNode (output)`
+ * `MediaElement (source)` => `GainNode (amplification)` => `destination`
  *
  * ⚠️ This function has to be run in response to a user interaction event, else the browser will reject it because of the strict autoplay policy.
  * ⚠️ Make sure to call the returned function `enable()` after calling this function to actually enable the amplification.
+ * ⚠️ You should implement a safety limit by using the [`clamp()`](https://github.com/Sv443-Network/UserUtils#clamp) function to prevent any accidental bleeding eardrums.
  *
  * @param mediaElement The media element to amplify (e.g. `<audio>` or `<video>`)
- * @param initialMultiplier The initial gain multiplier to apply (floating point number, default is `1.0`)
+ * @param initialGain The initial gain to apply to the GainNode responsible for volume amplification (floating point number, default is `1.0`)
  * @returns Returns an object with the following properties:
+ * **Important properties:**
  * | Property | Description |
  * | :-- | :-- |
- * | `setGain()` | Used to change the gain multiplier |
- * | `getGain()` | Returns the current gain multiplier |
- * | `enable()` | Call to enable the amplification for the first time or if it was disabled before |
+ * | `enable()` | Call to enable the amplification for the first time or re-enable it if it was disabled before |
  * | `disable()` | Call to disable amplification |
- * | `setLimiterOptions()` | Used for changing the [options of the 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 }` |
+ * | `enabled` | Whether the amplification is currently enabled |
+ * | `setGain()` | Used to change the gain value from the default given by the parameter {@linkcode initialGain} |
+ * | `getGain()` | Returns the current gain value |
+ *
+ * **Other properties:**
+ * | Property | Description |
+ * | :-- | :-- |
  * | `context` | The AudioContext instance |
- * | `source` | The MediaElementSourceNode instance |
- * | `gainNode` | The GainNode instance |
- * | `limiterNode` | The DynamicsCompressorNode instance used for limiting clipping and distortion |
+ * | `sourceNode` | A MediaElementSourceNode instance created from the passed {@linkcode mediaElement} |
+ * | `gainNode` | The GainNode instance used for volume amplification |
  */
-export declare function amplifyMedia<TElem extends HTMLMediaElement>(mediaElement: TElem, initialMultiplier?: number): {
-    /** Sets the gain multiplier */
-    setGain(multiplier: number): void;
-    /** Returns the current gain multiplier */
+export declare function amplifyMedia<TElem extends HTMLMediaElement>(mediaElement: TElem, initialGain?: number): {
+    context: AudioContext;
+    sourceNode: MediaElementAudioSourceNode;
+    gainNode: GainNode;
+    /** Sets the gain of the amplifying GainNode */
+    setGain(gain: number): void;
+    /** Returns the current gain of the amplifying GainNode */
     getGain(): number;
+    /** Whether the amplification is currently enabled */
+    enabled: boolean;
     /** Enable the amplification for the first time or if it was disabled before */
     enable(): void;
     /** Disable the amplification */
     disable(): void;
-    /**
-     * 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: Partial<Record<"threshold" | "knee" | "ratio" | "attack" | "release", number>>): void;
-    context: AudioContext;
-    source: MediaElementAudioSourceNode;
-    gainNode: GainNode;
-    limiterNode: DynamicsCompressorNode;
 };
-/** An object which contains the results of `amplifyMedia()` */
-export type AmplifyMediaResult = ReturnType<typeof amplifyMedia>;
 /** Checks if an element is scrollable in the horizontal and vertical directions */
 export declare function isScrollable(element: Element): {
     vertical: boolean;

package/dist/lib/index.d.ts

@@ -1,7 +1,7 @@
 export * from "./array";
-export * from "./config";
+export * from "./ConfigManager";
 export * from "./dom";
 export * from "./math";
 export * from "./misc";
-export * from "./onSelector";
+export * from "./SelectorObserver";
 export * from "./translation";

package/dist/lib/math.d.ts

@@ -1,11 +1,18 @@
-/** Ensures the passed `value` always stays between `min` and `max` */
+/** Ensures the passed {@linkcode value} always stays between {@linkcode min} and {@linkcode max} */
 export declare function clamp(value: number, min: number, max: number): number;
 /**
- * Transforms the value parameter from the numerical range `range_1_min-range_1_max` to the numerical range `range_2_min-range_2_max`
+ * Transforms the value parameter from the numerical range `range1min─range1max` to the numerical range `range2min─range2max`
  * For example, you can map the value 2 in the range of 0-5 to the range of 0-10 and you'd get a 4 as a result.
  */
-export declare function mapRange(value: number, range_1_min: number, range_1_max: number, range_2_min: number, range_2_max: number): number;
-/** Returns a random number between `min` and `max` (inclusive) */
+export declare function mapRange(value: number, range1min: number, range1max: number, range2min: number, range2max: number): number;
+/** Returns a random number between {@linkcode min} and {@linkcode max} (inclusive) */
 export declare function randRange(min: number, max: number): number;
-/** Returns a random number between 0 and `max` (inclusive) */
+/** Returns a random number between 0 and {@linkcode max} (inclusive) */
 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
+ * @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.)
+ */
+export declare function randomId(length?: number, radix?: number): string;