@sv443-network/userutils 3.0.0 → 4.0.0

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # @sv443-network/userutils
 
+## 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,7 +32,6 @@ 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
   - [**Math:**](#math)
     - [clamp()](#clamp) - constrain a number between a min and max value
@@ -44,6 +45,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 +59,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,101 +652,6 @@ interceptWindowEvent("beforeunload");
 
 <br>
 
-### amplifyMedia()
-Usage:  
-```ts
-amplifyMedia(mediaElement: HTMLMediaElement, initialGain?: number): AmplifyMediaResult
-```
-  
-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 |
-  
-<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())
-});
-
-
-const disableButton = document.querySelector<HTMLButtonElement>("button#disable");
-
-disableButton.addEventListener("click", () => {
-  if(ampResult) {
-    // disable the amplification
-    ampResult.disable();
-  }
-});
-```
-
-</details>
-
-<br>
-
 ### isScrollable()
 Usage:  
 ```ts
@@ -1121,6 +1031,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 +1452,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 +1480,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.0.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 {
@@ -401,13 +364,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 +572,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;

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 {
@@ -380,13 +343,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 +551,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;

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 {
@@ -378,13 +341,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 +545,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, 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,53 +45,6 @@ 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;

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.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",