@adguard/agtree 4.0.0 → 4.0.2

package/dist/types/parser/misc/ubo-parameter-list-parser.d.ts

@@ -1,5 +1,5 @@
-import { ParameterListParser } from './parameter-list-parser.js';
 import { type ParameterList } from '../../nodes/index.js';
+import { ParameterListParser } from './parameter-list-parser.js';
 /**
  * Parser for uBO-specific parameter lists.
  */
@@ -13,6 +13,7 @@ export declare class UboParameterListParser extends ParameterListParser {
      * @param separator Separator character (default: comma).
      * @param requireQuotes Whether to require quotes around the parameter values (default: false).
      * @param supportedQuotes Set of accepted quotes (default: {@link QUOTE_SET}).
+     *
      * @returns Parameter list node.
      *
      * @note Based on {@link https://github.com/gorhill/uBlock/blob/f9ab4b75041815e6e5690d80851189ae3dc660d0/src/js/static-filtering-parser.js#L607-L699} to provide consistency.

package/dist/types/parser/misc/value-parser.d.ts

@@ -1,5 +1,5 @@
-import { BaseParser } from '../base-parser.js';
 import { type Value } from '../../nodes/index.js';
+import { BaseParser } from '../base-parser.js';
 /**
  * Value parser.
  * This parser is very simple, it just exists to provide a consistent interface for parsing.

package/dist/types/parser/network/host-rule-parser.d.ts

@@ -6,20 +6,27 @@ import { BaseParser } from '../base-parser.js';
  * HostRule is a structure for simple host-level rules (i.e. /etc/hosts syntax).
  * It also supports "just domain" syntax. In this case, the IP will be set to 0.0.0.0.
  *
- * Rules syntax looks like this:
+ * Rules syntax looks like this:.
  * ```text
  * IP_address canonical_hostname [aliases...]
  * ```
  *
+ * @see {@link http://man7.org/linux/man-pages/man5/hosts.5.html}
+ *
  * @example
  * `192.168.1.13 bar.mydomain.org bar` -- ipv4
  * `ff02::1 ip6-allnodes` -- ipv6
  * `::1 localhost ip6-localhost ip6-loopback` -- ipv6 aliases
  * `example.org` -- "just domain" syntax
- * @see {@link http://man7.org/linux/man-pages/man5/hosts.5.html}
  */
 export declare class HostRuleParser extends BaseParser {
+    /**
+     * Default IP address for host rules without explicit IP.
+     */
     static readonly NULL_IP = "0.0.0.0";
+    /**
+     * Comment marker character.
+     */
     static readonly COMMENT_MARKER = "#";
     /**
      * Parses an etc/hosts-like rule.
@@ -27,6 +34,7 @@ export declare class HostRuleParser extends BaseParser {
      * @param raw Raw input to parse.
      * @param options Global parser options.
      * @param baseOffset Starting offset of the input. Node locations are calculated relative to this offset.
+     *
      * @returns Host rule node.
      *
      * @throws If the input contains invalid data.

package/dist/types/parser/network/network-rule-parser.d.ts

@@ -16,7 +16,8 @@ export declare class NetworkRuleParser extends BaseParser {
      * @param raw Raw input to parse.
      * @param options Global parser options.
      * @param baseOffset Starting offset of the input. Node locations are calculated relative to this offset.
-     * @returns Network rule AST
+     *
+     * @returns Network rule AST.
      *
      * @throws If the rule is syntactically incorrect.
      */
@@ -24,8 +25,9 @@ export declare class NetworkRuleParser extends BaseParser {
     /**
      * Finds the index of the separator character in a network rule.
      *
-     * @param rule Network rule to check
-     * @returns The index of the separator character, or -1 if there is no separator
+     * @param rule Network rule to check.
+     *
+     * @returns The index of the separator character, or -1 if there is no separator.
      */
     static findNetworkRuleSeparatorIndex(rule: string): number;
 }

package/dist/types/parser/options.d.ts

@@ -4,7 +4,7 @@
 /**
  * Callback function type for handling parse errors in tolerant mode.
  *
- * @param error The error that occurred during parsing
+ * @param error The error that occurred during parsing.
  */
 export type OnParseError = (error: unknown) => void;
 /**

package/dist/types/parser/rule-parser.d.ts

@@ -13,6 +13,7 @@ export declare class RuleParser extends BaseParser {
      * @param raw Raw input to parse.
      * @param options Global parser options.
      * @param baseOffset Starting offset of the input. Node locations are calculated relative to this offset.
+     *
      * @returns Host rule or network rule node.
      */
     private static parseHostOrNetworkRule;
@@ -44,8 +45,11 @@ export declare class RuleParser extends BaseParser {
      * @param raw Raw input to parse.
      * @param options Global parser options.
      * @param baseOffset Starting offset of the input. Node locations are calculated relative to this offset.
-     * @returns Adblock rule node
-     * @throws If the input matches a pattern but syntactically invalid
+     *
+     * @returns Adblock rule node.
+     *
+     * @throws If the input matches a pattern but syntactically invalid.
+     *
      * @example
      * Take a look at the following example:
      * ```js

package/dist/types/tokenizer/tokenizer.d.ts

@@ -11,7 +11,7 @@ export declare const enum TokenType {
      */
     Whitespace = 1,
     /**
-     * Line break (`\r\n` or just `\n`)
+     * Line break (`\r\n` or just `\n`).
      */
     LineBreak = 2,
     /**
@@ -33,7 +33,7 @@ export declare const enum TokenType {
     AllowlistCosmeticSeparator = 6,
     /**
      * Raw content after cosmetic rule separator.
-     * For example, no need to tokenize CSS with this tokenizer after the `##`, `#?#`, etc. separators,
+     * For example, no need to tokenize CSS with this tokenizer after the `##`, `#?#`, etc. Separators,
      * so we use this token type as an optimization strategy.
      */
     RawContent = 7,

package/dist/types/utils/adblockers.d.ts

@@ -12,7 +12,7 @@ export declare const AdblockProduct: {
      */
     readonly Abp: "AdblockPlus";
     /**
-     * uBlock Origin.
+     * UBlock Origin..
      *
      * @see {@link https://github.com/gorhill/uBlock}
      */
@@ -26,7 +26,7 @@ export declare const AdblockProduct: {
 };
 export type AdblockProduct = typeof AdblockProduct[keyof typeof AdblockProduct];
 /**
- * Possible adblock syntaxes (supported by this library)
+ * Possible adblock syntaxes (supported by this library).
  */
 export declare const AdblockSyntax: {
     /**
@@ -44,29 +44,32 @@ export declare const AdblockSyntax: {
     /**
      * Adblock Plus syntax.
      *
+     * @see {@link https://adblockplus.org/}
+     *
      * @example
      * - `example.org#$#abort-on-property-read alert` is an Adblock Plus syntax, since it is not used by any other
      * adblockers directly (probably supported by some on-the-fly conversion, but this is not the native syntax).
-     * @see {@link https://adblockplus.org/}
      */
     readonly Abp: "AdblockPlus";
     /**
-     * uBlock Origin syntax.
+     * UBlock Origin syntax..
+     *
+     * @see {@link https://github.com/gorhill/uBlock}
      *
      * @example
      * - `example.com##+js(set, atob, noopFunc)` is an uBlock Origin syntax, since it is not used by any other
      * adblockers directly (probably supported by some on-the-fly conversion, but this is not the native syntax).
-     * @see {@link https://github.com/gorhill/uBlock}
      */
     readonly Ubo: "UblockOrigin";
     /**
      * AdGuard syntax.
      *
+     * @see {@link https://adguard.com/}
+     *
      * @example
      * - `example.org#%#//scriptlet("abort-on-property-read", "alert")` is an AdGuard syntax, since it is not used
      * by any other adblockers directly (probably supported by some on-the-fly conversion, but this is not the native
      * syntax).
-     * @see {@link https://adguard.com/}
      */
     readonly Adg: "AdGuard";
 };

package/dist/types/utils/clone.d.ts

@@ -1,5 +1,5 @@
 /**
- * @file Clone related utilities
+ * @file Clone related utilities.
  *
  * We should keep clone related functions in this file. Thus, we just provide
  * a simple interface for cloning values, we use it across the AGTree project,
@@ -9,7 +9,8 @@
  * Clones an input value to avoid side effects. Use it only in justified cases,
  * because it can impact performance negatively.
  *
- * @param value Value to clone
- * @returns Cloned value
+ * @param value Value to clone.
+ *
+ * @returns Cloned value.
  */
 export declare function clone<T>(value: T): T;

package/dist/types/utils/constants.d.ts

@@ -1,5 +1,5 @@
 /**
- * @file Constant values used by all parts of the library
+ * @file Constant values used by all parts of the library.
  */
 /**
  * Empty string.

package/dist/types/utils/cosmetic-rule-separator.d.ts

@@ -1,18 +1,18 @@
 /**
- * @file Cosmetic rule separator finder and categorizer
+ * @file Cosmetic rule separator finder and categorizer.
  */
 import { CosmeticRuleSeparator } from '../nodes/index.js';
 export interface CosmeticRuleSeparatorFinderResult {
     /**
-     * Separator type
+     * Separator type.
      */
     separator: CosmeticRuleSeparator;
     /**
-     * Separator start position
+     * Separator start position.
      */
     start: number;
     /**
-     * Separator end position
+     * Separator end position.
      */
     end: number;
 }
@@ -23,23 +23,26 @@ export declare class CosmeticRuleSeparatorUtils {
     /**
      * Checks whether the specified separator is an exception.
      *
-     * @param separator Separator to check
-     * @returns `true` if the separator is an exception, `false` otherwise
+     * @param separator Separator to check.
+     *
+     * @returns `true` if the separator is an exception, `false` otherwise.
      */
     static isException(separator: CosmeticRuleSeparator): boolean;
     /**
      * Checks whether the specified separator is marks an Extended CSS cosmetic rule.
      *
-     * @param separator Separator to check
-     * @returns `true` if the separator is marks an Extended CSS cosmetic rule, `false` otherwise
+     * @param separator Separator to check.
+     *
+     * @returns `true` if the separator is marks an Extended CSS cosmetic rule, `false` otherwise.
      */
     static isExtendedCssMarker(separator: CosmeticRuleSeparator): boolean;
     /**
      * Looks for the cosmetic rule separator in the rule. This is a simplified version that
      * masks the recursive function.
      *
-     * @param rule Raw rule
-     * @returns Separator result or null if no separator was found
+     * @param rule Raw rule.
+     *
+     * @returns Separator result or null if no separator was found.
      */
     static find(rule: string): CosmeticRuleSeparatorFinderResult | null;
 }

package/dist/types/utils/deep-freeze.d.ts

@@ -2,12 +2,12 @@
  * 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.
  */
 export declare const deepFreeze: <T extends object>(object: T) => Readonly<T>;

package/dist/types/utils/domain.d.ts

@@ -22,8 +22,9 @@ export declare 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: string): boolean;
 }

package/dist/types/utils/logical-expression.d.ts

@@ -15,8 +15,10 @@ export declare 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`.
@@ -26,9 +28,11 @@ export declare 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/types/utils/multi-value-map.d.ts

@@ -2,15 +2,15 @@
  * 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.
  */
 export declare class MultiValueMap<K, V> extends Map<K, V[]> {
     /**
      * 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: K, ...values: V[]): void;
 }

package/dist/types/utils/position-provider.d.ts

@@ -6,11 +6,11 @@
  */
 export interface Position {
     /**
-     * 1-based line number
+     * 1-based line number.
      */
     line: number;
     /**
-     * 1-based column number
+     * 1-based column number.
      */
     column: number;
 }
@@ -40,6 +40,7 @@ export declare 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: number): Position | null;

package/dist/types/utils/quotes.d.ts

@@ -1,80 +1,86 @@
 /**
- * @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.
  */
 export declare const QUOTE_SET: Set<string>;
 /**
- * Possible quote types for scriptlet parameters
+ * Possible quote types for scriptlet parameters.
  */
 export declare const QuoteType: {
     /**
-     * No quotes at all
+     * No quotes at all.
      */
     readonly None: "none";
     /**
-     * Single quotes (`'`)
+     * Single quotes (`'`).
      */
     readonly Single: "single";
     /**
-     * Double quotes (`"`)
+     * Double quotes (`"`).
      */
     readonly Double: "double";
     /**
-     * Backtick quotes (`` ` ``)
+     * Backtick quotes (`` ` ``).
      */
     readonly Backtick: "backtick";
 };
 export type QuoteType = typeof QuoteType[keyof typeof QuoteType];
 /**
- * Utility functions for working with quotes
+ * Utility functions for working with quotes.
  */
 export declare 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: string, char: string): string;
     /**
-     * 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: string, char: string): string;
     /**
-     * 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: string): QuoteType;
     /**
-     * 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: string, quoteType: QuoteType): string;
     /**
-     * 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: string): string;
     /**
      * 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: string): string;
     /**
@@ -95,44 +101,44 @@ export declare 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: string): string;
     /**
      * 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: string): string;
 }

package/dist/types/utils/regexp.d.ts

@@ -1,5 +1,5 @@
 /**
- * @file Regular expression utilities
+ * @file Regular expression utilities.
  */
 export declare const REGEX_START = "^";
 export declare const REGEX_END = "$";
@@ -13,13 +13,13 @@ export declare const ADBLOCK_WILDCARD_REGEX: string;
 export declare const REGEX_NEGATION_PREFIX = "^((?!";
 export declare 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
  */
 export declare const SPECIAL_REGEX_SYMBOLS: Set<string>;
 /**
- * Utility functions for working with RegExp patterns
+ * Utility functions for working with RegExp patterns.
  */
 export declare class RegExpUtils {
     /**
@@ -29,22 +29,25 @@ export declare 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: string): boolean;
     /**
      * 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: string): boolean;
     /**
      * 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: string): string;
     /**
@@ -52,31 +55,35 @@ export declare 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: string): string;
     /**
      * 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: string): string;
     /**
      * 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: string): string;
     /**
      * 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).