AG-9480 add trusted-set-constant scriptlet #137

Merge in ADGUARD-FILTERS/scriptlets from feature/AG-9480 to release/v1.8

Squashed commit of the following:

commit e69dccd
Author: Stanislav A <s.atroschenko@adguard.com>
Date:   Thu Jan 12 14:49:58 2023 +0300

    improve inferValue description

commit 3dcf6d4
Author: Stanislav A <s.atroschenko@adguard.com>
Date:   Thu Jan 12 12:59:05 2023 +0300

    add 32767 to const and tweak failing test

commit 39f1c2d
Author: Stanislav A <s.atroschenko@adguard.com>
Date:   Thu Jan 12 12:23:50 2023 +0300

    add testcases with string value

commit bb1960e
Author: Stanislav A <s.atroschenko@adguard.com>
Date:   Wed Jan 11 21:40:48 2023 +0300

    fix and improve description

commit 68b112c
Author: Stanislav A <s.atroschenko@adguard.com>
Date:   Wed Jan 11 19:37:30 2023 +0300

    improve funcs descriptions and warning

commit d620833
Author: Stanislav A <s.atroschenko@adguard.com>
Date:   Wed Jan 11 19:17:50 2023 +0300

    improve value type inferred and remove shouldInfer argument

commit 824e900
Author: Stanislav A <s.atroschenko@adguard.com>
Date:   Wed Jan 11 17:39:17 2023 +0300

    jsdoc set-constant helpers

commit 71a5451
Author: Stanislav A <s.atroschenko@adguard.com>
Date:   Wed Jan 11 14:58:30 2023 +0300

    fix typos

commit b9bb8fe
Author: Stanislav A <s.atroschenko@adguard.com>
Date:   Wed Jan 11 14:49:07 2023 +0300

    swap 0x7FFF to 32767 everywhere

commit 4fa3b37
Merge: 327216a 96e65b4
Author: Stanislav A <s.atroschenko@adguard.com>
Date:   Tue Jan 10 14:43:35 2023 +0300

    Merge branch 'release/v1.8' into feature/AG-9480

commit 327216a
Author: Stanislav A <s.atroschenko@adguard.com>
Date:   Tue Jan 10 14:32:47 2023 +0300

    update changelog

commit 0af2569
Author: Stanislav A <s.atroschenko@adguard.com>
Date:   Tue Jan 10 12:55:01 2023 +0300

    fix tests

commit 726e63d
Author: Stanislav A <s.atroschenko@adguard.com>
Date:   Mon Jan 9 21:16:26 2023 +0300

    update description

commit 105ea07
Author: Stanislav A <s.atroschenko@adguard.com>
Date:   Mon Jan 9 19:30:05 2023 +0300

    fix helper and add scriptlet tests

commit bcef888
Author: Stanislav A <s.atroschenko@adguard.com>
Date:   Fri Dec 30 18:49:45 2022 +0300

    draft inferValue helper

commit e45a707
Author: Stanislav A <s.atroschenko@adguard.com>
Date:   Thu Dec 29 16:24:04 2022 +0300

    draft trusted-set-constant

CHANGELOG.md

@@ -3,6 +3,7 @@
 ## Unreleased 1.8.x
 
 ### Added
+- new `trusted-set-constant` scriptlet [#137](https://github.com/AdguardTeam/Scriptlets/issues/137)
 - `throwFunc` and `noopCallbackFunc` prop values for `set-constant` scriptlet
 
 ### Changed

src/helpers/storage-utils.js

@@ -50,7 +50,7 @@ export const getLimitedStorageItemValue = (value) => {
         if (nativeIsNaN(validValue)) {
             throw new Error('Invalid value');
         }
-        if (Math.abs(validValue) > 0x7FFF) {
+        if (Math.abs(validValue) > 32767) {
             throw new Error('Invalid value');
         }
     } else if (value === 'yes') {

src/helpers/string-utils.js

@@ -372,3 +372,52 @@ export function generateRandomResponse(customResponseText) {
     customResponse = getRandomStrByLength(length);
     return customResponse;
 }
+
+/**
+ * Infers value from string argument
+ * Inferring goes from more specific to more ambiguous options
+ * Arrays, objects and strings are parsed via JSON.parse
+ *
+ * @param {string} value arbitrary string
+ * @returns {any} converted value
+ * @throws an error on unexpected input
+ */
+export function inferValue(value) {
+    if (value === 'undefined') {
+        return undefined;
+    } if (value === 'false') {
+        return false;
+    } if (value === 'true') {
+        return true;
+    } if (value === 'null') {
+        return null;
+    } if (value === 'NaN') {
+        return NaN;
+    }
+
+    // Number class constructor works 2 times faster than JSON.parse
+    // and wont interpret mixed inputs like '123asd' as parseFloat would
+    const MAX_ALLOWED_NUM = 32767;
+    const numVal = Number(value);
+    if (!nativeIsNaN(numVal)) {
+        if (Math.abs(numVal) > MAX_ALLOWED_NUM) {
+            throw new Error('number values bigger than 32767 are not allowed');
+        }
+        return numVal;
+    }
+
+    let errorMessage = `'${value}' value type can't be inferred`;
+    try {
+        // Parse strings, arrays and objects represented as JSON strings
+        // '[1,2,3,"string"]' > [1, 2, 3, 'string']
+        // '"arbitrary string"' > 'arbitrary string'
+        const parsableVal = JSON.parse(value);
+        if (parsableVal instanceof Object || typeof parsableVal === 'string') {
+            return parsableVal;
+        }
+    } catch (e) {
+        errorMessage += `: ${e}`;
+    }
+
+    throw new TypeError(errorMessage);
+}

src/scriptlets/scriptlets-list.js

@@ -54,3 +54,4 @@ export * from './trusted-set-cookie';
 export * from './trusted-set-cookie-reload';
 export * from './trusted-replace-fetch-response';
 export * from './trusted-set-local-storage-item';
+export * from './trusted-set-constant';

src/scriptlets/set-attr.js

@@ -60,7 +60,7 @@ export function setAttr(source, selector, attr, value = '') {
     if (value.length !== 0
         && (nativeIsNaN(parseInt(value, 10))
             || parseInt(value, 10) < 0
-            || parseInt(value, 10) > 0x7FFF)) {
+            || parseInt(value, 10) > 32767)) {
         return;
     }
 

src/scriptlets/set-constant.js

@@ -132,7 +132,7 @@ export function setConstant(source, property, value, stack) {
         if (nativeIsNaN(constantValue)) {
             return;
         }
-        if (Math.abs(constantValue) > 0x7FFF) {
+        if (Math.abs(constantValue) > 32767) {
             return;
         }
     } else if (value === '-1') {
@@ -159,6 +159,18 @@ export function setConstant(source, property, value, stack) {
         return canceled;
     };
 
+    /**
+     * Safely sets property on a given object
+     *
+     * IMPORTANT! this duplicates corresponding func in trusted-set-constant scriptlet as
+     * reorganizing this to common helpers will most definitely complicate debugging
+     *
+     * @param {Object} base arbitrary reachable object
+     * @param {string} prop property name
+     * @param {boolean} configurable if set property should be configurable
+     * @param {Object} handler custom property descriptor object
+     * @returns {boolean} true if prop was trapped successfully
+     */
     const trapProp = (base, prop, configurable, handler) => {
         if (!handler.init(base[prop])) {
             return false;
@@ -195,6 +207,17 @@ export function setConstant(source, property, value, stack) {
         return true;
     };
 
+    /**
+     * Traverses given chain to set constant value to its end prop
+     * Chains that yet include non-object values (e.g null) are valid and will be
+     * traversed when appropriate chain member is set by an external script
+     *
+     * IMPORTANT! this duplicates corresponding func in trusted-set-constant scriptlet as
+     * reorganizing this to common helpers will most definitely complicate debugging
+     *
+     * @param {Object} owner object that owns chain
+     * @param {string} property chain of owner properties
+     */
     const setChainPropAccess = (owner, property) => {
         const chainInfo = getPropertyInChain(owner, property);
         const { base } = chainInfo;