@sv443-network/userutils 1.0.0 → 1.1.1

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # @sv443-network/userutils
 
+## 1.1.1
+
+### Patch Changes
+
+- 4799a9f: Fix TS error in ConfigManager migration functions
+
+## 1.1.0
+
+### Minor Changes
+
+- db5cded: Added `isScrollable()` to check whether an element has a horizontal or vertical scroll bar
+
+### Patch Changes
+
+- 9e26464: Replaced most occurrences of `HTMLElement` in the docs with `Element` for better compatibility
+
 ## 1.0.0
 
 ### Major Changes

package/README.md

@@ -2,6 +2,7 @@
 
 ## UserUtils
 Zero-dependency library with various utilities for userscripts - register listeners for when CSS selectors exist, intercept events, manage persistent user configurations, modify the DOM more easily and more.  
+  
 Contains builtin TypeScript declarations. Webpack compatible and supports ESM and CJS.  
 If you like using this library, please consider [supporting the development ❤️](https://github.com/sponsors/Sv443)
 
@@ -26,6 +27,7 @@ If you like using this library, please consider [supporting the development ❤
     - [interceptEvent()](#interceptevent) - conditionally intercepts events registered by `addEventListener()` on any given EventTarget object
     - [interceptWindowEvent()](#interceptwindowevent) - conditionally intercepts events registered by `addEventListener()` on the window object
     - [amplifyMedia()](#amplifymedia) - amplify an audio or video element's volume past the maximum of 100%
+    - [isScrollable()](#isscrollable) - check if an element has a horizontal or vertical scroll bar
   - [Math:](#math)
     - [clamp()](#clamp) - constrain a number between a min and max value
     - [mapRange()](#maprange) - map a number from one range to the same spot in another range
@@ -80,14 +82,13 @@ If you like using this library, please consider [supporting the development ❤
 
 ## Preamble:
 This library is written in TypeScript and contains builtin TypeScript declarations.  
-The usages and examples in this readme are written in TypeScript, but the library can also be used in plain JavaScript.  
-  
-Some features require the `@run-at` or `@grant` directives to be tweaked in the userscript header or have other requirements.  
-Their documentation will contain a section marked by a warning emoji (⚠️) that will go into more detail.  
   
 Each feature has example code that can be expanded by clicking on the text "Example - click to view".  
+The usages and examples are written in TypeScript, but the library can also be used in plain JavaScript after removing the type annotations (and changing the imports if you are using CommonJS).  
+If the usage section contains multiple definitions of the function, each occurrence represents an overload and you can choose which one you want to use.  
   
-If the usage section contains multiple definitions of the function, each occurrence represents an overload and you can choose which one you want to use.
+Some features require the `@run-at` or `@grant` directives to be tweaked in the userscript header or have other requirements.  
+Their documentation will contain a section marked by a warning emoji (⚠️) that will go into more detail.
 
 <br><br>
 
@@ -123,6 +124,7 @@ If set to `false` (default), querySelector() will be used and only the first mat
 If `continuous` is set to `true`, the listener will not be deregistered after it was called once (defaults to false).  
   
 When using TypeScript, the generic `TElement` can be used to specify the type of the element(s) that the listener will return.  
+It will default to `HTMLElement` if left undefined.  
   
 ⚠️ In order to use this function, [`initOnSelector()`](#initonselector) has to be called as soon as possible.  
 This initialization function has to be called after `DOMContentLoaded` is fired (or immediately if `@run-at document-end` is set).  
@@ -132,6 +134,8 @@ Calling onSelector() before `DOMContentLoaded` is fired will not throw an error,
 <details><summary><h4>Example - click to view</h4></summary>
 
 ```ts
+import { initOnSelector, onSelector } from "@sv443-network/userutils";
+
 document.addEventListener("DOMContentLoaded", initOnSelector);
 
 // Continuously checks if `div` elements are added to the DOM, then returns all of them (even previously detected ones) in a NodeList
@@ -177,6 +181,8 @@ You may see all options [here](https://developer.mozilla.org/en-US/docs/Web/API/
 <details><summary><h4>Example - click to view</h4></summary>
 
 ```ts
+import { initOnSelector } from "@sv443-network/userutils";
+
 document.addEventListener("DOMContentLoaded", () => {
   initOnSelector({
     attributes: true,
@@ -201,6 +207,8 @@ Since multiple listeners can be registered for the same selector, the value of t
 <details><summary><h4>Example - click to view</h4></summary>
 
 ```ts
+import { initOnSelector, onSelector, getSelectorMap } from "@sv443-network/userutils";
+
 document.addEventListener("DOMContentLoaded", initOnSelector);
 
 onSelector<HTMLDivElement>("div", {
@@ -244,6 +252,8 @@ Userscripts are sandboxed and do not have access to the regular window object, s
 <details><summary><h4>Example - click to view</h4></summary>
 
 ```ts
+import { getUnsafeWindow } from "@sv443-network/userutils";
+
 // trick the site into thinking the mouse was moved:
 const mouseEvent = new MouseEvent("mousemove", {
   view: getUnsafeWindow(),
@@ -252,6 +262,7 @@ const mouseEvent = new MouseEvent("mousemove", {
   movementX: 10,
   movementY: 0,
 });
+
 document.body.dispatchEvent(mouseEvent);
 ```
 
@@ -262,7 +273,7 @@ document.body.dispatchEvent(mouseEvent);
 ### insertAfter()
 Usage:  
 ```ts
-insertAfter(beforeElement: HTMLElement, afterElement: HTMLElement): HTMLElement
+insertAfter(beforeElement: Element, afterElement: Element): Element
 ```
   
 Inserts the element passed as `afterElement` as a sibling after the passed `beforeElement`.  
@@ -273,10 +284,13 @@ The passed `afterElement` will be returned.
 <details><summary><h4>Example - click to view</h4></summary>
 
 ```ts
+import { insertAfter } from "@sv443-network/userutils";
+
 // insert a <div> as a sibling next to an element
 const beforeElement = document.querySelector("#before");
 const afterElement = document.createElement("div");
 afterElement.innerText = "After";
+
 insertAfter(beforeElement, afterElement);
 ```
 
@@ -287,7 +301,7 @@ insertAfter(beforeElement, afterElement);
 ### addParent()
 Usage:  
 ```ts
-addParent(element: HTMLElement, newParent: HTMLElement): HTMLElement
+addParent(element: Element, newParent: Element): Element
 ```
   
 Adds a parent element around the passed `element` and returns the new parent.  
@@ -298,10 +312,13 @@ Previously registered event listeners are kept intact.
 <details><summary><h4>Example - click to view</h4></summary>
 
 ```ts
+import { addParent } from "@sv443-network/userutils";
+
 // add an <a> around an element
 const element = document.querySelector("#element");
 const newParent = document.createElement("a");
 newParent.href = "https://example.org/";
+
 addParent(element, newParent);
 ```
 
@@ -321,6 +338,8 @@ Adds a global style to the page in form of a `<style>` element that's inserted i
 <details><summary><h4>Example - click to view</h4></summary>
 
 ```ts
+import { addGlobalStyle } from "@sv443-network/userutils";
+
 document.addEventListener("DOMContentLoaded", () => {
   addGlobalStyle(`
     body {
@@ -347,6 +366,8 @@ The resulting PromiseSettledResult array will contain the image elements if reso
 <details><summary><h4>Example - click to view</h4></summary>
 
 ```ts
+import { preloadImages } from "@sv443-network/userutils";
+
 preloadImages([
   "https://example.org/image1.png",
   "https://example.org/image2.png",
@@ -376,6 +397,8 @@ This function has to be run in response to a user interaction event, else the br
 <details><summary><h4>Example - click to view</h4></summary>
 
 ```ts
+import { openInNewTab } from "@sv443-network/userutils";
+
 document.querySelector("#my-button").addEventListener("click", () => {
   openInNewTab("https://example.org/");
 });
@@ -391,7 +414,7 @@ Usage:
 interceptEvent(
   eventObject: EventTarget,
   eventName: string,
-  predicate: () => boolean
+  predicate: (event: Event) => boolean
 ): void
 ```
   
@@ -403,7 +426,10 @@ Calling this function will set the `Error.stackTraceLimit` to 1000 (if it's not
 <details><summary><h4>Example - click to view</h4></summary>
 
 ```ts
-interceptEvent(document.body, "click", () => {
+import { interceptEvent } from "@sv443-network/userutils";
+
+interceptEvent(document.body, "click", (event) => {
+  console.log("Intercepting click event:", event);
   return true; // prevent all click events on the body element
 });
 ```
@@ -417,7 +443,7 @@ Usage:
 ```ts
 interceptWindowEvent(
   eventName: string,
-  predicate: () => boolean
+  predicate: (event: Event) => boolean
 ): void
 ```
   
@@ -425,11 +451,14 @@ Intercepts all events dispatched on the `window` object and prevents the listene
 This is essentially the same as [`interceptEvent()`](#interceptevent), but automatically uses the `unsafeWindow` (or falls back to regular `window`).  
   
 ⚠️ This function should be called as soon as possible (I recommend using `@run-at document-start`), as it will only intercept events that are *attached* after this function is called.  
+⚠️ In order for all events to be interceptable, the directive `@grant unsafeWindow` should be set.  
   
 <details><summary><h4>Example - click to view</h4></summary>
 
 ```ts
-interceptWindowEvent("beforeunload", () => {
+import { interceptWindowEvent } from "@sv443-network/userutils";
+
+interceptWindowEvent("beforeunload", (event) => {
   return true; // prevent the pesky "Are you sure you want to leave this page?" popup
 });
 ```
@@ -463,6 +492,8 @@ The returned AmplifyMediaResult object has the following properties:
 <details><summary><h4>Example - click to view</h4></summary>
 
 ```ts
+import { amplifyMedia } from "@sv443-network/userutils";
+
 const audio = document.querySelector<HTMLAudioElement>("audio");
 const button = document.querySelector<HTMLButtonElement>("button");
 
@@ -485,6 +516,31 @@ button.addEventListener("click", () => {
 
 </details>
 
+<br>
+
+### isScrollable()
+Usage:  
+```ts
+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>
+
+```ts
+import { isScrollable } from "@sv443-network/userutils";
+
+const element = document.querySelector("#element");
+const { horizontal, vertical } = isScrollable(element);
+
+console.log("Element has a horizontal scroll bar:", horizontal);
+console.log("Element has a vertical scroll bar:", vertical);
+```
+
+</details>
+
 <br><br>
 
 ## Math:
@@ -500,6 +556,8 @@ Clamps a number between a min and max boundary (inclusive).
 <details><summary><h4>Example - click to view</h4></summary>
 
 ```ts
+import { clamp } from "@sv443-network/userutils";
+
 clamp(7, 0, 10);     // 7
 clamp(-1, 0, 10);    // 0
 clamp(5, -5, 0);     // 0
@@ -531,6 +589,8 @@ Maps a number from one range to the spot it would be in another range.
 <details><summary><h4>Example - click to view</h4></summary>
 
 ```ts
+import { mapRange } from "@sv443-network/userutils";
+
 mapRange(5, 0, 10, 0, 100); // 50
 mapRange(5, 0, 10, 0, 50);  // 25
 
@@ -556,6 +616,8 @@ If only one argument is passed, it will be used as the `max` value and `min` wil
 <details><summary><h4>Example - click to view</h4></summary>
 
 ```ts
+import { randRange } from "@sv443-network/userutils";
+
 randRange(0, 10);  // 4
 randRange(10, 20); // 17
 randRange(10);     // 7
@@ -575,8 +637,9 @@ new ConfigManager(options: ConfigManagerOptions)
   
 A class that manages a userscript's configuration that is persistently saved to and loaded from GM storage.  
 Also supports automatic migration of outdated data formats via provided migration functions.  
+You may create as many instances as you like as long as they have different IDs.  
   
-⚠️ The configuration is stored as a JSON string, so only JSON-compatible data can be used.  
+⚠️ The configuration is stored as a JSON string, so only JSON-compatible data can be used. Circular structures and complex objects will throw an error on load and save.  
 ⚠️ The directives `@grant GM.getValue` and `@grant GM.setValue` are required for this to work.  
   
 The options object has the following properties:
@@ -608,7 +671,8 @@ Writes the default configuration given in `options.defaultConfig` synchronously
 `deleteConfig(): Promise<void>`  
 Fully deletes the configuration from persistent storage.  
 The internal cache will be left untouched, so any subsequent calls to `getData()` will return the data that was last loaded.  
-If `loadData()` or `setData()` are called after this, the persistent storage will be populated again.  
+If `loadData()` or `setData()` are called after this, the persistent storage will be populated with the value of `options.defaultConfig` again.  
+⚠️ If you want to use this method, the additional directive `@grant GM.deleteValue` is required.  
 
 <br>
 
@@ -636,7 +700,7 @@ const formatVersion = 2;
 /** Functions that migrate outdated data to the latest format - make sure a function exists for every previously used formatVersion and that no numbers are skipped! */
 const migrations = {
   // migrate from format version 0 to 1
-  1: (oldData: any) => {
+  1: (oldData: Record<string, unknown>) => {
     return {
       foo: oldData.foo,
       bar: oldData.bar,
@@ -644,7 +708,7 @@ const migrations = {
     };
   },
   // asynchronously migrate from format version 1 to 2
-  2: async (oldData: any) => {
+  2: async (oldData: Record<string, unknown>) => {
     // arbitrary async operation required for the new format
     const qux = JSON.parse(await (await fetch("https://api.example.org/some-data")).text());
     return {
@@ -656,7 +720,7 @@ const migrations = {
   },
 };
 
-const configMgr = new ConfigManager({
+const manager = new ConfigManager({
   /** A unique ID for this configuration - choose wisely as changing it is not supported yet! */
   id: "my-userscript",
   /** Default / fallback configuration data */
@@ -672,7 +736,7 @@ async function init() {
   // wait for the config to be loaded from persistent storage
   // if no data was saved in persistent storage before or getData() is called before loadData(), the value of options.defaultConfig will be returned
   // if the previously saved data needs to be migrated to a newer version, it will happen in this function call
-  const configData = await configMgr.loadData();
+  const configData = await manager.loadData();
 
   console.log(configData.foo); // "hello"
 
@@ -681,12 +745,12 @@ async function init() {
   configData.bar = 123;
 
   // save the updated config - synchronously to the cache and asynchronously to persistent storage
-  configMgr.saveData(configData).then(() => {
+  manager.saveData(configData).then(() => {
     console.log("Config saved to persistent storage!");
   });
 
   // the internal cache is updated synchronously, so the updated data can be accessed before the Promise resolves:
-  console.log(configMgr.getData().foo); // "world"
+  console.log(manager.getData().foo); // "world"
 }
 
 init();
@@ -708,6 +772,8 @@ If an array or NodeList is passed, the amount of contained items will be used.
 <details><summary><h4>Example - click to view</h4></summary>
 
 ```ts
+import { autoPlural } from "@sv443-network/userutils";
+
 autoPlural("apple", 0); // "apples"
 autoPlural("apple", 1); // "apple"
 autoPlural("apple", 2); // "apples"
@@ -734,6 +800,8 @@ Pauses async execution for a given amount of time.
 <details><summary><h4>Example - click to view</h4></summary>
 
 ```ts
+import { pauseFor } from "@sv443-network/userutils";
+
 async function run() {
   console.log("Hello");
   await pauseFor(3000); // waits for 3 seconds
@@ -759,6 +827,8 @@ The timeout will default to 300ms if left undefined.
 <details><summary><h4>Example - click to view</h4></summary>
 
 ```ts
+import { debounce } from "@sv443-network/userutils";
+
 window.addEventListener("resize", debounce((event) => {
   console.log("Window was resized:", event);
 }, 500)); // 500ms timeout
@@ -783,7 +853,9 @@ The timeout will default to 10 seconds if left undefined.
 <details><summary><h4>Example - click to view</h4></summary>
 
 ```ts
-fetchAdvanced("https://api.example.org/data", {
+import { fetchAdvanced } from "@sv443-network/userutils";
+
+fetchAdvanced("https://jokeapi.dev/joke/Any?safe-mode", {
   timeout: 5000,
   // also accepts any other fetch options like headers:
   headers: {
@@ -812,6 +884,8 @@ Returns undefined if the array is empty.
 <details><summary><h4>Example - click to view</h4></summary>
 
 ```ts
+import { randomItem } from "@sv443-network/userutils";
+
 randomItem(["foo", "bar", "baz"]); // "bar"
 randomItem([ ]);                   // undefined
 ```
@@ -832,12 +906,15 @@ If the array is empty, it will return undefined for both values.
 <details><summary><h4>Example - click to view</h4></summary>
 
 ```ts
+import { randomItemIndex } from "@sv443-network/userutils";
+
 randomItemIndex(["foo", "bar", "baz"]); // ["bar", 1]
 randomItemIndex([ ]);                   // [undefined, undefined]
+
 // using array destructuring:
-const [item, index] = randomItemIndex(["foo", "bar", "baz"]);
+const [item, index] = randomItemIndex(["foo", "bar", "baz"]); // ["bar", 1]
 // or if you only want the index:
-const [, index] = randomItemIndex(["foo", "bar", "baz"]);
+const [, index] = randomItemIndex(["foo", "bar", "baz"]); // 1
 ```
 
 </details>
@@ -856,6 +933,8 @@ Returns undefined if the array is empty.
 <details><summary><h4>Example - click to view</h4></summary>
 
 ```ts
+import { takeRandomItem } from "@sv443-network/userutils";
+
 const arr = ["foo", "bar", "baz"];
 takeRandomItem(arr); // "bar"
 console.log(arr);    // ["foo", "baz"]
@@ -877,7 +956,14 @@ If the array is empty, the originally passed empty array will be returned withou
 <details><summary><h4>Example - click to view</h4></summary>
 
 ```ts
-randomizeArray([1, 2, 3, 4, 5, 6]); // [3, 1, 5, 2, 4, 6]
+import { randomizeArray } from "@sv443-network/userutils";
+
+const foo = [1, 2, 3, 4, 5, 6];
+
+console.log(randomizeArray(foo)); // [3, 1, 5, 2, 4, 6]
+console.log(randomizeArray(foo)); // [4, 5, 2, 1, 6, 3]
+
+console.log(foo); // [1, 2, 3, 4, 5, 6] - original array is not mutated
 ```
 
 </details>