@adguard/agtree 4.0.0 → 4.0.2

package/dist/utils/deep-freeze.js

@@ -1,5 +1,5 @@
 /*
- * AGTree v4.0.0 (build date: Wed, 21 Jan 2026 17:25:36 GMT)
+ * AGTree v4.0.2 (build date: Tue, 17 Mar 2026 23:34:38 GMT)
  * (c) 2026 Adguard Software Ltd.
  * Released under the MIT license
  * https://github.com/AdguardTeam/tsurlfilter/tree/master/packages/agtree#readme
@@ -8,13 +8,13 @@
  * Simple deep freeze implementation.
  * It freezes the object and all its properties recursively.
  *
- * @param object Object to freeze.
- *
- * @returns Frozen object.
- *
  * @template T Type of the object to freeze.
  *
  * @see {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/freeze#deep_freezing}
+ *
+ * @param object Object to freeze.
+ *
+ * @returns Frozen object.
  */
 const deepFreeze = (object) => {
     // Retrieve the property names defined on object

package/dist/utils/domain.js

@@ -1,5 +1,5 @@
 /*
- * AGTree v4.0.0 (build date: Wed, 21 Jan 2026 17:25:36 GMT)
+ * AGTree v4.0.2 (build date: Tue, 17 Mar 2026 23:34:38 GMT)
  * (c) 2026 Adguard Software Ltd.
  * Released under the MIT license
  * https://github.com/AdguardTeam/tsurlfilter/tree/master/packages/agtree#readme
@@ -31,8 +31,9 @@ class DomainUtils {
     /**
      * Check if the input is a valid domain or hostname.
      *
-     * @param domain Domain to check
-     * @returns `true` if the domain is valid, `false` otherwise
+     * @param domain Domain to check.
+     *
+     * @returns `true` if the domain is valid, `false` otherwise.
      */
     static isValidDomainOrHostname(domain) {
         let domainToCheck = domain;

package/dist/utils/error.js

@@ -1,5 +1,5 @@
 /*
- * AGTree v4.0.0 (build date: Wed, 21 Jan 2026 17:25:36 GMT)
+ * AGTree v4.0.2 (build date: Tue, 17 Mar 2026 23:34:38 GMT)
  * (c) 2026 Adguard Software Ltd.
  * Released under the MIT license
  * https://github.com/AdguardTeam/tsurlfilter/tree/master/packages/agtree#readme
@@ -8,6 +8,7 @@
  * Checks if error has message.
  *
  * @param error Error object.
+ *
  * @returns If param is error.
  */
 function isErrorWithMessage(error) {
@@ -20,6 +21,7 @@ function isErrorWithMessage(error) {
  * Converts error to the error with message.
  *
  * @param maybeError Possible error.
+ *
  * @returns Error with message.
  */
 function toErrorWithMessage(maybeError) {

package/dist/utils/index.js

@@ -1,5 +1,5 @@
 /*
- * AGTree v4.0.0 (build date: Wed, 21 Jan 2026 17:25:36 GMT)
+ * AGTree v4.0.2 (build date: Tue, 17 Mar 2026 23:34:38 GMT)
  * (c) 2026 Adguard Software Ltd.
  * Released under the MIT license
  * https://github.com/AdguardTeam/tsurlfilter/tree/master/packages/agtree#readme

package/dist/utils/logical-expression.js

@@ -1,5 +1,5 @@
 /*
- * AGTree v4.0.0 (build date: Wed, 21 Jan 2026 17:25:36 GMT)
+ * AGTree v4.0.2 (build date: Tue, 17 Mar 2026 23:34:38 GMT)
  * (c) 2026 Adguard Software Ltd.
  * Released under the MIT license
  * https://github.com/AdguardTeam/tsurlfilter/tree/master/packages/agtree#readme
@@ -21,8 +21,10 @@ class LogicalExpressionUtils {
     /**
      * Get all variables in the expression.
      *
-     * @param node Logical expression node
-     * @returns List of variables in the expression (nodes)
+     * @param node Logical expression node.
+     *
+     * @returns List of variables in the expression (nodes).
+     *
      * @example
      * If the expression is `a && b || c`, the returned list will be
      * nodes for `a`, `b`, and `c`.
@@ -45,9 +47,11 @@ class LogicalExpressionUtils {
      * Evaluate the parsed logical expression. You'll need to provide a
      * variable table.
      *
-     * @param node Logical expression node
-     * @param table Variable table (key: variable name, value: boolean)
-     * @returns Evaluation result
+     * @param node Logical expression node.
+     * @param table Variable table (key: variable name, value: boolean).
+     *
+     * @returns Evaluation result.
+     *
      * @example
      * If the expression is `a && b`, and the variable table is
      * `{ a: true, b: false }`, the result will be `false`.

package/dist/utils/multi-value-map.js

@@ -1,5 +1,5 @@
 /*
- * AGTree v4.0.0 (build date: Wed, 21 Jan 2026 17:25:36 GMT)
+ * AGTree v4.0.2 (build date: Tue, 17 Mar 2026 23:34:38 GMT)
  * (c) 2026 Adguard Software Ltd.
  * Released under the MIT license
  * https://github.com/AdguardTeam/tsurlfilter/tree/master/packages/agtree#readme
@@ -10,15 +10,15 @@ import { isUndefined } from './type-guards.js';
  * A very simple map extension that allows to store multiple values for the same key
  * by storing them in an array.
  *
- * @todo Add more methods if needed
+ * @todo Add more methods if needed.
  */
 class MultiValueMap extends Map {
     /**
      * Adds a value to the map. If the key already exists, the value will be appended to the existing array,
      * otherwise a new array will be created for the key.
      *
-     * @param key Key to add
-     * @param values Value(s) to add
+     * @param key Key to add.
+     * @param values Value(s) to add.
      */
     add(key, ...values) {
         let currentValues = super.get(key);

package/dist/utils/noop-modifier.js

@@ -1,5 +1,5 @@
 /*
- * AGTree v4.0.0 (build date: Wed, 21 Jan 2026 17:25:36 GMT)
+ * AGTree v4.0.2 (build date: Tue, 17 Mar 2026 23:34:38 GMT)
  * (c) 2026 Adguard Software Ltd.
  * Released under the MIT license
  * https://github.com/AdguardTeam/tsurlfilter/tree/master/packages/agtree#readme

package/dist/utils/position-provider.js

@@ -1,5 +1,5 @@
 /*
- * AGTree v4.0.0 (build date: Wed, 21 Jan 2026 17:25:36 GMT)
+ * AGTree v4.0.2 (build date: Tue, 17 Mar 2026 23:34:38 GMT)
  * (c) 2026 Adguard Software Ltd.
  * Released under the MIT license
  * https://github.com/AdguardTeam/tsurlfilter/tree/master/packages/agtree#readme
@@ -55,6 +55,7 @@ class PositionProvider {
      * Converts a character offset to a line and column position.
      *
      * @param offset The zero-based character offset in the source code.
+     *
      * @returns A Position object containing the 1-based line and column number, or null if the offset is out of range.
      */
     convertOffsetToPosition(offset) {

package/dist/utils/quotes.js

@@ -1,5 +1,5 @@
 /*
- * AGTree v4.0.0 (build date: Wed, 21 Jan 2026 17:25:36 GMT)
+ * AGTree v4.0.2 (build date: Tue, 17 Mar 2026 23:34:38 GMT)
  * (c) 2026 Adguard Software Ltd.
  * Released under the MIT license
  * https://github.com/AdguardTeam/tsurlfilter/tree/master/packages/agtree#readme
@@ -7,10 +7,10 @@
 import { ESCAPE_CHARACTER, EMPTY, SINGLE_QUOTE, DOUBLE_QUOTE, BACKTICK_QUOTE, COMMA, SPACE, OPEN_PARENTHESIS, CLOSE_PARENTHESIS, OPEN_SQUARE_BRACKET, CLOSE_SQUARE_BRACKET } from './constants.js';
 
 /**
- * @file Utility functions for working with quotes
+ * @file Utility functions for working with quotes.
  */
 /**
- * Set of all possible quote characters supported by the library
+ * Set of all possible quote characters supported by the library.
  */
 const QUOTE_SET = new Set([
     SINGLE_QUOTE,
@@ -18,36 +18,37 @@ const QUOTE_SET = new Set([
     BACKTICK_QUOTE,
 ]);
 /**
- * Possible quote types for scriptlet parameters
+ * Possible quote types for scriptlet parameters.
  */
 const QuoteType = {
     /**
-     * No quotes at all
+     * No quotes at all.
      */
     None: 'none',
     /**
-     * Single quotes (`'`)
+     * Single quotes (`'`).
      */
     Single: 'single',
     /**
-     * Double quotes (`"`)
+     * Double quotes (`"`).
      */
     Double: 'double',
     /**
-     * Backtick quotes (`` ` ``)
+     * Backtick quotes (`` ` ``).
      */
     Backtick: 'backtick',
 };
 /**
- * Utility functions for working with quotes
+ * Utility functions for working with quotes.
  */
 class QuoteUtils {
     /**
-     * Escape all unescaped occurrences of the character
+     * Escape all unescaped occurrences of the character.
      *
-     * @param string String to escape
-     * @param char Character to escape
-     * @returns Escaped string
+     * @param string String to escape.
+     * @param char Character to escape.
+     *
+     * @returns Escaped string.
      */
     static escapeUnescapedOccurrences(string, char) {
         let result = EMPTY;
@@ -60,11 +61,12 @@ class QuoteUtils {
         return result;
     }
     /**
-     * Unescape all single escaped occurrences of the character
+     * Unescape all single escaped occurrences of the character.
+     *
+     * @param string String to unescape.
+     * @param char Character to unescape.
      *
-     * @param string String to unescape
-     * @param char Character to unescape
-     * @returns Unescaped string
+     * @returns Unescaped string.
      */
     static unescapeSingleEscapedOccurrences(string, char) {
         let result = EMPTY;
@@ -79,10 +81,11 @@ class QuoteUtils {
         return result;
     }
     /**
-     * Get quote type of the string
+     * Get quote type of the string.
+     *
+     * @param string String to check.
      *
-     * @param string String to check
-     * @returns Quote type of the string
+     * @returns Quote type of the string.
      */
     static getStringQuoteType(string) {
         // Don't check 1-character strings to avoid false positives
@@ -100,11 +103,12 @@ class QuoteUtils {
         return QuoteType.None;
     }
     /**
-     * Set quote type of the string
+     * Set quote type of the string.
      *
-     * @param string String to set quote type of
-     * @param quoteType Quote type to set
-     * @returns String with the specified quote type
+     * @param string String to set quote type of.
+     * @param quoteType Quote type to set.
+     *
+     * @returns String with the specified quote type.
      */
     static setStringQuoteType(string, quoteType) {
         const actualQuoteType = QuoteUtils.getStringQuoteType(string);
@@ -159,10 +163,11 @@ class QuoteUtils {
         }
     }
     /**
-     * Removes bounding quotes from a string, if any
+     * Removes bounding quotes from a string, if any.
+     *
+     * @param string Input string.
      *
-     * @param string Input string
-     * @returns String without quotes
+     * @returns String without quotes.
      */
     static removeQuotes(string) {
         if (
@@ -178,8 +183,9 @@ class QuoteUtils {
      * Removes bounding quotes from a string, if any, and unescapes the escaped quotes,
      * like transforming `'abc\'def'` to `abc'def`.
      *
-     * @param string Input string
-     * @returns String without quotes
+     * @param string Input string.
+     *
+     * @returns String without quotes.
      */
     static removeQuotesAndUnescape(string) {
         const quoteType = QuoteUtils.getStringQuoteType(string);
@@ -216,22 +222,22 @@ class QuoteUtils {
      * Convert `""` to `\"` within strings inside of attribute selectors,
      * because it is not compatible with the standard CSS syntax.
      *
+     * @see {@link https://kb.adguard.com/en/general/how-to-create-your-own-ad-filters#tag-content}
+     * @see {@link https://kb.adguard.com/en/general/how-to-create-your-own-ad-filters#wildcard}
+     *
      * @param selector CSS selector string.
      *
      * @returns Escaped CSS selector.
      *
-     * @note In the legacy syntax, `""` is used to escape double quotes, but it cannot be used
-     * in the standard CSS syntax, so we use conversion functions to handle this.
-     * @note This function is intended to be used on whole attribute selector or whole selector strings.
-     *
-     * @see {@link https://kb.adguard.com/en/general/how-to-create-your-own-ad-filters#tag-content}
-     * @see {@link https://kb.adguard.com/en/general/how-to-create-your-own-ad-filters#wildcard}
-     *
      * @example
      * ```ts
      * QuoteUtils.escapeAttributeDoubleQuotes('[attr="value with "" quotes"]');
      * QuoteUtils.escapeAttributeDoubleQuotes('div[attr="value with "" quotes"] > span');
      * ```
+     *
+     * @note In the legacy syntax, `""` is used to escape double quotes, but it cannot be used
+     * in the standard CSS syntax, so we use conversion functions to handle this.
+     * @note This function is intended to be used on whole attribute selector or whole selector strings.
      */
     static escapeAttributeDoubleQuotes(selector) {
         const nestingBlockPairs = new Map([
@@ -291,22 +297,22 @@ class QuoteUtils {
      * Convert escaped double quotes `\"` to `""` within strings inside of attribute selectors,
      * because it is not compatible with the standard CSS syntax.
      *
+     * @see {@link https://kb.adguard.com/en/general/how-to-create-your-own-ad-filters#tag-content}
+     * @see {@link https://kb.adguard.com/en/general/how-to-create-your-own-ad-filters#wildcard}
+     *
      * @param selector CSS selector string.
      *
      * @returns Unescaped CSS selector.
      *
-     * @note In the legacy syntax, `""` is used to escape double quotes, but it cannot be used
-     * in the standard CSS syntax, so we use conversion functions to handle this.
-     * @note This function is intended to be used on whole attribute selector or whole selector strings.
-     *
-     * @see {@link https://kb.adguard.com/en/general/how-to-create-your-own-ad-filters#tag-content}
-     * @see {@link https://kb.adguard.com/en/general/how-to-create-your-own-ad-filters#wildcard}
-     *
      * @example
      * ```ts
      * QuoteUtils.unescapeAttributeDoubleQuotes('[attr="value with \\" quotes"]');
      * QuoteUtils.unescapeAttributeDoubleQuotes('div[attr="value with \\" quotes"] > span');
      * ```
+     *
+     * @note In the legacy syntax, `""` is used to escape double quotes, but it cannot be used
+     * in the standard CSS syntax, so we use conversion functions to handle this.
+     * @note This function is intended to be used on whole attribute selector or whole selector strings.
      */
     static unescapeAttributeDoubleQuotes(selector) {
         const nestingBlockPairs = new Map([

package/dist/utils/regexp.js

@@ -1,5 +1,5 @@
 /*
- * AGTree v4.0.0 (build date: Wed, 21 Jan 2026 17:25:36 GMT)
+ * AGTree v4.0.2 (build date: Tue, 17 Mar 2026 23:34:38 GMT)
  * (c) 2026 Adguard Software Ltd.
  * Released under the MIT license
  * https://github.com/AdguardTeam/tsurlfilter/tree/master/packages/agtree#readme
@@ -8,7 +8,7 @@ import GlobToRegExp from 'glob-to-regexp';
 import { CARET, ASTERISK, PIPE, DOT, CLOSE_CURLY_BRACKET, CLOSE_PARENTHESIS, CLOSE_SQUARE_BRACKET, DOLLAR_SIGN, ESCAPE_CHARACTER, OPEN_CURLY_BRACKET, OPEN_PARENTHESIS, OPEN_SQUARE_BRACKET, PLUS, QUESTION_MARK, SLASH, REGEX_MARKER, EMPTY } from './constants.js';
 
 /**
- * @file Regular expression utilities
+ * @file Regular expression utilities.
  */
 // Special RegExp constants
 const REGEX_START = CARET; // '^'
@@ -25,7 +25,7 @@ const ADBLOCK_WILDCARD_REGEX = REGEX_ANY_CHARACTERS;
 const REGEX_NEGATION_PREFIX = '^((?!';
 const REGEX_NEGATION_SUFFIX = ').)*$';
 /**
- * Special RegExp symbols
+ * Special RegExp symbols.
  *
  * @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions#special-escape
  */
@@ -47,7 +47,7 @@ const SPECIAL_REGEX_SYMBOLS = new Set([
     SLASH,
 ]);
 /**
- * Utility functions for working with RegExp patterns
+ * Utility functions for working with RegExp patterns.
  */
 class RegExpUtils {
     /**
@@ -57,8 +57,9 @@ class RegExpUtils {
      * Note: it does not perform a full validation of the pattern,
      * it just checks if the string starts and ends with a slash.
      *
-     * @param pattern - Pattern to check
-     * @returns `true` if the string is a RegExp pattern, `false` otherwise
+     * @param pattern Pattern to check.
+     *
+     * @returns `true` if the string is a RegExp pattern, `false` otherwise.
      */
     static isRegexPattern(pattern) {
         const trimmedPattern = pattern.trim();
@@ -71,8 +72,9 @@ class RegExpUtils {
     /**
      * Checks whether a string is a negated RegExp pattern.
      *
-     * @param pattern - Pattern to check
-     * @returns `true` if the string is a negated RegExp pattern, `false` otherwise
+     * @param pattern Pattern to check.
+     *
+     * @returns `true` if the string is a negated RegExp pattern, `false` otherwise.
      */
     static isNegatedRegexPattern(pattern) {
         if (pattern.startsWith(REGEX_MARKER) && pattern.endsWith(REGEX_MARKER)) {
@@ -84,8 +86,9 @@ class RegExpUtils {
     /**
      * Removes negation from a RegExp pattern.
      *
-     * @param pattern - RegExp pattern to remove negation from
-     * @returns RegExp pattern without negation
+     * @param pattern RegExp pattern to remove negation from.
+     *
+     * @returns RegExp pattern without negation.
      */
     static removeNegationFromRegexPattern(pattern) {
         let result = pattern.trim();
@@ -103,8 +106,9 @@ class RegExpUtils {
      *
      * RegExp modifiers are not supported.
      *
-     * @param pattern Pattern to negate (can be wrapped in slashes or not)
-     * @returns Negated RegExp pattern
+     * @param pattern Pattern to negate (can be wrapped in slashes or not).
+     *
+     * @returns Negated RegExp pattern.
      */
     static negateRegexPattern(pattern) {
         let result = pattern.trim();
@@ -136,8 +140,9 @@ class RegExpUtils {
     /**
      * Ensures that a pattern is wrapped in slashes.
      *
-     * @param pattern Pattern to ensure slashes for
-     * @returns Pattern with slashes
+     * @param pattern Pattern to ensure slashes for.
+     *
+     * @returns Pattern with slashes.
      */
     static ensureSlashes(pattern) {
         let result = pattern;
@@ -151,11 +156,13 @@ class RegExpUtils {
     }
     /**
      * Converts a basic adblock rule pattern to a RegExp pattern. Based on
-     * https://github.com/AdguardTeam/tsurlfilter/blob/9b26e0b4a0e30b87690bc60f7cf377d112c3085c/packages/tsurlfilter/src/rules/simple-regex.ts#L219
+     * https://github.com/AdguardTeam/tsurlfilter/blob/9b26e0b4a0e30b87690bc60f7cf377d112c3085c/packages/tsurlfilter/src/rules/simple-regex.ts#L219.
      *
-     * @param pattern Pattern to convert
-     * @returns RegExp equivalent of the pattern
      * @see {@link https://kb.adguard.com/en/general/how-to-create-your-own-ad-filters#basic-rules}
+     *
+     * @param pattern Pattern to convert.
+     *
+     * @returns RegExp equivalent of the pattern.
      */
     static patternToRegexp(pattern) {
         const trimmed = pattern.trim();
@@ -222,7 +229,7 @@ class RegExpUtils {
      * Creates a length-matching regular expression string: /^(?=.{min,max}$).*\/s
      * Where:
      * - (?=.{min,max}$) is a lookahead that ensures the string length is between min and max
-     * - .* matches any character (including newlines, due to the 's' flag)
+     * - .* matches any character (including newlines, due to the 's' flag).
      *
      * @param min Minimum length or `null` for no minimum (default to `0`).
      * @param max Maximum length or `null` for no maximum (default to no maximum).