@sv443-network/userutils 9.4.3 → 10.0.0

package/dist/lib/Dialog.d.ts

@@ -2,12 +2,13 @@
  * @module lib/Dialog  
  * This module contains the Dialog class, which allows you to quickly and easily create modal dialogs - [see the documentation for more info](https://github.com/Sv443-Network/UserUtils/blob/main/docs.md#dialog)  
  */
-import { NanoEmitter } from "./NanoEmitter.js";
+import { NanoEmitter } from "@sv443-network/coreutils";
 export declare const defaultDialogCss: string;
 /** ID of the last opened (top-most) dialog */
 export declare let currentDialogId: string | null;
 /** IDs of all currently open dialogs, top-most first */
 export declare const openDialogs: string[];
+/** Default English strings used in the Dialog */
 export declare const defaultStrings: {
     closeDialogTooltip: string;
 };

package/dist/lib/Errors.d.ts

@@ -0,0 +1,9 @@
+/**
+ * @module lib/errors  
+ * Contains custom error classes  
+ */
+import { DatedError } from "@sv443-network/coreutils";
+/** Error due to the platform, like using a feature that's not supported by the browser */
+export declare class PlatformError extends DatedError {
+    constructor(message: string, options?: ErrorOptions);
+}

package/dist/lib/GMStorageEngine.d.ts

@@ -0,0 +1,33 @@
+import { DataStoreEngine, type DataStoreData, type DataStoreEngineDSOptions, type SerializableVal } from "@sv443-network/coreutils";
+/** Options for the {@linkcode GMStorageEngine} class */
+export type GMStorageEngineOptions = {
+    /**
+     * Specifies the necessary options for storing data.  
+     * - ⚠️ Only specify this if you are using this instance standalone! The parent DataStore will set this automatically.  
+     */
+    dataStoreOptions?: DataStoreEngineDSOptions<DataStoreData>;
+};
+/**
+ * Storage engine for the {@linkcode DataStore} class that uses GreaseMonkey's `GM.getValue` and `GM.setValue` functions.  
+ *  
+ * - ⚠️ Requires the grants `GM.getValue`, `GM.setValue`, `GM.deleteValue`, and `GM.listValues` in your userscript metadata.  
+ * - ⚠️ Don't reuse engine instances, always create a new one for each {@linkcode DataStore} instance.  
+ */
+export declare class GMStorageEngine<TData extends DataStoreData> extends DataStoreEngine<TData> {
+    protected options: GMStorageEngineOptions;
+    /**
+     * Creates an instance of `GMStorageEngine`.  
+     *  
+     * - ⚠️ Requires the grants `GM.getValue`, `GM.setValue`, `GM.deleteValue`, and `GM.listValues` in your userscript metadata.  
+     * - ⚠️ Don't reuse engine instances, always create a new one for each {@linkcode DataStore} instance.  
+     */
+    constructor(options?: GMStorageEngineOptions);
+    /** Fetches a value from persistent storage */
+    getValue<TValue extends SerializableVal = string>(name: string, defaultValue: TValue): Promise<string | TValue>;
+    /** Sets a value in persistent storage */
+    setValue<TValue extends SerializableVal = string>(name: string, value: TValue): Promise<void>;
+    /** Deletes a value from persistent storage */
+    deleteValue(name: string): Promise<void>;
+    /** Deletes all values from GM storage. Use with caution! */
+    deleteStorage(): Promise<void>;
+}

package/dist/lib/Mixins.d.ts

@@ -2,15 +2,15 @@
  * @module lib/Mixins  
  * Allows for defining and applying mixin functions to allow multiple sources to modify a value in a controlled way.  
  */
-import type { Prettify } from "./types.js";
+import { type Prettify } from "@sv443-network/coreutils";
 /** Full mixin object (either sync or async), as it is stored in the instance's mixin array. */
 export type MixinObj<TArg, TCtx> = Prettify<MixinObjSync<TArg, TCtx> | MixinObjAsync<TArg, TCtx>>;
-/** Asynchronous mixin object, as it is stored in the instance's mixin array. */
+/** Synchronous mixin object, as it is stored in the instance's mixin array. */
 export type MixinObjSync<TArg, TCtx> = Prettify<{
     /** The mixin function */
     fn: (arg: TArg, ctx?: TCtx) => TArg;
 } & MixinObjBase>;
-/** Synchronous mixin object, as it is stored in the instance's mixin array. */
+/** Asynchronous mixin object, as it is stored in the instance's mixin array. */
 export type MixinObjAsync<TArg, TCtx> = Prettify<{
     /** The mixin function */
     fn: (arg: TArg, ctx?: TCtx) => TArg | Promise<TArg>;
@@ -29,13 +29,13 @@ export type MixinConfig = {
     /** If set, the mixin will only be applied if the given signal is not aborted. */
     signal?: AbortSignal;
 };
-/** Configuration object for the Mixins class */
+/** Configuration object for the {@linkcode Mixins} class */
 export type MixinsConstructorConfig = {
     /**
      * If true, when no priority is specified, an auto-incrementing integer priority will be used, starting at `defaultPriority` or 0 (unique per mixin key). Defaults to false.  
-     * If a priority value is already used, it will be incremented until a unique value is found.  
-     * This is useful to ensure that mixins are applied in the order they were added, even if they don't specify a priority.  
-     * It also allows for a finer level of interjection when the priority is a floating point number.  
+     * This means that the first mixin added will have the lowest priority of `defaultPriority`, and the last one will have the highest priority and be applied first.  
+     * If a priority value is already in use, it will be incremented until a unique value is found.  
+     * A finer level of interjection can be achieved by manually setting the priority to a floating point number, while the auto-incrementing priority will always be an integer.  
      */
     autoIncrementPriority: boolean;
     /** The default priority for mixins that do not specify one. Defaults to 0. */
@@ -48,8 +48,8 @@ export type MixinsConstructorConfig = {
 /**
  * The mixin class allows for defining and applying mixin functions to allow multiple sources to modify values in a controlled way.  
  * Mixins are identified via their string key and can be added with {@linkcode add()}  
- * When calling {@linkcode resolve()}, all registered mixin functions with the same key will be applied to the input value in the order of their priority.  
- * If a mixin has the stopPropagation flag set to true, no further mixins will be applied after it.  
+ * When calling {@linkcode resolve()}, all registered mixin functions with the same key will be applied to the input value in the order of their priority, or alternatively the order they were added.  
+ * If a mixin function has its `stopPropagation` flag set to true when being added, no further mixin functions will be applied after it.  
  * @template TMixinMap A map of mixin keys to their respective function signatures. The first argument of the function is the input value, the second argument is an optional context object. If it is defined here, it must be passed as the third argument in {@linkcode resolve()}.  
  * @example ```ts  
  * const ac = new AbortController();  
@@ -116,12 +116,15 @@ export declare class Mixins<TMixinMap extends Record<string, (arg: any, ctx?: an
     /**
      * Applies all mixins with the given key to the input value, respecting the priority and stopPropagation settings.  
      * If additional context is set in the MixinMap, it will need to be passed as the third argument.  
-     * @returns The modified value after all mixins have been applied.  
+     * @returns The modified value after all mixins have been applied. The method will return a Promise if at least one of the mixins is async. If all mixins are indicated to be synchronous in TS, but at least one of them turns out to be asynchronous, the return type will be a Promise. With `await`, this will not make a difference, but `.then().catch()` could be affected.  
      */
     resolve<TKey extends TMixinKey, TArg extends Parameters<TMixinMap[TKey]>[0], TCtx extends Parameters<TMixinMap[TKey]>[1]>(mixinKey: TKey, inputValue: TArg, ...inputCtx: TCtx extends undefined ? [void] : [TCtx]): ReturnType<TMixinMap[TKey]> extends Promise<any> ? ReturnType<TMixinMap[TKey]> : ReturnType<TMixinMap[TKey]>;
     /** Calculates the priority for a mixin based on the given configuration and the current auto-increment state of the instance */
     protected calcPriority(mixinKey: TMixinKey, config: Partial<MixinConfig>): number | undefined;
-    /** Removes all mixins with the given key */
+    /**
+     * Removes all mixins with the given key.  
+     * Note: this method is protected to avoid third-party code from removing mixins. If needed, you can extend the Mixins class and expose this method publicly.  
+     */
     protected removeAll(mixinKey: TMixinKey): void;
 }
 export {};

package/dist/lib/SelectorObserver.d.ts

@@ -2,8 +2,7 @@
  * @module lib/SelectorObserver  
  * This module contains the SelectorObserver class, allowing you to register listeners that get called whenever the element(s) behind a selector exist in the DOM - [see the documentation for more info](https://github.com/Sv443-Network/UserUtils/blob/main/docs.md#selectorobserver)  
  */
-import { type DebouncerType } from "./Debouncer.js";
-import type { Prettify } from "./types.js";
+import { type DebouncerType, type Prettify } from "@sv443-network/coreutils";
 /** Options for the `onSelector()` method of {@linkcode SelectorObserver} */
 export type SelectorListenerOptions<TElem extends Element = HTMLElement> = Prettify<SelectorOptionsOne<TElem> | SelectorOptionsAll<TElem>>;
 export type SelectorOptionsOne<TElem extends Element> = SelectorOptionsCommon & {

package/dist/lib/dom.d.ts

@@ -32,6 +32,12 @@ export declare function preloadImages(srcUrls: string[], rejects?: boolean): Pro
  * @param additionalProps Additional properties to set on the anchor element (only applies when `GM.openInTab` is not available)  
  */
 export declare function openInNewTab(href: string, background?: boolean, additionalProps?: Partial<HTMLAnchorElement>): void;
+/** Add stackTraceLimit to ErrorConstructor */
+declare global {
+    interface ErrorConstructor {
+        stackTraceLimit: number;
+    }
+}
 /**
  * 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.  
@@ -73,7 +79,8 @@ export declare function getSiblingsFrame<TSibling extends Element = HTMLElement>
  * Uses a [Trusted Types policy](https://developer.mozilla.org/en-US/docs/Web/API/Trusted_Types_API) on Chromium-based browsers to trick the browser into thinking the HTML is safe.  
  * Use this if the page makes use of the CSP directive `require-trusted-types-for 'script'` and throws a "This document requires 'TrustedHTML' assignment" error on Chromium-based browsers.  
  *  
- * - ⚠️ This function does not perform any sanitization and should thus be used with utmost caution, as it can easily lead to XSS vulnerabilities!  
+ * - ⚠️ This function does not perform any sanitization and should thus be used with utmost caution, as it can easily lead to XSS vulnerabilities when used with untrusted input!  
+ * - ⚠️ Only use this function when absolutely necessary, prefer using `element.textContent = "foo"` or other safer alternatives like the [DOMPurify library](https://github.com/cure53/DOMPurify) whenever possible.  
  */
 export declare function setInnerHtmlUnsafe<TElement extends Element = HTMLElement>(element: TElement, html: string): TElement;
 /**

package/dist/lib/index.d.ts

@@ -2,19 +2,11 @@
  * @module UserUtils  
  * UserUtils is a lightweight library with various utilities for userscripts, allowing you to register listeners for when CSS selectors exist, intercept events, create persistent & synchronous data stores, modify the DOM more easily and much more  
  */
-export * from "./array.js";
-export * from "./colors.js";
-export * from "./crypto.js";
-export * from "./DataStore.js";
-export * from "./DataStoreSerializer.js";
-export * from "./Debouncer.js";
+export * from "@sv443-network/coreutils";
 export * from "./Dialog.js";
 export * from "./dom.js";
-export * from "./errors.js";
-export * from "./math.js";
-export * from "./misc.js";
+export * from "./Errors.js";
+export * from "./GMStorageEngine.js";
 export * from "./Mixins.js";
-export * from "./NanoEmitter.js";
 export * from "./SelectorObserver.js";
 export * from "./translation.js";
-export * from "./types.js";

package/dist/lib/translation.d.ts

@@ -2,7 +2,7 @@
  * @module lib/translation  
  * This module contains a translation system that supports flat and nested JSON objects and value transformation functions - [see the documentation for more info](https://github.com/Sv443-Network/UserUtils/blob/main/docs.md#translation)  
  */
-import type { Stringifiable } from "./types.js";
+import type { Stringifiable } from "@sv443-network/coreutils";
 /**
  * Translation object to pass to {@linkcode tr.addTranslations()}  
  * Can be a flat object of identifier keys and the translation text as the value, or an infinitely nestable object containing the same.  

package/package.json

@@ -1,24 +1,19 @@
 {
   "name": "@sv443-network/userutils",
   "libName": "UserUtils",
-  "version": "9.4.3",
+  "version": "10.0.0",
   "description": "General purpose DOM/GreaseMonkey library that allows you to register listeners for when CSS selectors exist, intercept events, create persistent & synchronous data stores, modify the DOM more easily and much more",
-  "main": "dist/index.js",
-  "module": "dist/index.js",
+  "main": "dist/UserUtils.mjs",
+  "module": "dist/UserUtils.mjs",
   "types": "dist/lib/index.d.ts",
   "exports": {
     ".": {
-      "browser": "./dist/index.global.js",
+      "browser": "./dist/UserUtils.umd.js",
       "types": "./dist/lib/index.d.ts",
-      "require": "./dist/index.cjs",
-      "import": "./dist/index.js"
+      "require": "./dist/UserUtils.cjs",
+      "import": "./dist/UserUtils.mjs"
     }
   },
-  "engines": {
-    "pnpm": ">=9",
-    "npm": "please-use-pnpm",
-    "yarn": "please-use-pnpm"
-  },
   "type": "module",
   "repository": {
     "type": "git",
@@ -38,63 +33,61 @@
   },
   "homepage": "https://github.com/Sv443-Network/UserUtils",
   "dependencies": {
-    "nanoevents": "^9.1.0"
+    "@sv443-network/coreutils": "3.0.1",
+    "nanoevents": "9.1.0"
   },
   "devDependencies": {
-    "@changesets/cli": "^2.27.11",
-    "@eslint/eslintrc": "^3.2.0",
-    "@eslint/js": "^9.23.0",
-    "@testing-library/dom": "^10.4.0",
-    "@types/express": "^4.17.21",
-    "@types/greasemonkey": "^4.0.7",
-    "@types/node": "^22.10.5",
-    "@types/tx2": "^1.0.3",
-    "@typescript-eslint/eslint-plugin": "^8.21.0",
-    "@typescript-eslint/parser": "^8.21.0",
-    "@typescript-eslint/utils": "^8.21.0",
-    "@vitest/coverage-v8": "^3.0.9",
-    "concurrently": "^8.2.2",
-    "eslint": "^9.18.0",
-    "express": "^4.21.2",
-    "globals": "^15.14.0",
-    "jsdom": "^26.0.0",
-    "kleur": "^4.1.5",
-    "tslib": "^2.8.1",
-    "tsup": "^8.3.5",
-    "tsx": "^4.19.2",
-    "typescript": "^5.7.3",
-    "vitest": "^3.0.9"
+    "@changesets/cli": "2.29.8",
+    "@eslint/eslintrc": "3.3.3",
+    "@eslint/js": "9.39.2",
+    "@swc/core": "1.15.11",
+    "@testing-library/dom": "10.4.1",
+    "@types/express": "4.17.25",
+    "@types/greasemonkey": "4.0.7",
+    "@types/node": "22.19.9",
+    "@types/tx2": "1.0.3",
+    "@typescript-eslint/eslint-plugin": "8.54.0",
+    "@typescript-eslint/parser": "8.54.0",
+    "@typescript-eslint/utils": "8.54.0",
+    "@vitest/coverage-v8": "3.2.4",
+    "concurrently": "8.2.2",
+    "eslint": "9.39.2",
+    "express": "4.22.1",
+    "globals": "15.15.0",
+    "jsdom": "26.1.0",
+    "kleur": "4.1.5",
+    "tslib": "2.8.1",
+    "tsup": "8.5.1",
+    "tsx": "4.21.0",
+    "typescript": "5.9.3",
+    "vitest": "3.2.4"
   },
   "files": [
-    "/dist/index.js",
-    "/dist/index.cjs",
-    "/dist/index.mjs",
-    "/dist/index.global.js",
-    "/dist/index.umd.js",
+    "/dist/UserUtils.mjs",
+    "/dist/UserUtils.cjs",
+    "/dist/UserUtils.umd.js",
     "/dist/lib/**.d.ts",
     "/package.json",
     "/README.md",
     "/CHANGELOG.md",
     "/LICENSE.txt"
   ],
+  "publishConfig": {
+    "provenance": true
+  },
   "scripts": {
     "lint": "eslint . && tsc --noEmit",
-    "build-types": "tsc --emitDeclarationOnly --declaration --outDir dist && node --import tsx ./tools/fix-dts.mts",
-    "build-common": "tsup lib/index.ts --format cjs,esm --clean --treeshake",
-    "build-all": "tsup lib/index.ts --format cjs,esm,iife --treeshake --onSuccess \"pnpm build-types && pnpm post-build-global\"",
-    "build": "pnpm build-common -- && pnpm build-types",
-    "post-build-global": "node --import tsx ./tools/post-build-global.mts",
-    "dev": "pnpm build-common -- --sourcemap --watch --onSuccess \"pnpm build-types\"",
-    "dev-all": "pnpm build-all -- --watch",
+    "build": "tsup",
+    "dev": "tsup --watch",
     "update-jsr-version": "node --import tsx ./tools/update-jsr-version.mts",
     "publish-package": "changeset publish",
     "publish-package-jsr": "pnpm update-jsr-version && npx jsr publish --allow-dirty",
-    "check-jsr": "npx jsr publish --allow-dirty --dry-run",
+    "check-jsr": "pnpm update-jsr-version && npx jsr publish --allow-dirty --dry-run",
     "change": "changeset",
     "test-gm-serve": "node --import tsx ./test/TestPage/server.mts",
     "test-gm-dev": "cd test/TestScript && pnpm dev",
     "test-gm": "concurrently \"pnpm test-gm-serve\" \"pnpm test-gm-dev\"",
-    "test": "vitest --passWithNoTests",
-    "test-coverage": "vitest --passWithNoTests --coverage"
+    "test": "vitest",
+    "test-coverage": "vitest --coverage"
   }
 }