@sv443-network/userutils 2.0.1 → 4.0.0

package/README.md

@@ -1,23 +1,29 @@
 <div style="text-align: center;" align="center">
 
+<!-- #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.  
   
-Contains builtin TypeScript declarations. Webpack compatible and supports ESM and CJS.  
+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)
 
+<br>
+<sub>
+
+View the documentation of previous major releases: [3.0.0](https://github.com/Sv443-Network/UserUtils/blob/v3.0.0/README.md), [2.0.1](https://github.com/Sv443-Network/UserUtils/blob/v2.0.1/README.md), [1.2.0](https://github.com/Sv443-Network/UserUtils/blob/v1.2.0/README.md), [0.5.3](https://github.com/Sv443-Network/UserUtils/blob/v0.5.3/README.md)
+
+</sub>
 </div>
 <br>
 
+<!-- #MARKER Table of Contents -->
 ## Table of Contents:
 - [**Installation**](#installation)
-- [**Preamble**](#preamble)
+- [**Preamble** (info about the documentation)](#preamble)
 - [**License**](#license)
 - [**Features**](#features)
   - [**DOM:**](#dom)
-    - [onSelector()](#onselector) - call a listener once a selector is found in the DOM
-    - [initOnSelector()](#initonselector) - needs to be called once to be able to use `onSelector()`
-    - [getSelectorMap()](#getselectormap) - returns all currently registered selectors, listeners and options
+    - [SelectorObserver](#selectorobserver) - class that manages listeners that are called when selectors are found in the DOM
     - [getUnsafeWindow()](#getunsafewindow) - get the unsafeWindow object or fall back to the regular window object
     - [insertAfter()](#insertafter) - insert an element as a sibling after another element
     - [addParent()](#addparent) - add a parent element around another element
@@ -26,19 +32,21 @@ If you like using this library, please consider [supporting the development ❤
     - [openInNewTab()](#openinnewtab) - open a link in a new tab
     - [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
-    - [amplifyMedia()](#amplifymedia) - amplify an audio or video element's volume past the maximum of 100%
     - [isScrollable()](#isscrollable) - check if an element has a horizontal or vertical scroll bar
   - [**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
     - [randRange()](#randrange) - generate a random number between a min and max boundary
+    - [randomId()](#randomid) - generate a random ID of a given length and radix
   - [**Misc:**](#misc)
-    - [ConfigManager()](#configmanager) - class that manages persistent userscript configurations, including data migration
+    - [ConfigManager](#configmanager) - class that manages persistent userscript configurations, including data migration
     - [autoPlural()](#autoplural) - automatically pluralize a string
     - [pauseFor()](#pausefor) - pause the execution of a function for a given amount of time
     - [debounce()](#debounce) - call a function only once, after a given amount of time
     - [fetchAdvanced()](#fetchadvanced) - wrapper around the fetch API with a timeout option
     - [insertValues()](#insertvalues) - insert values into a string at specified placeholders
+    - [compress()](#compress) - compress a string with Gzip or Deflate
+    - [decompress()](#decompress) - decompress a previously compressed string
   - [**Arrays:**](#arrays)
     - [randomItem()](#randomitem) - returns a random item from an array
     - [randomItemIndex()](#randomitemindex) - returns a tuple of a random item and its index from an array
@@ -51,9 +59,13 @@ If you like using this library, please consider [supporting the development ❤
     - [tr.getLanguage()](#trgetlanguage) - returns the currently active language
   - [**Utility types for TypeScript:**](#utility-types)
     - [Stringifiable](#stringifiable) - any value that is a string or can be converted to one (implicitly or explicitly)
+    - [NonEmptyArray](#nonemptyarray) - any array that should have at least one item
+    - [NonEmptyString](#nonemptystring) - any string that should have at least one character
+    - [LooseUnion](#looseunion) - a union that gives autocomplete in the IDE but also allows any other value of the same type
 
 <br><br>
 
+<!-- #MARKER Installation -->
 ## Installation:
 - If you are using a bundler like webpack, you can install this package using npm:
   ```
@@ -75,7 +87,11 @@ If you like using this library, please consider [supporting the development ❤
   ```
   // @require https://greasyfork.org/scripts/472956-userutils/code/UserUtils.js
   ```
-
+  ```
+  // @require https://openuserjs.org/src/libs/Sv443/UserUtils.js
+  ```
+  (in order for your userscript not to break on a major library update, use the versioned URL at the top of the [GreasyFork page](https://greasyfork.org/scripts/472956-userutils))  
+    
   Then, access the functions on the global variable `UserUtils`:
   ```ts
   UserUtils.addGlobalStyle("body { background-color: red; }");
@@ -88,164 +104,316 @@ If you like using this library, please consider [supporting the development ❤
 
 <br><br>
 
+<!-- #MARKER Preamble -->
 ## Preamble:
 This library is written in TypeScript and contains builtin TypeScript declarations.  
   
 Each feature has example code that can be expanded by clicking on the text "Example - click to view".  
-The usages and examples are written in TypeScript, but the library can also be used in plain JavaScript after removing the type annotations (and changing the imports if you are using CommonJS).  
-If the usage section contains multiple definitions of the function, each occurrence represents an overload and you can choose which one you want to use.  
+The usages and examples are written in TypeScript and use ESM import syntax, but the library can also be used in plain JavaScript after removing the type annotations (and changing the imports if you are using CommonJS or the global declaration).  
+If the usage section contains multiple usages of the function, each occurrence represents an overload and you can choose which one you want to use.  
   
 Some features require the `@run-at` or `@grant` directives to be tweaked in the userscript header or have other requirements.  
 Their documentation will contain a section marked by a warning emoji (⚠️) that will go into more detail.
 
 <br><br>
 
+<!-- #MARKER License -->
 ## License:
 This library is licensed under the MIT License.  
 See the [license file](./LICENSE.txt) for details.
 
 <br><br>
 
+<!-- #MARKER Features -->
 ## Features:
 
 <br>
 
+<!-- #SECTION DOM -->
 ## DOM:
 
-### onSelector()
+### SelectorObserver
 Usage:  
 ```ts
-onSelector<TElement = HTMLElement>(selector: string, options: {
-  listener: (elements: TElement | NodeListOf<TElement>) => void,
-  all?: boolean,
-  continuous?: boolean,
-}): void
+new SelectorObserver(baseElement: Element, options?: SelectorObserverOptions)
+new SelectorObserver(baseElementSelector: string, options?: SelectorObserverOptions)
 ```
+
+A class that manages listeners that are called when elements at given selectors are found in the DOM.  
+This is useful for userscripts that need to wait for elements to be added to the DOM at an indeterminate point in time before they can be interacted with.  
   
-Registers a listener to be called whenever the element(s) behind a selector is/are found in the DOM.  
-If the selector already exists, the listener will be called immediately.  
+The constructor takes a `baseElement`, which is a parent of the elements you want to observe.  
+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"] }`  
+Additionally, there are the following extra options:
+- `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)
   
-If `all` is set to `true`, querySelectorAll() will be used instead and the listener will return a NodeList of matching elements.  
-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.  
+⚠️ 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.
+
+<br>
+
+#### Methods:
+`addListener<TElement = HTMLElement>(selector: string, options: SelectorListenerOptions): void`  
+Adds a listener (specified in `options.listener`) for the given selector that will be called once the selector exists in the DOM. It will be passed the element(s) that match the selector as the only argument.  
+The listener will be called immediately if the selector already exists in the DOM.  
+
+> `options.listener` is the only required property of the `options` object.  
+> It is a function that will be called once the selector exists in the DOM.  
+> It will be passed the found element or NodeList of elements, depending on if `options.all` is set to true or false.
   
-If `continuous` is set to `true`, the listener will not be deregistered after it was called once (defaults to false).  
+> If `options.all` is set to true, querySelectorAll() will be used instead and the listener will be passed a `NodeList` of matching elements.  
+> 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.
   
-When using TypeScript, the generic `TElement` can be used to specify the type of the element(s) that the listener will return.  
-It will default to `HTMLElement` if left undefined.  
+> If `options.continuous` is set to true, the 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 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.
   
-⚠️ In order to use this function, [`initOnSelector()`](#initonselector) has to be called as soon as possible.  
-This initialization function has to be called after `DOMContentLoaded` is fired (or immediately if `@run-at document-end` is set).  
+> 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.
   
-Calling onSelector() before `DOMContentLoaded` is fired will not throw an error, but it also won't trigger listeners until the DOM is accessible.
+> When using TypeScript, the generic `TElement` can be used to specify the type of the element(s) that the listener will return.  
+> It will default to HTMLElement if left undefined.
   
-<details><summary><b>Example - click to view</b></summary>
-
-```ts
-import { initOnSelector, onSelector } from "@sv443-network/userutils";
-
-document.addEventListener("DOMContentLoaded", initOnSelector);
+<br>
 
-// Continuously checks if `div` elements are added to the DOM, then returns all of them (even previously detected ones) in a NodeList
-onSelector<HTMLDivElement>("div", {
-  listener: (elements) => {
-    console.log("Elements found:", elements); // type = NodeListOf<HTMLDivElement>
-  },
-  all: true,
-  continuous: true,
-});
+`enable(immediatelyCheckSelectors?: boolean): boolean`  
+Enables the observation of the child elements for the first time or if it was disabled before.  
+`immediatelyCheckSelectors` is set to true by default, which means all previously registered selectors will be checked. Set to false to only check them on the first detected mutation.  
+Returns true if the observation was enabled, false if it was already enabled or the passed `baseElementSelector` couldn't be found.  
+  
+<br>
 
-// Checks if an input element with a value attribute of "5" is added to the DOM, then returns it and deregisters the listener
-onSelector<HTMLInputElement>("input[value=\"5\"]", {
-  listener: (element) => {
-    console.log("Element found:", element); // type = HTMLInputElement
-  },
-});
-```
+`disable(): void`  
+Disables the observation of the child elements.  
+If selectors are currently being checked, the current selector will be finished before disabling.  
+  
+<br>
 
-</details>
+`isEnabled(): boolean`  
+Returns whether the observation of the child elements is currently enabled.  
+  
+<br>
 
+`clearListeners(): void`  
+Removes all listeners for all selectors.  
+  
 <br>
 
-### initOnSelector()
-Usage:  
-```ts
-initOnSelector(options?: MutationObserverInit): void
-```
+`removeAllListeners(selector: string): boolean`  
+Removes all listeners for the given selector.  
   
-Initializes the MutationObserver that is used by [`onSelector()`](#onselector) to check for the registered selectors whenever a DOM change occurs on the `<body>`  
-By default, this only checks if elements are added or removed (at any depth).  
+<br>
 
-⚠️ This function needs to be run after the DOM has loaded (when using `@run-at document-end` or after `DOMContentLoaded` has fired).  
+`removeListener(selector: string, options: SelectorListenerOptions): boolean`  
+Removes a specific listener for the given selector and options.  
   
-The options object is passed directly to the MutationObserver.observe() method.  
-Note that `options.subtree` and `options.childList` will be set to true by default.  
-You may see all options [here](https://developer.mozilla.org/en-US/docs/Web/API/MutationObserver/observe#options), but these are the important ones:  
-> Set `options.attributes` to `true` to also check for attribute changes on every single descendant of the `<body>` (defaults to false).  
-> Set `options.characterData` to `true` to also check for character data changes on every single descendant of the `<body>` (defaults to false).  
->   
-> ⚠️ Using these extra options can have a performance impact on larger sites or sites with a constantly changing DOM.
+<br>
+
+`getAllListeners(): Map<string, SelectorListenerOptions[]>`  
+Returns a Map of all selectors and their listeners.  
   
-<details><summary><b>Example - click to view</b></summary>
+<br>
+
+`getListeners(selector: string): SelectorListenerOptions[] | undefined`  
+Returns all listeners for the given selector or undefined if there are none.  
+
+<br>
+
+<details><summary><b>Examples - click to view</b></summary>
+
+#### Basic usage:
 
 ```ts
-import { initOnSelector } from "@sv443-network/userutils";
+import { SelectorObserver } from "@sv443-network/userutils";
+
+// adding a single-shot listener before the element exists:
+const fooObserver = new SelectorObserver("body");
+
+fooObserver.addListener("#my-element", {
+  listener: (element) => {
+    console.log("Element found:", element);
+  },
+});
 
 document.addEventListener("DOMContentLoaded", () => {
-  initOnSelector({
-    attributes: true,
-    characterData: true,
+  // starting observation after the <body> element is available:
+  fooObserver.enable();
+
+
+  // adding custom observer options:
+
+  const barObserver = new SelectorObserver(document.body, {
+    // only check if the following attributes change:
+    attributeFilter: ["class", "style", "data-whatever"],
+    // debounce all listeners by 100ms unless specified otherwise:
+    defaultDebounce: 100,
   });
+
+  barObserver.addListener("#my-element", {
+    listener: (element) => {
+      console.log("Element's attributes changed:", element);
+    },
+  });
+
+  barObserver.addListener("#my-other-element", {
+    // set the debounce higher than provided by the defaultDebounce property:
+    debounce: 250,
+    listener: (element) => {
+      console.log("Other element's attributes changed:", element);
+    },
+  });
+
+  barObserver.enable();
+
+
+  // using custom listener options:
+
+  const bazObserver = new SelectorObserver(document.body);
+
+  // for TypeScript, specify that input elements are returned by the listener:
+  bazObserver.addListener<HTMLInputElement>("input", {
+    all: true,        // use querySelectorAll() instead of querySelector()
+    continuous: true, // don't remove the listener after it was called once
+    debounce: 50,     // debounce the listener by 50ms
+    listener: (elements) => {
+      // type of `elements` is NodeListOf<HTMLInputElement>
+      console.log("Input elements found:", elements);
+    },
+  });
+
+  bazObserver.enable();
+
+
+  // use a different element as the base:
+
+  const myElement = document.querySelector("#my-element");
+  if(myElement) {
+    const quxObserver = new SelectorObserver(myElement);
+
+    quxObserver.addListener("#my-child-element", {
+      listener: (element) => {
+        console.log("Child element found:", element);
+      },
+    });
+
+    quxObserver.enable();
+  }
 });
 ```
 
-</details>
-
 <br>
 
-### getSelectorMap()
-Usage:  
+#### Get and remove listeners:
+
 ```ts
-getSelectorMap(): Map<string, OnSelectorOptions[]>
+import { SelectorObserver } from "@sv443-network/userutils";
+
+document.addEventListener("DOMContentLoaded", () => {
+  const observer = new SelectorObserver(document.body);
+
+  observer.addListener("#my-element-foo", {
+    continuous: true,
+    listener: (element) => {
+      console.log("Element found:", element);
+    },
+  });
+
+  observer.addListener("#my-element-bar", {
+    listener: (element) => {
+      console.log("Element found again:", element);
+    },
+  });
+
+  observer.enable();
+
+
+  // get all listeners:
+
+  console.log(observer.getAllListeners());
+  // Map(2) {
+  //   '#my-element-foo' => [ { listener: [Function: listener] } ],
+  //   '#my-element-bar' => [ { listener: [Function: listener] } ]
+  // }
+
+
+  // get listeners for a specific selector:
+
+  console.log(observer.getListeners("#my-element-foo"));
+  // [ { listener: [Function: listener], continuous: true } ]
+
+
+  // remove all listeners for a specific selector:
+
+  observer.removeAllListeners("#my-element-foo");
+  console.log(observer.getAllListeners());
+  // Map(1) {
+  //   '#my-element-bar' => [ { listener: [Function: listener] } ]
+  // }
+});
 ```
-  
-Returns a Map of all currently registered selectors and their options, including listener function.  
-Since multiple listeners can be registered for the same selector, the value of the Map is an array of `OnSelectorOptions` objects.  
-  
-<details><summary><b>Example - click to view</b></summary>
+
+<br>
+
+#### Chaining:
 
 ```ts
-import { initOnSelector, onSelector, getSelectorMap } from "@sv443-network/userutils";
+import { SelectorObserver } from "@sv443-network/userutils";
+import type { SelectorObserverOptions } from "@sv443-network/userutils";
 
-document.addEventListener("DOMContentLoaded", initOnSelector);
+// apply a default debounce to all SelectorObserver instances:
+const defaultOptions: SelectorObserverOptions = {
+  defaultDebounce: 100,
+};
 
-onSelector<HTMLDivElement>("div", {
-  listener: (elements) => void 0,
-  all: true,
-  continuous: true,
-});
+document.addEventListener("DOMContentLoaded", () => {
+  // initialize generic observer that in turn initializes "sub-observers":
+  const fooObserver = new SelectorObserver(document.body, {
+    ...defaultOptions,
+    // define any other specific options here
+  });
 
-onSelector<HTMLDivElement>("div", {
-  listener: (elements) => void 0,
-});
+  const myElementSelector = "#my-element";
 
-const selectorMap = getSelectorMap();
-// Map(1) {
-//   "div" => [
-//     {
-//       listener: (elements) => void 0,
-//       all: true,
-//       continuous: true,
-//     },
-//     {
-//       listener: (elements) => void 0,
-//     },
-//   ]
-// }
+  // this relatively expensive listener (as it is in the full <body> scope) will only fire once:
+  fooObserver.addListener(myElementSelector, {
+    listener: (element) => {
+      // only enable barObserver once its baseElement exists:
+      barObserver.enable();
+    },
+  });
+
+  // barObserver is created at the same time as fooObserver, but only enabled once #my-element exists
+  const barObserver = new SelectorObserver(element, {
+    ...defaultOptions,
+    // define any other specific options here
+  });
+
+  // this selector will be checked for immediately after `enable()` is called
+  // and on each subsequent mutation because `continuous` is set to true.
+  // however it is much less expensive as it is scoped to a lower element which will receive less DOM updates
+  barObserver.addListener(".my-child-element", {
+    all: true,
+    continuous: true,
+    listener: (elements) => {
+      console.log("Child elements found:", elements);
+    },
+  });
+
+  // immediately enable fooObserver as the <body> is available as soon as "DOMContentLoaded" fires:
+  fooObserver.enable();
+});
 ```
 
 </details>
 
+
 <br>
 
 ### getUnsafeWindow()
@@ -383,6 +551,9 @@ preloadImages([
 ], true)
   .then((results) => {
     console.log("Images preloaded. Results:", results);
+  })
+  .catch((results) => {
+    console.error("Couldn't preload all images. Results:", results);
   });
 ```
 
@@ -422,11 +593,12 @@ Usage:
 interceptEvent(
   eventObject: EventTarget,
   eventName: string,
-  predicate: (event: Event) => boolean
+  predicate?: (event: Event) => boolean
 ): void
 ```
   
 Intercepts all events dispatched on the `eventObject` and prevents the listeners from being called as long as the predicate function returns a truthy value.  
+If no predicate is specified, all events will be discarded.  
 Calling this function will set the `Error.stackTraceLimit` to 1000 (if it's not already higher) to ensure the stack trace is preserved.  
   
 ⚠️ This function should be called as soon as possible (I recommend using `@run-at document-start`), as it will only intercept events that are *attached* after this function is called.  
@@ -437,8 +609,12 @@ Calling this function will set the `Error.stackTraceLimit` to 1000 (if it's not
 import { interceptEvent } from "@sv443-network/userutils";
 
 interceptEvent(document.body, "click", (event) => {
-  console.log("Intercepting click event:", event);
-  return true; // prevent all click events on the body element
+  // prevent all click events on <a> elements within the entire <body>
+  if(event.target instanceof HTMLAnchorElement) {
+    console.log("Intercepting click event:", event);
+    return true;
+  }
+  return false; // allow all other click events through
 });
 ```
 
@@ -451,11 +627,12 @@ Usage:
 ```ts
 interceptWindowEvent(
   eventName: string,
-  predicate: (event: Event) => boolean
+  predicate?: (event: Event) => boolean
 ): void
 ```
   
 Intercepts all events dispatched on the `window` object and prevents the listeners from being called as long as the predicate function returns a truthy value.  
+If no predicate is specified, all events will be discarded.  
 This is essentially the same as [`interceptEvent()`](#interceptevent), but automatically uses the `unsafeWindow` (or falls back to regular `window`).  
   
 ⚠️ This function should be called as soon as possible (I recommend using `@run-at document-start`), as it will only intercept events that are *attached* after this function is called.  
@@ -466,111 +643,9 @@ This is essentially the same as [`interceptEvent()`](#interceptevent), but autom
 ```ts
 import { interceptWindowEvent } from "@sv443-network/userutils";
 
-interceptWindowEvent("beforeunload", (event) => {
-  return true; // prevent the pesky "Are you sure you want to leave this page?" popup
-});
-```
-
-</details>
-
-<br>
-
-### amplifyMedia()
-Usage:  
-```ts
-amplifyMedia(mediaElement: HTMLMediaElement, initialMultiplier?: number): AmplifyMediaResult
-```
-  
-Amplifies the gain of a media element (like `<audio>` or `<video>`) by a given multiplier (defaults to 1.0).  
-This is how you can increase the volume of a media element beyond the default maximum volume of 1.0 or 100%.  
-Make sure to limit the multiplier to a reasonable value ([clamp()](#clamp) is good for this), as it may cause bleeding eardrums.  
-  
-This is the processing workflow applied to the media element:  
-`MediaElement (source)` => `DynamicsCompressorNode (limiter)` => `GainNode` => `AudioDestination (output)`  
-  
-A limiter (compression) is applied to the audio to prevent clipping.  
-Its properties can be changed by calling the returned function `setLimiterOptions()`  
-The limiter options set by default are `{ threshold: -12, knee: 30, ratio: 12, attack: 0.003, release: 0.25 }`  
-  
-⚠️ 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.  
-  
-The returned object of the type `AmplifyMediaResult` has the following 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 |
-| `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: -12, knee: 30, ratio: 12, attack: 0.003, release: 0.25 }` |
-| `context` | The AudioContext instance |
-| `source` | The MediaElementSourceNode instance |
-| `gainNode` | The GainNode instance used for actually boosting the gain |
-| `limiterNode` | The DynamicsCompressorNode instance used for limiting clipping and distortion |
-  
-<details><summary><b>Example - click to view</b></summary>
-
-```ts
-import { amplifyMedia, clamp } from "@sv443-network/userutils";
-import type { AmplifyMediaResult } from "@sv443-network/userutils";
-
-const audioElement = document.querySelector<HTMLAudioElement>("audio");
-
-let ampResult: AmplifyMediaResult | undefined;
-
-function setGain(newValue: number) {
-  if(!ampResult)
-    return;
-  // constrain the value to between 0 and 3 for safety
-  ampResult.setGain(clamp(newValue, 0, 3));
-  console.log("Gain set to", ampResult.getGain());
-}
-
-
-const amplifyButton = document.querySelector<HTMLButtonElement>("button#amplify");
-
-// amplifyMedia() needs to be called in response to a user interaction event:
-amplifyButton.addEventListener("click", () => {
-  // only needs to be initialized once, afterwards the returned object
-  // can be used to change settings and enable/disable the amplification
-  if(!ampResult) {
-    // initialize amplification and set gain to 2x
-    ampResult = amplifyMedia(audioElement, 2);
-    // enable the amplification
-    ampResult.enable();
-  }
-
-  setGain(2.5);  // set gain to 2.5x
-
-  console.log(ampResult.getGain()); // 2.5
-});
-
-
-const disableButton = document.querySelector<HTMLButtonElement>("button#disable");
-
-disableButton.addEventListener("click", () => {
-  if(ampResult) {
-    // disable the amplification
-    ampResult.disable();
-  }
-});
-
-
-const limiterButton = document.querySelector<HTMLButtonElement>("button#limiter");
-
-limiterButton.addEventListener("click", () => {
-  if(ampResult) {
-    // change the limiter options to a more aggressive setting
-    // see https://developer.mozilla.org/en-US/docs/Web/API/DynamicsCompressorNode/DynamicsCompressorNode#options
-    ampResult.setLimiterOptions({
-      threshold: -10,
-      knee: 20,
-      ratio: 20,
-      attack: 0.001,
-      release: 0.1,
-    });
-  }
-});
+// prevent the pesky "Are you sure you want to leave this page?" popup
+// as no predicate is specified, all events will be discarded by default
+interceptWindowEvent("beforeunload");
 ```
 
 </details>
@@ -602,6 +677,7 @@ console.log("Element has a vertical scroll bar:", vertical);
 
 <br><br>
 
+<!-- #SECTION Math -->
 ## Math:
 
 ### clamp()
@@ -636,10 +712,10 @@ Usage:
 ```ts
 mapRange(
   value: number,
-  range_1_min: number,
-  range_1_max: number,
-  range_2_min: number,
-  range_2_max: number
+  range1min: number,
+  range1max: number,
+  range2min: number,
+  range2max: number
 ): number
 ```
   
@@ -684,11 +760,39 @@ randRange(10);     // 7
 
 </details>
 
+<br>
+
+### randomId()
+Usage:  
+```ts
+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)  
+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.  
+  
+<details><summary><b>Example - click to view</b></summary>
+
+```ts
+import { randomId } from "@sv443-network/userutils";
+
+randomId();       // "1bda419a73629d4f" (length 16, radix 16)
+randomId(10);     // "f86cd354a4"       (length 10, radix 16)
+randomId(10, 2);  // "1010001101"       (length 10, radix 2)
+randomId(10, 10); // "0183428506"       (length 10, radix 10)
+randomId(10, 36); // "z46jfpa37r"       (length 10, radix 36)
+```
+
+</details>
+
 <br><br>
 
+<!-- #SECTION Misc -->
 ## Misc:
 
-### ConfigManager()
+### ConfigManager
 Usage:  
 ```ts
 new ConfigManager(options: ConfigManagerOptions)
@@ -711,7 +815,7 @@ The options object has the following properties:
 
 <br>
 
-### Methods:
+#### Methods:
 `loadData(): Promise<TData>`  
 Asynchronously loads the configuration data from persistent storage and returns it.  
 If no data was saved in persistent storage before, the value of `options.defaultConfig` will be returned and written to persistent storage.  
@@ -927,8 +1031,109 @@ fetchAdvanced("https://jokeapi.dev/joke/Any?safe-mode", {
 
 </details>
 
+<br>
+
+### insertValues()
+Usage:  
+```ts
+insertValues(input: string, ...values: Stringifiable[]): string
+```
+  
+Inserts values into a string in the format `%n`, where `n` is the number of the value, starting at 1.  
+The values will be stringified using `toString()` (see [Stringifiable](#stringifiable)) before being inserted into the input string.  
+If not enough values are passed, the remaining placeholders will be left untouched.  
+  
+<details><summary><b>Example - click to view</b></summary>
+
+```ts
+import { insertValues } from "@sv443-network/userutils";
+
+insertValues("Hello, %1!", "World");                        // "Hello, World!"
+insertValues("Hello, %1! My name is %2.", "World", "John"); // "Hello, World! My name is John."
+insertValues("Testing %1", { toString: () => "foo" });      // "Testing foo"
+
+// using an array for the values and not passing enough arguments:
+const values = ["foo", "bar", "baz"];
+insertValues("Testing %1, %2, %3 and %4", ...values); // "Testing foo, bar and baz and %4"
+```
+
+</details>
+
+<br>
+
+### compress()
+Usage:  
+```ts
+compress(input: string | ArrayBuffer, compressionFormat: CompressionFormat, outputType?: "base64"): Promise<string>
+compress(input: string | ArrayBuffer, compressionFormat: CompressionFormat, outputType: "arrayBuffer"): Promise<ArrayBuffer>
+```
+  
+Compresses a string or ArrayBuffer using the specified compression format. Most browsers should support at least `gzip` and `deflate`  
+The `outputType` dictates which format the output will be in. It will default to `base64` if left undefined.  
+  
+⚠️ You need to provide the `@grant unsafeWindow` directive if you are using the `base64` output type or you will get a TypeError.  
+⚠️ Not all browsers might support compression. Please check [on this page](https://developer.mozilla.org/en-US/docs/Web/API/CompressionStream#browser_compatibility) for compatibility and supported compression formats.  
+  
+<details><summary><b>Example - click to view</b></summary>
+
+```ts
+import { compress } from "@sv443-network/userutils";
+
+// using gzip:
+
+const fooGz = await compress("Hello, World!", "gzip");
+const barGz = await compress("Hello, World!".repeat(20), "gzip");
+
+// not as efficient with short strings but can save quite a lot of space with larger strings:
+console.log(fooGz); // "H4sIAAAAAAAAE/NIzcnJ11EIzy/KSVEEANDDSuwNAAAA"
+console.log(barGz); // "H4sIAAAAAAAAE/NIzcnJ11EIzy/KSVH0GJkcAKOPcmYEAQAA"
+
+// depending on the type of data you might want to use a different compression format like deflate:
+
+const fooDeflate = await compress("Hello, World!", "deflate");
+const barDeflate = await compress("Hello, World!".repeat(20), "deflate");
+
+// again, it's not as efficient initially but gets better with longer inputs:
+console.log(fooDeflate); // "eJzzSM3JyddRCM8vyklRBAAfngRq"
+console.log(barDeflate); // "eJzzSM3JyddRCM8vyklR9BiZHAAIEVg1"
+```
+
+</details>
+
+<br>
+
+### decompress()
+Usage:  
+```ts
+decompress(input: string | ArrayBuffer, compressionFormat: CompressionFormat, outputType?: "string"): Promise<string>
+decompress(input: string | ArrayBuffer, compressionFormat: CompressionFormat, outputType: "arrayBuffer"): Promise<ArrayBuffer>
+```
+  
+Decompresses a string or ArrayBuffer that has been previously [compressed](#compress) using the specified compression format. Most browsers should support at least `gzip` and `deflate`  
+The `outputType` dictates which format the output will be in. It will default to `string` if left undefined.  
+  
+⚠️ You need to provide the `@grant unsafeWindow` directive if you are using the `string` output type or you will get a TypeError.  
+⚠️ Not all browsers might support decompression. Please check [on this page](https://developer.mozilla.org/en-US/docs/Web/API/DecompressionStream#browser_compatibility) for compatibility and supported compression formats.  
+  
+<details><summary><b>Example - click to view</b></summary>
+
+```ts
+import { compress, decompress } from "@sv443-network/userutils";
+
+const compressed = await compress("Hello, World!".repeat(20), "gzip");
+
+console.log(compressed); // "H4sIAAAAAAAAE/NIzcnJ11EIzy/KSVH0GJkcAKOPcmYEAQAA"
+
+const decompressed = await decompress(compressed, "gzip");
+
+console.log(decompressed); // "Hello, World!"
+```
+
+</details>
+
 <br><br>
 
+<!-- #SECTION Arrays -->
 ## Arrays:
 
 ### randomItem()
@@ -1029,6 +1234,7 @@ console.log(foo); // [1, 2, 3, 4, 5, 6] - original array is not mutated
 
 <br><br>
 
+<!-- #SECTION Translation -->
 ## Translation:
 This is a very lightweight translation function that can be used to translate simple strings.  
 Pluralization is not supported but can be achieved manually by adding variations to the translations, identified by a different suffix. See the example section of [`tr.addLanguage()`](#traddlanguage) for an example on how this might be done.
@@ -1204,6 +1410,7 @@ If no language has been set yet, it will return undefined.
 
 <br><br>
 
+<!-- #SECTION Utility types -->
 ## Utility types:
 UserUtils also offers some utility types that can be used in TypeScript projects.  
 They don't alter the runtime behavior of the code, but they can be used to make the code more readable and to prevent errors.
@@ -1236,13 +1443,99 @@ logSomething(true);      // "Log: true"
 logSomething({});        // "Log: [object Object]"
 logSomething(Symbol(1)); // "Log: Symbol(1)"
 logSomething(fooObject); // "Log: hello world"
-logSomething(barObject); // type error
+
+logSomething(barObject); // Type Error
+```
+
+</details>
+
+<br>
+
+## NonEmptyArray
+Usage:
+```ts
+NonEmptyArray<TItem = unknown>
+```
+  
+This type describes an array that has at least one item.  
+Use the generic parameter to specify the type of the items in the array.  
+  
+<details><summary><b>Example - click to view</b></summary>
+
+```ts
+import type { NonEmptyArray } from "@sv443-network/userutils";
+
+function logFirstItem(array: NonEmptyArray<string>) {
+  console.log(parseInt(array[0]));
+}
+
+function somethingElse(array: NonEmptyArray) {
+  // array is typed as NonEmptyArray<unknown> when not passing a
+  // generic parameter, so this throws a TS error:
+  console.log(parseInt(array[0])); // Argument of type 'unknown' is not assignable to parameter of type 'string'
+}
+
+logFirstItem(["04abc", "69"]); // 4
+```
+
+</details>
+
+<br>
+
+## NonEmptyString
+Usage:
+```ts
+NonEmptyString<TString extends string>
+```
+  
+This type describes a string that has at least one character.  
+  
+<details><summary><b>Example - click to view</b></summary>
+
+```ts
+import type { NonEmptyString } from "@sv443-network/userutils";
+
+function convertToNumber<T extends string>(str: NonEmptyString<T>) {
+  console.log(parseInt(str));
+}
+
+convertToNumber("04abc"); // "4"
+convertToNumber("");      // type error: Argument of type 'string' is not assignable to parameter of type 'never'
+```
+
+</details>
+
+<br>
+
+## LooseUnion
+Usage:
+```ts
+LooseUnion<TUnion extends string | number | object>
+```
+  
+A type that offers autocomplete in the IDE for the passed union but also allows any value of the same type to be passed.  
+Supports unions of strings, numbers and objects.  
+  
+<details><summary><b>Example - click to view</b></summary>
+
+```ts
+function foo(bar: LooseUnion<"a" | "b" | "c">) {
+  console.log(bar);
+}
+
+// when typing the following, autocomplete suggests "a", "b" and "c"
+// foo("
+
+foo("a"); // included in autocomplete, no type error
+foo("");  // *not* included in autocomplete, still no type error
+foo(1);   // type error: Argument of type '1' is not assignable to parameter of type 'LooseUnion<"a" | "b" | "c">'
 ```
 
 </details>
 
 <br><br><br><br>
 
+<!-- #MARKER Footer -->
 <div style="text-align: center;" align="center">
 
 Made with ❤️ by [Sv443](https://github.com/Sv443)