@adguard/agtree 2.1.2 → 3.0.0-alpha.1

package/dist/types/serializer/misc/list-item-serializer.d.ts

@@ -0,0 +1,13 @@
+import { BaseSerializer } from '../base-serializer';
+import { type ListItem, ListItemNodeType } from '../../nodes';
+import { type OutputByteBuffer } from '../../utils/output-byte-buffer';
+export declare class ListItemSerializer extends BaseSerializer {
+    /**
+     * Serializes a list item to binary format.
+     *
+     * @param item List item to serialize.
+     * @param buffer Output byte buffer.
+     * @template T Type of the list item.
+     */
+    static serialize<T extends ListItemNodeType>(item: ListItem<T>, buffer: OutputByteBuffer): void;
+}

package/dist/types/serializer/misc/list-items-serializer.d.ts

@@ -0,0 +1,12 @@
+import { type ListItem, type ListItemNodeType } from '../../nodes';
+import { type OutputByteBuffer } from '../../utils/output-byte-buffer';
+export declare class ListItemsSerializer {
+    /**
+     * Serializes a list of items to binary format.
+     *
+     * @param items List of items to serialize.
+     * @param buffer Output byte buffer.
+     * @template T Type of the list items.
+     */
+    static serialize<T extends ListItemNodeType>(items: ListItem<T>[], buffer: OutputByteBuffer): void;
+}

package/dist/types/serializer/misc/logical-expression-serializer.d.ts

@@ -0,0 +1,51 @@
+import { type AnyExpressionNode } from '../../nodes';
+import { type OutputByteBuffer } from '../../utils/output-byte-buffer';
+import { BaseSerializer } from '../base-serializer';
+/**
+ * Possible node types in the logical expression.
+ */
+export declare const enum NodeType {
+    Variable = "Variable",
+    Operator = "Operator",
+    Parenthesis = "Parenthesis"
+}
+/**
+ * `LogicalExpressionParser` is responsible for parsing logical expressions.
+ *
+ * @example
+ * From the following rule:
+ * ```adblock
+ * !#if (adguard_ext_android_cb || adguard_ext_safari)
+ * ```
+ * this parser will parse the expression `(adguard_ext_android_cb || adguard_ext_safari)`.
+ */
+export declare class LogicalExpressionSerializer extends BaseSerializer {
+    /**
+     * Serializes a variable node to binary format.
+     *
+     * @param node Node to serialize.
+     * @param buffer ByteBuffer for writing binary data.
+     */
+    private static serializeVariableNode;
+    /**
+     * Serializes a parenthesis node to binary format.
+     *
+     * @param node Node to serialize.
+     * @param buffer ByteBuffer for writing binary data.
+     */
+    private static serializeParenthesisNode;
+    /**
+     * Serializes an operator node to binary format.
+     *
+     * @param node Node to serialize.
+     * @param buffer ByteBuffer for writing binary data.
+     */
+    private static serializeOperatorNode;
+    /**
+     * Serializes a logical expression node to binary format.
+     *
+     * @param node Node to serialize.
+     * @param buffer ByteBuffer for writing binary data.
+     */
+    static serialize(node: AnyExpressionNode, buffer: OutputByteBuffer): void;
+}

package/dist/types/serializer/misc/modifier-list-serializer.d.ts

@@ -0,0 +1,20 @@
+import { type OutputByteBuffer } from '../../utils/output-byte-buffer';
+import { type ModifierList } from '../../nodes';
+import { BaseSerializer } from '../base-serializer';
+/**
+ * `ModifierListSerializer` is responsible for serializing modifier lists. Please note that the name is not
+ * uniform, "modifiers" are also known as "options".
+ *
+ * @see {@link https://kb.adguard.com/en/general/how-to-create-your-own-ad-filters#basic-rules-modifiers}
+ * @see {@link https://kb.adguard.com/en/general/how-to-create-your-own-ad-filters#non-basic-rules-modifiers}
+ * @see {@link https://help.eyeo.com/adblockplus/how-to-write-filters#options}
+ */
+export declare class ModifierListSerializer extends BaseSerializer {
+    /**
+     * Serializes a modifier list node to binary format.
+     *
+     * @param node Node to serialize.
+     * @param buffer ByteBuffer for writing binary data.
+     */
+    static serialize(node: ModifierList, buffer: OutputByteBuffer): void;
+}

package/dist/types/serializer/misc/modifier-serializer.d.ts

@@ -0,0 +1,18 @@
+import { type Modifier } from '../../nodes';
+import { type OutputByteBuffer } from '../../utils/output-byte-buffer';
+import { BaseSerializer } from '../base-serializer';
+/**
+ * `ModifierSerializer` is responsible for serializing modifiers.
+ *
+ * @example
+ * `match-case`, `~third-party`, `domain=example.com|~example.org`
+ */
+export declare class ModifierSerializer extends BaseSerializer {
+    /**
+     * Serializes a modifier node to binary format.
+     *
+     * @param node Node to serialize.
+     * @param buffer ByteBuffer for writing binary data.
+     */
+    static serialize(node: Modifier, buffer: OutputByteBuffer): void;
+}

package/dist/types/serializer/misc/parameter-list-serializer.d.ts

@@ -0,0 +1,14 @@
+import { type ParameterList } from '../../nodes';
+import { type OutputByteBuffer } from '../../utils/output-byte-buffer';
+import { BaseSerializer } from '../base-serializer';
+export declare class ParameterListSerializer extends BaseSerializer {
+    /**
+     * Serializes a parameter list node to binary format.
+     *
+     * @param node Node to serialize.
+     * @param buffer ByteBuffer for writing binary data.
+     * @param frequentValuesMap Optional map of frequent values.
+     * @param toLower Whether to lowercase the value before the frequent value match (defaults to `false`).
+     */
+    static serialize(node: ParameterList, buffer: OutputByteBuffer, frequentValuesMap?: Map<string, number>, toLower?: boolean): void;
+}

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

@@ -0,0 +1,17 @@
+import { type Value } from '../../nodes';
+import { type OutputByteBuffer } from '../../utils/output-byte-buffer';
+import { BaseSerializer } from '../base-serializer';
+/**
+ * Value serializer.
+ */
+export declare class ValueSerializer extends BaseSerializer {
+    /**
+     * Serializes a value node to binary format.
+     *
+     * @param node Node to serialize.
+     * @param buffer ByteBuffer for writing binary data.
+     * @param frequentValuesMap Optional map of frequent values.
+     * @param toLower Whether to lowercase the value before the frequent value match (defaults to `false`).
+     */
+    static serialize(node: Value, buffer: OutputByteBuffer, frequentValuesMap?: Map<string, number>, toLower?: boolean): void;
+}

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

@@ -0,0 +1,30 @@
+import { type HostRule } from '../../nodes';
+import { type OutputByteBuffer } from '../../utils/output-byte-buffer';
+import { BaseSerializer } from '../base-serializer';
+/**
+ * `HostRuleSerializer` is responsible for serializing hosts-like rules.
+ *
+ * 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:
+ * ```text
+ * IP_address canonical_hostname [aliases...]
+ * ```
+ *
+ * @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 HostRuleSerializer extends BaseSerializer {
+    /**
+     * Serializes a host rule node to binary format.
+     *
+     * @param node Node to serialize.
+     * @param buffer ByteBuffer for writing binary data.
+     */
+    static serialize(node: HostRule, buffer: OutputByteBuffer): void;
+}

package/dist/types/serializer/network/hostname-list-serializer.d.ts

@@ -0,0 +1,12 @@
+import { BaseSerializer } from '../base-serializer';
+import { type HostnameList } from '../../nodes';
+import type { OutputByteBuffer } from '../../utils/output-byte-buffer';
+export declare class HostnameListSerializer extends BaseSerializer {
+    /**
+     * Serializes a hostname list node to binary format.
+     *
+     * @param node Node to serialize.
+     * @param buffer ByteBuffer for writing binary data.
+     */
+    static serialize(node: HostnameList, buffer: OutputByteBuffer): void;
+}

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

@@ -0,0 +1,18 @@
+import { type NetworkRule } from '../../nodes';
+import { type OutputByteBuffer } from '../../utils/output-byte-buffer';
+import { BaseSerializer } from '../base-serializer';
+/**
+ * `NetworkRuleSerializer` is responsible for serializing network rules.
+ *
+ * @see {@link https://kb.adguard.com/en/general/how-to-create-your-own-ad-filters#basic-rules}
+ * @see {@link https://help.eyeo.com/adblockplus/how-to-write-filters#basic}
+ */
+export declare class NetworkRuleSerializer extends BaseSerializer {
+    /**
+     * Serializes a network rule node to binary format.
+     *
+     * @param node Node to serialize.
+     * @param buffer ByteBuffer for writing binary data.
+     */
+    static serialize(node: NetworkRule, buffer: OutputByteBuffer): void;
+}

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

@@ -0,0 +1,17 @@
+import { type AnyRule } from '../nodes';
+import { type OutputByteBuffer } from '../utils/output-byte-buffer';
+import { BaseSerializer } from './base-serializer';
+/**
+ * `RuleSerializer` is responsible for serializing the rules.
+ *
+ * It automatically determines the category and syntax of the rule, so you can pass any kind of rule to it.
+ */
+export declare class RuleSerializer extends BaseSerializer {
+    /**
+     * Serializes a rule node to binary format.
+     *
+     * @param node Node to serialize.
+     * @param buffer ByteBuffer for writing binary data.
+     */
+    static serialize(node: AnyRule, buffer: OutputByteBuffer): void;
+}

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

@@ -0,0 +1,48 @@
+/**
+ * @file Possible adblock syntaxes are listed here.
+ */
+/**
+ * Possible adblock syntaxes (supported by this library)
+ */
+export declare enum AdblockSyntax {
+    /**
+     * Common syntax, which is supported by more than one adblocker (or by all adblockers).
+     *
+     * We typically use this syntax when we cannot determine the concrete syntax of the rule,
+     * because the syntax is used by more than one adblocker natively.
+     *
+     * @example
+     * - `||example.org^$important` is a common syntax, since it is used by all adblockers natively, and
+     * we cannot determine at parsing level whether `important` is a valid option or not, and if it is valid,
+     * then which adblocker supports it.
+     */
+    Common = "Common",
+    /**
+     * Adblock Plus syntax.
+     *
+     * @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/}
+     */
+    Abp = "AdblockPlus",
+    /**
+     * uBlock Origin syntax.
+     *
+     * @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}
+     */
+    Ubo = "UblockOrigin",
+    /**
+     * AdGuard syntax.
+     *
+     * @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/}
+     */
+    Adg = "AdGuard"
+}

package/dist/types/utils/binary-schema-version.d.ts

@@ -0,0 +1,9 @@
+/**
+ * @file Binary schema version.
+ */
+/**
+ * Binary schema version.
+ * This version number is used to ensure that the binary format is compatible with the current library version.
+ * We increment this number if the serialized format changes in a way that is not backwards-compatible.
+ */
+export declare const BINARY_SCHEMA_VERSION = 1;

package/dist/types/utils/byte-buffer.d.ts

@@ -0,0 +1,54 @@
+/**
+ * @file Core ByteBuffer implementation for handling binary data in chunks.
+ */
+/**
+ * Core ByteBuffer implementation for handling binary data in chunks.
+ * This class allows for efficient byte storage and manipulation by organizing data into chunks
+ * and providing methods to read and write bytes.
+ */
+export declare class ByteBuffer {
+    /**
+     * The size of each chunk in bytes (32 KB).
+     */
+    static readonly CHUNK_SIZE = 32768;
+    /**
+     * An array of Uint8Array chunks that make up the buffer.
+     */
+    protected chunks: Uint8Array[];
+    /**
+     * The total number of chunks in the buffer.
+     */
+    protected chunksLength: number;
+    /**
+     * Constructs a new ByteBuffer instance.
+     *
+     * @param chunks Optional array of chunks to initialize the ByteBuffer with.
+     * @param cloneChunks Flag indicating if the chunks should be cloned. For performance reasons,
+     * its default value is `false`. If the original chunks are guaranteed not to change,
+     * leave this flag as `false` to avoid unnecessary copying.
+     */
+    constructor(chunks?: Uint8Array[], cloneChunks?: boolean);
+    /**
+     * Ensures that the buffer has enough capacity to accommodate a given position.
+     * This method adjusts the `chunks` array size to ensure it can hold the specified position.
+     *
+     * @param position The position to ensure capacity for.
+     */
+    protected ensureCapacity(position: number): void;
+    /**
+     * Writes a byte to the buffer at the specified position.
+     * If the position is outside of the buffer's current size, the buffer is resized to accommodate it.
+     *
+     * @param position The position at which to write the byte.
+     * @param value The byte value to write (0-255).
+     */
+    protected writeByte(position: number, value: number): void;
+    /**
+     * Reads a byte from the specified position in the buffer.
+     * Returns `undefined` if the position is outside of the buffer's current size.
+     *
+     * @param position The position from which to read the byte.
+     * @returns The read byte value, or `undefined` if the position is out of bounds.
+     */
+    protected readByte(position: number): number | undefined;
+}

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

@@ -0,0 +1,14 @@
+import { type CosmeticRuleType } from '../nodes';
+/**
+ * Utility functions for categorizing rules.
+ */
+export declare class RuleCategorizer {
+    /**
+     * Determines the type of a given raw cosmetic rule.
+     *
+     * @param rawRule Raw rule to check.
+     *
+     * @returns Type of the cosmetic rule or `null` if the rule is cannot be parsed as a cosmetic rule.
+     */
+    static getCosmeticRuleType(rawRule: string): CosmeticRuleType | null;
+}

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

@@ -0,0 +1,15 @@
+/**
+ * @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,
+ * and the implementation "under the hood" can be improved later, if needed.
+ */
+/**
+ * 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
+ */
+export declare function clone<T>(value: T): T;

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

@@ -0,0 +1,188 @@
+/**
+ * @file Constant values used by all parts of the library
+ */
+/**
+ * Empty string.
+ */
+export declare const EMPTY = "";
+export declare const SPACE = " ";
+export declare const TAB = "\t";
+export declare const COLON = ":";
+export declare const COMMA = ",";
+export declare const DOT = ".";
+export declare const SEMICOLON = ";";
+export declare const AMPERSAND = "&";
+export declare const ASTERISK = "*";
+export declare const AT_SIGN = "@";
+export declare const BACKTICK = "`";
+export declare const CARET = "^";
+export declare const DOLLAR_SIGN = "$";
+export declare const EQUALS = "=";
+export declare const EXCLAMATION_MARK = "!";
+export declare const GREATER_THAN = ">";
+export declare const HASHMARK = "#";
+export declare const LESS_THAN = "<";
+export declare const MINUS = "-";
+export declare const PERCENT = "%";
+export declare const PIPE = "|";
+export declare const PLUS = "+";
+export declare const QUESTION_MARK = "?";
+export declare const SLASH = "/";
+export declare const TILDE = "~";
+export declare const UNDERSCORE = "_";
+export declare const BACKSLASH = "\\";
+export declare const ESCAPE_CHARACTER = "\\";
+export declare const CR = "\r";
+export declare const FF = "\f";
+export declare const LF = "\n";
+export declare const CRLF: string;
+export declare const DOUBLE_NEWLINE = "\n\n";
+export declare const NEWLINE = "\n";
+export declare const BACKTICK_QUOTE = "`";
+export declare const DOUBLE_QUOTE = "\"";
+export declare const SINGLE_QUOTE = "'";
+export declare const OPEN_PARENTHESIS = "(";
+export declare const CLOSE_PARENTHESIS = ")";
+export declare const OPEN_SQUARE_BRACKET = "[";
+export declare const CLOSE_SQUARE_BRACKET = "]";
+export declare const OPEN_CURLY_BRACKET = "{";
+export declare const CLOSE_CURLY_BRACKET = "}";
+export declare const ASSIGN_OPERATOR = "=";
+export declare const SMALL_LETTER_A = "a";
+export declare const SMALL_LETTER_B = "b";
+export declare const SMALL_LETTER_C = "c";
+export declare const SMALL_LETTER_D = "d";
+export declare const SMALL_LETTER_E = "e";
+export declare const SMALL_LETTER_F = "f";
+export declare const SMALL_LETTER_G = "g";
+export declare const SMALL_LETTER_H = "h";
+export declare const SMALL_LETTER_I = "i";
+export declare const SMALL_LETTER_J = "j";
+export declare const SMALL_LETTER_K = "k";
+export declare const SMALL_LETTER_L = "l";
+export declare const SMALL_LETTER_M = "m";
+export declare const SMALL_LETTER_N = "n";
+export declare const SMALL_LETTER_O = "o";
+export declare const SMALL_LETTER_P = "p";
+export declare const SMALL_LETTER_Q = "q";
+export declare const SMALL_LETTER_R = "r";
+export declare const SMALL_LETTER_S = "s";
+export declare const SMALL_LETTER_T = "t";
+export declare const SMALL_LETTER_U = "u";
+export declare const SMALL_LETTER_V = "v";
+export declare const SMALL_LETTER_W = "w";
+export declare const SMALL_LETTER_X = "x";
+export declare const SMALL_LETTER_Y = "y";
+export declare const SMALL_LETTER_Z = "z";
+/**
+ * Set of all small letters.
+ */
+export declare const SMALL_LETTERS: Set<string>;
+export declare const CAPITAL_LETTER_A = "A";
+export declare const CAPITAL_LETTER_B = "B";
+export declare const CAPITAL_LETTER_C = "C";
+export declare const CAPITAL_LETTER_D = "D";
+export declare const CAPITAL_LETTER_E = "E";
+export declare const CAPITAL_LETTER_F = "F";
+export declare const CAPITAL_LETTER_G = "G";
+export declare const CAPITAL_LETTER_H = "H";
+export declare const CAPITAL_LETTER_I = "I";
+export declare const CAPITAL_LETTER_J = "J";
+export declare const CAPITAL_LETTER_K = "K";
+export declare const CAPITAL_LETTER_L = "L";
+export declare const CAPITAL_LETTER_M = "M";
+export declare const CAPITAL_LETTER_N = "N";
+export declare const CAPITAL_LETTER_O = "O";
+export declare const CAPITAL_LETTER_P = "P";
+export declare const CAPITAL_LETTER_Q = "Q";
+export declare const CAPITAL_LETTER_R = "R";
+export declare const CAPITAL_LETTER_S = "S";
+export declare const CAPITAL_LETTER_T = "T";
+export declare const CAPITAL_LETTER_U = "U";
+export declare const CAPITAL_LETTER_V = "V";
+export declare const CAPITAL_LETTER_W = "W";
+export declare const CAPITAL_LETTER_X = "X";
+export declare const CAPITAL_LETTER_Y = "Y";
+export declare const CAPITAL_LETTER_Z = "Z";
+/**
+ * Set of all capital letters.
+ */
+export declare const CAPITAL_LETTERS: Set<string>;
+export declare const NUMBER_0 = "0";
+export declare const NUMBER_1 = "1";
+export declare const NUMBER_2 = "2";
+export declare const NUMBER_3 = "3";
+export declare const NUMBER_4 = "4";
+export declare const NUMBER_5 = "5";
+export declare const NUMBER_6 = "6";
+export declare const NUMBER_7 = "7";
+export declare const NUMBER_8 = "8";
+export declare const NUMBER_9 = "9";
+/**
+ * Set of all numbers as strings.
+ */
+export declare const NUMBERS: Set<string>;
+export declare const REGEX_MARKER = "/";
+export declare const ADG_SCRIPTLET_MASK = "//scriptlet";
+export declare const UBO_SCRIPTLET_MASK = "+js";
+export declare const UBO_SCRIPTLET_MASK_LEGACY = "script:inject";
+export declare const UBO_HTML_MASK = "^";
+export declare const MODIFIERS_SEPARATOR = ",";
+export declare const MODIFIER_ASSIGN_OPERATOR = "=";
+export declare const NEGATION_MARKER = "~";
+/**
+ * The wildcard symbol — `*`.
+ */
+export declare const WILDCARD = "*";
+/**
+ * Classic domain separator.
+ *
+ * @example
+ * ```adblock
+ * ! Domains are separated by ",":
+ * example.com,~example.org##.ads
+ * ```
+ */
+export declare const COMMA_DOMAIN_LIST_SEPARATOR = ",";
+/**
+ * Modifier separator for $app, $denyallow, $domain, $method.
+ *
+ * @example
+ * ```adblock
+ * ! Domains are separated by "|":
+ * ads.js^$script,domains=example.com|~example.org
+ * ```
+ */
+export declare const PIPE_MODIFIER_SEPARATOR = "|";
+export declare const CSS_CLASS_MARKER = ".";
+export declare const CSS_ID_MARKER = "#";
+export declare const CSS_SELECTORS_SEPARATOR = ",";
+export declare const CSS_MEDIA_MARKER = "@media";
+export declare const CSS_PSEUDO_MARKER = ":";
+export declare const CSS_PSEUDO_OPEN = "(";
+export declare const CSS_PSEUDO_CLOSE = ")";
+export declare const CSS_NOT_PSEUDO = "not";
+export declare const CSS_BLOCK_OPEN = "{";
+export declare const CSS_BLOCK_CLOSE = "}";
+export declare const CSS_ATTRIBUTE_SELECTOR_OPEN = "[";
+export declare const CSS_ATTRIBUTE_SELECTOR_CLOSE = "]";
+export declare const CSS_IMPORTANT = "!important";
+export declare const CSS_DECLARATION_END = ";";
+export declare const CSS_DECLARATION_SEPARATOR = ":";
+export declare const HINT_MARKER = "!+";
+export declare const HINT_MARKER_LEN: number;
+export declare const NETWORK_RULE_EXCEPTION_MARKER = "@@";
+export declare const NETWORK_RULE_EXCEPTION_MARKER_LEN: number;
+export declare const NETWORK_RULE_SEPARATOR = "$";
+export declare const AGLINT_COMMAND_PREFIX = "aglint";
+export declare const AGLINT_CONFIG_COMMENT_MARKER = "--";
+export declare const PREPROCESSOR_MARKER = "!#";
+export declare const PREPROCESSOR_MARKER_LEN: number;
+export declare const PREPROCESSOR_SEPARATOR = " ";
+export declare const SAFARI_CB_AFFINITY = "safari_cb_affinity";
+export declare const IF = "if";
+export declare const INCLUDE = "include";
+export declare const NULL = 0;
+export declare const UINT8_MAX = 255;
+export declare const UINT16_MAX = 65535;
+export declare const UINT32_MAX = 4294967295;

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

@@ -0,0 +1,45 @@
+/**
+ * @file Cosmetic rule separator finder and categorizer
+ */
+import { CosmeticRuleSeparator } from '../nodes';
+export interface CosmeticRuleSeparatorFinderResult {
+    /**
+     * Separator type
+     */
+    separator: CosmeticRuleSeparator;
+    /**
+     * Separator start position
+     */
+    start: number;
+    /**
+     * Separator end position
+     */
+    end: number;
+}
+/**
+ * Utility class for cosmetic rule separators.
+ */
+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
+     */
+    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
+     */
+    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
+     */
+    static find(rule: string): CosmeticRuleSeparatorFinderResult | null;
+}

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

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

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

@@ -0,0 +1,26 @@
+/**
+ * @file Utility functions for domain and hostname validation.
+ */
+/**
+ * Marker for a wildcard top-level domain — `.*`.
+ *
+ * @example
+ * `example.*` — matches with any TLD, e.g. `example.org`, `example.com`, etc.
+ */
+export declare const WILDCARD_TLD: string;
+/**
+ * Marker for a wildcard subdomain — `*.`.
+ *
+ * @example
+ * `*.example.org` — matches with any subdomain, e.g. `foo.example.org` or `bar.example.org`
+ */
+export declare const WILDCARD_SUBDOMAIN: string;
+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
+     */
+    static isValidDomainOrHostname(domain: string): boolean;
+}

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

@@ -0,0 +1,8 @@
+/**
+ * Converts error object to error with message. This method might be helpful to handle thrown errors.
+ *
+ * @param error Error object.
+ *
+ * @returns Message of the error.
+ */
+export declare function getErrorMessage(error: unknown): string;