@sv443-network/userutils 4.0.0 → 4.1.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @sv443-network/userutils
 
+## 4.1.0
+
+### Minor Changes
+
+- 885323d: Added function `observeElementProp` to allow observing element property changes
+
 ## 4.0.0
 
 ### Major Changes

package/README.md

@@ -33,6 +33,7 @@ View the documentation of previous major releases: [3.0.0](https://github.com/Sv
     - [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
     - [isScrollable()](#isscrollable) - check if an element has a horizontal or vertical scroll bar
+    - [observeElementProp()](#observeelementprop) - observe changes to an element's property that can't be observed with MutationObserver
   - [**Math:**](#math)
     - [clamp()](#clamp) - constrain a number between a min and max value
     - [mapRange()](#maprange) - map a number from one range to the same spot in another range
@@ -675,6 +676,59 @@ console.log("Element has a vertical scroll bar:", vertical);
 
 </details>
 
+<br>
+
+### observeElementProp()
+Usage:  
+```ts
+observeElementProp(
+  element: Element,
+  property: string,
+  callback: (oldValue: any, newValue: any) => void
+): void
+```
+  
+This function observes changes to the given property of a given element.  
+While regular HTML attributes can be observed using a MutationObserver, this is not always possible for properties that are assigned on the JS object.  
+This function shims the setter of the provided property and calls the callback function whenever it is changed through any means.  
+  
+When using TypeScript, the types for `element`, `property` and the arguments for `callback` will be automatically inferred.  
+  
+<details><summary><b>Example - click to view</b></summary>
+
+```ts
+import { observeElementProp } from "@sv443-network/userutils";
+
+const myInput = document.querySelector("input#my-input");
+
+let value = 0;
+
+setInterval(() => {
+  value += 1;
+  myInput.value = String(value);
+}, 1000);
+
+
+const observer = new MutationObserver((mutations) => {
+  // will never be called:
+  console.log("MutationObserver mutation:", mutations);
+});
+
+// one would think this should work, but "value" is a JS object *property*, not a DOM *attribute*
+observer.observe(myInput, {
+  attributes: true,
+  attributeFilter: ["value"],
+});
+
+
+observeElementProp(myInput, "value", (oldValue, newValue) => {
+  // will be called every time the value changes:
+  console.log("Value changed from", oldValue, "to", newValue);
+});
+```
+
+</details>
+
 <br><br>
 
 <!-- #SECTION Math -->

package/dist/index.global.js

@@ -9,7 +9,7 @@
 // ==UserLibrary==
 // @name         UserUtils
 // @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      4.0.0
+// @version      4.1.0
 // @license      MIT
 // @copyright    Sv443 (https://github.com/Sv443)
 
@@ -333,6 +333,28 @@ var UserUtils = (function (exports) {
       horizontal: (overflowX === "scroll" || overflowX === "auto") && element.scrollWidth > element.clientWidth
     };
   }
+  function observeElementProp(element, property, callback) {
+    const elementPrototype = Object.getPrototypeOf(element);
+    if (elementPrototype.hasOwnProperty(property)) {
+      const descriptor = Object.getOwnPropertyDescriptor(elementPrototype, property);
+      Object.defineProperty(element, property, {
+        get: function() {
+          var _a;
+          return (_a = descriptor == null ? void 0 : descriptor.get) == null ? void 0 : _a.apply(this, arguments);
+        },
+        set: function() {
+          var _a;
+          const oldValue = this[property];
+          (_a = descriptor == null ? void 0 : descriptor.set) == null ? void 0 : _a.apply(this, arguments);
+          const newValue = this[property];
+          if (typeof callback === "function") {
+            callback.bind(this, oldValue, newValue);
+          }
+          return newValue;
+        }
+      });
+    }
+  }
 
   // lib/misc.ts
   function autoPlural(word, num) {
@@ -585,6 +607,7 @@ var UserUtils = (function (exports) {
   exports.interceptWindowEvent = interceptWindowEvent;
   exports.isScrollable = isScrollable;
   exports.mapRange = mapRange;
+  exports.observeElementProp = observeElementProp;
   exports.openInNewTab = openInNewTab;
   exports.pauseFor = pauseFor;
   exports.preloadImages = preloadImages;

package/dist/index.js

@@ -312,6 +312,28 @@ function isScrollable(element) {
     horizontal: (overflowX === "scroll" || overflowX === "auto") && element.scrollWidth > element.clientWidth
   };
 }
+function observeElementProp(element, property, callback) {
+  const elementPrototype = Object.getPrototypeOf(element);
+  if (elementPrototype.hasOwnProperty(property)) {
+    const descriptor = Object.getOwnPropertyDescriptor(elementPrototype, property);
+    Object.defineProperty(element, property, {
+      get: function() {
+        var _a;
+        return (_a = descriptor == null ? void 0 : descriptor.get) == null ? void 0 : _a.apply(this, arguments);
+      },
+      set: function() {
+        var _a;
+        const oldValue = this[property];
+        (_a = descriptor == null ? void 0 : descriptor.set) == null ? void 0 : _a.apply(this, arguments);
+        const newValue = this[property];
+        if (typeof callback === "function") {
+          callback.bind(this, oldValue, newValue);
+        }
+        return newValue;
+      }
+    });
+  }
+}
 
 // lib/misc.ts
 function autoPlural(word, num) {
@@ -564,6 +586,7 @@ exports.interceptEvent = interceptEvent;
 exports.interceptWindowEvent = interceptWindowEvent;
 exports.isScrollable = isScrollable;
 exports.mapRange = mapRange;
+exports.observeElementProp = observeElementProp;
 exports.openInNewTab = openInNewTab;
 exports.pauseFor = pauseFor;
 exports.preloadImages = preloadImages;

package/dist/index.mjs

@@ -310,6 +310,28 @@ function isScrollable(element) {
     horizontal: (overflowX === "scroll" || overflowX === "auto") && element.scrollWidth > element.clientWidth
   };
 }
+function observeElementProp(element, property, callback) {
+  const elementPrototype = Object.getPrototypeOf(element);
+  if (elementPrototype.hasOwnProperty(property)) {
+    const descriptor = Object.getOwnPropertyDescriptor(elementPrototype, property);
+    Object.defineProperty(element, property, {
+      get: function() {
+        var _a;
+        return (_a = descriptor == null ? void 0 : descriptor.get) == null ? void 0 : _a.apply(this, arguments);
+      },
+      set: function() {
+        var _a;
+        const oldValue = this[property];
+        (_a = descriptor == null ? void 0 : descriptor.set) == null ? void 0 : _a.apply(this, arguments);
+        const newValue = this[property];
+        if (typeof callback === "function") {
+          callback.bind(this, oldValue, newValue);
+        }
+        return newValue;
+      }
+    });
+  }
+}
 
 // lib/misc.ts
 function autoPlural(word, num) {
@@ -545,4 +567,4 @@ tr.getLanguage = () => {
   return curLang;
 };
 
-export { ConfigManager, SelectorObserver, addGlobalStyle, addParent, autoPlural, clamp, compress, debounce, decompress, fetchAdvanced, getUnsafeWindow, insertAfter, insertValues, interceptEvent, interceptWindowEvent, isScrollable, mapRange, openInNewTab, pauseFor, preloadImages, randRange, randomId, randomItem, randomItemIndex, randomizeArray, takeRandomItem, tr };
+export { ConfigManager, SelectorObserver, addGlobalStyle, addParent, autoPlural, clamp, compress, debounce, decompress, fetchAdvanced, getUnsafeWindow, insertAfter, insertValues, interceptEvent, interceptWindowEvent, isScrollable, mapRange, observeElementProp, openInNewTab, pauseFor, preloadImages, randRange, randomId, randomItem, randomItemIndex, randomizeArray, takeRandomItem, tr };

package/dist/lib/dom.d.ts

@@ -50,3 +50,13 @@ export declare function isScrollable(element: Element): {
     vertical: boolean;
     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.
+ * This function shims the getter and setter of the property to invoke the callback.
+ *
+ * [Source](https://stackoverflow.com/a/61975440)
+ * @param property The name of the property to observe
+ * @param callback Callback to execute when the value is changed
+ */
+export declare function observeElementProp<TElem extends Element = HTMLElement, TPropKey extends keyof TElem = keyof TElem>(element: TElem, property: TPropKey, callback: (oldVal: TElem[TPropKey], newVal: TElem[TPropKey]) => void): void;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sv443-network/userutils",
-  "version": "4.0.0",
+  "version": "4.1.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",
   "main": "dist/index.js",
   "module": "dist/index.mjs",