@sv443-network/userutils 9.2.0 → 9.3.0

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # @sv443-network/userutils
 
+## 9.3.0
+
+### Minor Changes
+
+- 89d7970: Added `DataStoreSerializer` methods `serializePartial()` and `deserializePartial()` for partial data exports and imports
+- 5d71770: Added function `purifyObj()` to remove an object's prototype chain (i.e. omit all inherited properties like `toString`, `__proto__`, etc.)
+
+## 9.2.1
+
+### Patch Changes
+
+- 24dad2b: Fixed TS type for `DataStoreSerializer.serialize()`
+
 ## 9.2.0
 
 ### Minor Changes
@@ -11,7 +24,7 @@
 - 905fea4: Added function `onDomLoad()` to call a callback and/or resolve a Promise when the DOM is loaded, even retroactively
 - 4264154: Added function `bitSetHas()` to check if a given value is present in a [bitset](https://www.geeksforgeeks.org/cpp-bitset-and-its-application/)
 - bf55335: Replaced a bunch of generic `Error`s with the new custom error class instances
-- bf55335: Added custom error classes `ChecksumMismatchError`, `DataMigrationError` and `PlatformError`, extending from the base class `UUError`
+- bf55335: Added custom error classes `ChecksumMismatchError`, `MigrationError` and `PlatformError`, extending from the base class `UUError`
   The base class has the additional property `date` which is the time of the error creation
 
 ### Patch Changes

package/README-summary.md

@@ -74,6 +74,7 @@ View the documentation of previous major releases:
     - [`consumeGen()`](https://github.com/Sv443-Network/UserUtils/blob/main/docs.md#consumegen) - consumes a ValueGen and returns the value
     - [`consumeStringGen()`](https://github.com/Sv443-Network/UserUtils/blob/main/docs.md#consumestringgen) - consumes a StringGen and returns the string
     - [`getListLength()`](https://github.com/Sv443-Network/UserUtils/blob/main/docs.md#getlistlength) - get the length of any object with a numeric `length`, `count` or `size` property
+    - [`purifyObj()`](https://github.com/Sv443-Network/UserUtils/blob/main/docs.md#purifyobj) - removes the prototype chain (all default properties like `toString`, `__proto__`, etc.) from an object
 - **Arrays:**
     - [`randomItem()`](https://github.com/Sv443-Network/UserUtils/blob/main/docs.md#randomitem) - returns a random item from an array
     - [`randomItemIndex()`](https://github.com/Sv443-Network/UserUtils/blob/main/docs.md#randomitemindex) - returns a tuple of a random item and its index from an array
@@ -109,7 +110,7 @@ View the documentation of previous major releases:
 - **Custom Error classes:**
     - [`UUError`](https://github.com/Sv443-Network/UserUtils/blob/main/docs.md#uuerror) - base class for all custom UserUtils errors - has a custom `date` prop set to the time of creation
     - [`ChecksumMismatchError`](https://github.com/Sv443-Network/UserUtils/blob/main/docs.md#checksummismatcherror) - thrown when a string of data doesn't match its checksum
-    - [`DataMigrationError`](https://github.com/Sv443-Network/UserUtils/blob/main/docs.md#datamigrationerror) - thrown when a data migration fails
+    - [`MigrationError`](https://github.com/Sv443-Network/UserUtils/blob/main/docs.md#migrationerror) - thrown when a data migration fails
     - [`PlatformError`](https://github.com/Sv443-Network/UserUtils/blob/main/docs.md#platformerror) - thrown when a function is called in an unsupported environment
 
 <br><br>

package/README.md

@@ -77,6 +77,7 @@ View the documentation of previous major releases:
     - [`consumeGen()`](./docs.md#consumegen) - consumes a ValueGen and returns the value
     - [`consumeStringGen()`](./docs.md#consumestringgen) - consumes a StringGen and returns the string
     - [`getListLength()`](./docs.md#getlistlength) - get the length of any object with a numeric `length`, `count` or `size` property
+    - [`purifyObj()`](./docs.md#purifyobj) - removes the prototype chain (all default properties like `toString`, `__proto__`, etc.) from an object
   - [**Arrays:**](./docs.md#arrays)
     - [`randomItem()`](./docs.md#randomitem) - returns a random item from an array
     - [`randomItemIndex()`](./docs.md#randomitemindex) - returns a tuple of a random item and its index from an array
@@ -112,7 +113,7 @@ View the documentation of previous major releases:
   - [**Custom Error classes**](./docs.md#error-classes)
     - [`UUError`](./docs.md#uuerror) - base class for all custom UserUtils errors - has a custom `date` prop set to the time of creation
     - [`ChecksumMismatchError`](./docs.md#checksummismatcherror) - thrown when a string of data doesn't match its checksum
-    - [`DataMigrationError`](./docs.md#datamigrationerror) - thrown when a data migration fails
+    - [`MigrationError`](./docs.md#migrationerror) - thrown when a data migration fails
     - [`PlatformError`](./docs.md#platformerror) - thrown when a function is called in an unsupported environment
 
 <br><br>

package/dist/index.cjs

@@ -747,14 +747,15 @@ var DataStoreSerializer = class _DataStoreSerializer {
     });
   }
   /**
-   * Serializes the data stores into a string.  
+   * Serializes only a subset of the data stores into a string.  
+   * @param stores An array of store IDs or functions that take a store ID and return a boolean
    * @param useEncoding Whether to encode the data using each DataStore's `encodeData()` method
    * @param stringified Whether to return the result as a string or as an array of `SerializedDataStore` objects
    */
-  serialize(useEncoding = true, stringified = true) {
+  serializePartial(stores, useEncoding = true, stringified = true) {
     return __async(this, null, function* () {
       const serData = [];
-      for (const storeInst of this.stores) {
+      for (const storeInst of this.stores.filter((s) => typeof stores === "function" ? stores(s.id) : stores.includes(s.id))) {
         const data = useEncoding && storeInst.encodingEnabled() ? yield storeInst.encodeData(JSON.stringify(storeInst.getData())) : JSON.stringify(storeInst.getData());
         serData.push({
           id: storeInst.id,
@@ -768,15 +769,25 @@ var DataStoreSerializer = class _DataStoreSerializer {
     });
   }
   /**
-   * Deserializes the data exported via {@linkcode serialize()} and imports it into the DataStore instances.  
+   * Serializes the data stores into a string.  
+   * @param useEncoding Whether to encode the data using each DataStore's `encodeData()` method
+   * @param stringified Whether to return the result as a string or as an array of `SerializedDataStore` objects
+   */
+  serialize(useEncoding = true, stringified = true) {
+    return __async(this, null, function* () {
+      return this.serializePartial(this.stores.map((s) => s.id), useEncoding, stringified);
+    });
+  }
+  /**
+   * Deserializes the data exported via {@linkcode serialize()} and imports only a subset into the DataStore instances.  
    * Also triggers the migration process if the data format has changed.
    */
-  deserialize(serializedData) {
+  deserializePartial(stores, data) {
     return __async(this, null, function* () {
-      const deserStores = typeof serializedData === "string" ? JSON.parse(serializedData) : serializedData;
+      const deserStores = typeof data === "string" ? JSON.parse(data) : data;
       if (!Array.isArray(deserStores) || !deserStores.every(_DataStoreSerializer.isSerializedDataStore))
         throw new TypeError("Invalid serialized data format! Expected an array of SerializedDataStore objects.");
-      for (const storeData of deserStores) {
+      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);
         if (!storeInst)
           throw new Error(`DataStore instance with ID "${storeData.id}" not found! Make sure to provide it in the DataStoreSerializer constructor.`);
@@ -795,6 +806,15 @@ Has: ${checksum}`);
       }
     });
   }
+  /**
+   * Deserializes the data exported via {@linkcode serialize()} and imports the data into all matching DataStore instances.  
+   * Also triggers the migration process if the data format has changed.
+   */
+  deserialize(data) {
+    return __async(this, null, function* () {
+      return this.deserializePartial(this.stores.map((s) => s.id), data);
+    });
+  }
   /**
    * Loads the persistent data of the DataStore instances into the in-memory cache.  
    * Also triggers the migration process if the data format has changed.
@@ -1472,6 +1492,9 @@ function consumeStringGen(strGen) {
 function getListLength(obj, zeroOnInvalid = true) {
   return "length" in obj ? obj.length : "size" in obj ? obj.size : "count" in obj ? obj.count : zeroOnInvalid ? 0 : NaN;
 }
+function purifyObj(obj) {
+  return Object.assign(/* @__PURE__ */ Object.create(null), obj);
+}
 
 // lib/SelectorObserver.ts
 var SelectorObserver = class {
@@ -1853,6 +1876,7 @@ exports.openInNewTab = openInNewTab;
 exports.pauseFor = pauseFor;
 exports.preloadImages = preloadImages;
 exports.probeElementStyle = probeElementStyle;
+exports.purifyObj = purifyObj;
 exports.randRange = randRange;
 exports.randomId = randomId;
 exports.randomItem = randomItem;

package/dist/index.global.js

@@ -8,7 +8,7 @@
 // ==UserLibrary==
 // @name         UserUtils
 // @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
-// @version      9.2.0
+// @version      9.3.0
 // @license      MIT
 // @copyright    Sv443 (https://github.com/Sv443)
 
@@ -765,14 +765,15 @@ var UserUtils = (function (exports) {
       });
     }
     /**
-     * Serializes the data stores into a string.  
+     * Serializes only a subset of the data stores into a string.  
+     * @param stores An array of store IDs or functions that take a store ID and return a boolean
      * @param useEncoding Whether to encode the data using each DataStore's `encodeData()` method
      * @param stringified Whether to return the result as a string or as an array of `SerializedDataStore` objects
      */
-    serialize(useEncoding = true, stringified = true) {
+    serializePartial(stores, useEncoding = true, stringified = true) {
       return __async(this, null, function* () {
         const serData = [];
-        for (const storeInst of this.stores) {
+        for (const storeInst of this.stores.filter((s) => typeof stores === "function" ? stores(s.id) : stores.includes(s.id))) {
           const data = useEncoding && storeInst.encodingEnabled() ? yield storeInst.encodeData(JSON.stringify(storeInst.getData())) : JSON.stringify(storeInst.getData());
           serData.push({
             id: storeInst.id,
@@ -786,15 +787,25 @@ var UserUtils = (function (exports) {
       });
     }
     /**
-     * Deserializes the data exported via {@linkcode serialize()} and imports it into the DataStore instances.  
+     * Serializes the data stores into a string.  
+     * @param useEncoding Whether to encode the data using each DataStore's `encodeData()` method
+     * @param stringified Whether to return the result as a string or as an array of `SerializedDataStore` objects
+     */
+    serialize(useEncoding = true, stringified = true) {
+      return __async(this, null, function* () {
+        return this.serializePartial(this.stores.map((s) => s.id), useEncoding, stringified);
+      });
+    }
+    /**
+     * Deserializes the data exported via {@linkcode serialize()} and imports only a subset into the DataStore instances.  
      * Also triggers the migration process if the data format has changed.
      */
-    deserialize(serializedData) {
+    deserializePartial(stores, data) {
       return __async(this, null, function* () {
-        const deserStores = typeof serializedData === "string" ? JSON.parse(serializedData) : serializedData;
+        const deserStores = typeof data === "string" ? JSON.parse(data) : data;
         if (!Array.isArray(deserStores) || !deserStores.every(_DataStoreSerializer.isSerializedDataStore))
           throw new TypeError("Invalid serialized data format! Expected an array of SerializedDataStore objects.");
-        for (const storeData of deserStores) {
+        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);
           if (!storeInst)
             throw new Error(`DataStore instance with ID "${storeData.id}" not found! Make sure to provide it in the DataStoreSerializer constructor.`);
@@ -813,6 +824,15 @@ Has: ${checksum}`);
         }
       });
     }
+    /**
+     * Deserializes the data exported via {@linkcode serialize()} and imports the data into all matching DataStore instances.  
+     * Also triggers the migration process if the data format has changed.
+     */
+    deserialize(data) {
+      return __async(this, null, function* () {
+        return this.deserializePartial(this.stores.map((s) => s.id), data);
+      });
+    }
     /**
      * Loads the persistent data of the DataStore instances into the in-memory cache.  
      * Also triggers the migration process if the data format has changed.
@@ -1510,6 +1530,9 @@ Has: ${checksum}`);
   function getListLength(obj, zeroOnInvalid = true) {
     return "length" in obj ? obj.length : "size" in obj ? obj.size : "count" in obj ? obj.count : zeroOnInvalid ? 0 : NaN;
   }
+  function purifyObj(obj) {
+    return Object.assign(/* @__PURE__ */ Object.create(null), obj);
+  }
 
   // lib/SelectorObserver.ts
   var SelectorObserver = class {
@@ -1891,6 +1914,7 @@ Has: ${checksum}`);
   exports.pauseFor = pauseFor;
   exports.preloadImages = preloadImages;
   exports.probeElementStyle = probeElementStyle;
+  exports.purifyObj = purifyObj;
   exports.randRange = randRange;
   exports.randomId = randomId;
   exports.randomItem = randomItem;

package/dist/index.js

@@ -745,14 +745,15 @@ var DataStoreSerializer = class _DataStoreSerializer {
     });
   }
   /**
-   * Serializes the data stores into a string.  
+   * Serializes only a subset of the data stores into a string.  
+   * @param stores An array of store IDs or functions that take a store ID and return a boolean
    * @param useEncoding Whether to encode the data using each DataStore's `encodeData()` method
    * @param stringified Whether to return the result as a string or as an array of `SerializedDataStore` objects
    */
-  serialize(useEncoding = true, stringified = true) {
+  serializePartial(stores, useEncoding = true, stringified = true) {
     return __async(this, null, function* () {
       const serData = [];
-      for (const storeInst of this.stores) {
+      for (const storeInst of this.stores.filter((s) => typeof stores === "function" ? stores(s.id) : stores.includes(s.id))) {
         const data = useEncoding && storeInst.encodingEnabled() ? yield storeInst.encodeData(JSON.stringify(storeInst.getData())) : JSON.stringify(storeInst.getData());
         serData.push({
           id: storeInst.id,
@@ -766,15 +767,25 @@ var DataStoreSerializer = class _DataStoreSerializer {
     });
   }
   /**
-   * Deserializes the data exported via {@linkcode serialize()} and imports it into the DataStore instances.  
+   * Serializes the data stores into a string.  
+   * @param useEncoding Whether to encode the data using each DataStore's `encodeData()` method
+   * @param stringified Whether to return the result as a string or as an array of `SerializedDataStore` objects
+   */
+  serialize(useEncoding = true, stringified = true) {
+    return __async(this, null, function* () {
+      return this.serializePartial(this.stores.map((s) => s.id), useEncoding, stringified);
+    });
+  }
+  /**
+   * Deserializes the data exported via {@linkcode serialize()} and imports only a subset into the DataStore instances.  
    * Also triggers the migration process if the data format has changed.
    */
-  deserialize(serializedData) {
+  deserializePartial(stores, data) {
     return __async(this, null, function* () {
-      const deserStores = typeof serializedData === "string" ? JSON.parse(serializedData) : serializedData;
+      const deserStores = typeof data === "string" ? JSON.parse(data) : data;
       if (!Array.isArray(deserStores) || !deserStores.every(_DataStoreSerializer.isSerializedDataStore))
         throw new TypeError("Invalid serialized data format! Expected an array of SerializedDataStore objects.");
-      for (const storeData of deserStores) {
+      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);
         if (!storeInst)
           throw new Error(`DataStore instance with ID "${storeData.id}" not found! Make sure to provide it in the DataStoreSerializer constructor.`);
@@ -793,6 +804,15 @@ Has: ${checksum}`);
       }
     });
   }
+  /**
+   * Deserializes the data exported via {@linkcode serialize()} and imports the data into all matching DataStore instances.  
+   * Also triggers the migration process if the data format has changed.
+   */
+  deserialize(data) {
+    return __async(this, null, function* () {
+      return this.deserializePartial(this.stores.map((s) => s.id), data);
+    });
+  }
   /**
    * Loads the persistent data of the DataStore instances into the in-memory cache.  
    * Also triggers the migration process if the data format has changed.
@@ -1470,6 +1490,9 @@ function consumeStringGen(strGen) {
 function getListLength(obj, zeroOnInvalid = true) {
   return "length" in obj ? obj.length : "size" in obj ? obj.size : "count" in obj ? obj.count : zeroOnInvalid ? 0 : NaN;
 }
+function purifyObj(obj) {
+  return Object.assign(/* @__PURE__ */ Object.create(null), obj);
+}
 
 // lib/SelectorObserver.ts
 var SelectorObserver = class {
@@ -1807,4 +1830,4 @@ var tr = {
   }
 };
 
-export { ChecksumMismatchError, DataStore, DataStoreSerializer, Debouncer, Dialog, MigrationError, NanoEmitter, PlatformError, SelectorObserver, UUError, addGlobalStyle, addParent, autoPlural, bitSetHas, clamp, compress, computeHash, consumeGen, consumeStringGen, currentDialogId, darkenColor, debounce, decompress, defaultDialogCss, defaultStrings, digitCount, fetchAdvanced, getListLength, getSiblingsFrame, getUnsafeWindow, hexToRgb, insertValues, interceptEvent, interceptWindowEvent, isDomLoaded, isScrollable, lightenColor, mapRange, observeElementProp, onDomLoad, openDialogs, openInNewTab, pauseFor, preloadImages, probeElementStyle, randRange, randomId, randomItem, randomItemIndex, randomizeArray, rgbToHex, roundFixed, setInnerHtmlUnsafe, takeRandomItem, tr };
+export { ChecksumMismatchError, DataStore, DataStoreSerializer, Debouncer, Dialog, MigrationError, NanoEmitter, PlatformError, SelectorObserver, UUError, addGlobalStyle, addParent, autoPlural, bitSetHas, clamp, compress, computeHash, consumeGen, consumeStringGen, currentDialogId, darkenColor, debounce, decompress, defaultDialogCss, defaultStrings, digitCount, fetchAdvanced, getListLength, getSiblingsFrame, getUnsafeWindow, hexToRgb, insertValues, interceptEvent, interceptWindowEvent, isDomLoaded, isScrollable, lightenColor, mapRange, observeElementProp, onDomLoad, openDialogs, openInNewTab, pauseFor, preloadImages, probeElementStyle, purifyObj, randRange, randomId, randomItem, randomItemIndex, randomizeArray, rgbToHex, roundFixed, setInnerHtmlUnsafe, takeRandomItem, tr };

package/dist/lib/DataStoreSerializer.d.ts

@@ -6,7 +6,7 @@ import type { DataStore } from "./DataStore.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) */
+    /** Whether to ensure the integrity of the data when importing it by throwing an error (doesn't throw when the checksum property doesn't exist) */
     ensureIntegrity?: boolean;
 };
 /** Serialized data of a DataStore instance */
@@ -19,7 +19,7 @@ export type SerializedDataStore = {
     formatVersion: number;
     /** Whether the data is encoded */
     encoded: boolean;
-    /** The checksum of the data - key is not present for data without a checksum */
+    /** The checksum of the data - key is not present when `addChecksum` is `false` */
     checksum?: string;
 };
 /** Result of {@linkcode DataStoreSerializer.loadStoresData()} */
@@ -43,23 +43,49 @@ export declare class DataStoreSerializer {
     constructor(stores: DataStore[], options?: DataStoreSerializerOptions);
     /** Calculates the checksum of a string */
     protected calcChecksum(input: string): Promise<string>;
+    /**
+     * Serializes only a subset of the data stores into a string.  
+     * @param stores An array of store IDs or functions that take a store ID and return a boolean  
+     * @param useEncoding Whether to encode the data using each DataStore's `encodeData()` method  
+     * @param stringified Whether to return the result as a string or as an array of `SerializedDataStore` objects  
+     */
+    serializePartial(stores: string[] | ((id: string) => boolean), useEncoding?: boolean, stringified?: true): Promise<string>;
+    /**
+     * Serializes only a subset of the data stores into a string.  
+     * @param stores An array of store IDs or functions that take a store ID and return a boolean  
+     * @param useEncoding Whether to encode the data using each DataStore's `encodeData()` method  
+     * @param stringified Whether to return the result as a string or as an array of `SerializedDataStore` objects  
+     */
+    serializePartial(stores: string[] | ((id: string) => boolean), useEncoding?: boolean, stringified?: false): Promise<SerializedDataStore[]>;
+    /**
+     * Serializes only a subset of the data stores into a string.  
+     * @param stores An array of store IDs or functions that take a store ID and return a boolean  
+     * @param useEncoding Whether to encode the data using each DataStore's `encodeData()` method  
+     * @param stringified Whether to return the result as a string or as an array of `SerializedDataStore` objects  
+     */
+    serializePartial(stores: string[] | ((id: string) => boolean), useEncoding?: boolean, stringified?: boolean): Promise<string | SerializedDataStore[]>;
     /**
      * Serializes the data stores into a string.  
      * @param useEncoding Whether to encode the data using each DataStore's `encodeData()` method  
      * @param stringified Whether to return the result as a string or as an array of `SerializedDataStore` objects  
      */
-    serialize(useEncoding: boolean, stringified: true): Promise<string>;
+    serialize(useEncoding?: boolean, stringified?: true): Promise<string>;
     /**
      * Serializes the data stores into a string.  
      * @param useEncoding Whether to encode the data using each DataStore's `encodeData()` method  
      * @param stringified Whether to return the result as a string or as an array of `SerializedDataStore` objects  
      */
-    serialize(useEncoding: boolean, stringified: false): Promise<SerializedDataStore[]>;
+    serialize(useEncoding?: boolean, stringified?: false): Promise<SerializedDataStore[]>;
+    /**
+     * Deserializes the data exported via {@linkcode serialize()} and imports only a subset into the DataStore instances.  
+     * Also triggers the migration process if the data format has changed.  
+     */
+    deserializePartial(stores: string[] | ((id: string) => boolean), data: string | SerializedDataStore[]): Promise<void>;
     /**
-     * Deserializes the data exported via {@linkcode serialize()} and imports it into the DataStore instances.  
+     * Deserializes the data exported via {@linkcode serialize()} and imports the data into all matching DataStore instances.  
      * Also triggers the migration process if the data format has changed.  
      */
-    deserialize(serializedData: string | SerializedDataStore[]): Promise<void>;
+    deserialize(data: string | SerializedDataStore[]): Promise<void>;
     /**
      * Loads the persistent data of the DataStore instances into the in-memory cache.  
      * Also triggers the migration process if the data format has changed.  

package/dist/lib/misc.d.ts

@@ -61,3 +61,9 @@ export declare function consumeStringGen<TStrUnion extends string>(strGen: Strin
  * Set {@linkcode zeroOnInvalid} to false to return NaN instead of 0 if the object doesn't have any of the properties.  
  */
 export declare function getListLength(obj: ListWithLength, zeroOnInvalid?: boolean): number;
+/**
+ * Turns the passed object into a "pure" object without a prototype chain, meaning it won't have any default properties like `toString`, `__proto__`, `__defineGetter__`, etc.  
+ * This makes the object immune to prototype pollution attacks and allows for cleaner object literals, at the cost of being harder to work with in some cases.  
+ * It also effectively transforms a `Stringifiable` value into one that will throw a TypeError when stringified instead of defaulting to `[object Object]`  
+ */
+export declare function purifyObj<TObj extends object>(obj: TObj): TObj;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@sv443-network/userutils",
   "libName": "UserUtils",
-  "version": "9.2.0",
+  "version": "9.3.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",