@sv443-network/userutils 1.1.3 → 2.0.0

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # @sv443-network/userutils
 
+## 2.0.0
+
+### Major Changes
+
+- b53a946: Added compression to `amplifyMedia()` to prevent audio clipping and distortion and modified return type accordingly:
+  - Renamed: `amplify()` to `setGain()` and `getAmpLevel()` to `getGain()`
+  - Added properties: `enable()`, `disable()`, `setLimiterOptions()` and `limiterNode`
+  - Other changes: Amplification is no longer enabled automatically, `enable()` must now be called manually after initializing
+
+## 1.2.0
+
+### Minor Changes
+
+- 84b37f1: Added utility type Stringifiable to describe a string or any value that can be converted to one
+- 142c5e2: Added function insertValues() to insert values into a string with placeholders
+- 16ce257: Added lightweight translation system
+
 ## 1.1.3
 
 ### Patch Changes

package/README.md

@@ -14,7 +14,7 @@ If you like using this library, please consider [supporting the development ❤
 - [**Preamble**](#preamble)
 - [**License**](#license)
 - [**Features**](#features)
-  - [DOM:](#dom)
+  - [**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
@@ -28,21 +28,29 @@ If you like using this library, please consider [supporting the development ❤
     - [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)
+  - [**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
-  - [Misc:](#misc)
+  - [**Misc:**](#misc)
     - [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
-  - [Arrays:](#arrays)
+    - [insertValues()](#insertvalues) - insert values into a string at specified placeholders
+  - [**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
     - [takeRandomItem()](#takerandomitem) - returns a random item from an array and mutates it to remove the item
     - [randomizeArray()](#randomizearray) - returns a copy of the array with its items in a random order
+  - [**Translation:**](#translation)
+    - [tr()](#tr) - simple translation of a string to another language
+    - [tr.addLanguage()](#traddlanguage) - add a language and its translations
+    - [tr.setLanguage()](#trsetlanguage) - set the currently active language for translations
+    - [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)
 
 <br><br>
 
@@ -131,7 +139,7 @@ This initialization function has to be called after `DOMContentLoaded` is fired
   
 Calling onSelector() before `DOMContentLoaded` is fired will not throw an error, but it also won't trigger listeners until the DOM is accessible.
   
-<details><summary><h4>Example - click to view</h4></summary>
+<details><summary><b>Example - click to view</b></summary>
 
 ```ts
 import { initOnSelector, onSelector } from "@sv443-network/userutils";
@@ -178,7 +186,7 @@ You may see all options [here](https://developer.mozilla.org/en-US/docs/Web/API/
 >   
 > ⚠️ Using these extra options can have a performance impact on larger sites or sites with a constantly changing DOM.
   
-<details><summary><h4>Example - click to view</h4></summary>
+<details><summary><b>Example - click to view</b></summary>
 
 ```ts
 import { initOnSelector } from "@sv443-network/userutils";
@@ -204,7 +212,7 @@ getSelectorMap(): Map<string, OnSelectorOptions[]>
 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><h4>Example - click to view</h4></summary>
+<details><summary><b>Example - click to view</b></summary>
 
 ```ts
 import { initOnSelector, onSelector, getSelectorMap } from "@sv443-network/userutils";
@@ -249,7 +257,7 @@ getUnsafeWindow(): Window
 Returns the unsafeWindow object or falls back to the regular window object if the `@grant unsafeWindow` is not given.  
 Userscripts are sandboxed and do not have access to the regular window object, so this function is useful for websites that reject some events that were dispatched by the userscript.  
   
-<details><summary><h4>Example - click to view</h4></summary>
+<details><summary><b>Example - click to view</b></summary>
 
 ```ts
 import { getUnsafeWindow } from "@sv443-network/userutils";
@@ -281,7 +289,7 @@ The passed `afterElement` will be returned.
   
 ⚠️ This function needs to be run after the DOM has loaded (when using `@run-at document-end` or after `DOMContentLoaded` has fired).  
   
-<details><summary><h4>Example - click to view</h4></summary>
+<details><summary><b>Example - click to view</b></summary>
 
 ```ts
 import { insertAfter } from "@sv443-network/userutils";
@@ -309,7 +317,7 @@ Previously registered event listeners are kept intact.
   
 ⚠️ This function needs to be run after the DOM has loaded (when using `@run-at document-end` or after `DOMContentLoaded` has fired).  
   
-<details><summary><h4>Example - click to view</h4></summary>
+<details><summary><b>Example - click to view</b></summary>
 
 ```ts
 import { addParent } from "@sv443-network/userutils";
@@ -335,7 +343,7 @@ addGlobalStyle(css: string): void
 Adds a global style to the page in form of a `<style>` element that's inserted into the `<head>`.  
 ⚠️ This function needs to be run after the DOM has loaded (when using `@run-at document-end` or after `DOMContentLoaded` has fired).  
   
-<details><summary><h4>Example - click to view</h4></summary>
+<details><summary><b>Example - click to view</b></summary>
 
 ```ts
 import { addGlobalStyle } from "@sv443-network/userutils";
@@ -363,7 +371,7 @@ Preloads images into browser cache by creating an invisible `<img>` element for
 The images will be loaded in parallel and the returned Promise will only resolve once all images have been loaded.  
 The resulting PromiseSettledResult array will contain the image elements if resolved, or an ErrorEvent if rejected, but only if `rejects` is set to true.  
   
-<details><summary><h4>Example - click to view</h4></summary>
+<details><summary><b>Example - click to view</b></summary>
 
 ```ts
 import { preloadImages } from "@sv443-network/userutils";
@@ -394,7 +402,7 @@ This function has to be run in response to a user interaction event, else the br
   
 ⚠️ This function needs to be run after the DOM has loaded (when using `@run-at document-end` or after `DOMContentLoaded` has fired).  
   
-<details><summary><h4>Example - click to view</h4></summary>
+<details><summary><b>Example - click to view</b></summary>
 
 ```ts
 import { openInNewTab } from "@sv443-network/userutils";
@@ -423,7 +431,7 @@ Calling this function will set the `Error.stackTraceLimit` to 1000 (if it's not
   
 ⚠️ 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.  
   
-<details><summary><h4>Example - click to view</h4></summary>
+<details><summary><b>Example - click to view</b></summary>
 
 ```ts
 import { interceptEvent } from "@sv443-network/userutils";
@@ -453,7 +461,7 @@ This is essentially the same as [`interceptEvent()`](#interceptevent), but autom
 ⚠️ 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.  
 ⚠️ In order for all events to be interceptable, the directive `@grant unsafeWindow` should be set.  
   
-<details><summary><h4>Example - click to view</h4></summary>
+<details><summary><b>Example - click to view</b></summary>
 
 ```ts
 import { interceptWindowEvent } from "@sv443-network/userutils";
@@ -470,47 +478,98 @@ interceptWindowEvent("beforeunload", (event) => {
 ### amplifyMedia()
 Usage:  
 ```ts
-amplifyMedia(mediaElement: HTMLMediaElement, multiplier?: number): AmplifyMediaResult
+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 clipping or bleeding eardrums.  
+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 default props are `{ threshold: -2, knee: 40, 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 AmplifyMediaResult object has the following properties:
+The returned object of the type `AmplifyMediaResult` has the following properties:
 | Property | Description |
 | :-- | :-- |
-| `mediaElement` | The passed media element |
-| `amplify()` | A function to change the amplification level |
-| `getAmpLevel()` | A function to return the current amplification level |
+| `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: -2, knee: 40, ratio: 12, attack: 0.003, release: 0.25 }` |
 | `context` | The AudioContext instance |
 | `source` | The MediaElementSourceNode instance |
-| `gain` | The GainNode instance |
+| `gainNode` | The GainNode instance used for actually boosting the gain |
+| `limiterNode` | The DynamicsCompressorNode instance used for limiting clipping and distortion |
   
-<details><summary><h4>Example - click to view</h4></summary>
+<details><summary><b>Example - click to view</b></summary>
 
 ```ts
-import { amplifyMedia } from "@sv443-network/userutils";
+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 audio = document.querySelector<HTMLAudioElement>("audio");
-const button = document.querySelector<HTMLButtonElement>("button");
+const amplifyButton = document.querySelector<HTMLButtonElement>("button#amplify");
 
-// amplifyMedia needs to be called in response to a user interaction event:
-button.addEventListener("click", () => {
-  const { amplify, getAmpLevel } = amplifyMedia(audio);
+// 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 setGain = (value: number) => {
-    // constrain the value to between 0 and 5
-    amplify(clamp(value, 0, 5));
-    console.log("Gain set to", getAmpLevel());
+
+const disableButton = document.querySelector<HTMLButtonElement>("button#disable");
+
+disableButton.addEventListener("click", () => {
+  if(ampResult) {
+    // disable the amplification
+    ampResult.disable();
   }
+});
 
-  setGain(2);    // set gain to 2x
-  setGain(3.5);  // set gain to 3.5x
 
-  console.log(getAmpLevel()); // 3.5
+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,
+    });
+  }
 });
 ```
 
@@ -527,7 +586,7 @@ isScrollable(element: Element): { horizontal: boolean, vertical: boolean }
 Checks if an element has a horizontal or vertical scroll bar.  
 This uses the computed style of the element, so it will also work if the element is hidden.  
   
-<details><summary><h4>Example - click to view</h4></summary>
+<details><summary><b>Example - click to view</b></summary>
 
 ```ts
 import { isScrollable } from "@sv443-network/userutils";
@@ -553,7 +612,7 @@ clamp(num: number, min: number, max: number): number
   
 Clamps a number between a min and max boundary (inclusive).  
   
-<details><summary><h4>Example - click to view</h4></summary>
+<details><summary><b>Example - click to view</b></summary>
 
 ```ts
 import { clamp } from "@sv443-network/userutils";
@@ -586,7 +645,7 @@ mapRange(
   
 Maps a number from one range to the spot it would be in another range.  
   
-<details><summary><h4>Example - click to view</h4></summary>
+<details><summary><b>Example - click to view</b></summary>
 
 ```ts
 import { mapRange } from "@sv443-network/userutils";
@@ -613,7 +672,7 @@ randRange(max: number): number
 Returns a random number between `min` and `max` (inclusive).  
 If only one argument is passed, it will be used as the `max` value and `min` will be set to 0.  
   
-<details><summary><h4>Example - click to view</h4></summary>
+<details><summary><b>Example - click to view</b></summary>
 
 ```ts
 import { randRange } from "@sv443-network/userutils";
@@ -676,7 +735,7 @@ If `loadData()` or `setData()` are called after this, the persistent storage wil
 
 <br>
 
-<details><summary><h4>Example - click to view</h4></summary>
+<details><summary><b>Example - click to view</b></summary>
 
 ```ts
 import { ConfigManager } from "@sv443-network/userutils";
@@ -769,7 +828,7 @@ autoPlural(str: string, num: number | Array | NodeList): string
 Automatically pluralizes a string if the given number is not 1.  
 If an array or NodeList is passed, the amount of contained items will be used.  
   
-<details><summary><h4>Example - click to view</h4></summary>
+<details><summary><b>Example - click to view</b></summary>
 
 ```ts
 import { autoPlural } from "@sv443-network/userutils";
@@ -797,7 +856,7 @@ pauseFor(ms: number): Promise<void>
   
 Pauses async execution for a given amount of time.  
   
-<details><summary><h4>Example - click to view</h4></summary>
+<details><summary><b>Example - click to view</b></summary>
 
 ```ts
 import { pauseFor } from "@sv443-network/userutils";
@@ -824,7 +883,7 @@ This is very useful for functions that are called repeatedly, like event listene
 All passed properties will be passed down to the debounced function.  
 The timeout will default to 300ms if left undefined.  
   
-<details><summary><h4>Example - click to view</h4></summary>
+<details><summary><b>Example - click to view</b></summary>
 
 ```ts
 import { debounce } from "@sv443-network/userutils";
@@ -850,7 +909,7 @@ fetchAdvanced(url: string, options?: {
 A wrapper around the native `fetch()` function that adds options like a timeout property.  
 The timeout will default to 10 seconds if left undefined.  
   
-<details><summary><h4>Example - click to view</h4></summary>
+<details><summary><b>Example - click to view</b></summary>
 
 ```ts
 import { fetchAdvanced } from "@sv443-network/userutils";
@@ -881,7 +940,7 @@ randomItem(array: Array): any
 Returns a random item from an array.  
 Returns undefined if the array is empty.  
   
-<details><summary><h4>Example - click to view</h4></summary>
+<details><summary><b>Example - click to view</b></summary>
 
 ```ts
 import { randomItem } from "@sv443-network/userutils";
@@ -903,7 +962,7 @@ randomItemIndex(array: Array): [item: any, index: number]
 Returns a tuple of a random item and its index from an array.  
 If the array is empty, it will return undefined for both values.  
   
-<details><summary><h4>Example - click to view</h4></summary>
+<details><summary><b>Example - click to view</b></summary>
 
 ```ts
 import { randomItemIndex } from "@sv443-network/userutils";
@@ -930,7 +989,7 @@ takeRandomItem(array: Array): any
 Returns a random item from an array and mutates the array by removing the item.  
 Returns undefined if the array is empty.  
   
-<details><summary><h4>Example - click to view</h4></summary>
+<details><summary><b>Example - click to view</b></summary>
 
 ```ts
 import { takeRandomItem } from "@sv443-network/userutils";
@@ -953,7 +1012,7 @@ randomizeArray(array: Array): Array
 Returns a copy of an array with its items in a random order.  
 If the array is empty, the originally passed empty array will be returned without copying.  
   
-<details><summary><h4>Example - click to view</h4></summary>
+<details><summary><b>Example - click to view</b></summary>
 
 ```ts
 import { randomizeArray } from "@sv443-network/userutils";
@@ -968,8 +1027,220 @@ console.log(foo); // [1, 2, 3, 4, 5, 6] - original array is not mutated
 
 </details>
 
+<br><br>
+
+## 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.
+
+<br>
+
+### tr()
+Usage:  
+```ts
+tr(key: string, ...values: Stringifiable[]): string
+```
+  
+The function returns the translation of the passed key in the language added by [`tr.addLanguage()`](#traddlanguage) and set by [`tr.setLanguage()`](#trsetlanguage)  
+Should the translation contain placeholders in the format `%n`, where `n` is the number of the value starting at 1, they will be replaced with the respective item of the `values` rest parameter.  
+The items of the `values` rest parameter will be stringified using `toString()` (see [Stringifiable](#stringifiable)) before being inserted into the translation.
+  
+If the key is not found or no language has been added or set before calling this function, it will return the key itself.  
+If the key is found and the translation contains placeholders but no values are passed, it will return the translation as-is, including unmodified placeholders.  
+If the key is found, the translation doesn't contain placeholders but values are still passed, they will be ignored and the translation will be returned as-is.  
+  
+<details><summary><b>Example - click to view</b></summary>
+
+```ts
+import { tr } from "@sv443-network/userutils";
+
+tr.addLanguage("en", {
+  "welcome": "Welcome",
+  "welcome_name": "Welcome, %1",
+});
+tr.addLanguage("de", {
+  "welcome": "Willkommen",
+  "welcome_name": "Willkommen, %1",
+});
+
+// this has to be called at least once before calling tr()
+tr.setLanguage("en");
+
+console.log(tr("welcome"));              // "Welcome"
+console.log(tr("welcome_name", "John")); // "Welcome, John"
+console.log(tr("non_existent_key"));     // "non_existent_key"
+
+// language can be changed at any time, synchronously
+tr.setLanguage("de");
+
+console.log(tr("welcome"));              // "Willkommen"
+console.log(tr("welcome_name", "John")); // "Willkommen, John"
+```
+
+</details>
+
 <br>
 
+### tr.addLanguage()
+Usage:  
+```ts
+tr.addLanguage(language: string, translations: Record<string, string>): void
+```
+
+Adds a language and its associated translations to the translation function.  
+The passed language can be any unique identifier, though I recommend sticking to the [ISO 639-1 standard.](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes)  
+The passed translations should be an object where the key is the translation key used in `tr()` and the value is the translation itself.  
+If `tr.addLanguage()` is called multiple times with the same language, the previous translations of that language will be overwritten.  
+  
+The translation values may contain placeholders in the format `%n`, where `n` is the number of the value starting at 1.  
+These can be used to inject values into the translation when calling `tr()`  
+  
+<details><summary><b>Example - click to view</b></summary>
+
+```ts
+import { tr } from "@sv443-network/userutils";
+
+// add a language with associated translations:
+
+tr.addLanguage("de", {
+  "color": "Farbe",
+});
+
+
+// with placeholders:
+
+tr.addLanguage("en", {
+  "welcome_generic": "Welcome!",
+  "welcome_name": "Welcome, %1!",
+  "welcome_extended": "Welcome, %1!\nYour last login was on %2\nYou have %3 unread messages",
+});
+
+
+// can be used for different locales too:
+
+tr.addLanguage("en-US", {
+  "fries": "french fries",
+});
+tr.addLanguage("en-GB", {
+  "fries": "chips",
+});
+
+
+// apply default values for different locales to reduce redundancy in shared translation values:
+
+const translation_de = {
+  "greeting": "Guten Tag!",
+  "foo": "Foo",
+};
+tr.addLanguage("de-DE", translation_de);
+tr.addLanguage("de-CH", {
+  ...translation_de,
+  // overwrite the "greeting" but keep other keys as they are
+  "greeting": "Grüezi!",
+});
+tr.addLanguage("de-AT", {
+  ...translation_de,
+  // overwrite "greeting" again but keep other keys as they are
+  "greeting": "Grüß Gott!",
+});
+
+
+// example for custom pluralization:
+
+tr.addLanguage("en", {
+  "items_added-0": "Added %1 items to your cart",
+  "items_added-1": "Added %1 item to your cart",
+  "items_added-n": "Added all %1 items to your cart",
+});
+
+/** Returns the custom pluralization identifier for the given number of items (or size of Array/NodeList) */
+function pl(num: number | unknown[] | NodeList) {
+  if(typeof num !== "number")
+    num = num.length;
+
+  if(num === 0)
+    return "0";
+  else if(num === 1)
+    return "1";
+  else
+    return "n";
+};
+
+const items = [];
+tr(`items_added-${pl(items)}`, items.length); // "Added 0 items to your cart"
+
+items.push("foo");
+tr(`items_added-${pl(items)}`, items.length); // "Added 1 item to your cart"
+
+items.push("bar");
+tr(`items_added-${pl(items)}`, items.length); // "Added all 2 items to your cart"
+```
+
+</details>
+
+<br>
+
+### tr.setLanguage()
+Usage:  
+```ts
+tr.setLanguage(language: string): void
+```
+
+Synchronously sets the language that will be used for translations.  
+No validation is done on the passed language, so make sure it is correct and it has been added with `tr.addLanguage()` before calling `tr()`  
+  
+For an example, see [`tr()`](#tr)
+
+<br>
+
+### tr.getLanguage()
+Usage:  
+```ts
+tr.getLanguage(): string | undefined
+```
+
+Returns the currently active language set by [`tr.setLanguage()`](#trsetlanguage)  
+If no language has been set yet, it will return undefined.
+
+<br><br>
+
+## 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.
+
+### Stringifiable
+This type describes any value that either is a string itself or can be converted to a string.  
+To be considered stringifiable, the object needs to have a `toString()` method that returns a string (all primitive types have this method).  
+This method allows not just explicit conversion by calling it, but also implicit conversion by passing it into the `String()` constructor or by interpolating it in a template string.  
+  
+<details><summary><b>Example - click to view</b></summary>
+
+```ts
+import type { Stringifiable } from "@sv443-network/userutils";
+
+function logSomething(value: Stringifiable) {
+  console.log(`Log: ${value}`); // implicit conversion using `value.toString()`
+}
+
+const fooObject = {
+  toString: () => "hello world",
+};
+
+const barObject = {
+  baz: "",
+};
+
+logSomething("foo");     // "Log: foo"
+logSomething(42);        // "Log: 42"
+logSomething(true);      // "Log: true"
+logSomething({});        // "Log: [object Object]"
+logSomething(Symbol(1)); // "Log: Symbol(1)"
+logSomething(fooObject); // "Log: hello world"
+logSomething(barObject); // type error
+```
+
+</details>
+
 <br><br><br><br>
 
 <div style="text-align: center;" align="center">

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      1.1.3
+// @version      2.0.0
 // @license      MIT
 // @copyright    Sv443 (https://github.com/Sv443)
 
@@ -315,22 +315,52 @@ var UserUtils = (function (exports) {
   function interceptWindowEvent(eventName, predicate) {
     return interceptEvent(getUnsafeWindow(), eventName, predicate);
   }
-  function amplifyMedia(mediaElement, multiplier = 1) {
+  function amplifyMedia(mediaElement, initialMultiplier = 1) {
     const context = new (window.AudioContext || window.webkitAudioContext)();
-    const result = {
-      mediaElement,
-      amplify: (multiplier2) => {
-        result.gain.gain.value = multiplier2;
+    const props = {
+      /** Sets the gain multiplier */
+      setGain(multiplier) {
+        props.gainNode.gain.setValueAtTime(multiplier, props.context.currentTime);
+      },
+      /** Returns the current gain multiplier */
+      getGain() {
+        return props.gainNode.gain.value;
+      },
+      /** Enable the amplification for the first time or if it was disabled before */
+      enable() {
+        props.source.connect(props.limiterNode);
+        props.limiterNode.connect(props.gainNode);
+        props.gainNode.connect(props.context.destination);
+      },
+      /** Disable the amplification */
+      disable() {
+        props.source.disconnect(props.limiterNode);
+        props.limiterNode.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);
       },
-      getAmpLevel: () => result.gain.gain.value,
       context,
       source: context.createMediaElementSource(mediaElement),
-      gain: context.createGain()
+      gainNode: context.createGain(),
+      limiterNode: context.createDynamicsCompressor()
     };
-    result.source.connect(result.gain);
-    result.gain.connect(context.destination);
-    result.amplify(multiplier);
-    return result;
+    props.setLimiterOptions({
+      threshold: -2,
+      knee: 40,
+      ratio: 12,
+      attack: 3e-3,
+      release: 0.25
+    });
+    props.setGain(initialMultiplier);
+    return props;
   }
   function isScrollable(element) {
     const { overflowX, overflowY } = getComputedStyle(element);
@@ -370,6 +400,13 @@ var UserUtils = (function (exports) {
       return res;
     });
   }
+  function insertValues(str, ...values) {
+    return str.replace(/%\d/gm, (match) => {
+      var _a, _b;
+      const argIndex = Number(match.substring(1)) - 1;
+      return (_b = (_a = values[argIndex]) != null ? _a : match) == null ? void 0 : _b.toString();
+    });
+  }
 
   // lib/onSelector.ts
   var selectorMap = /* @__PURE__ */ new Map();
@@ -421,6 +458,31 @@ var UserUtils = (function (exports) {
     return selectorMap;
   }
 
+  // lib/translation.ts
+  var trans = {};
+  var curLang;
+  function tr(key, ...args) {
+    var _a;
+    if (!curLang)
+      return key;
+    const trText = (_a = trans[curLang]) == null ? void 0 : _a[key];
+    if (!trText)
+      return key;
+    if (args.length > 0 && trText.match(/%\d/)) {
+      return insertValues(trText, ...args);
+    }
+    return trText;
+  }
+  tr.addLanguage = (language, translations) => {
+    trans[language] = translations;
+  };
+  tr.setLanguage = (language) => {
+    curLang = language;
+  };
+  tr.getLanguage = () => {
+    return curLang;
+  };
+
   exports.ConfigManager = ConfigManager;
   exports.addGlobalStyle = addGlobalStyle;
   exports.addParent = addParent;
@@ -433,6 +495,7 @@ var UserUtils = (function (exports) {
   exports.getUnsafeWindow = getUnsafeWindow;
   exports.initOnSelector = initOnSelector;
   exports.insertAfter = insertAfter;
+  exports.insertValues = insertValues;
   exports.interceptEvent = interceptEvent;
   exports.interceptWindowEvent = interceptWindowEvent;
   exports.isScrollable = isScrollable;
@@ -447,6 +510,7 @@ var UserUtils = (function (exports) {
   exports.randomizeArray = randomizeArray;
   exports.removeOnSelector = removeOnSelector;
   exports.takeRandomItem = takeRandomItem;
+  exports.tr = tr;
 
   return exports;
 

package/dist/index.js

@@ -294,22 +294,52 @@ function interceptEvent(eventObject, eventName, predicate) {
 function interceptWindowEvent(eventName, predicate) {
   return interceptEvent(getUnsafeWindow(), eventName, predicate);
 }
-function amplifyMedia(mediaElement, multiplier = 1) {
+function amplifyMedia(mediaElement, initialMultiplier = 1) {
   const context = new (window.AudioContext || window.webkitAudioContext)();
-  const result = {
-    mediaElement,
-    amplify: (multiplier2) => {
-      result.gain.gain.value = multiplier2;
+  const props = {
+    /** Sets the gain multiplier */
+    setGain(multiplier) {
+      props.gainNode.gain.setValueAtTime(multiplier, props.context.currentTime);
+    },
+    /** Returns the current gain multiplier */
+    getGain() {
+      return props.gainNode.gain.value;
+    },
+    /** Enable the amplification for the first time or if it was disabled before */
+    enable() {
+      props.source.connect(props.limiterNode);
+      props.limiterNode.connect(props.gainNode);
+      props.gainNode.connect(props.context.destination);
+    },
+    /** Disable the amplification */
+    disable() {
+      props.source.disconnect(props.limiterNode);
+      props.limiterNode.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);
     },
-    getAmpLevel: () => result.gain.gain.value,
     context,
     source: context.createMediaElementSource(mediaElement),
-    gain: context.createGain()
+    gainNode: context.createGain(),
+    limiterNode: context.createDynamicsCompressor()
   };
-  result.source.connect(result.gain);
-  result.gain.connect(context.destination);
-  result.amplify(multiplier);
-  return result;
+  props.setLimiterOptions({
+    threshold: -2,
+    knee: 40,
+    ratio: 12,
+    attack: 3e-3,
+    release: 0.25
+  });
+  props.setGain(initialMultiplier);
+  return props;
 }
 function isScrollable(element) {
   const { overflowX, overflowY } = getComputedStyle(element);
@@ -349,6 +379,13 @@ function fetchAdvanced(_0) {
     return res;
   });
 }
+function insertValues(str, ...values) {
+  return str.replace(/%\d/gm, (match) => {
+    var _a, _b;
+    const argIndex = Number(match.substring(1)) - 1;
+    return (_b = (_a = values[argIndex]) != null ? _a : match) == null ? void 0 : _b.toString();
+  });
+}
 
 // lib/onSelector.ts
 var selectorMap = /* @__PURE__ */ new Map();
@@ -400,6 +437,31 @@ function getSelectorMap() {
   return selectorMap;
 }
 
+// lib/translation.ts
+var trans = {};
+var curLang;
+function tr(key, ...args) {
+  var _a;
+  if (!curLang)
+    return key;
+  const trText = (_a = trans[curLang]) == null ? void 0 : _a[key];
+  if (!trText)
+    return key;
+  if (args.length > 0 && trText.match(/%\d/)) {
+    return insertValues(trText, ...args);
+  }
+  return trText;
+}
+tr.addLanguage = (language, translations) => {
+  trans[language] = translations;
+};
+tr.setLanguage = (language) => {
+  curLang = language;
+};
+tr.getLanguage = () => {
+  return curLang;
+};
+
 exports.ConfigManager = ConfigManager;
 exports.addGlobalStyle = addGlobalStyle;
 exports.addParent = addParent;
@@ -412,6 +474,7 @@ exports.getSelectorMap = getSelectorMap;
 exports.getUnsafeWindow = getUnsafeWindow;
 exports.initOnSelector = initOnSelector;
 exports.insertAfter = insertAfter;
+exports.insertValues = insertValues;
 exports.interceptEvent = interceptEvent;
 exports.interceptWindowEvent = interceptWindowEvent;
 exports.isScrollable = isScrollable;
@@ -426,3 +489,4 @@ exports.randomItemIndex = randomItemIndex;
 exports.randomizeArray = randomizeArray;
 exports.removeOnSelector = removeOnSelector;
 exports.takeRandomItem = takeRandomItem;
+exports.tr = tr;

package/dist/index.mjs

@@ -292,22 +292,52 @@ function interceptEvent(eventObject, eventName, predicate) {
 function interceptWindowEvent(eventName, predicate) {
   return interceptEvent(getUnsafeWindow(), eventName, predicate);
 }
-function amplifyMedia(mediaElement, multiplier = 1) {
+function amplifyMedia(mediaElement, initialMultiplier = 1) {
   const context = new (window.AudioContext || window.webkitAudioContext)();
-  const result = {
-    mediaElement,
-    amplify: (multiplier2) => {
-      result.gain.gain.value = multiplier2;
+  const props = {
+    /** Sets the gain multiplier */
+    setGain(multiplier) {
+      props.gainNode.gain.setValueAtTime(multiplier, props.context.currentTime);
+    },
+    /** Returns the current gain multiplier */
+    getGain() {
+      return props.gainNode.gain.value;
+    },
+    /** Enable the amplification for the first time or if it was disabled before */
+    enable() {
+      props.source.connect(props.limiterNode);
+      props.limiterNode.connect(props.gainNode);
+      props.gainNode.connect(props.context.destination);
+    },
+    /** Disable the amplification */
+    disable() {
+      props.source.disconnect(props.limiterNode);
+      props.limiterNode.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);
     },
-    getAmpLevel: () => result.gain.gain.value,
     context,
     source: context.createMediaElementSource(mediaElement),
-    gain: context.createGain()
+    gainNode: context.createGain(),
+    limiterNode: context.createDynamicsCompressor()
   };
-  result.source.connect(result.gain);
-  result.gain.connect(context.destination);
-  result.amplify(multiplier);
-  return result;
+  props.setLimiterOptions({
+    threshold: -2,
+    knee: 40,
+    ratio: 12,
+    attack: 3e-3,
+    release: 0.25
+  });
+  props.setGain(initialMultiplier);
+  return props;
 }
 function isScrollable(element) {
   const { overflowX, overflowY } = getComputedStyle(element);
@@ -347,6 +377,13 @@ function fetchAdvanced(_0) {
     return res;
   });
 }
+function insertValues(str, ...values) {
+  return str.replace(/%\d/gm, (match) => {
+    var _a, _b;
+    const argIndex = Number(match.substring(1)) - 1;
+    return (_b = (_a = values[argIndex]) != null ? _a : match) == null ? void 0 : _b.toString();
+  });
+}
 
 // lib/onSelector.ts
 var selectorMap = /* @__PURE__ */ new Map();
@@ -398,4 +435,29 @@ function getSelectorMap() {
   return selectorMap;
 }
 
-export { ConfigManager, addGlobalStyle, addParent, amplifyMedia, autoPlural, clamp, debounce, fetchAdvanced, getSelectorMap, getUnsafeWindow, initOnSelector, insertAfter, interceptEvent, interceptWindowEvent, isScrollable, mapRange, onSelector, openInNewTab, pauseFor, preloadImages, randRange, randomItem, randomItemIndex, randomizeArray, removeOnSelector, takeRandomItem };
+// lib/translation.ts
+var trans = {};
+var curLang;
+function tr(key, ...args) {
+  var _a;
+  if (!curLang)
+    return key;
+  const trText = (_a = trans[curLang]) == null ? void 0 : _a[key];
+  if (!trText)
+    return key;
+  if (args.length > 0 && trText.match(/%\d/)) {
+    return insertValues(trText, ...args);
+  }
+  return trText;
+}
+tr.addLanguage = (language, translations) => {
+  trans[language] = translations;
+};
+tr.setLanguage = (language) => {
+  curLang = language;
+};
+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 };

package/dist/lib/dom.d.ts

@@ -45,28 +45,51 @@ export declare function interceptEvent<TEvtObj extends EventTarget, TPredicateEv
 export declare function interceptWindowEvent<TEvtKey extends keyof WindowEventMap>(eventName: TEvtKey, predicate: (event: WindowEventMap[TEvtKey]) => boolean): void;
 /**
  * Amplifies the gain of the passed media element's audio by the specified multiplier.
- * This function supports any media element like `<audio>` or `<video>`
+ * Also applies a limiter to prevent clipping and distortion.
+ * This function supports any MediaElement instance like `<audio>` or `<video>`
  *
- * 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.
+ * This is the audio processing workflow:
+ * `MediaElement (source)` => `DynamicsCompressorNode (limiter)` => `GainNode` => `AudioDestinationNode (output)`
  *
+ * ⚠️ 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.
+ *
+ * @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`)
  * @returns Returns an object with the following properties:
  * | Property | Description |
  * | :-- | :-- |
- * | `mediaElement` | The passed media element |
- * | `amplify()` | A function to change the amplification level |
- * | `getAmpLevel()` | A function to return the current amplification level |
+ * | `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: -2, knee: 40, ratio: 12, attack: 0.003, release: 0.25 }` |
  * | `context` | The AudioContext instance |
  * | `source` | The MediaElementSourceNode instance |
- * | `gain` | The GainNode instance |
+ * | `gainNode` | The GainNode instance |
+ * | `limiterNode` | The DynamicsCompressorNode instance used for limiting clipping and distortion |
  */
-export declare function amplifyMedia<TElem extends HTMLMediaElement>(mediaElement: TElem, multiplier?: number): {
-    mediaElement: TElem;
-    amplify: (multiplier: number) => void;
-    getAmpLevel: () => number;
+export declare function amplifyMedia<TElem extends HTMLMediaElement>(mediaElement: TElem, initialMultiplier?: number): {
+    /** Sets the gain multiplier */
+    setGain(multiplier: number): void;
+    /** Returns the current gain multiplier */
+    getGain(): number;
+    /** 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;
-    gain: GainNode;
+    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

@@ -4,3 +4,4 @@ export * from "./dom";
 export * from "./math";
 export * from "./misc";
 export * from "./onSelector";
+export * from "./translation";

package/dist/lib/misc.d.ts

@@ -1,9 +1,13 @@
+/** Represents any value that is either a string itself or can be converted to one (implicitly or explicitly) because it has a toString() method */
+export type Stringifiable = string | {
+    toString(): string;
+};
 /**
  * Automatically appends an `s` to the passed `word`, if `num` is not equal to 1
  * @param word A word in singular form, to auto-convert to plural
  * @param num If this is an array or NodeList, the amount of items is used
  */
-export declare function autoPlural(word: string, num: number | unknown[] | NodeList): string;
+export declare function autoPlural(word: Stringifiable, num: number | unknown[] | NodeList): string;
 /** Pauses async execution for the specified time in ms */
 export declare function pauseFor(time: number): Promise<void>;
 /**
@@ -18,3 +22,10 @@ export type FetchAdvancedOpts = RequestInit & Partial<{
 }>;
 /** Calls the fetch API with special options like a timeout */
 export declare function fetchAdvanced(url: string, options?: FetchAdvancedOpts): Promise<Response>;
+/**
+ * Inserts the passed values into a string at the respective placeholders.
+ * The placeholder format is `%n`, where `n` is the 1-indexed argument number.
+ * @param str The string to insert the values into
+ * @param values The values to insert, in order, starting at `%1`
+ */
+export declare function insertValues(str: string, ...values: Stringifiable[]): string;

package/dist/lib/translation.d.ts

@@ -0,0 +1,16 @@
+import { Stringifiable } from "./misc";
+/**
+ * Returns the translated text for the specified key in the current language set by `setLanguage()`
+ * If the key is not found in the previously registered translation, the key itself is returned.
+ *
+ * ⚠️ Remember to register a language with `tr.addLanguage()` and set it as active with `tr.setLanguage()` before using this function, otherwise it will always return the key itself.
+ * @param key Key of the translation to return
+ * @param args Optional arguments to be passed to the translated text. They will replace placeholders in the format `%n`, where `n` is the 1-indexed argument number
+ */
+declare function tr(key: string, ...args: Stringifiable[]): string;
+declare namespace tr {
+    var addLanguage: (language: string, translations: Record<string, string>) => void;
+    var setLanguage: (language: string) => void;
+    var getLanguage: () => string;
+}
+export { tr };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sv443-network/userutils",
-  "version": "1.1.3",
+  "version": "2.0.0",
   "description": "Library with various utilities for userscripts - register listeners for when CSS selectors exist, intercept events, manage persistent user configurations, modify the DOM more easily and more",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -9,10 +9,10 @@
     "lint": "tsc --noEmit && eslint .",
     "build-types": "tsc --emitDeclarationOnly --declaration --outDir dist",
     "build-common": "tsup lib/index.ts --format cjs,esm --clean --treeshake",
-    "build-global": "tsup lib/index.ts --format cjs,esm,iife --treeshake --onSuccess \"npm run post-build-global\"",
+    "build-global": "tsup lib/index.ts --format cjs,esm,iife --treeshake --onSuccess \"npm run post-build-global && echo Finished building.\"",
     "build": "npm run build-common -- && npm run build-types",
     "post-build-global": "npm run node-ts -- ./tools/post-build-global.mts",
-    "dev": "npm run build-common -- --sourcemap --watch --onSuccess \"npm run build-types\"",
+    "dev": "npm run build-common -- --sourcemap --watch --onSuccess \"npm run build-types && echo Finished building.\"",
     "publish-package": "changeset publish",
     "node-ts": "node --no-warnings=ExperimentalWarning --enable-source-maps --loader ts-node/esm"
   },