@sv443-network/userutils 9.3.0 → 9.4.0

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # @sv443-network/userutils
 
+## 9.4.0
+
+### Minor Changes
+
+- 5075831: Added `Mixins` class for allowing multiple sources to modify values in a controlled way
+- 99dedfd: Added unit tests
+- 7530fd0: Added `Debouncer.getListeners()` method to get an array of all listener functions
+- 48306da: Added `stores` filter parameter to the `DataStoreSerializer` methods `loadStoresData()`, `resetStoresData()` and `deleteStoresData()`
+
+### Patch Changes
+
+- f6a68c7: Fixed error when calling `interceptEvent()` in a non-GM environment
+
 ## 9.3.0
 
 ### Minor Changes

package/README.md

@@ -3,7 +3,7 @@
 <!-- #region Description -->
 ## UserUtils
 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.  
-Contains builtin TypeScript declarations. Supports ESM and CJS imports via a bundler and global declaration via `@require`  
+Contains builtin TypeScript declarations. Supports ESM and CJS imports via a bundler and global declaration via `@require` or `<script>`  
 The library works in any DOM environment with or without the [GreaseMonkey API](https://wiki.greasespot.net/Greasemonkey_Manual:API), but some features will be unavailable or limited.  
   
 You may want to check out my [template for userscripts in TypeScript](https://github.com/Sv443/Userscript.ts) that you can use to get started quickly. It also includes this library by default.  
@@ -11,12 +11,14 @@ If you like using this library, please consider [supporting the development ❤
 
 <br>
 
-[![minified bundle size badge](https://badgen.net/bundlephobia/min/@sv443-network/userutils)](https://bundlephobia.com/package/@sv443-network/userutils)
-[![minified and gzipped bundle size badge](https://badgen.net/bundlephobia/minzip/@sv443-network/userutils)](https://bundlephobia.com/package/@sv443-network/userutils)
-[![tree shaking support badge](https://badgen.net/bundlephobia/tree-shaking/@sv443-network/userutils)](https://bundlephobia.com/package/@sv443-network/userutils)
+[![Tree shaking support badge](https://badgen.net/bundlephobia/tree-shaking/@sv443-network/userutils)](https://bundlephobia.com/package/@sv443-network/userutils)
+[![Code coverage percentage badge](https://img.shields.io/coverallsCoverage/github/Sv443-Network/UserUtils?branch=main)](https://coveralls.io/github/Sv443-Network/UserUtils)
+[![Minified bundle size badge](https://badgen.net/bundlephobia/min/@sv443-network/userutils)](https://bundlephobia.com/package/@sv443-network/userutils)
+[![Minified and gzipped bundle size badge](https://badgen.net/bundlephobia/minzip/@sv443-network/userutils)](https://bundlephobia.com/package/@sv443-network/userutils)
 
-[![github stargazers badge](https://badgen.net/github/stars/Sv443-Network/UserUtils?icon=github)](https://github.com/Sv443-Network/UserUtils/stargazers)
-[![discord server badge](https://badgen.net/discord/online-members/aBH4uRG?icon=discord)](https://dc.sv443.net/)
+[![Discord server badge](https://badgen.net/discord/online-members/aBH4uRG?icon=discord)](https://dc.sv443.net/)
+[![Github stargazers badge](https://badgen.net/github/stars/Sv443-Network/UserUtils?icon=github)](https://github.com/Sv443-Network/UserUtils/stargazers)
+[![Support development on Github Sponsors badge](https://img.shields.io/github/sponsors/Sv443?icon=github)](https://github.com/sponsors/Sv443)
 
 <sup>
 View the documentation of previous major releases:
@@ -63,6 +65,7 @@ View the documentation of previous major releases:
     - [`DataStore`](./docs.md#datastore) - class that manages a hybrid sync & async persistent JSON database, including data migration
     - [`DataStoreSerializer`](./docs.md#datastoreserializer) - class for importing & exporting data of multiple DataStore instances, including compression, checksumming and running migrations
     - [`Dialog`](./docs.md#dialog) - class for creating custom modal dialogs with a promise-based API and a generic, default style
+    - [`Mixins`](./docs.md#mixins) - class for creating mixin functions that allow multiple sources to modify a target value in a highly flexible way
     - [`NanoEmitter`](./docs.md#nanoemitter) - tiny event emitter class with a focus on performance and simplicity (based on [nanoevents](https://npmjs.com/package/nanoevents))
     - [`Debouncer`](./docs.md#debouncer) - class for debouncing function calls with a given timeout
     - [`debounce()`](./docs.md#debounce) - function wrapper for the Debouncer class for easier usage

package/dist/index.cjs

@@ -3,6 +3,8 @@
 var nanoevents = require('nanoevents');
 
 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;
@@ -18,6 +20,7 @@ var __spreadValues = (a, b) => {
     }
   return a;
 };
+var __spreadProps = (a, b) => __defProps(a, __getOwnPropDescs(b));
 var __objRest = (source, exclude) => {
   var target = {};
   for (var prop in source)
@@ -250,16 +253,16 @@ function addGlobalStyle(style) {
 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));
+    image.src = src;
   }));
   return Promise.allSettled(promises);
 }
 function openInNewTab(href, background, additionalProps) {
-  var _a;
   try {
-    (_a = GM.openInTab) == null ? void 0 : _a.call(GM, href, background);
+    if (typeof window.GM === "object")
+      GM.openInTab(href, background);
   } catch (e) {
     const openElem = document.createElement("a");
     Object.assign(openElem, __spreadValues({
@@ -276,12 +279,17 @@ function openInNewTab(href, background, additionalProps) {
     });
     document.body.appendChild(openElem);
     openElem.click();
-    setTimeout(openElem.remove, 0);
+    setTimeout(() => {
+      try {
+        openElem.remove();
+      } catch (e2) {
+      }
+    }, 0);
   }
 }
 function interceptEvent(eventObject, eventName, predicate = () => true) {
   var _a;
-  if (((_a = GM == null ? undefined : GM.info) == null ? undefined : _a.scriptHandler) && GM.info.scriptHandler === "FireMonkey" && (eventObject === window || eventObject === getUnsafeWindow()))
+  if (typeof window.GM === "object" && ((_a = GM == null ? undefined : GM.info) == null ? undefined : _a.scriptHandler) && GM.info.scriptHandler === "FireMonkey" && (eventObject === window || eventObject === getUnsafeWindow()))
     throw new PlatformError("Intercepting window events is not supported on FireMonkey due to the isolated context the userscript runs in.");
   Error.stackTraceLimit = Math.max(Error.stackTraceLimit, 100);
   if (isNaN(Error.stackTraceLimit))
@@ -441,6 +449,8 @@ function computeHash(input, algorithm = "SHA-256") {
   });
 }
 function randomId(length = 16, radix = 16, enhancedEntropy = false, randomCase = true) {
+  if (length < 1)
+    throw new RangeError("The length argument must be at least 1");
   if (radix < 2 || radix > 36)
     throw new RangeError("The radix argument must be between 2 and 36");
   let arr = [];
@@ -785,7 +795,7 @@ var DataStoreSerializer = class _DataStoreSerializer {
   deserializePartial(stores, data) {
     return __async(this, null, function* () {
       const deserStores = typeof data === "string" ? JSON.parse(data) : data;
-      if (!Array.isArray(deserStores) || !deserStores.every(_DataStoreSerializer.isSerializedDataStore))
+      if (!Array.isArray(deserStores) || !deserStores.every(_DataStoreSerializer.isSerializedDataStoreObj))
         throw new TypeError("Invalid serialized data format! Expected an array of SerializedDataStore objects.");
       for (const storeData of deserStores.filter((s) => typeof stores === "function" ? stores(s.id) : stores.includes(s.id))) {
         const storeInst = this.stores.find((s) => s.id === storeData.id);
@@ -818,41 +828,59 @@ Has: ${checksum}`);
   /**
    * Loads the persistent data of the DataStore instances into the in-memory cache.  
    * Also triggers the migration process if the data format has changed.
+   * @param stores An array of store IDs or a function that takes the store IDs and returns a boolean - if omitted, all stores will be loaded
    * @returns Returns a PromiseSettledResult array with the results of each DataStore instance in the format `{ id: string, data: object }`
    */
-  loadStoresData() {
+  loadStoresData(stores) {
     return __async(this, null, function* () {
-      return Promise.allSettled(this.stores.map(
-        (store) => __async(this, null, function* () {
+      return Promise.allSettled(
+        this.getStoresFiltered(stores).map((store) => __async(this, null, function* () {
           return {
             id: store.id,
             data: yield store.loadData()
           };
-        })
-      ));
+        }))
+      );
     });
   }
-  /** Resets the persistent data of the DataStore instances to their default values. */
-  resetStoresData() {
+  /**
+   * Resets the persistent and in-memory data of the DataStore instances to their default values.
+   * @param stores An array of store IDs or a function that takes the store IDs and returns a boolean - if omitted, all stores will be affected
+   */
+  resetStoresData(stores) {
     return __async(this, null, function* () {
-      return Promise.allSettled(this.stores.map((store) => store.saveDefaultData()));
+      return Promise.allSettled(
+        this.getStoresFiltered(stores).map((store) => store.saveDefaultData())
+      );
     });
   }
   /**
    * Deletes the persistent data of the DataStore instances.  
-   * Leaves the in-memory data untouched.
+   * Leaves the in-memory data untouched.  
+   * @param stores An array of store IDs or a function that takes the store IDs and returns a boolean - if omitted, all stores will be affected
    */
-  deleteStoresData() {
+  deleteStoresData(stores) {
     return __async(this, null, function* () {
-      return Promise.allSettled(this.stores.map((store) => store.deleteData()));
+      return Promise.allSettled(
+        this.getStoresFiltered(stores).map((store) => store.deleteData())
+      );
     });
   }
+  /** Checks if a given value is an array of SerializedDataStore objects */
+  static isSerializedDataStoreObjArray(obj) {
+    return Array.isArray(obj) && obj.every((o) => typeof o === "object" && o !== null && "id" in o && "data" in o && "formatVersion" in o && "encoded" in o);
+  }
   /** Checks if a given value is a SerializedDataStore object */
-  static isSerializedDataStore(obj) {
+  static isSerializedDataStoreObj(obj) {
     return typeof obj === "object" && obj !== null && "id" in obj && "data" in obj && "formatVersion" in obj && "encoded" in obj;
   }
+  /** Returns the DataStore instances whose IDs match the provided array or function */
+  getStoresFiltered(stores) {
+    return this.stores.filter((s) => typeof stores === "undefined" ? true : Array.isArray(stores) ? stores.includes(s.id) : stores(s.id));
+  }
 };
 var NanoEmitter = class {
+  /** Creates a new instance of NanoEmitter - a lightweight event emitter with helper methods and a strongly typed event map */
   constructor(options = {}) {
     __publicField(this, "events", nanoevents.createNanoEvents());
     __publicField(this, "eventUnsubscribes", []);
@@ -861,7 +889,27 @@ var NanoEmitter = class {
       publicEmit: false
     }, options);
   }
-  /** Subscribes to an event - returns a function that unsubscribes the event listener */
+  /**
+   * Subscribes to an event and calls the callback when it's emitted.  
+   * @param event The event to subscribe to. Use `as "_"` in case your event names aren't thoroughly typed (like when using a template literal, e.g. \`event-${val}\` as "_")
+   * @returns Returns a function that can be called to unsubscribe the event listener
+   * @example ```ts
+   * const emitter = new NanoEmitter<{
+   *   foo: (bar: string) => void;
+   * }>({
+   *   publicEmit: true,
+   * });
+   * 
+   * let i = 0;
+   * const unsub = emitter.on("foo", (bar) => {
+   *   // unsubscribe after 10 events:
+   *   if(++i === 10) unsub();
+   *   console.log(bar);
+   * });
+   * 
+   * emitter.emit("foo", "bar");
+   * ```
+   */
   on(event, cb) {
     let unsub;
     const unsubProxy = () => {
@@ -874,19 +922,43 @@ var NanoEmitter = class {
     this.eventUnsubscribes.push(unsub);
     return unsubProxy;
   }
-  /** Subscribes to an event and calls the callback or resolves the Promise only once */
+  /**
+   * Subscribes to an event and calls the callback or resolves the Promise only once when it's emitted.  
+   * @param event The event to subscribe to. Use `as "_"` in case your event names aren't thoroughly typed (like when using a template literal, e.g. \`event-${val}\` as "_")
+   * @param cb The callback to call when the event is emitted - if provided or not, the returned Promise will resolve with the event arguments
+   * @returns Returns a Promise that resolves with the event arguments when the event is emitted
+   * @example ```ts
+   * const emitter = new NanoEmitter<{
+   *   foo: (bar: string) => void;
+   * }>();
+   * 
+   * // Promise syntax:
+   * const [bar] = await emitter.once("foo");
+   * console.log(bar);
+   * 
+   * // Callback syntax:
+   * emitter.once("foo", (bar) => console.log(bar));
+   * ```
+   */
   once(event, cb) {
     return new Promise((resolve) => {
       let unsub;
       const onceProxy = (...args) => {
-        unsub();
         cb == null ? undefined : cb(...args);
+        unsub == null ? undefined : unsub();
         resolve(args);
       };
-      unsub = this.on(event, onceProxy);
+      unsub = this.events.on(event, onceProxy);
+      this.eventUnsubscribes.push(unsub);
     });
   }
-  /** Emits an event on this instance - Needs `publicEmit` to be set to true in the constructor! */
+  /**
+   * Emits an event on this instance.  
+   * ⚠️ Needs `publicEmit` to be set to true in the NanoEmitter constructor or super() call!
+   * @param event The event to emit
+   * @param args The arguments to pass to the event listeners
+   * @returns Returns true if `publicEmit` is true and the event was emitted successfully
+   */
   emit(event, ...args) {
     if (this.emitterOptions.publicEmit) {
       this.events.emit(event, ...args);
@@ -894,7 +966,7 @@ var NanoEmitter = class {
     }
     return false;
   }
-  /** Unsubscribes all event listeners */
+  /** Unsubscribes all event listeners from this instance */
   unsubscribeAll() {
     for (const unsub of this.eventUnsubscribes)
       unsub();
@@ -934,6 +1006,10 @@ var Debouncer = class extends NanoEmitter {
   removeAllListeners() {
     this.listeners = [];
   }
+  /** Returns all registered listeners */
+  getListeners() {
+    return this.listeners;
+  }
   //#region timeout
   /** Sets the timeout for the debouncer */
   setTimeout(timeout) {
@@ -962,7 +1038,7 @@ var Debouncer = class extends NanoEmitter {
     const cl = (...a) => {
       this.queuedCall = undefined;
       this.emit("call", ...a);
-      this.listeners.forEach((l) => l.apply(this, a));
+      this.listeners.forEach((l) => l.call(this, ...a));
     };
     const setRepeatTimeout = () => {
       this.activeTimeout = setTimeout(() => {
@@ -1436,8 +1512,6 @@ function autoPlural(term, num, pluralType = "auto") {
       return `${term}${n === 1 ? "" : "s"}`;
     case "-ies":
       return `${String(term).slice(0, -1)}${n === 1 ? "y" : "ies"}`;
-    default:
-      return String(term);
   }
 }
 function insertValues(input, ...values) {
@@ -1496,6 +1570,112 @@ function purifyObj(obj) {
   return Object.assign(/* @__PURE__ */ Object.create(null), obj);
 }
 
+// lib/Mixins.ts
+var Mixins = class {
+  /**
+   * Creates a new Mixins instance.
+   * @param config Configuration object to customize the behavior.
+   */
+  constructor(config = {}) {
+    /** List of all registered mixins */
+    __publicField(this, "mixins", []);
+    /** Default configuration object for mixins */
+    __publicField(this, "defaultMixinCfg");
+    /** Whether the priorities should auto-increment if not specified */
+    __publicField(this, "autoIncPrioEnabled");
+    /** The current auto-increment priority counter */
+    __publicField(this, "autoIncPrioCounter", /* @__PURE__ */ new Map());
+    var _a, _b, _c;
+    this.defaultMixinCfg = purifyObj({
+      priority: (_a = config.defaultPriority) != null ? _a : 0,
+      stopPropagation: (_b = config.defaultStopPropagation) != null ? _b : false,
+      signal: config.defaultSignal
+    });
+    this.autoIncPrioEnabled = (_c = config.autoIncrementPriority) != null ? _c : false;
+  }
+  //#region public
+  /**
+   * Adds a mixin function to the given {@linkcode mixinKey}.  
+   * If no priority is specified, it will be calculated via the protected method {@linkcode calcPriority()} based on the constructor configuration, or fall back to the default priority.
+   * @param mixinKey The key to identify the mixin function.
+   * @param mixinFn The function to be called to apply the mixin. The first argument is the input value, the second argument is the context object (if any).
+   * @param config Configuration object to customize the mixin behavior, or just the priority if a number is passed.
+   * @returns Returns a cleanup function, to be called when this mixin is no longer needed.
+   */
+  add(mixinKey, mixinFn, config = purifyObj({})) {
+    const calcPrio = typeof config === "number" ? config : this.calcPriority(mixinKey, config);
+    const mixin = purifyObj(__spreadValues(__spreadValues(__spreadProps(__spreadValues({}, this.defaultMixinCfg), {
+      key: mixinKey,
+      fn: mixinFn
+    }), typeof config === "object" ? config : {}), typeof calcPrio === "number" && !isNaN(calcPrio) ? { priority: calcPrio } : {}));
+    this.mixins.push(mixin);
+    const rem = () => {
+      this.mixins = this.mixins.filter((m) => m !== mixin);
+    };
+    if (mixin.signal)
+      mixin.signal.addEventListener("abort", rem, { once: true });
+    return rem;
+  }
+  /** Returns a list of all added mixins with their keys and configuration objects, but not their functions */
+  list() {
+    return this.mixins.map((_a) => {
+      var _b = _a, rest = __objRest(_b, ["fn"]);
+      return rest;
+    });
+  }
+  /**
+   * 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.
+   */
+  resolve(mixinKey, inputValue, ...inputCtx) {
+    const mixins = this.mixins.filter((m) => m.key === mixinKey);
+    const sortedMixins = [...mixins].sort((a, b) => b.priority - a.priority);
+    let result = inputValue;
+    for (let i = 0; i < sortedMixins.length; i++) {
+      const mixin = sortedMixins[i];
+      result = mixin.fn(result, ...inputCtx);
+      if (result instanceof Promise) {
+        return (() => __async(this, null, function* () {
+          result = yield result;
+          if (mixin.stopPropagation)
+            return result;
+          for (let j = i + 1; j < sortedMixins.length; j++) {
+            const mixin2 = sortedMixins[j];
+            result = yield mixin2.fn(result, ...inputCtx);
+            if (mixin2.stopPropagation)
+              break;
+          }
+          return result;
+        }))();
+      } else if (mixin.stopPropagation)
+        break;
+    }
+    return result;
+  }
+  //#region protected
+  /** Calculates the priority for a mixin based on the given configuration and the current auto-increment state of the instance */
+  calcPriority(mixinKey, config) {
+    var _a;
+    if (config.priority !== undefined)
+      return undefined;
+    if (!this.autoIncPrioEnabled)
+      return (_a = config.priority) != null ? _a : this.defaultMixinCfg.priority;
+    if (!this.autoIncPrioCounter.has(mixinKey))
+      this.autoIncPrioCounter.set(mixinKey, this.defaultMixinCfg.priority);
+    let prio = this.autoIncPrioCounter.get(mixinKey);
+    while (this.mixins.some((m) => m.key === mixinKey && m.priority === prio))
+      prio++;
+    this.autoIncPrioCounter.set(mixinKey, prio + 1);
+    return prio;
+  }
+  /** Removes all mixins with the given key */
+  removeAll(mixinKey) {
+    this.mixins.filter((m) => m.key === mixinKey);
+    this.mixins = this.mixins.filter((m) => m.key !== mixinKey);
+  }
+};
+
 // lib/SelectorObserver.ts
 var SelectorObserver = class {
   constructor(baseElement, options = {}) {
@@ -1753,15 +1933,15 @@ function getFallbackLanguage() {
   return fallbackLang;
 }
 function addTransform(transform) {
-  const [pattern, fn] = transform;
+  const [regex, fn] = transform;
   valTransforms.push({
     fn,
-    regex: typeof pattern === "string" ? new RegExp(pattern, "gm") : pattern
+    regex
   });
 }
 function deleteTransform(patternOrFn) {
   const idx = valTransforms.findIndex(
-    (t) => typeof patternOrFn === "function" ? t.fn === patternOrFn : typeof patternOrFn === "string" ? t.regex.source === patternOrFn : t.regex === patternOrFn
+    (t) => typeof patternOrFn === "function" ? t.fn === patternOrFn : t.regex === patternOrFn
   );
   if (idx !== -1) {
     valTransforms.splice(idx, 1);
@@ -1838,6 +2018,7 @@ exports.DataStoreSerializer = DataStoreSerializer;
 exports.Debouncer = Debouncer;
 exports.Dialog = Dialog;
 exports.MigrationError = MigrationError;
+exports.Mixins = Mixins;
 exports.NanoEmitter = NanoEmitter;
 exports.PlatformError = PlatformError;
 exports.SelectorObserver = SelectorObserver;