@adguard/agtree 1.1.1 → 1.1.3

package/dist/agtree.d.ts

@@ -1,5 +1,5 @@
 /*
- * AGTree v1.1.1 (build date: Fri, 11 Aug 2023 13:11:01 GMT)
+ * AGTree v1.1.3 (build date: Mon, 28 Aug 2023 16:19:09 GMT)
  * (c) 2023 AdGuard Software Ltd.
  * Released under the MIT license
  * https://github.com/AdguardTeam/tsurlfilter/tree/master/packages/agtree#readme
@@ -60,9 +60,8 @@ declare const enum AdblockSyntax {
 declare const ADG_SCRIPTLET_MASK = "//scriptlet";
 declare const UBO_SCRIPTLET_MASK = "js";
 declare const MODIFIERS_SEPARATOR = ",";
-declare const MODIFIER_EXCEPTION_MARKER = "~";
 declare const MODIFIER_ASSIGN_OPERATOR = "=";
-declare const DOMAIN_EXCEPTION_MARKER = "~";
+declare const NEGATION_MARKER = "~";
 /**
  * Classic domain separator.
  *
@@ -72,9 +71,9 @@ declare const DOMAIN_EXCEPTION_MARKER = "~";
  * example.com,~example.org##.ads
  * ```
  */
-declare const CLASSIC_DOMAIN_SEPARATOR = ",";
+declare const COMMA_DOMAIN_LIST_SEPARATOR = ",";
 /**
- * Modifier domain separator.
+ * Modifier separator for $app, $denyallow, $domain, $method.
  *
  * @example
  * ```adblock
@@ -82,7 +81,7 @@ declare const CLASSIC_DOMAIN_SEPARATOR = ",";
  * ads.js^$script,domains=example.com|~example.org
  * ```
  */
-declare const MODIFIER_DOMAIN_SEPARATOR = "|";
+declare const PIPE_MODIFIER_SEPARATOR = "|";
 declare const HINT_MARKER = "!+";
 declare const NETWORK_RULE_EXCEPTION_MARKER = "@@";
 declare const NETWORK_RULE_SEPARATOR = "$";
@@ -161,6 +160,25 @@ declare const enum RuleCategory {
      */
     Network = "Network"
 }
+/**
+ * Represents similar types of modifiers values
+ * which may be separated by a comma `,` (only for DomainList) or a pipe `|`.
+ */
+declare const enum ListNodeType {
+    AppList = "AppList",
+    DomainList = "DomainList",
+    MethodList = "MethodList",
+    StealthOptionList = "StealthOptionList"
+}
+/**
+ * Represents child items for {@link ListNodeType}.
+ */
+declare const enum ListItemNodeType {
+    App = "App",
+    Domain = "Domain",
+    Method = "Method",
+    StealthOption = "StealthOption"
+}
 /**
  * Represents possible comment types.
  */
@@ -703,24 +721,82 @@ interface Modifier extends Node {
      */
     value?: Value;
 }
+/**
+ * Represents the separator used for various modifier values.
+ *
+ * @example
+ * `||example.com^$app=com.test1.app|TestApp.exe`
+ */
+type PipeSeparator = typeof PIPE_MODIFIER_SEPARATOR;
+/**
+ * Represents the separator used for basic rules domain list.
+ *
+ * @example
+ * `example.com,example.org###banner`
+ */
+type CommaSeparator = typeof COMMA_DOMAIN_LIST_SEPARATOR;
 /**
  * Represents the separator used in a domain list.
  *
  * @example
- * "," for the classic domain list, and "|" for the "domain" modifier parameter
+ * - `,` — for the classic domain list,
+ * - `|` — for the $domain modifier value
+ */
+type DomainListSeparator = CommaSeparator | PipeSeparator;
+/**
+ * Common interface for a list item of $app, $denyallow, $domain, $method
+ * which have similar syntax.
  */
-type DomainListSeparator = typeof CLASSIC_DOMAIN_SEPARATOR | typeof MODIFIER_DOMAIN_SEPARATOR;
+interface ListItem extends Node {
+    type: ListItemNodeType;
+    /**
+     * Value of the node.
+     */
+    value: string;
+    /**
+     * If the value is an negated.
+     *
+     * @example
+     * `~example.com` is negated, but `example.com` is not. `~` is the exception marker here.
+     */
+    exception: boolean;
+}
 /**
- * Represents a list of domains
+ * Represents an element of the app list — $app.
+ */
+interface App extends ListItem {
+    type: ListItemNodeType.App;
+}
+/**
+ * Represents an element of the domain list — $domain, $denyallow.
+ */
+interface Domain extends ListItem {
+    type: ListItemNodeType.Domain;
+}
+/**
+ * Represents an element of the method list — $method.
+ */
+interface Method extends ListItem {
+    type: ListItemNodeType.Method;
+}
+/**
+ * Represents an element of the stealth option list — $stealth.
+ */
+interface StealthOption extends ListItem {
+    type: ListItemNodeType.StealthOption;
+}
+/**
+ * Represents a list of domains.
+ * Needed for $domain and $denyallow.
  *
  * @example
- * `example.com,~example.net`.
+ * `example.com,~example.net` or `example.com|~example.net`
  */
 interface DomainList extends Node {
     /**
      * Type of the node. Basically, the idea is that each main AST part should have a type
      */
-    type: 'DomainList';
+    type: ListNodeType.DomainList;
     /**
      * Separator used in the domain list.
      */
@@ -731,21 +807,67 @@ interface DomainList extends Node {
     children: Domain[];
 }
 /**
- * Represents an element of the domain list (a domain).
+ * Represents a list of apps.
+ * Needed for $app.
+ *
+ * @example
+ * `Example.exe|com.example.osx`.
  */
-interface Domain extends Node {
-    type: 'Domain';
+interface AppList extends Node {
     /**
-     * Domain name
+     * Type of the node. Basically, the idea is that each main AST part should have a type
      */
-    value: string;
+    type: ListNodeType.AppList;
     /**
-     * If the domain is an exception.
-     *
-     * @example
-     * `~example.com` is an exception, but `example.com` is not. `~` is the exception marker here.
+     * Separator used in the app list.
      */
-    exception: boolean;
+    separator: PipeSeparator;
+    /**
+     * List of apps
+     */
+    children: App[];
+}
+/**
+ * Represents a list of methods.
+ * Needed for $method.
+ *
+ * @example
+ * `get|post|put`.
+ */
+interface MethodList extends Node {
+    /**
+     * Type of the node. Basically, the idea is that each main AST part should have a type
+     */
+    type: ListNodeType.MethodList;
+    /**
+     * Separator used in the method list.
+     */
+    separator: PipeSeparator;
+    /**
+     * List of methods
+     */
+    children: Method[];
+}
+/**
+ * Represents a list of stealth options.
+ * Needed for $stealth.
+ *
+ * @example
+ * `referrer|ip`.
+ */
+interface StealthOptionList extends Node {
+    /**
+     * Type of the node. Basically, the idea is that each main AST part should have a type
+     */
+    type: ListNodeType.StealthOptionList;
+    /**
+     * Separator used in the stealth option list.
+     */
+    separator: PipeSeparator;
+    /**
+     * List of stealth options
+     */
+    children: StealthOption[];
 }
 /**
  * Represents a CSS injection body.
@@ -1398,6 +1520,25 @@ declare class CosmeticRuleParser {
     static generate(ast: AnyCosmeticRule): string;
 }
 
+/**
+ * `AppListParser` is responsible for parsing an app list.
+ *
+ * @see {@link https://adguard.app/kb/general/ad-filtering/create-own-filters/#app-modifier}
+ */
+declare class AppListParser {
+    /**
+     * Parses an app list which items are separated by `|`,
+     * e.g. `Example.exe|com.example.osx`.
+     *
+     * @param raw Raw app list
+     * @param loc Location of the app list in the rule. If not set, the default location is used.
+     *
+     * @returns App list AST.
+     * @throws An {@link AdblockSyntaxError} if the app list is syntactically invalid.
+     */
+    static parse(raw: string, loc?: Location): AppList;
+}
+
 /**
  * `DomainListParser` is responsible for parsing a domain list.
  *
@@ -1411,22 +1552,62 @@ declare class DomainListParser {
     /**
      * Parses a domain list, eg. `example.com,example.org,~example.org`
      *
-     * @param raw Raw domain list
-     * @param separator Separator character
-     * @param loc Location of the domain list
-     * @returns Domain list AST
-     * @throws If the domain list is syntactically invalid
+     * @param raw Raw domain list.
+     * @param separator Separator character.
+     * @param loc Location of the domain list in the rule. If not set, the default location is used.
+     *
+     * @returns Domain list AST.
+     * @throws An {@link AdblockSyntaxError} if the domain list is syntactically invalid.
      */
     static parse(raw: string, separator?: DomainListSeparator, loc?: Location): DomainList;
     /**
      * Converts a domain list AST to a string.
      *
-     * @param ast Domain list AST
-     * @returns Raw string
+     * @param ast Domain list AST.
+     *
+     * @returns Raw string.
      */
     static generate(ast: DomainList): string;
 }
 
+/**
+ * `MethodListParser` is responsible for parsing a method list.
+ *
+ * @see {@link https://adguard.app/kb/general/ad-filtering/create-own-filters/#method-modifier}
+ */
+declare class MethodListParser {
+    /**
+     * Parses a method list which items are separated by `|`,
+     * e.g. `get|post|put`.
+     *
+     * @param raw Raw method list
+     * @param loc Location of the method list in the rule. If not set, the default location is used.
+     *
+     * @returns Method list AST.
+     * @throws An {@link AdblockSyntaxError} if the method list is syntactically invalid.
+     */
+    static parse(raw: string, loc?: Location): MethodList;
+}
+
+/**
+ * `StealthOptionListParser` is responsible for parsing a list of stealth options.
+ *
+ * @see {@link https://adguard.app/kb/general/ad-filtering/create-own-filters/#stealth-modifier}
+ */
+declare class StealthOptionListParser {
+    /**
+     * Parses a stealth option list which items are separated by `|`,
+     * e.g. `dpi|ip`.
+     *
+     * @param raw Raw list of stealth options.
+     * @param loc Location of the stealth option list in the rule. If not set, the default location is used.
+     *
+     * @returns Stealth option list AST.
+     * @throws An {@link AdblockSyntaxError} if the stealth option list is syntactically invalid.
+     */
+    static parse(raw: string, loc?: Location): StealthOptionList;
+}
+
 /**
  * `FilterListParser` is responsible for parsing a whole adblock filter list (list of rules).
  * It is a wrapper around `RuleParser` which parses each line separately.
@@ -1801,22 +1982,23 @@ declare class RuleConversionError extends Error {
     constructor(message: string);
 }
 
-/**
- * @file Validator for modifiers.
- */
-
 /**
  * Result of modifier validation:
- * - `{ ok: true }` for valid and _fully supported_ modifier;
- * - `{ ok: true, warn: <deprecation notice> }` for valid
+ * - `{ valid: true }` for valid and _fully supported_ modifier;
+ * - `{ valid: true, warn: <deprecation notice> }` for valid
  *   and _still supported but deprecated_ modifier;
- * - otherwise `{ ok: true, error: <invalidity reason> }`
+ * - otherwise `{ valid: true, error: <invalidity reason> }`
  */
 type ValidationResult = {
-    ok: boolean;
+    valid: boolean;
     error?: string;
     warn?: string;
 };
+
+/**
+ * @file Validator for modifiers.
+ */
+
 /**
  * Modifier validator class.
  */
@@ -2370,9 +2552,6 @@ declare class CssTree {
     static generateFunctionValue(node: FunctionNode): string;
 }
 
-/**
- * @file Utility functions for domain and hostname validation.
- */
 declare class DomainUtils {
     /**
      * Check if the input is a valid domain or hostname.
@@ -2560,6 +2739,20 @@ declare class QuoteUtils {
      * @returns String without quotes
      */
     static removeQuotes(string: string): string;
+    /**
+     * Wraps given `strings` with `quote` (defaults to single quote `'`)
+     * and joins them with `separator` (defaults to comma+space `, `).
+     *
+     * @param strings Strings to quote and join.
+     * @param quoteType Quote to use.
+     * @param separator Separator to use.
+     *
+     * @returns String with joined items.
+     *
+     * @example
+     * ['abc', 'def']: strings[]  ->  "'abc', 'def'": string
+     */
+    static quoteAndJoinStrings(strings: string[], quoteType?: QuoteType, separator?: string): string;
 }
 
 /**
@@ -2590,4 +2783,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, CLASSIC_DOMAIN_SEPARATOR, CommentBase, CommentMarker, CommentRule, CommentRuleParser, CommentRuleType, ConfigCommentRule, ConfigCommentRuleParser, CosmeticRule, CosmeticRuleParser, CosmeticRuleSeparator, CosmeticRuleSeparatorFinderResult, CosmeticRuleSeparatorUtils, CosmeticRuleType, CssInjectionRule, CssInjectionRuleBody, CssTree, CssTreeNodeType, CssTreeParserContext, DOMAIN_EXCEPTION_MARKER, 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, MODIFIER_DOMAIN_SEPARATOR, MODIFIER_EXCEPTION_MARKER, MetadataCommentRule, MetadataCommentRuleParser, Modifier, ModifierList, ModifierListParser, ModifierParser, NETWORK_RULE_EXCEPTION_MARKER, NETWORK_RULE_SEPARATOR, NetworkRule, NetworkRuleParser, Node, NotImplementedError, PREPROCESSOR_MARKER, Parameter, ParameterList, ParameterListParser, PreProcessorCommentRule, PreProcessorCommentRuleParser, QuoteType, QuoteUtils, RegExpUtils, RuleBase, RuleCategory, RuleConversionError, RuleConverter, RuleParser, SAFARI_CB_AFFINITY, SPECIAL_REGEX_SYMBOLS, ScriptletInjectionRule, ScriptletInjectionRuleBody, 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, RegExpUtils, RuleBase, RuleCategory, RuleConversionError, RuleConverter, RuleParser, SAFARI_CB_AFFINITY, SPECIAL_REGEX_SYMBOLS, ScriptletInjectionRule, ScriptletInjectionRuleBody, StealthOptionListParser, UBO_SCRIPTLET_MASK, Value, VariableTable, locRange, modifierValidator, shiftLoc, version };