@sv443-network/userutils 0.1.1

package/CHANGELOG.md

@@ -0,0 +1,27 @@
+# @sv443-network/userutils
+
+## 0.1.1
+
+### Patch Changes
+
+- bb60db0: minor fixes
+
+## 0.1.0
+
+### Minor Changes
+
+- 9206f6e: Initial release - Features:
+  - `onSelector()` to call a listener once a selector is found in the DOM
+  - `autoPlural()` to automatically pluralize a string
+  - `clamp()` to clamp a number between a min and max value
+  - `pauseFor()` to pause the execution of a function for a given amount of time
+  - `debounce()` to call a function only once, after a given amount of time
+  - `getUnsafeWindow()` to get the unsafeWindow object or fall back to the regular window object
+  - `insertAfter()` to insert an element as a sibling after another element
+  - `addParent()` to add a parent element around another element
+  - `addGlobalStyle()` to add a global style to the page
+  - `preloadImages()` to preload images into the browser cache for faster loading later on
+  - `fetchAdvanced()` as a wrapper around the fetch API with a timeout option
+  - `openInNewTab()` to open a link in a new tab
+  - `interceptEvent()` to conditionally intercept events registered by `addEventListener()` on any given EventTarget object
+  - `interceptWindowEvent()` to conditionally intercept events registered by `addEventListener()` on the window object

package/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Sven Fehler (Sv443)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,296 @@
+## UserUtils
+Library with various utilities for userscripts - register listeners for when CSS selectors exist, intercept events, modify the DOM more easily and more.  
+Contains builtin TypeScript definitions.
+
+<br>
+
+## Table of Contents:
+- [Installation](#installation)
+- [Features](#features)
+  - [onSelector()](#onselector) - call a listener once a selector is found in the DOM
+  - [autoPlural()](#autoplural) - automatically pluralize a string
+  - [clamp()](#clamp) - clamp a number between a min and max value
+  - [pauseFor()](#pausefor) - pause the execution of a function for a given amount of time
+  - [debounce()](#debounce) - call a function only once, after a given amount of time
+  - [getUnsafeWindow()](#getunsafewindow) - get the unsafeWindow object or fall back to the regular window object
+  - [insertAfter()](#insertafter) - insert an element as a sibling after another element
+  - [addParent()](#addparent) - add a parent element around another element
+  - [addGlobalStyle()](#addglobalstyle) - add a global style to the page
+  - [preloadImages()](#preloadimages) - preload images into the browser cache for faster loading later on
+  - [fetchAdvanced()](#fetchadvanced) - wrapper around the fetch API with a timeout option
+  - [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
+- [License](#license)
+
+<br><br>
+
+## Installation:
+- If you are using a bundler like webpack, you can install this package using npm:
+  ```
+  npm i @sv443-network/userutils
+  ```
+  Then, import it in your script as usual:
+  ```ts
+  import { addGlobalStyle } from "@sv443-network/userutils";
+  // or
+  import * as userUtils from "@sv443-network/userutils";
+  ```
+  Shameless plug: I also have a [webpack-based template for userscripts in TypeScript](https://github.com/Sv443/Userscript.ts) that you can use to get started quickly.
+
+<br>
+
+- If you are not using a bundler, you can include the latest release from GreasyFork by adding this directive to the userscript header:
+  ```
+  // @require https://greasyfork.org/scripts/TODO
+  ```
+
+<br>
+
+If you like using this library, please consider [supporting development](https://github.com/sponsors/Sv443)
+
+<br><br>
+
+## Features:
+
+### onSelector()
+\- UNFINISHED -  
+  
+Registers a listener to be called whenever the element(s) behind a selector is/are found in the DOM.  
+In order to use this function, the MutationObservers have to be initialized with `initOnSelector()` first.  
+  
+Example:
+```ts
+// TODO
+```
+
+<br>
+
+### autoPlural()
+Usage: `autoPlural(str: string, num: number | Array | NodeList): string`  
+  
+Automatically pluralizes a string if the given number is not 1.  
+If an array or NodeList is passed, the length of it will be used.  
+  
+Example:
+```ts
+autoPlural("apple", 0); // "apples"
+autoPlural("apple", 1); // "apple"
+autoPlural("apple", 2); // "apples"
+
+autoPlural("apple", [1]);    // "apple"
+autoPlural("apple", [1, 2]); // "apples"
+```
+
+<br>
+
+### clamp()
+Usage: `clamp(num: number, min: number, max: number): number`  
+  
+Clamps a number between a min and max value.  
+  
+Example:
+```ts
+clamp(5, 0, 10);        // 5
+clamp(-1, 0, 10);       // 0
+clamp(Infinity, 0, 10); // 10
+```
+
+<br>
+
+### pauseFor()
+Usage: `pauseFor(ms: number): Promise<void>`  
+  
+Pauses async execution for a given amount of time.  
+  
+Example:
+```ts
+async function run() {
+  console.log("Hello");
+  await pauseFor(3000); // waits for 3 seconds
+  console.log("World");
+}
+```
+
+<br>
+
+### debounce()
+Usage: `debounce(func: Function, timeout?: number): Function`  
+  
+Debounces a function, meaning that it will only be called once after a given amount of time.  
+This is very useful for functions that are called repeatedly, like event listeners, to remove extraneous calls.  
+The timeout will default to 300ms if left undefined.  
+  
+Example:
+```ts
+window.addEventListener("resize", debounce((event) => {
+  console.log("Window was resized:", event);
+}, 500)); // 500ms timeout
+```
+
+<br>
+
+### getUnsafeWindow()
+Usage: `getUnsafeWindow(): Window`  
+  
+Returns the unsafeWindow object or falls back to the regular window object if the `@grant unsafeWindow` is not given.  
+Userscripts are sandboxed and do not have access to the regular window object, so this function is useful for websites that reject some events that were dispatched by the userscript.  
+  
+Example:
+```ts
+const mouseEvent = new MouseEvent("click", {
+  view: getUnsafeWindow(),
+});
+document.body.dispatchEvent(mouseEvent);
+```
+
+<br>
+
+### insertAfter()
+Usage: `insertAfter(beforeElement: HTMLElement, afterElement: HTMLElement): HTMLElement`  
+  
+Inserts the element passed as `afterElement` as a sibling after the passed `beforeElement`.  
+The `afterElement` will be returned.  
+  
+Example:
+```ts
+const beforeElement = document.querySelector("#before");
+const afterElement = document.createElement("div");
+afterElement.innerText = "After";
+insertAfter(beforeElement, afterElement);
+```
+
+<br>
+
+### addParent()
+Usage: `addParent(element: HTMLElement, newParent: HTMLElement): HTMLElement`  
+  
+Adds a parent element around the passed `element` and returns the new parent.  
+Previously registered event listeners should be kept intact.  
+  
+Example:
+```ts
+const element = document.querySelector("#element");
+const newParent = document.createElement("a");
+newParent.href = "https://example.org/";
+addParent(element, newParent);
+```
+
+<br>
+
+### addGlobalStyle()
+Usage: `addGlobalStyle(css: string): void`  
+  
+Adds a global style to the page in form of a `<style>` element that's inserted into the `<head>`.  
+This function needs to be run after the DOM has loaded (when using `@run-at document-end` or after `DOMContentLoaded` has fired).  
+  
+Example:
+```ts
+document.addEventListener("DOMContentLoaded", () => {
+  addGlobalStyle(`
+    body {
+      background-color: red;
+    }
+  `);
+});
+```
+
+<br>
+
+### preloadImages()
+Usage: `preloadImages(...urls: string[]): Promise<void>`  
+  
+Preloads images into browser cache by creating an invisible `<img>` element for each URL passed.  
+The images will be loaded in parallel and the returned Promise will only resolve once all images have been loaded.  
+The resulting PromiseSettledResult array will contain the image elements if resolved, or an ErrorEvent if rejected.  
+  
+Example:
+```ts
+preloadImages(
+  "https://example.org/image1.png",
+  "https://example.org/image2.png",
+  "https://example.org/image3.png",
+).then((results) => {
+  console.log("Images preloaded. Results:", results);
+});
+```
+
+<br>
+
+### fetchAdvanced()
+Usage: `fetchAdvanced(url: string, options?: FetchAdvancedOptions): Promise<Response>`  
+  
+A wrapper around the native `fetch()` function that adds options like a timeout property.  
+The timeout will default to 10 seconds if left undefined.  
+  
+Example:
+```ts
+fetchAdvanced("https://example.org/", {
+  timeout: 5000,
+}).then((response) => {
+  console.log("Response:", response);
+});
+```
+
+<br>
+
+### openInNewTab()
+Usage: `openInNewTab(url: string): void`  
+  
+Creates an invisible anchor with a `_blank` target and clicks it.  
+Contrary to `window.open()`, this has a lesser chance to get blocked by the browser's popup blocker and doesn't open the URL as a new window.  
+This function has to be run in relatively quick succession in response to a user interaction event, else the browser might reject it.  
+  
+Example:
+```ts
+document.querySelector("#button").addEventListener("click", () => {
+  openInNewTab("https://example.org/");
+});
+```
+
+<br>
+
+### interceptEvent()
+Usage: `interceptEvent(eventObject: EventTarget, eventName: string, predicate: () => boolean): void`  
+  
+Intercepts all events dispatched on the `eventObject` and prevents the listeners from being called as long as the predicate function returns a truthy value.  
+This function should be called as soon as possible (I recommend using `@run-at document-start`), as it will only intercept events that are added after this function is called.  
+Calling this function will set the `Error.stackTraceLimit` to 1000 to ensure the stack trace is preserved.  
+  
+Example:
+```ts
+interceptEvent(document.body, "click", () => {
+  return true; // prevent all click events on the body
+});
+```
+
+<br>
+
+### interceptWindowEvent()
+Usage: `interceptWindowEvent(eventName: string, predicate: () => boolean): void`  
+  
+Intercepts all events dispatched on the `window` object and prevents the listeners from being called as long as the predicate function returns a truthy value.  
+This is essentially the same as [`interceptEvent()`](#interceptevent), but automatically uses the `unsafeWindow` (or falls back to regular `window`).  
+  
+Example:
+```ts
+interceptWindowEvent("beforeunload", () => {
+  return true; // prevent the pesky "Are you sure you want to leave this page?" popup
+});
+```
+
+
+<br><br>
+
+## License:
+This library is licensed under the MIT License.  
+See the [license file](./LICENSE.txt) for details.
+
+<br><br>
+
+<div style="text-align: center;" align="center">
+
+Made with ❤️ by [Sv443](https://github.com/Sv443)  
+If you like this library, please consider [supporting development](https://github.com/sponsors/Sv443)
+
+</div>

package/dist/index.d.mts

@@ -0,0 +1,84 @@
+type SelectorExistsOpts = {
+    /** The selector to check for */
+    selector: string;
+    /** Whether to use `querySelectorAll()` instead */
+    all?: boolean;
+    /** Whether to call the listener continuously instead of once */
+    continuous?: boolean;
+};
+type FetchAdvancedOpts = RequestInit & Partial<{
+    timeout: number;
+}>;
+
+/**
+ * Automatically appends an `s` to the passed `word`, if `num` is not equal to 1
+ * @param word A word in singular form, to auto-convert to plural
+ * @param num If this is an array or NodeList, the amount of items is used
+ */
+declare function autoPlural(word: string, num: number | unknown[] | NodeList): string;
+/** Ensures the passed `value` always stays between `min` and `max` */
+declare function clamp(value: number, min: number, max: number): number;
+/** Pauses async execution for the specified time in ms */
+declare function pauseFor(time: number): Promise<unknown>;
+/**
+ * Calls the passed `func` after the specified `timeout` in ms.
+ * Any subsequent calls to this function will reset the timer and discard previous calls.
+ */
+declare function debounce<TFunc extends (...args: TArgs[]) => void, TArgs = any>(func: TFunc, timeout?: number): (...args: TArgs[]) => void;
+/**
+ * Returns `unsafeWindow` if the `@grant unsafeWindow` is given, otherwise falls back to the regular `window`
+ */
+declare function getUnsafeWindow(): Window;
+/**
+ * Inserts `afterElement` as a sibling just after the provided `beforeElement`
+ * @returns Returns the `afterElement`
+ */
+declare function insertAfter(beforeElement: HTMLElement, afterElement: HTMLElement): HTMLElement;
+/**
+ * Adds a parent container around the provided element
+ * @returns Returns the new parent element
+ */
+declare function addParent(element: HTMLElement, newParent: HTMLElement): HTMLElement;
+/**
+ * Adds global CSS style in the form of a `<style>` element in the document's `<head>`
+ * This needs to be run after the `DOMContentLoaded` event has fired on the document object (or instantly if `@run-at document-end` is used).
+ * @param style CSS string
+ */
+declare function addGlobalStyle(style: string): void;
+/**
+ * Preloads an array of image URLs so they can be loaded instantly from the browser cache later on
+ * @param rejects If set to `true`, the returned PromiseSettledResults will contain rejections for any of the images that failed to load
+ * @returns Returns an array of `PromiseSettledResult` - each resolved result will contain the loaded image element, while each rejected result will contain an `ErrorEvent`
+ */
+declare function preloadImages(srcUrls: string[], rejects?: boolean): Promise<PromiseSettledResult<unknown>[]>;
+/** Calls the fetch API with special options like a timeout */
+declare function fetchAdvanced(url: string, options?: FetchAdvancedOpts): Promise<Response>;
+/**
+ * Creates an invisible anchor with a `_blank` target and clicks it.
+ * Contrary to `window.open()`, this has a lesser chance to get blocked by the browser's popup blocker and doesn't open the URL as a new window.
+ *
+ * This function has to be run in relatively quick succession in response to a user interaction event, else the browser might reject it.
+ */
+declare function openInNewTab(href: string): void;
+/**
+ * Intercepts the specified event on the passed object and prevents it from being called if the called `predicate` function returns a truthy value.
+ * Calling this function will set the `stackTraceLimit` to 1000 to ensure the stack trace is preserved.
+ */
+declare function interceptEvent<TEvtObj extends EventTarget>(eventObject: TEvtObj, eventName: Parameters<TEvtObj["addEventListener"]>[0], predicate: () => boolean): void;
+/**
+ * Intercepts the specified event on the window object and prevents it from being called if the called `predicate` function returns a truthy value.
+ * Calling this function will set the `stackTraceLimit` to 1000 to ensure the stack trace is preserved.
+ */
+declare function interceptWindowEvent(eventName: keyof WindowEventMap, predicate: () => boolean): void;
+
+/**
+ * Calls the `listener` as soon as the `selector` exists in the DOM.
+ * Listeners are deleted when they are called once, unless `options.continuous` is set.
+ * Multiple listeners with the same selector may be registered.
+ * @template TElem The type of element that this selector will return - FIXME: listener inferring doesn't work when this generic is given
+ */
+declare function onSelector<TElem = HTMLElement, TOpts extends SelectorExistsOpts = SelectorExistsOpts>(options: TOpts, listener: (element: TOpts["all"] extends true ? (TElem extends HTMLElement ? NodeListOf<TElem> : TElem) : TElem) => void): void;
+/** Removes all listeners registered in `onSelector()` with a matching selector property */
+declare function removeOnSelector(selector: string): void;
+
+export { FetchAdvancedOpts, SelectorExistsOpts, addGlobalStyle, addParent, autoPlural, clamp, debounce, fetchAdvanced, getUnsafeWindow, insertAfter, interceptEvent, interceptWindowEvent, onSelector, openInNewTab, pauseFor, preloadImages, removeOnSelector };

package/dist/index.d.ts

@@ -0,0 +1,84 @@
+type SelectorExistsOpts = {
+    /** The selector to check for */
+    selector: string;
+    /** Whether to use `querySelectorAll()` instead */
+    all?: boolean;
+    /** Whether to call the listener continuously instead of once */
+    continuous?: boolean;
+};
+type FetchAdvancedOpts = RequestInit & Partial<{
+    timeout: number;
+}>;
+
+/**
+ * Automatically appends an `s` to the passed `word`, if `num` is not equal to 1
+ * @param word A word in singular form, to auto-convert to plural
+ * @param num If this is an array or NodeList, the amount of items is used
+ */
+declare function autoPlural(word: string, num: number | unknown[] | NodeList): string;
+/** Ensures the passed `value` always stays between `min` and `max` */
+declare function clamp(value: number, min: number, max: number): number;
+/** Pauses async execution for the specified time in ms */
+declare function pauseFor(time: number): Promise<unknown>;
+/**
+ * Calls the passed `func` after the specified `timeout` in ms.
+ * Any subsequent calls to this function will reset the timer and discard previous calls.
+ */
+declare function debounce<TFunc extends (...args: TArgs[]) => void, TArgs = any>(func: TFunc, timeout?: number): (...args: TArgs[]) => void;
+/**
+ * Returns `unsafeWindow` if the `@grant unsafeWindow` is given, otherwise falls back to the regular `window`
+ */
+declare function getUnsafeWindow(): Window;
+/**
+ * Inserts `afterElement` as a sibling just after the provided `beforeElement`
+ * @returns Returns the `afterElement`
+ */
+declare function insertAfter(beforeElement: HTMLElement, afterElement: HTMLElement): HTMLElement;
+/**
+ * Adds a parent container around the provided element
+ * @returns Returns the new parent element
+ */
+declare function addParent(element: HTMLElement, newParent: HTMLElement): HTMLElement;
+/**
+ * Adds global CSS style in the form of a `<style>` element in the document's `<head>`
+ * This needs to be run after the `DOMContentLoaded` event has fired on the document object (or instantly if `@run-at document-end` is used).
+ * @param style CSS string
+ */
+declare function addGlobalStyle(style: string): void;
+/**
+ * Preloads an array of image URLs so they can be loaded instantly from the browser cache later on
+ * @param rejects If set to `true`, the returned PromiseSettledResults will contain rejections for any of the images that failed to load
+ * @returns Returns an array of `PromiseSettledResult` - each resolved result will contain the loaded image element, while each rejected result will contain an `ErrorEvent`
+ */
+declare function preloadImages(srcUrls: string[], rejects?: boolean): Promise<PromiseSettledResult<unknown>[]>;
+/** Calls the fetch API with special options like a timeout */
+declare function fetchAdvanced(url: string, options?: FetchAdvancedOpts): Promise<Response>;
+/**
+ * Creates an invisible anchor with a `_blank` target and clicks it.
+ * Contrary to `window.open()`, this has a lesser chance to get blocked by the browser's popup blocker and doesn't open the URL as a new window.
+ *
+ * This function has to be run in relatively quick succession in response to a user interaction event, else the browser might reject it.
+ */
+declare function openInNewTab(href: string): void;
+/**
+ * Intercepts the specified event on the passed object and prevents it from being called if the called `predicate` function returns a truthy value.
+ * Calling this function will set the `stackTraceLimit` to 1000 to ensure the stack trace is preserved.
+ */
+declare function interceptEvent<TEvtObj extends EventTarget>(eventObject: TEvtObj, eventName: Parameters<TEvtObj["addEventListener"]>[0], predicate: () => boolean): void;
+/**
+ * Intercepts the specified event on the window object and prevents it from being called if the called `predicate` function returns a truthy value.
+ * Calling this function will set the `stackTraceLimit` to 1000 to ensure the stack trace is preserved.
+ */
+declare function interceptWindowEvent(eventName: keyof WindowEventMap, predicate: () => boolean): void;
+
+/**
+ * Calls the `listener` as soon as the `selector` exists in the DOM.
+ * Listeners are deleted when they are called once, unless `options.continuous` is set.
+ * Multiple listeners with the same selector may be registered.
+ * @template TElem The type of element that this selector will return - FIXME: listener inferring doesn't work when this generic is given
+ */
+declare function onSelector<TElem = HTMLElement, TOpts extends SelectorExistsOpts = SelectorExistsOpts>(options: TOpts, listener: (element: TOpts["all"] extends true ? (TElem extends HTMLElement ? NodeListOf<TElem> : TElem) : TElem) => void): void;
+/** Removes all listeners registered in `onSelector()` with a matching selector property */
+declare function removeOnSelector(selector: string): void;
+
+export { FetchAdvancedOpts, SelectorExistsOpts, addGlobalStyle, addParent, autoPlural, clamp, debounce, fetchAdvanced, getUnsafeWindow, insertAfter, interceptEvent, interceptWindowEvent, onSelector, openInNewTab, pauseFor, preloadImages, removeOnSelector };

package/dist/index.js

@@ -0,0 +1,162 @@
+'use strict';
+
+var __defProp = Object.defineProperty;
+var __defProps = Object.defineProperties;
+var __getOwnPropDescs = Object.getOwnPropertyDescriptors;
+var __getOwnPropSymbols = Object.getOwnPropertySymbols;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __propIsEnum = Object.prototype.propertyIsEnumerable;
+var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
+var __spreadValues = (a, b) => {
+  for (var prop in b || (b = {}))
+    if (__hasOwnProp.call(b, prop))
+      __defNormalProp(a, prop, b[prop]);
+  if (__getOwnPropSymbols)
+    for (var prop of __getOwnPropSymbols(b)) {
+      if (__propIsEnum.call(b, prop))
+        __defNormalProp(a, prop, b[prop]);
+    }
+  return a;
+};
+var __spreadProps = (a, b) => __defProps(a, __getOwnPropDescs(b));
+var __async = (__this, __arguments, generator) => {
+  return new Promise((resolve, reject) => {
+    var fulfilled = (value) => {
+      try {
+        step(generator.next(value));
+      } catch (e) {
+        reject(e);
+      }
+    };
+    var rejected = (value) => {
+      try {
+        step(generator.throw(value));
+      } catch (e) {
+        reject(e);
+      }
+    };
+    var step = (x) => x.done ? resolve(x.value) : Promise.resolve(x.value).then(fulfilled, rejected);
+    step((generator = generator.apply(__this, __arguments)).next());
+  });
+};
+
+// lib/utils.ts
+function autoPlural(word, num) {
+  if (Array.isArray(num) || num instanceof NodeList)
+    num = num.length;
+  return `${word}${num === 1 ? "" : "s"}`;
+}
+function clamp(value, min, max) {
+  return Math.max(Math.min(value, max), min);
+}
+function pauseFor(time) {
+  return new Promise((res) => {
+    setTimeout(res, time);
+  });
+}
+function debounce(func, timeout = 300) {
+  let timer;
+  return function(...args) {
+    clearTimeout(timer);
+    timer = setTimeout(() => func.apply(this, args), timeout);
+  };
+}
+function getUnsafeWindow() {
+  try {
+    return unsafeWindow;
+  } catch (e) {
+    return window;
+  }
+}
+function insertAfter(beforeElement, afterElement) {
+  var _a;
+  (_a = beforeElement.parentNode) == null ? void 0 : _a.insertBefore(afterElement, beforeElement.nextSibling);
+  return afterElement;
+}
+function addParent(element2, newParent) {
+  const oldParent = element2.parentNode;
+  if (!oldParent)
+    throw new Error("Element doesn't have a parent node");
+  oldParent.replaceChild(newParent, element2);
+  newParent.appendChild(element2);
+  return newParent;
+}
+function addGlobalStyle(style) {
+  const styleElem = document.createElement("style");
+  styleElem.innerHTML = style;
+  document.head.appendChild(styleElem);
+}
+function preloadImages(srcUrls, rejects = false) {
+  const promises = srcUrls.map((src) => new Promise((res, rej) => {
+    const image = new Image();
+    image.src = src;
+    image.addEventListener("load", () => res(image));
+    image.addEventListener("error", (evt) => rejects && rej(evt));
+  }));
+  return Promise.allSettled(promises);
+}
+function fetchAdvanced(_0) {
+  return __async(this, arguments, function* (url, options = {}) {
+    const { timeout = 1e4 } = options;
+    const controller = new AbortController();
+    const id = setTimeout(() => controller.abort(), timeout);
+    const res = yield fetch(url, __spreadProps(__spreadValues({}, options), {
+      signal: controller.signal
+    }));
+    clearTimeout(id);
+    return res;
+  });
+}
+function openInNewTab(href) {
+  const openElem = document.createElement("a");
+  Object.assign(openElem, {
+    className: "userutils-open-in-new-tab",
+    target: "_blank",
+    rel: "noopener noreferrer",
+    href
+  });
+  openElem.style.display = "none";
+  document.body.appendChild(openElem);
+  openElem.click();
+  setTimeout(openElem.remove, 50);
+}
+function interceptEvent(eventObject, eventName, predicate) {
+  if (Error.stackTraceLimit < 1e3) {
+    Error.stackTraceLimit = 1e3;
+  }
+  (function(original) {
+    element.__proto__.addEventListener = function(...args) {
+      if (args[0] === eventName && predicate())
+        return;
+      else
+        return original.apply(this, args);
+    };
+  })(eventObject.__proto__.addEventListener);
+}
+function interceptWindowEvent(eventName, predicate) {
+  return interceptEvent(getUnsafeWindow(), eventName, predicate);
+}
+
+// lib/onSelector.ts
+function onSelector(options, listener) {
+}
+function removeOnSelector(selector) {
+}
+
+exports.addGlobalStyle = addGlobalStyle;
+exports.addParent = addParent;
+exports.autoPlural = autoPlural;
+exports.clamp = clamp;
+exports.debounce = debounce;
+exports.fetchAdvanced = fetchAdvanced;
+exports.getUnsafeWindow = getUnsafeWindow;
+exports.insertAfter = insertAfter;
+exports.interceptEvent = interceptEvent;
+exports.interceptWindowEvent = interceptWindowEvent;
+exports.onSelector = onSelector;
+exports.openInNewTab = openInNewTab;
+exports.pauseFor = pauseFor;
+exports.preloadImages = preloadImages;
+exports.removeOnSelector = removeOnSelector;
+//# sourceMappingURL=out.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../lib/utils.ts","../lib/onSelector.ts"],"names":["element"],"mappings":"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","sourcesContent":["import type { FetchAdvancedOpts } from \"./types\";\n\n/**\n * Automatically appends an `s` to the passed `word`, if `num` is not equal to 1\n * @param word A word in singular form, to auto-convert to plural\n * @param num If this is an array or NodeList, the amount of items is used\n */\nexport function autoPlural(word: string, num: number | unknown[] | NodeList) {\n  if(Array.isArray(num) || num instanceof NodeList)\n    num = num.length;\n  return `${word}${num === 1 ? \"\" : \"s\"}`;\n}\n\n/** Ensures the passed `value` always stays between `min` and `max` */\nexport function clamp(value: number, min: number, max: number) {\n  return Math.max(Math.min(value, max), min);\n}\n\n/** Pauses async execution for the specified time in ms */\nexport function pauseFor(time: number) {\n  return new Promise((res) => {\n    setTimeout(res, time);\n  });\n}\n\n/**\n * Calls the passed `func` after the specified `timeout` in ms.  \n * Any subsequent calls to this function will reset the timer and discard previous calls.\n */\nexport function debounce<TFunc extends (...args: TArgs[]) => void, TArgs = any>(func: TFunc, timeout = 300) { // eslint-disable-line @typescript-eslint/no-explicit-any\n  let timer: number | undefined;\n  return function(...args: TArgs[]) {\n    clearTimeout(timer);\n    timer = setTimeout(() => func.apply(this, args), timeout) as unknown as number;\n  };\n}\n\n/**\n * Returns `unsafeWindow` if the `@grant unsafeWindow` is given, otherwise falls back to the regular `window`\n */\nexport function getUnsafeWindow() {\n  try {\n    // throws ReferenceError if the \"@grant unsafeWindow\" isn't present\n    return unsafeWindow;\n  }\n  catch(e) {\n    return window;\n  }\n}\n\n/**\n * Inserts `afterElement` as a sibling just after the provided `beforeElement`\n * @returns Returns the `afterElement`\n */\nexport function insertAfter(beforeElement: HTMLElement, afterElement: HTMLElement) {\n  beforeElement.parentNode?.insertBefore(afterElement, beforeElement.nextSibling);\n  return afterElement;\n}\n\n/**\n * Adds a parent container around the provided element\n * @returns Returns the new parent element\n */\nexport function addParent(element: HTMLElement, newParent: HTMLElement) {\n  const oldParent = element.parentNode;\n\n  if(!oldParent)\n    throw new Error(\"Element doesn't have a parent node\");\n\n  oldParent.replaceChild(newParent, element);\n  newParent.appendChild(element);\n\n  return newParent;\n}\n\n/**\n * Adds global CSS style in the form of a `<style>` element in the document's `<head>`  \n * This needs to be run after the `DOMContentLoaded` event has fired on the document object (or instantly if `@run-at document-end` is used).\n * @param style CSS string\n */\nexport function addGlobalStyle(style: string) {\n  const styleElem = document.createElement(\"style\");\n  styleElem.innerHTML = style;\n  document.head.appendChild(styleElem);\n}\n\n/**\n * Preloads an array of image URLs so they can be loaded instantly from the browser cache later on\n * @param rejects If set to `true`, the returned PromiseSettledResults will contain rejections for any of the images that failed to load\n * @returns Returns an array of `PromiseSettledResult` - each resolved result will contain the loaded image element, while each rejected result will contain an `ErrorEvent`\n */\nexport function preloadImages(srcUrls: string[], rejects = false) {\n  const promises = srcUrls.map(src => new Promise((res, rej) => {\n    const image = new Image();\n    image.src = src;\n    image.addEventListener(\"load\", () => res(image));\n    image.addEventListener(\"error\", (evt) => rejects && rej(evt));\n  }));\n\n  return Promise.allSettled(promises);\n}\n\n/** Calls the fetch API with special options like a timeout */\nexport async function fetchAdvanced(url: string, options: FetchAdvancedOpts = {}) {\n  const { timeout = 10000 } = options;\n\n  const controller = new AbortController();\n  const id = setTimeout(() => controller.abort(), timeout);\n\n  const res = await fetch(url, {\n    ...options,\n    signal: controller.signal,\n  });\n\n  clearTimeout(id);\n  return res;\n}\n\n/**\n * Creates an invisible anchor with a `_blank` target and clicks it.  \n * Contrary to `window.open()`, this has a lesser chance to get blocked by the browser's popup blocker and doesn't open the URL as a new window.  \n *   \n * This function has to be run in relatively quick succession in response to a user interaction event, else the browser might reject it.\n */\nexport function openInNewTab(href: string) {\n  const openElem = document.createElement(\"a\");\n  Object.assign(openElem, {\n    className: \"userutils-open-in-new-tab\",\n    target: \"_blank\",\n    rel: \"noopener noreferrer\",\n    href,\n  });\n  openElem.style.display = \"none\";\n\n  document.body.appendChild(openElem);\n  openElem.click();\n  // timeout just to be safe\n  setTimeout(openElem.remove, 50);\n}\n\n/**\n * Intercepts the specified event on the passed object and prevents it from being called if the called `predicate` function returns a truthy value.  \n * Calling this function will set the `stackTraceLimit` to 1000 to ensure the stack trace is preserved.\n */\nexport function interceptEvent<TEvtObj extends EventTarget>(eventObject: TEvtObj, eventName: Parameters<TEvtObj[\"addEventListener\"]>[0], predicate: () => boolean) {  \n  // default is between 10 and 100 on conventional browsers so this should hopefully be more than enough\n  // @ts-ignore\n  if(Error.stackTraceLimit < 1000) {\n    // @ts-ignore\n    Error.stackTraceLimit = 1000;\n  }\n\n  (function(original: typeof eventObject.addEventListener) {\n    // @ts-ignore\n    element.__proto__.addEventListener = function(...args: Parameters<typeof eventObject.addEventListener>) {\n      if(args[0] === eventName && predicate())\n        return;\n      else\n        return original.apply(this, args);\n    };\n    // @ts-ignore\n  })(eventObject.__proto__.addEventListener);\n}\n\n/**\n * Intercepts the specified event on the window object and prevents it from being called if the called `predicate` function returns a truthy value.  \n * Calling this function will set the `stackTraceLimit` to 1000 to ensure the stack trace is preserved.\n */\nexport function interceptWindowEvent(eventName: keyof WindowEventMap, predicate: () => boolean) {  \n  return interceptEvent(getUnsafeWindow(), eventName, predicate);\n}\n","import { SelectorExistsOpts } from \"./types\";\n\n/**\n * Calls the `listener` as soon as the `selector` exists in the DOM.  \n * Listeners are deleted when they are called once, unless `options.continuous` is set.  \n * Multiple listeners with the same selector may be registered.\n * @template TElem The type of element that this selector will return - FIXME: listener inferring doesn't work when this generic is given\n */\nexport function onSelector<TElem = HTMLElement, TOpts extends SelectorExistsOpts = SelectorExistsOpts>(\n  options: TOpts,\n  listener: (element: TOpts[\"all\"] extends true ? (TElem extends HTMLElement ? NodeListOf<TElem> : TElem) : TElem) => void,\n) {\n  // TODO:\n  void [options, listener];\n}\n\n/** Removes all listeners registered in `onSelector()` with a matching selector property */\nexport function removeOnSelector(selector: string) {\n  // TODO:\n  void [selector];\n}\n"]}

package/dist/index.mjs

@@ -0,0 +1,146 @@
+var __defProp = Object.defineProperty;
+var __defProps = Object.defineProperties;
+var __getOwnPropDescs = Object.getOwnPropertyDescriptors;
+var __getOwnPropSymbols = Object.getOwnPropertySymbols;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __propIsEnum = Object.prototype.propertyIsEnumerable;
+var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
+var __spreadValues = (a, b) => {
+  for (var prop in b || (b = {}))
+    if (__hasOwnProp.call(b, prop))
+      __defNormalProp(a, prop, b[prop]);
+  if (__getOwnPropSymbols)
+    for (var prop of __getOwnPropSymbols(b)) {
+      if (__propIsEnum.call(b, prop))
+        __defNormalProp(a, prop, b[prop]);
+    }
+  return a;
+};
+var __spreadProps = (a, b) => __defProps(a, __getOwnPropDescs(b));
+var __async = (__this, __arguments, generator) => {
+  return new Promise((resolve, reject) => {
+    var fulfilled = (value) => {
+      try {
+        step(generator.next(value));
+      } catch (e) {
+        reject(e);
+      }
+    };
+    var rejected = (value) => {
+      try {
+        step(generator.throw(value));
+      } catch (e) {
+        reject(e);
+      }
+    };
+    var step = (x) => x.done ? resolve(x.value) : Promise.resolve(x.value).then(fulfilled, rejected);
+    step((generator = generator.apply(__this, __arguments)).next());
+  });
+};
+
+// lib/utils.ts
+function autoPlural(word, num) {
+  if (Array.isArray(num) || num instanceof NodeList)
+    num = num.length;
+  return `${word}${num === 1 ? "" : "s"}`;
+}
+function clamp(value, min, max) {
+  return Math.max(Math.min(value, max), min);
+}
+function pauseFor(time) {
+  return new Promise((res) => {
+    setTimeout(res, time);
+  });
+}
+function debounce(func, timeout = 300) {
+  let timer;
+  return function(...args) {
+    clearTimeout(timer);
+    timer = setTimeout(() => func.apply(this, args), timeout);
+  };
+}
+function getUnsafeWindow() {
+  try {
+    return unsafeWindow;
+  } catch (e) {
+    return window;
+  }
+}
+function insertAfter(beforeElement, afterElement) {
+  var _a;
+  (_a = beforeElement.parentNode) == null ? void 0 : _a.insertBefore(afterElement, beforeElement.nextSibling);
+  return afterElement;
+}
+function addParent(element2, newParent) {
+  const oldParent = element2.parentNode;
+  if (!oldParent)
+    throw new Error("Element doesn't have a parent node");
+  oldParent.replaceChild(newParent, element2);
+  newParent.appendChild(element2);
+  return newParent;
+}
+function addGlobalStyle(style) {
+  const styleElem = document.createElement("style");
+  styleElem.innerHTML = style;
+  document.head.appendChild(styleElem);
+}
+function preloadImages(srcUrls, rejects = false) {
+  const promises = srcUrls.map((src) => new Promise((res, rej) => {
+    const image = new Image();
+    image.src = src;
+    image.addEventListener("load", () => res(image));
+    image.addEventListener("error", (evt) => rejects && rej(evt));
+  }));
+  return Promise.allSettled(promises);
+}
+function fetchAdvanced(_0) {
+  return __async(this, arguments, function* (url, options = {}) {
+    const { timeout = 1e4 } = options;
+    const controller = new AbortController();
+    const id = setTimeout(() => controller.abort(), timeout);
+    const res = yield fetch(url, __spreadProps(__spreadValues({}, options), {
+      signal: controller.signal
+    }));
+    clearTimeout(id);
+    return res;
+  });
+}
+function openInNewTab(href) {
+  const openElem = document.createElement("a");
+  Object.assign(openElem, {
+    className: "userutils-open-in-new-tab",
+    target: "_blank",
+    rel: "noopener noreferrer",
+    href
+  });
+  openElem.style.display = "none";
+  document.body.appendChild(openElem);
+  openElem.click();
+  setTimeout(openElem.remove, 50);
+}
+function interceptEvent(eventObject, eventName, predicate) {
+  if (Error.stackTraceLimit < 1e3) {
+    Error.stackTraceLimit = 1e3;
+  }
+  (function(original) {
+    element.__proto__.addEventListener = function(...args) {
+      if (args[0] === eventName && predicate())
+        return;
+      else
+        return original.apply(this, args);
+    };
+  })(eventObject.__proto__.addEventListener);
+}
+function interceptWindowEvent(eventName, predicate) {
+  return interceptEvent(getUnsafeWindow(), eventName, predicate);
+}
+
+// lib/onSelector.ts
+function onSelector(options, listener) {
+}
+function removeOnSelector(selector) {
+}
+
+export { addGlobalStyle, addParent, autoPlural, clamp, debounce, fetchAdvanced, getUnsafeWindow, insertAfter, interceptEvent, interceptWindowEvent, onSelector, openInNewTab, pauseFor, preloadImages, removeOnSelector };
+//# sourceMappingURL=out.js.map
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../lib/utils.ts","../lib/onSelector.ts"],"names":["element"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAOO,SAAS,WAAW,MAAc,KAAoC;AAC3E,MAAG,MAAM,QAAQ,GAAG,KAAK,eAAe;AACtC,UAAM,IAAI;AACZ,SAAO,GAAG,IAAI,GAAG,QAAQ,IAAI,KAAK,GAAG;AACvC;AAGO,SAAS,MAAM,OAAe,KAAa,KAAa;AAC7D,SAAO,KAAK,IAAI,KAAK,IAAI,OAAO,GAAG,GAAG,GAAG;AAC3C;AAGO,SAAS,SAAS,MAAc;AACrC,SAAO,IAAI,QAAQ,CAAC,QAAQ;AAC1B,eAAW,KAAK,IAAI;AAAA,EACtB,CAAC;AACH;AAMO,SAAS,SAAgE,MAAa,UAAU,KAAK;AAC1G,MAAI;AACJ,SAAO,YAAY,MAAe;AAChC,iBAAa,KAAK;AAClB,YAAQ,WAAW,MAAM,KAAK,MAAM,MAAM,IAAI,GAAG,OAAO;AAAA,EAC1D;AACF;AAKO,SAAS,kBAAkB;AAChC,MAAI;AAEF,WAAO;AAAA,EACT,SACM,GAAG;AACP,WAAO;AAAA,EACT;AACF;AAMO,SAAS,YAAY,eAA4B,cAA2B;AAtDnF;AAuDE,sBAAc,eAAd,mBAA0B,aAAa,cAAc,cAAc;AACnE,SAAO;AACT;AAMO,SAAS,UAAUA,UAAsB,WAAwB;AACtE,QAAM,YAAYA,SAAQ;AAE1B,MAAG,CAAC;AACF,UAAM,IAAI,MAAM,oCAAoC;AAEtD,YAAU,aAAa,WAAWA,QAAO;AACzC,YAAU,YAAYA,QAAO;AAE7B,SAAO;AACT;AAOO,SAAS,eAAe,OAAe;AAC5C,QAAM,YAAY,SAAS,cAAc,OAAO;AAChD,YAAU,YAAY;AACtB,WAAS,KAAK,YAAY,SAAS;AACrC;AAOO,SAAS,cAAc,SAAmB,UAAU,OAAO;AAChE,QAAM,WAAW,QAAQ,IAAI,SAAO,IAAI,QAAQ,CAAC,KAAK,QAAQ;AAC5D,UAAM,QAAQ,IAAI,MAAM;AACxB,UAAM,MAAM;AACZ,UAAM,iBAAiB,QAAQ,MAAM,IAAI,KAAK,CAAC;AAC/C,UAAM,iBAAiB,SAAS,CAAC,QAAQ,WAAW,IAAI,GAAG,CAAC;AAAA,EAC9D,CAAC,CAAC;AAEF,SAAO,QAAQ,WAAW,QAAQ;AACpC;AAGA,SAAsB,cAAc,IAA8C;AAAA,6CAA9C,KAAa,UAA6B,CAAC,GAAG;AAChF,UAAM,EAAE,UAAU,IAAM,IAAI;AAE5B,UAAM,aAAa,IAAI,gBAAgB;AACvC,UAAM,KAAK,WAAW,MAAM,WAAW,MAAM,GAAG,OAAO;AAEvD,UAAM,MAAM,MAAM,MAAM,KAAK,iCACxB,UADwB;AAAA,MAE3B,QAAQ,WAAW;AAAA,IACrB,EAAC;AAED,iBAAa,EAAE;AACf,WAAO;AAAA,EACT;AAAA;AAQO,SAAS,aAAa,MAAc;AACzC,QAAM,WAAW,SAAS,cAAc,GAAG;AAC3C,SAAO,OAAO,UAAU;AAAA,IACtB,WAAW;AAAA,IACX,QAAQ;AAAA,IACR,KAAK;AAAA,IACL;AAAA,EACF,CAAC;AACD,WAAS,MAAM,UAAU;AAEzB,WAAS,KAAK,YAAY,QAAQ;AAClC,WAAS,MAAM;AAEf,aAAW,SAAS,QAAQ,EAAE;AAChC;AAMO,SAAS,eAA4C,aAAsB,WAAuD,WAA0B;AAGjK,MAAG,MAAM,kBAAkB,KAAM;AAE/B,UAAM,kBAAkB;AAAA,EAC1B;AAEA,GAAC,SAAS,UAA+C;AAEvD,YAAQ,UAAU,mBAAmB,YAAY,MAAuD;AACtG,UAAG,KAAK,CAAC,MAAM,aAAa,UAAU;AACpC;AAAA;AAEA,eAAO,SAAS,MAAM,MAAM,IAAI;AAAA,IACpC;AAAA,EAEF,GAAG,YAAY,UAAU,gBAAgB;AAC3C;AAMO,SAAS,qBAAqB,WAAiC,WAA0B;AAC9F,SAAO,eAAe,gBAAgB,GAAG,WAAW,SAAS;AAC/D;;;AClKO,SAAS,WACd,SACA,UACA;AAGF;AAGO,SAAS,iBAAiB,UAAkB;AAGnD","sourcesContent":["import type { FetchAdvancedOpts } from \"./types\";\n\n/**\n * Automatically appends an `s` to the passed `word`, if `num` is not equal to 1\n * @param word A word in singular form, to auto-convert to plural\n * @param num If this is an array or NodeList, the amount of items is used\n */\nexport function autoPlural(word: string, num: number | unknown[] | NodeList) {\n  if(Array.isArray(num) || num instanceof NodeList)\n    num = num.length;\n  return `${word}${num === 1 ? \"\" : \"s\"}`;\n}\n\n/** Ensures the passed `value` always stays between `min` and `max` */\nexport function clamp(value: number, min: number, max: number) {\n  return Math.max(Math.min(value, max), min);\n}\n\n/** Pauses async execution for the specified time in ms */\nexport function pauseFor(time: number) {\n  return new Promise((res) => {\n    setTimeout(res, time);\n  });\n}\n\n/**\n * Calls the passed `func` after the specified `timeout` in ms.  \n * Any subsequent calls to this function will reset the timer and discard previous calls.\n */\nexport function debounce<TFunc extends (...args: TArgs[]) => void, TArgs = any>(func: TFunc, timeout = 300) { // eslint-disable-line @typescript-eslint/no-explicit-any\n  let timer: number | undefined;\n  return function(...args: TArgs[]) {\n    clearTimeout(timer);\n    timer = setTimeout(() => func.apply(this, args), timeout) as unknown as number;\n  };\n}\n\n/**\n * Returns `unsafeWindow` if the `@grant unsafeWindow` is given, otherwise falls back to the regular `window`\n */\nexport function getUnsafeWindow() {\n  try {\n    // throws ReferenceError if the \"@grant unsafeWindow\" isn't present\n    return unsafeWindow;\n  }\n  catch(e) {\n    return window;\n  }\n}\n\n/**\n * Inserts `afterElement` as a sibling just after the provided `beforeElement`\n * @returns Returns the `afterElement`\n */\nexport function insertAfter(beforeElement: HTMLElement, afterElement: HTMLElement) {\n  beforeElement.parentNode?.insertBefore(afterElement, beforeElement.nextSibling);\n  return afterElement;\n}\n\n/**\n * Adds a parent container around the provided element\n * @returns Returns the new parent element\n */\nexport function addParent(element: HTMLElement, newParent: HTMLElement) {\n  const oldParent = element.parentNode;\n\n  if(!oldParent)\n    throw new Error(\"Element doesn't have a parent node\");\n\n  oldParent.replaceChild(newParent, element);\n  newParent.appendChild(element);\n\n  return newParent;\n}\n\n/**\n * Adds global CSS style in the form of a `<style>` element in the document's `<head>`  \n * This needs to be run after the `DOMContentLoaded` event has fired on the document object (or instantly if `@run-at document-end` is used).\n * @param style CSS string\n */\nexport function addGlobalStyle(style: string) {\n  const styleElem = document.createElement(\"style\");\n  styleElem.innerHTML = style;\n  document.head.appendChild(styleElem);\n}\n\n/**\n * Preloads an array of image URLs so they can be loaded instantly from the browser cache later on\n * @param rejects If set to `true`, the returned PromiseSettledResults will contain rejections for any of the images that failed to load\n * @returns Returns an array of `PromiseSettledResult` - each resolved result will contain the loaded image element, while each rejected result will contain an `ErrorEvent`\n */\nexport function preloadImages(srcUrls: string[], rejects = false) {\n  const promises = srcUrls.map(src => new Promise((res, rej) => {\n    const image = new Image();\n    image.src = src;\n    image.addEventListener(\"load\", () => res(image));\n    image.addEventListener(\"error\", (evt) => rejects && rej(evt));\n  }));\n\n  return Promise.allSettled(promises);\n}\n\n/** Calls the fetch API with special options like a timeout */\nexport async function fetchAdvanced(url: string, options: FetchAdvancedOpts = {}) {\n  const { timeout = 10000 } = options;\n\n  const controller = new AbortController();\n  const id = setTimeout(() => controller.abort(), timeout);\n\n  const res = await fetch(url, {\n    ...options,\n    signal: controller.signal,\n  });\n\n  clearTimeout(id);\n  return res;\n}\n\n/**\n * Creates an invisible anchor with a `_blank` target and clicks it.  \n * Contrary to `window.open()`, this has a lesser chance to get blocked by the browser's popup blocker and doesn't open the URL as a new window.  \n *   \n * This function has to be run in relatively quick succession in response to a user interaction event, else the browser might reject it.\n */\nexport function openInNewTab(href: string) {\n  const openElem = document.createElement(\"a\");\n  Object.assign(openElem, {\n    className: \"userutils-open-in-new-tab\",\n    target: \"_blank\",\n    rel: \"noopener noreferrer\",\n    href,\n  });\n  openElem.style.display = \"none\";\n\n  document.body.appendChild(openElem);\n  openElem.click();\n  // timeout just to be safe\n  setTimeout(openElem.remove, 50);\n}\n\n/**\n * Intercepts the specified event on the passed object and prevents it from being called if the called `predicate` function returns a truthy value.  \n * Calling this function will set the `stackTraceLimit` to 1000 to ensure the stack trace is preserved.\n */\nexport function interceptEvent<TEvtObj extends EventTarget>(eventObject: TEvtObj, eventName: Parameters<TEvtObj[\"addEventListener\"]>[0], predicate: () => boolean) {  \n  // default is between 10 and 100 on conventional browsers so this should hopefully be more than enough\n  // @ts-ignore\n  if(Error.stackTraceLimit < 1000) {\n    // @ts-ignore\n    Error.stackTraceLimit = 1000;\n  }\n\n  (function(original: typeof eventObject.addEventListener) {\n    // @ts-ignore\n    element.__proto__.addEventListener = function(...args: Parameters<typeof eventObject.addEventListener>) {\n      if(args[0] === eventName && predicate())\n        return;\n      else\n        return original.apply(this, args);\n    };\n    // @ts-ignore\n  })(eventObject.__proto__.addEventListener);\n}\n\n/**\n * Intercepts the specified event on the window object and prevents it from being called if the called `predicate` function returns a truthy value.  \n * Calling this function will set the `stackTraceLimit` to 1000 to ensure the stack trace is preserved.\n */\nexport function interceptWindowEvent(eventName: keyof WindowEventMap, predicate: () => boolean) {  \n  return interceptEvent(getUnsafeWindow(), eventName, predicate);\n}\n","import { SelectorExistsOpts } from \"./types\";\n\n/**\n * Calls the `listener` as soon as the `selector` exists in the DOM.  \n * Listeners are deleted when they are called once, unless `options.continuous` is set.  \n * Multiple listeners with the same selector may be registered.\n * @template TElem The type of element that this selector will return - FIXME: listener inferring doesn't work when this generic is given\n */\nexport function onSelector<TElem = HTMLElement, TOpts extends SelectorExistsOpts = SelectorExistsOpts>(\n  options: TOpts,\n  listener: (element: TOpts[\"all\"] extends true ? (TElem extends HTMLElement ? NodeListOf<TElem> : TElem) : TElem) => void,\n) {\n  // TODO:\n  void [options, listener];\n}\n\n/** Removes all listeners registered in `onSelector()` with a matching selector property */\nexport function removeOnSelector(selector: string) {\n  // TODO:\n  void [selector];\n}\n"]}

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@sv443-network/userutils",
+  "version": "0.1.1",
+  "description": "Library with various utilities for userscripts - register listeners for when CSS selectors exist, intercept events, modify the DOM more easily and more ",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "lint": "tsc && eslint .",
+    "prepare-build": "tsup lib/index.ts --format cjs,esm --dts --clean --treeshake",
+    "build": "npm run prepare-build -- --minify",
+    "build-dev": "npm run prepare-build -- --sourcemap --watch"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Sv443-Network/UserUtils.git"
+  },
+  "keywords": [
+    "userscript",
+    "utilities"
+  ],
+  "author": {
+    "name": "Sv443",
+    "url": "https://github.com/Sv443"
+  },
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/Sv443-Network/UserUtils/issues"
+  },
+  "homepage": "https://github.com/Sv443-Network/UserUtils#readme",
+  "devDependencies": {
+    "@changesets/cli": "^2.26.2",
+    "@types/greasemonkey": "^4.0.4",
+    "@typescript-eslint/eslint-plugin": "^6.2.1",
+    "@typescript-eslint/parser": "^6.2.1",
+    "eslint": "^8.46.0",
+    "tslib": "^2.6.1",
+    "tsup": "^7.2.0",
+    "typescript": "^5.1.6"
+  },
+  "browserslist": [
+    "last 1 version",
+    "> 1%",
+    "not dead"
+  ]
+}