@adguard/agtree 1.1.5 → 1.1.7

package/dist/agtree.d.ts

@@ -1,10 +1,10 @@
 /*
- * AGTree v1.1.5 (build date: Tue, 05 Sep 2023 15:10:53 GMT)
+ * AGTree v1.1.7 (build date: Tue, 07 Nov 2023 14:17:46 GMT)
  * (c) 2023 AdGuard Software Ltd.
  * Released under the MIT license
  * https://github.com/AdguardTeam/tsurlfilter/tree/master/packages/agtree#readme
  */
-import { MediaQueryListPlain, SelectorListPlain, DeclarationListPlain, FunctionNodePlain, CssNode, CssNodePlain, SelectorList, DeclarationList, MediaQueryList, MediaQuery, Selector, AttributeSelector, PseudoClassSelectorPlain, PseudoClassSelector, FunctionNode } from '@adguard/ecss-tree';
+import { MediaQueryListPlain, SelectorListPlain, DeclarationListPlain, FunctionNodePlain, CssNode, CssNodePlain, SelectorList, DeclarationList, MediaQueryList, MediaQuery, Selector, SelectorPlain, AttributeSelector, PseudoClassSelectorPlain, PseudoClassSelector, FunctionNode } from '@adguard/ecss-tree';
 import * as ecssTree from '@adguard/ecss-tree';
 export { ecssTree as ECSSTree };
 
@@ -2066,12 +2066,38 @@ declare class ModifierValidator {
 }
 declare const modifierValidator: ModifierValidator;
 
+/**
+ * @file Conversion result interface and helper functions
+ */
+
+/**
+ * Common conversion result interface
+ *
+ * @template T Type of the item to convert
+ * @template U Type of the conversion result (defaults to `T`, but can be `T[]` as well)
+ */
+interface ConversionResult<T, U extends T | T[] = T> {
+    /**
+     * Conversion result
+     */
+    result: U;
+    /**
+     * Indicates whether the input item was converted
+     */
+    isConverted: boolean;
+}
+/**
+ * Adblock rule node conversion result interface, where the conversion result is an array of rules
+ */
+type NodeConversionResult<T extends Node> = ConversionResult<T, T[]>;
+
 /**
  * @file Base class for converters
  *
  * TS doesn't support abstract static methods, so we should use
  * a workaround and extend this class instead of implementing it
  */
+
 /**
  * Basic class for rule converters
  */
@@ -2080,26 +2106,121 @@ declare class ConverterBase {
      * Converts some data to AdGuard format
      *
      * @param data Data to convert
-     * @returns Converted data
+     * @returns An object which follows the {@link ConversionResult} interface. Its `result` property contains
+     * the converted node, and its `isConverted` flag indicates whether the original node was converted.
+     * If the node was not converted, the result will contain the original node with the same object reference
      * @throws If the data is invalid or incompatible
      */
-    static convertToAdg(data: unknown): unknown;
+    static convertToAdg(data: unknown): ConversionResult<unknown>;
     /**
      * Converts some data to Adblock Plus format
      *
      * @param data Data to convert
-     * @returns Converted data
+     * @returns An object which follows the {@link ConversionResult} interface. Its `result` property contains
+     * the converted node, and its `isConverted` flag indicates whether the original node was converted.
+     * If the node was not converted, the result will contain the original node with the same object reference
      * @throws If the data is invalid or incompatible
      */
-    static convertToAbp(data: unknown): unknown;
+    static convertToAbp(data: unknown): ConversionResult<unknown>;
     /**
      * Converts some data to uBlock Origin format
      *
      * @param data Data to convert
-     * @returns Converted data
+     * @returns An object which follows the {@link ConversionResult} interface. Its `result` property contains
+     * the converted node, and its `isConverted` flag indicates whether the original node was converted.
+     * If the node was not converted, the result will contain the original node with the same object reference
      * @throws If the data is invalid or incompatible
      */
-    static convertToUbo(data: unknown): unknown;
+    static convertToUbo(data: unknown): ConversionResult<unknown>;
+}
+
+/**
+ * @file Adblock filter list converter
+ */
+
+/**
+ * Adblock filter list converter class
+ *
+ * This class just provides an extra layer on top of the {@link RuleConverter}
+ * and can be used to convert entire filter lists.
+ *
+ * @todo Implement `convertToUbo` and `convertToAbp`
+ * @todo Implement tolerant mode, which will allow to convert a filter list
+ * even if some of its rules are invalid
+ */
+declare class FilterListConverter extends ConverterBase {
+    /**
+     * Converts an adblock filter list to AdGuard format, if possible.
+     *
+     * @param filterListNode Filter list node to convert
+     * @param tolerant Indicates whether the converter should be tolerant to invalid rules. If enabled and a rule is
+     * invalid, it will be left as is. If disabled and a rule is invalid, the whole filter list will be failed.
+     * Defaults to `true`.
+     * @returns An object which follows the {@link ConversionResult} interface. Its `result` property contains
+     * the converted node, and its `isConverted` flag indicates whether the original node was converted.
+     * If the node was not converted, the result will contain the original node with the same object reference
+     * @throws If the filter list is invalid or cannot be converted (if the tolerant mode is disabled)
+     */
+    static convertToAdg(filterListNode: FilterList, tolerant?: boolean): ConversionResult<FilterList>;
+}
+
+/**
+ * @file Filter list converter for raw filter lists
+ *
+ * Technically, this is a wrapper around `FilterListConverter` that works with nodes instead of strings.
+ */
+
+/**
+ * Adblock filter list converter class.
+ *
+ * You can use this class to convert string-based filter lists, since most of the converters work with nodes.
+ * This class just provides an extra layer on top of the {@link FilterListConverter} and calls the parser/serializer
+ * before/after the conversion internally.
+ *
+ * @todo Implement `convertToUbo` and `convertToAbp`
+ */
+declare class RawFilterListConverter extends ConverterBase {
+    /**
+     * Converts an adblock filter list text to AdGuard format, if possible.
+     *
+     * @param rawFilterList Raw filter list text to convert
+     * @param tolerant Indicates whether the converter should be tolerant to invalid rules. If enabled and a rule is
+     * invalid, it will be left as is. If disabled and a rule is invalid, the whole filter list will be failed.
+     * Defaults to `true`.
+     * @returns An object which follows the {@link ConversionResult} interface. Its `result` property contains
+     * the array of converted filter list text, and its `isConverted` flag indicates whether the original rule was
+     * converted. If the rule was not converted, the original filter list text will be returned
+     * @throws If the filter list is invalid or cannot be converted (if the tolerant mode is disabled)
+     */
+    static convertToAdg(rawFilterList: string, tolerant?: boolean): ConversionResult<string>;
+}
+
+/**
+ * @file Rule converter for raw rules
+ *
+ * Technically, this is a wrapper around `RuleConverter` that works with nodes instead of strings.
+ */
+
+/**
+ * Adblock filtering rule converter class.
+ *
+ * You can use this class to convert string-based adblock rules, since most of the converters work with nodes.
+ * This class just provides an extra layer on top of the {@link RuleConverter} and calls the parser/serializer
+ * before/after the conversion internally.
+ *
+ * @todo Implement `convertToUbo` and `convertToAbp`
+ */
+declare class RawRuleConverter extends ConverterBase {
+    /**
+     * Converts an adblock filtering rule to AdGuard format, if possible.
+     *
+     * @param rawRule Raw rule text to convert
+     * @returns An object which follows the {@link ConversionResult} interface. Its `result` property contains
+     * the array of converted rule texts, and its `isConverted` flag indicates whether the original rule was converted.
+     * If the rule was not converted, the original rule text will be returned
+     * @throws If the rule is invalid or cannot be converted
+     */
+    static convertToAdg(rawRule: string): ConversionResult<string, string[]>;
 }
 
 /**
@@ -2117,26 +2238,32 @@ declare class RuleConverterBase extends ConverterBase {
      * Converts an adblock filtering rule to AdGuard format, if possible.
      *
      * @param rule Rule node to convert
-     * @returns Array of converted rule nodes
+     * @returns An object which follows the {@link NodeConversionResult} interface. Its `result` property contains
+     * the array of converted rule nodes, and its `isConverted` flag indicates whether the original rule was converted.
+     * If the rule was not converted, the result array will contain the original node with the same object reference
      * @throws If the rule is invalid or cannot be converted
      */
-    static convertToAdg(rule: Node): Node[];
+    static convertToAdg(rule: Node): NodeConversionResult<Node>;
     /**
      * Converts an adblock filtering rule to Adblock Plus format, if possible.
      *
      * @param rule Rule node to convert
-     * @returns Array of converted rule nodes
+     * @returns An object which follows the {@link NodeConversionResult} interface. Its `result` property contains
+     * the array of converted rule nodes, and its `isConverted` flag indicates whether the original rule was converted.
+     * If the rule was not converted, the result array will contain the original node with the same object reference
      * @throws If the rule is invalid or cannot be converted
      */
-    static convertToAbp(rule: Node): Node[];
+    static convertToAbp(rule: Node): NodeConversionResult<Node>;
     /**
      * Converts an adblock filtering rule to uBlock Origin format, if possible.
      *
      * @param rule Rule node to convert
-     * @returns Array of converted rule nodes
+     * @returns An object which follows the {@link NodeConversionResult} interface. Its `result` property contains
+     * the array of converted rule nodes, and its `isConverted` flag indicates whether the original rule was converted.
+     * If the rule was not converted, the result array will contain the original node with the same object reference
      * @throws If the rule is invalid or cannot be converted
      */
-    static convertToUbo(rule: Node): Node[];
+    static convertToUbo(rule: Node): NodeConversionResult<Node>;
 }
 
 /**
@@ -2157,35 +2284,12 @@ declare class RuleConverter extends RuleConverterBase {
      * Converts an adblock filtering rule to AdGuard format, if possible.
      *
      * @param rule Rule node to convert
-     * @returns Array of converted rule nodes
+     * @returns An object which follows the {@link NodeConversionResult} interface. Its `result` property contains
+     * the array of converted rule nodes, and its `isConverted` flag indicates whether the original rule was converted.
+     * If the rule was not converted, the result array will contain the original node with the same object reference
      * @throws If the rule is invalid or cannot be converted
      */
-    static convertToAdg(rule: AnyRule): AnyRule[];
-}
-
-/**
- * @file Adblock filter list converter
- */
-
-/**
- * Adblock filter list converter class
- *
- * This class just provides an extra layer on top of the {@link RuleConverter}
- * and can be used to convert entire filter lists.
- *
- * @todo Implement `convertToUbo` and `convertToAbp`
- * @todo Implement tolerant mode, which will allow to convert a filter list
- * even if some of its rules are invalid
- */
-declare class FilterListConverter extends ConverterBase {
-    /**
-     * Converts an adblock filter list to AdGuard format, if possible.
-     *
-     * @param filterListNode Filter list node to convert
-     * @returns Converted filter list node
-     * @throws If the filter list is invalid or cannot be converted
-     */
-    static convertToAdg(filterListNode: FilterList): FilterList;
+    static convertToAdg(rule: AnyRule): NodeConversionResult<AnyRule>;
 }
 
 /**
@@ -2473,6 +2577,21 @@ declare class CssTree {
      * @returns CSS selector as string
      */
     static generateSelector(ast: Selector): string;
+    /**
+     * Generates string representation of the selector list.
+     *
+     * @param ast SelectorList AST
+     * @returns String representation of the selector list
+     */
+    static generateSelectorListPlain(ast: SelectorListPlain): string;
+    /**
+     * Selector generation based on CSSTree's AST. This is necessary because CSSTree
+     * only adds spaces in some edge cases.
+     *
+     * @param ast CSS Tree AST
+     * @returns CSS selector as string
+     */
+    static generateSelectorPlain(ast: SelectorPlain): string;
     /**
      * Block generation based on CSSTree's AST. This is necessary because CSSTree only adds spaces in some edge cases.
      *
@@ -2550,6 +2669,14 @@ declare class CssTree {
      * @example `responseheader(name)` -> `name`
      */
     static generateFunctionValue(node: FunctionNode): string;
+    /**
+     * Helper function to generate a raw string from a function selector's children
+     *
+     * @param node Function node
+     * @returns Generated function value
+     * @example `responseheader(name)` -> `name`
+     */
+    static generateFunctionPlainValue(node: FunctionNodePlain): string;
 }
 
 declare class DomainUtils {
@@ -2783,4 +2910,4 @@ declare const FORBIDDEN_CSS_FUNCTIONS: Set<string>;
  */
 declare const version: string;
 
-export { ADBLOCK_URL_SEPARATOR, ADBLOCK_URL_SEPARATOR_REGEX, ADBLOCK_URL_START, ADBLOCK_URL_START_REGEX, ADBLOCK_WILDCARD, ADBLOCK_WILDCARD_REGEX, ADG_SCRIPTLET_MASK, AGLINT_COMMAND_PREFIX, AdblockSyntax, AdblockSyntaxError, Agent, AgentCommentRule, AgentCommentRuleParser, AgentParser, AnyCommentRule, AnyCosmeticRule, AnyExpressionNode, AnyOperator, AnyRule, AppListParser, COMMA_DOMAIN_LIST_SEPARATOR, CommentBase, CommentMarker, CommentRule, CommentRuleParser, CommentRuleType, ConfigCommentRule, ConfigCommentRuleParser, CosmeticRule, CosmeticRuleParser, CosmeticRuleSeparator, CosmeticRuleSeparatorFinderResult, CosmeticRuleSeparatorUtils, CosmeticRuleType, CssInjectionRule, CssInjectionRuleBody, CssTree, CssTreeNodeType, CssTreeParserContext, Domain, DomainList, DomainListParser, DomainListSeparator, DomainUtils, EXT_CSS_LEGACY_ATTRIBUTES, EXT_CSS_PSEUDO_CLASSES, ElementHidingRule, ElementHidingRuleBody, EmptyRule, ExpressionOperatorNode, ExpressionParenthesisNode, ExpressionVariableNode, FORBIDDEN_CSS_FUNCTIONS, FilterList, FilterListConverter, FilterListParser, HINT_MARKER, Hint, HintCommentRule, HintCommentRuleParser, HintParser, HtmlFilteringRule, HtmlFilteringRuleBody, IF, INCLUDE, JsInjectionRule, Location, LocationRange, LogicalExpressionParser, LogicalExpressionUtils, METADATA_HEADERS, MODIFIERS_SEPARATOR, MODIFIER_ASSIGN_OPERATOR, MetadataCommentRule, MetadataCommentRuleParser, MethodListParser, Modifier, ModifierList, ModifierListParser, ModifierParser, NEGATION_MARKER, NETWORK_RULE_EXCEPTION_MARKER, NETWORK_RULE_SEPARATOR, NetworkRule, NetworkRuleParser, Node, NotImplementedError, PIPE_MODIFIER_SEPARATOR, PREPROCESSOR_MARKER, Parameter, ParameterList, ParameterListParser, PreProcessorCommentRule, PreProcessorCommentRuleParser, QuoteType, QuoteUtils, RegExpUtils, RuleBase, RuleCategory, RuleConversionError, RuleConverter, RuleParser, SAFARI_CB_AFFINITY, SPECIAL_REGEX_SYMBOLS, ScriptletInjectionRule, ScriptletInjectionRuleBody, StealthOptionListParser, UBO_SCRIPTLET_MASK, Value, VariableTable, locRange, modifierValidator, shiftLoc, version };
+export { ADBLOCK_URL_SEPARATOR, ADBLOCK_URL_SEPARATOR_REGEX, ADBLOCK_URL_START, ADBLOCK_URL_START_REGEX, ADBLOCK_WILDCARD, ADBLOCK_WILDCARD_REGEX, ADG_SCRIPTLET_MASK, AGLINT_COMMAND_PREFIX, AdblockSyntax, AdblockSyntaxError, Agent, AgentCommentRule, AgentCommentRuleParser, AgentParser, AnyCommentRule, AnyCosmeticRule, AnyExpressionNode, AnyOperator, AnyRule, AppListParser, COMMA_DOMAIN_LIST_SEPARATOR, CommentBase, CommentMarker, CommentRule, CommentRuleParser, CommentRuleType, ConfigCommentRule, ConfigCommentRuleParser, CosmeticRule, CosmeticRuleParser, CosmeticRuleSeparator, CosmeticRuleSeparatorFinderResult, CosmeticRuleSeparatorUtils, CosmeticRuleType, CssInjectionRule, CssInjectionRuleBody, CssTree, CssTreeNodeType, CssTreeParserContext, Domain, DomainList, DomainListParser, DomainListSeparator, DomainUtils, EXT_CSS_LEGACY_ATTRIBUTES, EXT_CSS_PSEUDO_CLASSES, ElementHidingRule, ElementHidingRuleBody, EmptyRule, ExpressionOperatorNode, ExpressionParenthesisNode, ExpressionVariableNode, FORBIDDEN_CSS_FUNCTIONS, FilterList, FilterListConverter, FilterListParser, HINT_MARKER, Hint, HintCommentRule, HintCommentRuleParser, HintParser, HtmlFilteringRule, HtmlFilteringRuleBody, IF, INCLUDE, JsInjectionRule, Location, LocationRange, LogicalExpressionParser, LogicalExpressionUtils, METADATA_HEADERS, MODIFIERS_SEPARATOR, MODIFIER_ASSIGN_OPERATOR, MetadataCommentRule, MetadataCommentRuleParser, MethodListParser, Modifier, ModifierList, ModifierListParser, ModifierParser, NEGATION_MARKER, NETWORK_RULE_EXCEPTION_MARKER, NETWORK_RULE_SEPARATOR, NetworkRule, NetworkRuleParser, Node, NotImplementedError, PIPE_MODIFIER_SEPARATOR, PREPROCESSOR_MARKER, Parameter, ParameterList, ParameterListParser, PreProcessorCommentRule, PreProcessorCommentRuleParser, QuoteType, QuoteUtils, RawFilterListConverter, RawRuleConverter, RegExpUtils, RuleBase, RuleCategory, RuleConversionError, RuleConverter, RuleParser, SAFARI_CB_AFFINITY, SPECIAL_REGEX_SYMBOLS, ScriptletInjectionRule, ScriptletInjectionRuleBody, StealthOptionListParser, UBO_SCRIPTLET_MASK, Value, VariableTable, locRange, modifierValidator, shiftLoc, version };