@sv443-network/userutils 3.0.0 → 4.1.0

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # @sv443-network/userutils
 
+## 4.1.0
+
+### Minor Changes
+
+- 885323d: Added function `observeElementProp` to allow observing element property changes
+
+## 4.0.0
+
+### Major Changes
+
+- dae5450: Removed `amplifyMedia` function due to massive inconsistencies in sound quality
+
+### Minor Changes
+
+- 168c2aa: Added functions `compress` and `decompress` to compress and decompress strings using gzip or deflate
+- 49bc85e: Added utility types `NonEmptyString` and `LooseUnion`
+
+### Patch Changes
+
+- 2ae665d: fixed wrong TS type for SelectorObserver options in constructor
+
 ## 3.0.0
 
 ### Major Changes

package/README.md

@@ -4,13 +4,15 @@
 ## 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. Fully web compatible and supports ESM, CJS and global imports.  
+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: [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)
+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>
 
@@ -30,8 +32,8 @@ View the documentation of previous major releases: [2.0.1](https://github.com/Sv
     - [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
+    - [observeElementProp()](#observeelementprop) - observe changes to an element's property that can't be observed with MutationObserver
   - [**Math:**](#math)
     - [clamp()](#clamp) - constrain a number between a min and max value
     - [mapRange()](#maprange) - map a number from one range to the same spot in another range
@@ -44,6 +46,8 @@ View the documentation of previous major releases: [2.0.1](https://github.com/Sv
     - [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
@@ -56,7 +60,9 @@ View the documentation of previous major releases: [2.0.1](https://github.com/Sv
     - [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](https://github.com/Sv443-Network/UserUtils#nonemptyarray) - any array that should have at least one item
+    - [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>
 
@@ -647,120 +653,78 @@ interceptWindowEvent("beforeunload");
 
 <br>
 
-### amplifyMedia()
+### isScrollable()
 Usage:  
 ```ts
-amplifyMedia(mediaElement: HTMLMediaElement, initialGain?: number): AmplifyMediaResult
+isScrollable(element: Element): { horizontal: boolean, vertical: boolean }
 ```
   
-Amplifies the volume of a media element (like `<audio>` or `<video>`) by the given gain value.  
-This is how you can increase the volume of a media element beyond the default maximum volume of 100%.  
-Make sure to limit the value to a reasonable value ([clamp()](#clamp) is good for this), as it may otherwise cause bleeding eardrums.  
-  
-The default gain value passed to the GainNode is `1.0`  
-It may be read and changed at any point by calling the `getGain()` and `setGain()` methods of the returned object.  
-  
-To activate the amplification for the first time, call the `enable()` method of the returned object.  
-  
-This is the processing workflow applied to the media element:  
-`MediaElement (source)` => `GainNode (pre-amplifier)` => 10x `BiquadFilterNode` => `GainNode (post-amplifier)` => `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.  
-  
-The returned object of the type `AmplifyMediaResult` has the following properties:  
-**Important properties:**
-| Property | Description |
-| :-- | :-- |
-| `enable()` | Call to enable the amplification for the first time or re-enable it if it was disabled before |
-| `disable()` | Call to disable amplification |
-| `enabled` | Whether the amplification is currently enabled |
-| `setGain()` | Used to change the gain value from the default given by the parameter `initialGain` |
-| `getGain()` | Returns the current gain value |
-
-**Other properties:**
-| Property | Description |
-| :-- | :-- |
-| `context` | The AudioContext instance used as the audio destination and context within the nodes are created |
-| `sourceNode` | A MediaElementSourceNode instance created from the passed `mediaElement` |
-| `gainNode` | The GainNode instance used for volume amplification |
+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.  
   
-<br>
-
 <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 updateGainValue(gainValue: number) {
-  if(!ampResult)
-    return;
-  // constrain the value to between 0 and 3 for safety
-  ampResult.setGain(clamp(gainValue, 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 it to ~2x
-    ampResult = amplifyMedia(audioElement, 2.0);
-  }
-  if(!ampResult.enabled) {
-    // enable the amplification
-    ampResult.enable();
-  }
-
-  updateGainValue(3.5); // try to set gain to ~3.5x
-
-  console.log(ampResult.getGain()); // 3.0 (because of the clamp())
-});
-
+import { isScrollable } from "@sv443-network/userutils";
 
-const disableButton = document.querySelector<HTMLButtonElement>("button#disable");
+const element = document.querySelector("#element");
+const { horizontal, vertical } = isScrollable(element);
 
-disableButton.addEventListener("click", () => {
-  if(ampResult) {
-    // disable the amplification
-    ampResult.disable();
-  }
-});
+console.log("Element has a horizontal scroll bar:", horizontal);
+console.log("Element has a vertical scroll bar:", vertical);
 ```
 
 </details>
 
 <br>
 
-### isScrollable()
+### observeElementProp()
 Usage:  
 ```ts
-isScrollable(element: Element): { horizontal: boolean, vertical: boolean }
+observeElementProp(
+  element: Element,
+  property: string,
+  callback: (oldValue: any, newValue: any) => void
+): void
 ```
   
-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.  
+This function observes changes to the given property of a given element.  
+While regular HTML attributes can be observed using a MutationObserver, this is not always possible for properties that are assigned on the JS object.  
+This function shims the setter of the provided property and calls the callback function whenever it is changed through any means.  
+  
+When using TypeScript, the types for `element`, `property` and the arguments for `callback` will be automatically inferred.  
   
 <details><summary><b>Example - click to view</b></summary>
 
 ```ts
-import { isScrollable } from "@sv443-network/userutils";
+import { observeElementProp } from "@sv443-network/userutils";
 
-const element = document.querySelector("#element");
-const { horizontal, vertical } = isScrollable(element);
+const myInput = document.querySelector("input#my-input");
 
-console.log("Element has a horizontal scroll bar:", horizontal);
-console.log("Element has a vertical scroll bar:", vertical);
+let value = 0;
+
+setInterval(() => {
+  value += 1;
+  myInput.value = String(value);
+}, 1000);
+
+
+const observer = new MutationObserver((mutations) => {
+  // will never be called:
+  console.log("MutationObserver mutation:", mutations);
+});
+
+// one would think this should work, but "value" is a JS object *property*, not a DOM *attribute*
+observer.observe(myInput, {
+  attributes: true,
+  attributeFilter: ["value"],
+});
+
+
+observeElementProp(myInput, "value", (oldValue, newValue) => {
+  // will be called every time the value changes:
+  console.log("Value changed from", oldValue, "to", newValue);
+});
 ```
 
 </details>
@@ -1121,6 +1085,106 @@ 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 -->
@@ -1442,6 +1506,11 @@ logSomething(barObject); // Type Error
 <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.  
   
@@ -1465,6 +1534,59 @@ 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 -->

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      3.0.0
+// @version      4.1.0
 // @license      MIT
 // @copyright    Sv443 (https://github.com/Sv443)
 
@@ -326,43 +326,6 @@ var UserUtils = (function (exports) {
   function interceptWindowEvent(eventName, predicate = () => true) {
     return interceptEvent(getUnsafeWindow(), eventName, predicate);
   }
-  function amplifyMedia(mediaElement, initialGain = 1) {
-    const context = new (window.AudioContext || window.webkitAudioContext)();
-    const props = {
-      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 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() {
-        if (props.enabled)
-          return;
-        props.enabled = true;
-        props.sourceNode.connect(props.gainNode);
-        props.gainNode.connect(props.context.destination);
-      },
-      /** Disable the amplification */
-      disable() {
-        if (!props.enabled)
-          return;
-        props.enabled = false;
-        props.sourceNode.disconnect(props.gainNode);
-        props.gainNode.disconnect(props.context.destination);
-        props.sourceNode.connect(props.context.destination);
-      }
-    };
-    props.setGain(initialGain);
-    return props;
-  }
   function isScrollable(element) {
     const { overflowX, overflowY } = getComputedStyle(element);
     return {
@@ -370,6 +333,28 @@ var UserUtils = (function (exports) {
       horizontal: (overflowX === "scroll" || overflowX === "auto") && element.scrollWidth > element.clientWidth
     };
   }
+  function observeElementProp(element, property, callback) {
+    const elementPrototype = Object.getPrototypeOf(element);
+    if (elementPrototype.hasOwnProperty(property)) {
+      const descriptor = Object.getOwnPropertyDescriptor(elementPrototype, property);
+      Object.defineProperty(element, property, {
+        get: function() {
+          var _a;
+          return (_a = descriptor == null ? void 0 : descriptor.get) == null ? void 0 : _a.apply(this, arguments);
+        },
+        set: function() {
+          var _a;
+          const oldValue = this[property];
+          (_a = descriptor == null ? void 0 : descriptor.set) == null ? void 0 : _a.apply(this, arguments);
+          const newValue = this[property];
+          if (typeof callback === "function") {
+            callback.bind(this, oldValue, newValue);
+          }
+          return newValue;
+        }
+      });
+    }
+  }
 
   // lib/misc.ts
   function autoPlural(word, num) {
@@ -401,13 +386,43 @@ var UserUtils = (function (exports) {
       return res;
     });
   }
-  function insertValues(str, ...values) {
-    return str.replace(/%\d/gm, (match) => {
+  function insertValues(input, ...values) {
+    return input.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();
     });
   }
+  function compress(input, compressionFormat, outputType = "base64") {
+    return __async(this, null, function* () {
+      const byteArray = typeof input === "string" ? new TextEncoder().encode(input) : input;
+      const comp = new CompressionStream(compressionFormat);
+      const writer = comp.writable.getWriter();
+      writer.write(byteArray);
+      writer.close();
+      const buf = yield new Response(comp.readable).arrayBuffer();
+      return outputType === "arrayBuffer" ? buf : ab2str(buf);
+    });
+  }
+  function decompress(input, compressionFormat, outputType = "string") {
+    return __async(this, null, function* () {
+      const byteArray = typeof input === "string" ? str2ab(input) : input;
+      const decomp = new DecompressionStream(compressionFormat);
+      const writer = decomp.writable.getWriter();
+      writer.write(byteArray);
+      writer.close();
+      const buf = yield new Response(decomp.readable).arrayBuffer();
+      return outputType === "arrayBuffer" ? buf : new TextDecoder().decode(buf);
+    });
+  }
+  function ab2str(buf) {
+    return getUnsafeWindow().btoa(
+      new Uint8Array(buf).reduce((data, byte) => data + String.fromCharCode(byte), "")
+    );
+  }
+  function str2ab(str) {
+    return Uint8Array.from(getUnsafeWindow().atob(str), (c) => c.charCodeAt(0));
+  }
 
   // lib/SelectorObserver.ts
   var SelectorObserver = class {
@@ -579,10 +594,11 @@ var UserUtils = (function (exports) {
   exports.SelectorObserver = SelectorObserver;
   exports.addGlobalStyle = addGlobalStyle;
   exports.addParent = addParent;
-  exports.amplifyMedia = amplifyMedia;
   exports.autoPlural = autoPlural;
   exports.clamp = clamp;
+  exports.compress = compress;
   exports.debounce = debounce;
+  exports.decompress = decompress;
   exports.fetchAdvanced = fetchAdvanced;
   exports.getUnsafeWindow = getUnsafeWindow;
   exports.insertAfter = insertAfter;
@@ -591,6 +607,7 @@ var UserUtils = (function (exports) {
   exports.interceptWindowEvent = interceptWindowEvent;
   exports.isScrollable = isScrollable;
   exports.mapRange = mapRange;
+  exports.observeElementProp = observeElementProp;
   exports.openInNewTab = openInNewTab;
   exports.pauseFor = pauseFor;
   exports.preloadImages = preloadImages;

package/dist/index.js

@@ -305,43 +305,6 @@ function interceptEvent(eventObject, eventName, predicate = () => true) {
 function interceptWindowEvent(eventName, predicate = () => true) {
   return interceptEvent(getUnsafeWindow(), eventName, predicate);
 }
-function amplifyMedia(mediaElement, initialGain = 1) {
-  const context = new (window.AudioContext || window.webkitAudioContext)();
-  const props = {
-    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 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() {
-      if (props.enabled)
-        return;
-      props.enabled = true;
-      props.sourceNode.connect(props.gainNode);
-      props.gainNode.connect(props.context.destination);
-    },
-    /** Disable the amplification */
-    disable() {
-      if (!props.enabled)
-        return;
-      props.enabled = false;
-      props.sourceNode.disconnect(props.gainNode);
-      props.gainNode.disconnect(props.context.destination);
-      props.sourceNode.connect(props.context.destination);
-    }
-  };
-  props.setGain(initialGain);
-  return props;
-}
 function isScrollable(element) {
   const { overflowX, overflowY } = getComputedStyle(element);
   return {
@@ -349,6 +312,28 @@ function isScrollable(element) {
     horizontal: (overflowX === "scroll" || overflowX === "auto") && element.scrollWidth > element.clientWidth
   };
 }
+function observeElementProp(element, property, callback) {
+  const elementPrototype = Object.getPrototypeOf(element);
+  if (elementPrototype.hasOwnProperty(property)) {
+    const descriptor = Object.getOwnPropertyDescriptor(elementPrototype, property);
+    Object.defineProperty(element, property, {
+      get: function() {
+        var _a;
+        return (_a = descriptor == null ? void 0 : descriptor.get) == null ? void 0 : _a.apply(this, arguments);
+      },
+      set: function() {
+        var _a;
+        const oldValue = this[property];
+        (_a = descriptor == null ? void 0 : descriptor.set) == null ? void 0 : _a.apply(this, arguments);
+        const newValue = this[property];
+        if (typeof callback === "function") {
+          callback.bind(this, oldValue, newValue);
+        }
+        return newValue;
+      }
+    });
+  }
+}
 
 // lib/misc.ts
 function autoPlural(word, num) {
@@ -380,13 +365,43 @@ function fetchAdvanced(_0) {
     return res;
   });
 }
-function insertValues(str, ...values) {
-  return str.replace(/%\d/gm, (match) => {
+function insertValues(input, ...values) {
+  return input.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();
   });
 }
+function compress(input, compressionFormat, outputType = "base64") {
+  return __async(this, null, function* () {
+    const byteArray = typeof input === "string" ? new TextEncoder().encode(input) : input;
+    const comp = new CompressionStream(compressionFormat);
+    const writer = comp.writable.getWriter();
+    writer.write(byteArray);
+    writer.close();
+    const buf = yield new Response(comp.readable).arrayBuffer();
+    return outputType === "arrayBuffer" ? buf : ab2str(buf);
+  });
+}
+function decompress(input, compressionFormat, outputType = "string") {
+  return __async(this, null, function* () {
+    const byteArray = typeof input === "string" ? str2ab(input) : input;
+    const decomp = new DecompressionStream(compressionFormat);
+    const writer = decomp.writable.getWriter();
+    writer.write(byteArray);
+    writer.close();
+    const buf = yield new Response(decomp.readable).arrayBuffer();
+    return outputType === "arrayBuffer" ? buf : new TextDecoder().decode(buf);
+  });
+}
+function ab2str(buf) {
+  return getUnsafeWindow().btoa(
+    new Uint8Array(buf).reduce((data, byte) => data + String.fromCharCode(byte), "")
+  );
+}
+function str2ab(str) {
+  return Uint8Array.from(getUnsafeWindow().atob(str), (c) => c.charCodeAt(0));
+}
 
 // lib/SelectorObserver.ts
 var SelectorObserver = class {
@@ -558,10 +573,11 @@ exports.ConfigManager = ConfigManager;
 exports.SelectorObserver = SelectorObserver;
 exports.addGlobalStyle = addGlobalStyle;
 exports.addParent = addParent;
-exports.amplifyMedia = amplifyMedia;
 exports.autoPlural = autoPlural;
 exports.clamp = clamp;
+exports.compress = compress;
 exports.debounce = debounce;
+exports.decompress = decompress;
 exports.fetchAdvanced = fetchAdvanced;
 exports.getUnsafeWindow = getUnsafeWindow;
 exports.insertAfter = insertAfter;
@@ -570,6 +586,7 @@ exports.interceptEvent = interceptEvent;
 exports.interceptWindowEvent = interceptWindowEvent;
 exports.isScrollable = isScrollable;
 exports.mapRange = mapRange;
+exports.observeElementProp = observeElementProp;
 exports.openInNewTab = openInNewTab;
 exports.pauseFor = pauseFor;
 exports.preloadImages = preloadImages;

package/dist/index.mjs

@@ -303,43 +303,6 @@ function interceptEvent(eventObject, eventName, predicate = () => true) {
 function interceptWindowEvent(eventName, predicate = () => true) {
   return interceptEvent(getUnsafeWindow(), eventName, predicate);
 }
-function amplifyMedia(mediaElement, initialGain = 1) {
-  const context = new (window.AudioContext || window.webkitAudioContext)();
-  const props = {
-    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 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() {
-      if (props.enabled)
-        return;
-      props.enabled = true;
-      props.sourceNode.connect(props.gainNode);
-      props.gainNode.connect(props.context.destination);
-    },
-    /** Disable the amplification */
-    disable() {
-      if (!props.enabled)
-        return;
-      props.enabled = false;
-      props.sourceNode.disconnect(props.gainNode);
-      props.gainNode.disconnect(props.context.destination);
-      props.sourceNode.connect(props.context.destination);
-    }
-  };
-  props.setGain(initialGain);
-  return props;
-}
 function isScrollable(element) {
   const { overflowX, overflowY } = getComputedStyle(element);
   return {
@@ -347,6 +310,28 @@ function isScrollable(element) {
     horizontal: (overflowX === "scroll" || overflowX === "auto") && element.scrollWidth > element.clientWidth
   };
 }
+function observeElementProp(element, property, callback) {
+  const elementPrototype = Object.getPrototypeOf(element);
+  if (elementPrototype.hasOwnProperty(property)) {
+    const descriptor = Object.getOwnPropertyDescriptor(elementPrototype, property);
+    Object.defineProperty(element, property, {
+      get: function() {
+        var _a;
+        return (_a = descriptor == null ? void 0 : descriptor.get) == null ? void 0 : _a.apply(this, arguments);
+      },
+      set: function() {
+        var _a;
+        const oldValue = this[property];
+        (_a = descriptor == null ? void 0 : descriptor.set) == null ? void 0 : _a.apply(this, arguments);
+        const newValue = this[property];
+        if (typeof callback === "function") {
+          callback.bind(this, oldValue, newValue);
+        }
+        return newValue;
+      }
+    });
+  }
+}
 
 // lib/misc.ts
 function autoPlural(word, num) {
@@ -378,13 +363,43 @@ function fetchAdvanced(_0) {
     return res;
   });
 }
-function insertValues(str, ...values) {
-  return str.replace(/%\d/gm, (match) => {
+function insertValues(input, ...values) {
+  return input.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();
   });
 }
+function compress(input, compressionFormat, outputType = "base64") {
+  return __async(this, null, function* () {
+    const byteArray = typeof input === "string" ? new TextEncoder().encode(input) : input;
+    const comp = new CompressionStream(compressionFormat);
+    const writer = comp.writable.getWriter();
+    writer.write(byteArray);
+    writer.close();
+    const buf = yield new Response(comp.readable).arrayBuffer();
+    return outputType === "arrayBuffer" ? buf : ab2str(buf);
+  });
+}
+function decompress(input, compressionFormat, outputType = "string") {
+  return __async(this, null, function* () {
+    const byteArray = typeof input === "string" ? str2ab(input) : input;
+    const decomp = new DecompressionStream(compressionFormat);
+    const writer = decomp.writable.getWriter();
+    writer.write(byteArray);
+    writer.close();
+    const buf = yield new Response(decomp.readable).arrayBuffer();
+    return outputType === "arrayBuffer" ? buf : new TextDecoder().decode(buf);
+  });
+}
+function ab2str(buf) {
+  return getUnsafeWindow().btoa(
+    new Uint8Array(buf).reduce((data, byte) => data + String.fromCharCode(byte), "")
+  );
+}
+function str2ab(str) {
+  return Uint8Array.from(getUnsafeWindow().atob(str), (c) => c.charCodeAt(0));
+}
 
 // lib/SelectorObserver.ts
 var SelectorObserver = class {
@@ -552,4 +567,4 @@ tr.getLanguage = () => {
   return curLang;
 };
 
-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 };
+export { ConfigManager, SelectorObserver, addGlobalStyle, addParent, autoPlural, clamp, compress, debounce, decompress, fetchAdvanced, getUnsafeWindow, insertAfter, insertValues, interceptEvent, interceptWindowEvent, isScrollable, mapRange, observeElementProp, openInNewTab, pauseFor, preloadImages, randRange, randomId, randomItem, randomItemIndex, randomizeArray, takeRandomItem, tr };

package/dist/lib/SelectorObserver.d.ts

@@ -34,13 +34,13 @@ export declare class SelectorObserver {
      * @param baseElementSelector The selector of the element to observe
      * @param options Fine-tune what triggers the MutationObserver's checking function - `subtree` and `childList` are set to true by default
      */
-    constructor(baseElementSelector: string, options: SelectorObserverOptions);
+    constructor(baseElementSelector: string, options?: SelectorObserverOptions);
     /**
      * 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);
+    constructor(baseElement: Element, options?: SelectorObserverOptions);
     private checkAllSelectors;
     private checkSelector;
     private debounce;

package/dist/lib/array.d.ts

@@ -1,13 +1,13 @@
 /** Describes an array with at least one item */
-export type NonEmptyArray<T = unknown> = [T, ...T[]];
+export type NonEmptyArray<TArray = unknown> = [TArray, ...TArray[]];
 /** Returns a random item from the passed array */
-export declare function randomItem<T = unknown>(array: T[]): T | undefined;
+export declare function randomItem<TItem = unknown>(array: TItem[]): TItem | undefined;
 /**
  * Returns a tuple of a random item and its index from the passed array
  * Returns `[undefined, undefined]` if the passed array is empty
  */
-export declare function randomItemIndex<T = unknown>(array: T[]): [item?: T, index?: number];
+export declare function randomItemIndex<TItem = unknown>(array: TItem[]): [item?: TItem, index?: number];
 /** Returns a random item from the passed array and mutates the array to remove the item */
-export declare function takeRandomItem<T = unknown>(arr: T[]): T | undefined;
+export declare function takeRandomItem<TItem = unknown>(arr: TItem[]): TItem | undefined;
 /** Returns a copy of the array with its items in a random order */
-export declare function randomizeArray<T = unknown>(array: T[]): T[];
+export declare function randomizeArray<TItem = unknown>(array: TItem[]): TItem[];

package/dist/lib/dom.d.ts

@@ -45,55 +45,18 @@ export declare function interceptEvent<TEvtObj extends EventTarget, TPredicateEv
  * 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;
-/** 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 value.
- * This function supports any MediaElement instance like `<audio>` or `<video>`
- *
- * This is the audio processing workflow:
- * `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 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 |
- * | :-- | :-- |
- * | `enable()` | Call to enable the amplification for the first time or re-enable it if it was disabled before |
- * | `disable()` | Call to disable amplification |
- * | `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 |
- * | `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, 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;
-};
 /** Checks if an element is scrollable in the horizontal and vertical directions */
 export declare function isScrollable(element: Element): {
     vertical: boolean;
     horizontal: boolean;
 };
+/**
+ * Executes the callback when the passed element's property changes.
+ * Contrary to an element's attributes, properties can usually not be observed with a MutationObserver.
+ * This function shims the getter and setter of the property to invoke the callback.
+ *
+ * [Source](https://stackoverflow.com/a/61975440)
+ * @param property The name of the property to observe
+ * @param callback Callback to execute when the value is changed
+ */
+export declare function observeElementProp<TElem extends Element = HTMLElement, TPropKey extends keyof TElem = keyof TElem>(element: TElem, property: TPropKey, callback: (oldVal: TElem[TPropKey], newVal: TElem[TPropKey]) => void): void;

package/dist/lib/misc.d.ts

@@ -2,6 +2,19 @@
 export type Stringifiable = string | {
     toString(): string;
 };
+/**
+ * A type that offers autocomplete for the passed union but also allows any arbitrary value of the same type to be passed.
+ * Supports unions of strings, numbers and objects.
+ */
+export type LooseUnion<TUnion extends string | number | object> = (TUnion) | (TUnion extends string ? (string & {}) : (TUnion extends number ? (number & {}) : (TUnion extends Record<keyof any, unknown> ? (object & {}) : never)));
+/**
+ * A type that allows all strings except for empty ones
+ * @example
+ * function foo<T extends string>(bar: NonEmptyString<T>) {
+ *   console.log(bar);
+ * }
+ */
+export type NonEmptyString<TString extends string> = TString extends "" ? never : TString;
 /**
  * Automatically appends an `s` to the passed {@linkcode word}, if {@linkcode num} is not equal to 1
  * @param word A word in singular form, to auto-convert to plural
@@ -25,7 +38,15 @@ export declare function fetchAdvanced(url: string, options?: FetchAdvancedOpts):
 /**
  * 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 input 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;
+export declare function insertValues(input: string, ...values: Stringifiable[]): string;
+/** Compresses a string or an ArrayBuffer using the provided {@linkcode compressionFormat} and returns it as a base64 string */
+export declare function compress(input: string | ArrayBuffer, compressionFormat: CompressionFormat, outputType?: "base64"): Promise<string>;
+/** Compresses a string or an ArrayBuffer using the provided {@linkcode compressionFormat} and returns it as an ArrayBuffer */
+export declare function compress(input: string | ArrayBuffer, compressionFormat: CompressionFormat, outputType: "arrayBuffer"): Promise<ArrayBuffer>;
+/** Decompresses a previously compressed base64 string or ArrayBuffer, with the format passed by {@linkcode compressionFormat}, converted to a string */
+export declare function decompress(input: string | ArrayBuffer, compressionFormat: CompressionFormat, outputType?: "string"): Promise<string>;
+/** Decompresses a previously compressed base64 string or ArrayBuffer, with the format passed by {@linkcode compressionFormat}, converted to an ArrayBuffer */
+export declare function decompress(input: string | ArrayBuffer, compressionFormat: CompressionFormat, outputType: "arrayBuffer"): Promise<ArrayBuffer>;

package/package.json

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