@sv443-network/userutils 6.2.0 → 7.0.0

package/dist/lib/DataStoreSerializer.d.ts

@@ -0,0 +1,44 @@
+import { type DataStore } from "./index.js";
+export type DataStoreSerializerOptions = {
+    /** Whether to add a checksum to the exported data */
+    addChecksum?: boolean;
+    /** Whether to ensure the integrity of the data when importing it (unless the checksum property doesn't exist) */
+    ensureIntegrity?: boolean;
+};
+/** Serialized data of a DataStore instance */
+export type SerializedDataStore = {
+    /** The ID of the DataStore instance */
+    id: string;
+    /** The serialized data */
+    data: string;
+    /** The format version of the data */
+    formatVersion: number;
+    /** Whether the data is encoded */
+    encoded: boolean;
+    /** The checksum of the data - key is not present for data without a checksum */
+    checksum?: string;
+};
+/**
+ * Allows for easy serialization and deserialization of multiple DataStore instances.
+ *
+ * All methods are at least `protected`, so you can easily extend this class and overwrite them to use a different storage method or to add additional functionality.
+ * Remember that you can call `super.methodName()` in the subclass to access the original method.
+ *
+ * ⚠️ Needs to run in a secure context (HTTPS) due to the use of the SubtleCrypto API if checksumming is enabled.
+ */
+export declare class DataStoreSerializer {
+    protected stores: DataStore[];
+    protected options: Required<DataStoreSerializerOptions>;
+    constructor(stores: DataStore[], options?: DataStoreSerializerOptions);
+    /** Calculates the checksum of a string */
+    protected calcChecksum(input: string): Promise<string>;
+    /** Serializes a DataStore instance */
+    protected serializeStore(storeInst: DataStore): Promise<SerializedDataStore>;
+    /** Serializes the data stores into a string */
+    serialize(): Promise<string>;
+    /**
+     * Deserializes the data exported via {@linkcode serialize()} and imports it into the DataStore instances.
+     * Also triggers the migration process if the data format has changed.
+     */
+    deserialize(serializedData: string): Promise<void>;
+}

package/dist/lib/SelectorObserver.d.ts

@@ -20,6 +20,7 @@ type SelectorOptionsCommon = {
     /** Whether to call the function at the very first call ("rising" edge) or the very last call ("falling" edge, default) */
     debounceEdge?: "rising" | "falling";
 };
+type UnsubscribeFunction = () => void;
 export type SelectorObserverOptions = {
     /** If set, applies this debounce in milliseconds to all listeners that don't have their own debounce set */
     defaultDebounce?: number;
@@ -32,13 +33,15 @@ export type SelectorObserverOptions = {
     disableOnNoListeners?: boolean;
     /** Whether to ensure the observer is enabled when a new listener is added - default is true */
     enableOnAddListener?: boolean;
+    /** If set to a number, the checks will be run on interval instead of on mutation events - in that case all MutationObserverInit props will be ignored */
+    checkInterval?: number;
 };
 export type SelectorObserverConstructorOptions = MutationObserverInit & SelectorObserverOptions;
 /** Observes the children of the given element for changes */
 export declare class SelectorObserver {
     private enabled;
     private baseElement;
-    private observer;
+    private observer?;
     private observerOptions;
     private customOptions;
     private listenerMap;
@@ -54,9 +57,10 @@ export declare class SelectorObserver {
      * @param options Fine-tune what triggers the MutationObserver's checking function - `subtree` and `childList` are set to true by default
      */
     constructor(baseElement: Element, options?: SelectorObserverConstructorOptions);
-    private checkAllSelectors;
-    private checkSelector;
-    private debounce;
+    /** Call to check all selectors in the {@linkcode listenerMap} using {@linkcode checkSelector()} */
+    protected checkAllSelectors(): void;
+    /** Checks if the element(s) with the given {@linkcode selector} exist in the DOM and calls the respective {@linkcode listeners} accordingly */
+    protected checkSelector(selector: string, listeners: SelectorListenerOptions[]): void;
     /**
      * Starts observing the children of the base element for changes to the given {@linkcode selector} according to the set {@linkcode options}
      * @param selector The selector to observe
@@ -65,8 +69,9 @@ export declare class SelectorObserver {
      * @param [options.all] Whether to use `querySelectorAll()` instead - default is false
      * @param [options.continuous] Whether to call the listener continuously instead of just once - default is false
      * @param [options.debounce] Whether to debounce the listener to reduce calls to `querySelector` or `querySelectorAll` - set undefined or <=0 to disable (default)
+     * @returns Returns a function that can be called to remove this listener more easily
      */
-    addListener<TElem extends Element = HTMLElement>(selector: string, options: SelectorListenerOptions<TElem>): void;
+    addListener<TElem extends Element = HTMLElement>(selector: string, options: SelectorListenerOptions<TElem>): UnsubscribeFunction;
     /** Disables the observation of the child elements */
     disable(): void;
     /**

package/dist/lib/dom.d.ts

@@ -2,16 +2,11 @@
  * Returns `unsafeWindow` if the `@grant unsafeWindow` is given, otherwise falls back to the regular `window`
  */
 export declare function getUnsafeWindow(): Window;
-/**
- * Inserts {@linkcode afterElement} as a sibling just after the provided {@linkcode beforeElement}
- * @returns Returns the {@linkcode afterElement}
- */
-export declare function insertAfter(beforeElement: Element, afterElement: Element): Element;
 /**
  * Adds a parent container around the provided element
  * @returns Returns the new parent element
  */
-export declare function addParent(element: Element, newParent: Element): Element;
+export declare function addParent<TElem extends Element, TParentElem extends Element>(element: TElem, newParent: TParentElem): TParentElem;
 /**
  * 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).
@@ -24,14 +19,14 @@ export declare function addGlobalStyle(style: string): HTMLStyleElement;
  * @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`
  */
-export declare function preloadImages(srcUrls: string[], rejects?: boolean): Promise<PromiseSettledResult<unknown>[]>;
+export declare function preloadImages(srcUrls: string[], rejects?: boolean): Promise<PromiseSettledResult<HTMLImageElement>[]>;
 /**
- * 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 response to a user interaction event, else the browser might reject it.
+ * Tries to use `GM.openInTab` to open the given URL in a new tab, otherwise if the grant is not given, creates an invisible anchor element and clicks it.
+ * For the fallback to work, this function needs to be run in response to a user interaction event, else the browser might reject it.
+ * @param href The URL to open in a new tab
+ * @param background If set to `true`, the tab will be opened in the background - set to `undefined` (default) to use the browser's default behavior
  */
-export declare function openInNewTab(href: string): void;
+export declare function openInNewTab(href: string, background?: boolean): void;
 /**
  * Intercepts the specified event on the passed object and prevents it from being called if the called {@linkcode predicate} function returns a truthy value.
  * If no predicate is specified, all events will be discarded.
@@ -47,10 +42,7 @@ export declare function interceptEvent<TEvtObj extends EventTarget, TPredicateEv
  */
 export declare function interceptWindowEvent<TEvtKey extends keyof WindowEventMap>(eventName: TEvtKey, predicate?: (event: WindowEventMap[TEvtKey]) => boolean): void;
 /** Checks if an element is scrollable in the horizontal and vertical directions */
-export declare function isScrollable(element: Element): {
-    vertical: boolean;
-    horizontal: boolean;
-};
+export declare function isScrollable(element: Element): Record<"vertical" | "horizontal", boolean>;
 /**
  * Executes the callback when the passed element's property changes.
  * Contrary to an element's attributes, properties can usually not be observed with a MutationObserver.

package/dist/lib/index.d.ts

@@ -1,7 +1,9 @@
-export * from "./array";
-export * from "./DataStore";
-export * from "./dom";
-export * from "./math";
-export * from "./misc";
-export * from "./SelectorObserver";
-export * from "./translation";
+export * from "./array.js";
+export * from "./DataStore.js";
+export * from "./DataStoreSerializer.js";
+export * from "./dom.js";
+export * from "./math.js";
+export * from "./misc.js";
+export * from "./SelectorObserver.js";
+export * from "./translation.js";
+export * from "./types.js";

package/dist/lib/math.d.ts

@@ -9,11 +9,3 @@ export declare function mapRange(value: number, range1min: number, range1max: nu
 export declare function randRange(min: number, max: number): number;
 /** Returns a random number between 0 and {@linkcode max} (inclusive) */
 export declare function randRange(max: number): number;
-/**
- * Generates a random ID with the specified length and radix (16 characters and hexadecimal by default)
- * Uses [`crypto.getRandomValues()`](https://developer.mozilla.org/en-US/docs/Web/API/Crypto/getRandomValues) for better cryptographic randomness
- * ⚠️ Not suitable for generating encryption keys! Use [`crypto.subtle.generateKey()`](https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto/generateKey) for that.
- * @param length The length of the ID to generate (defaults to 16)
- * @param radix The [radix](https://en.wikipedia.org/wiki/Radix) of each digit (defaults to 16 which is hexadecimal. Use 2 for binary, 10 for decimal, 36 for alphanumeric, etc.)
- */
-export declare function randomId(length?: number, radix?: number): string;

package/dist/lib/misc.d.ts

@@ -1,20 +1,4 @@
-/** Represents any value that is either a string itself or can be converted to one (implicitly and explicitly) because it has a toString() method */
-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;
+import type { Stringifiable } from "./types.js";
 /**
  * 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
@@ -30,7 +14,8 @@ export declare function pauseFor(time: number): Promise<void>;
  * @param timeout The time in ms to wait before calling the function
  * @param edge Whether to call the function at the very first call ("rising" edge) or the very last call ("falling" edge, default)
  */
-export declare function debounce<TFunc extends (...args: TArgs[]) => void, TArgs = any>(func: TFunc, timeout?: number, edge?: "rising" | "falling"): (...args: TArgs[]) => void;
+export declare function debounce<TFunc extends (...args: TArgs[]) => void, // eslint-disable-next-line @typescript-eslint/no-explicit-any
+TArgs = any>(func: TFunc, timeout?: number, edge?: "rising" | "falling"): (...args: TArgs[]) => void;
 /** Options for the `fetchAdvanced()` function */
 export type FetchAdvancedOpts = Omit<RequestInit & Partial<{
     /** Timeout in milliseconds after which the fetch call will be canceled with an AbortController signal */
@@ -53,3 +38,19 @@ export declare function compress(input: string | ArrayBuffer, compressionFormat:
 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>;
+/**
+ * Creates a hash / checksum of the given {@linkcode input} string or ArrayBuffer using the specified {@linkcode algorithm} ("SHA-256" by default).
+ *
+ * ⚠️ Uses the SubtleCrypto API so it needs to run in a secure context (HTTPS).
+ * ⚠️ If you use this for cryptography, make sure to use a secure algorithm (under no circumstances use SHA-1) and to [salt](https://en.wikipedia.org/wiki/Salt_(cryptography)) your input data.
+ */
+export declare function computeHash(input: string | ArrayBuffer, algorithm?: string): Promise<string>;
+/**
+ * Generates a random ID with the specified length and radix (16 characters and hexadecimal by default)
+ *
+ * ⚠️ Not suitable for generating anything related to cryptography! Use [SubtleCrypto's `generateKey()`](https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto/generateKey) for that instead.
+ * @param length The length of the ID to generate (defaults to 16)
+ * @param radix The [radix](https://en.wikipedia.org/wiki/Radix) of each digit (defaults to 16 which is hexadecimal. Use 2 for binary, 10 for decimal, 36 for alphanumeric, etc.)
+ * @param enhancedEntropy If set to true, uses [`crypto.getRandomValues()`](https://developer.mozilla.org/en-US/docs/Web/API/Crypto/getRandomValues) for better cryptographic randomness (this also makes it take MUCH longer to generate)
+ */
+export declare function randomId(length?: number, radix?: number, enhancedEntropy?: boolean): string;

package/dist/lib/translation.d.ts

@@ -1,4 +1,4 @@
-import { Stringifiable } from "./misc";
+import type { Stringifiable } from "./types.js";
 /**
  * Returns the translated text for the specified key in the current language set by {@linkcode tr.setLanguage()}
  * If the key is not found in the previously registered translation, the key itself is returned.

package/dist/lib/types.d.ts

@@ -0,0 +1,17 @@
+/** Represents any value that is either a string itself or can be converted to one (implicitly and explicitly) because it has a toString() method */
+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;

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "@sv443-network/userutils",
   "libName": "UserUtils",
-  "version": "6.2.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",
+  "version": "7.0.0",
+  "description": "Library with various utilities for userscripts - register listeners for when CSS selectors exist, intercept events, create persistent & synchronous data stores, modify the DOM more easily and more",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
+  "exports": "./lib/index.ts",
   "types": "dist/lib/index.d.ts",
   "scripts": {
     "lint": "tsc --noEmit && eslint .",