@adguard/agtree 2.2.0 → 3.0.0-alpha.2

package/dist/utils/byte-buffer.js

@@ -0,0 +1,91 @@
+/*
+ * AGTree v3.0.0-alpha.2 (build date: Tue, 17 Dec 2024 16:50:04 GMT)
+ * (c) 2024 Adguard Software Ltd.
+ * Released under the MIT license
+ * https://github.com/AdguardTeam/tsurlfilter/tree/master/packages/agtree#readme
+ */
+/* eslint-disable no-bitwise */
+/**
+ * @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.
+ */
+class ByteBuffer {
+    /**
+     * The size of each chunk in bytes (32 KB).
+     */
+    // ! IMPORTANT: If you ever change this value, make sure to update optimized bitwise operations in the code.
+    static CHUNK_SIZE = 32768; // 32 * 1024
+    /**
+     * An array of Uint8Array chunks that make up the buffer.
+     */
+    chunks;
+    /**
+     * The total number of chunks in the buffer.
+     */
+    chunksLength;
+    /**
+     * 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, cloneChunks = false) {
+        const chunksToUse = chunks ?? [];
+        this.chunks = cloneChunks ? chunksToUse.map((chunk) => new Uint8Array(chunk)) : chunksToUse;
+        this.chunksLength = chunks?.length ?? 0;
+    }
+    /**
+     * 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.
+     */
+    ensureCapacity(position) {
+        // same as Math.floor(position / chunk size), just optimized for the 32 KB chunk size
+        const requiredChunkIndex = position >>> 0x000F;
+        for (let i = this.chunksLength; i <= requiredChunkIndex; i += 1) {
+            this.chunks.push(new Uint8Array(ByteBuffer.CHUNK_SIZE));
+            this.chunksLength += 1;
+        }
+    }
+    /**
+     * 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).
+     */
+    writeByte(position, value) {
+        // same as Math.floor(position / chunk size), just optimized for the 32 KB chunk size
+        const chunkIndex = position >>> 0x000F;
+        // same as position % chunk size, just optimized for the 32 KB chunk size
+        const chunkOffset = position & 0x7FFF;
+        if (chunkIndex >= this.chunksLength) {
+            this.ensureCapacity(position);
+        }
+        this.chunks[chunkIndex][chunkOffset] = value;
+    }
+    /**
+     * 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.
+     */
+    readByte(position) {
+        const chunkIndex = position >>> 0x000F;
+        const chunkOffset = position & 0x7FFF;
+        if (chunkIndex >= this.chunksLength) {
+            return undefined;
+        }
+        return this.chunks[chunkIndex][chunkOffset];
+    }
+}
+
+export { ByteBuffer };

package/dist/utils/categorizer.js

@@ -0,0 +1,44 @@
+/*
+ * AGTree v3.0.0-alpha.2 (build date: Tue, 17 Dec 2024 16:50:04 GMT)
+ * (c) 2024 Adguard Software Ltd.
+ * Released under the MIT license
+ * https://github.com/AdguardTeam/tsurlfilter/tree/master/packages/agtree#readme
+ */
+import { CosmeticRuleParser } from '../parser/cosmetic/cosmetic-rule-parser.js';
+import { isNull } from './type-guards.js';
+import { defaultParserOptions } from '../parser/options.js';
+
+/**
+ * Utility functions for categorizing rules.
+ */
+// TODO: Optimize functions to avoid produce unnecessary data (currently, most of node data is not used).
+// TODO: Add support for other rule categories, like network rules (when needed).
+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) {
+        try {
+            const node = CosmeticRuleParser.parse(rawRule, {
+                ...defaultParserOptions,
+                isLocIncluded: false,
+                includeRaws: false,
+            });
+            // If rule cannot be recognized as a cosmetic rule, return null.
+            if (isNull(node)) {
+                return null;
+            }
+            return node.type;
+        }
+        catch {
+            // Be tolerant to parsing errors and simply return null.
+            return null;
+        }
+    }
+}
+
+export { RuleCategorizer };

package/dist/utils/clone.js

@@ -0,0 +1,28 @@
+/*
+ * AGTree v3.0.0-alpha.2 (build date: Tue, 17 Dec 2024 16:50:04 GMT)
+ * (c) 2024 Adguard Software Ltd.
+ * Released under the MIT license
+ * https://github.com/AdguardTeam/tsurlfilter/tree/master/packages/agtree#readme
+ */
+import cloneDeep from 'clone-deep';
+
+/**
+ * @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
+ */
+function clone(value) {
+    // TODO: Replace cloneDeep with a more efficient implementation
+    return cloneDeep(value);
+}
+
+export { clone };

package/dist/utils/constants.js

@@ -0,0 +1,249 @@
+/*
+ * AGTree v3.0.0-alpha.2 (build date: Tue, 17 Dec 2024 16:50:04 GMT)
+ * (c) 2024 Adguard Software Ltd.
+ * Released under the MIT license
+ * https://github.com/AdguardTeam/tsurlfilter/tree/master/packages/agtree#readme
+ */
+/**
+ * @file Constant values used by all parts of the library
+ */
+// TODO: remove unused constants
+// General
+/**
+ * Empty string.
+ */
+const EMPTY = '';
+const SPACE = ' ';
+const TAB = '\t';
+const COLON = ':';
+const COMMA = ',';
+const DOT = '.';
+const SEMICOLON = ';';
+const AMPERSAND = '&';
+const ASTERISK = '*';
+const AT_SIGN = '@';
+const CARET = '^';
+const DOLLAR_SIGN = '$';
+const EQUALS = '=';
+const EXCLAMATION_MARK = '!';
+const HASHMARK = '#';
+const PIPE = '|';
+const PLUS = '+';
+const QUESTION_MARK = '?';
+const SLASH = '/';
+const UNDERSCORE = '_';
+// Escape characters
+const BACKSLASH = '\\';
+const ESCAPE_CHARACTER = BACKSLASH;
+// Newlines
+const CR = '\r';
+const FF = '\f';
+const LF = '\n';
+const CRLF = CR + LF;
+const NEWLINE = LF;
+// Quotes
+const BACKTICK_QUOTE = '`';
+const DOUBLE_QUOTE = '"';
+const SINGLE_QUOTE = '\'';
+// Brackets
+const OPEN_PARENTHESIS = '(';
+const CLOSE_PARENTHESIS = ')';
+const OPEN_SQUARE_BRACKET = '[';
+const CLOSE_SQUARE_BRACKET = ']';
+const OPEN_CURLY_BRACKET = '{';
+const CLOSE_CURLY_BRACKET = '}';
+// Letters
+const SMALL_LETTER_A = 'a';
+const SMALL_LETTER_B = 'b';
+const SMALL_LETTER_C = 'c';
+const SMALL_LETTER_D = 'd';
+const SMALL_LETTER_E = 'e';
+const SMALL_LETTER_F = 'f';
+const SMALL_LETTER_G = 'g';
+const SMALL_LETTER_H = 'h';
+const SMALL_LETTER_I = 'i';
+const SMALL_LETTER_J = 'j';
+const SMALL_LETTER_K = 'k';
+const SMALL_LETTER_L = 'l';
+const SMALL_LETTER_M = 'm';
+const SMALL_LETTER_N = 'n';
+const SMALL_LETTER_O = 'o';
+const SMALL_LETTER_P = 'p';
+const SMALL_LETTER_Q = 'q';
+const SMALL_LETTER_R = 'r';
+const SMALL_LETTER_S = 's';
+const SMALL_LETTER_T = 't';
+const SMALL_LETTER_U = 'u';
+const SMALL_LETTER_V = 'v';
+const SMALL_LETTER_W = 'w';
+const SMALL_LETTER_X = 'x';
+const SMALL_LETTER_Y = 'y';
+const SMALL_LETTER_Z = 'z';
+/**
+ * Set of all small letters.
+ */
+const SMALL_LETTERS = new Set([
+    SMALL_LETTER_A,
+    SMALL_LETTER_B,
+    SMALL_LETTER_C,
+    SMALL_LETTER_D,
+    SMALL_LETTER_E,
+    SMALL_LETTER_F,
+    SMALL_LETTER_G,
+    SMALL_LETTER_H,
+    SMALL_LETTER_I,
+    SMALL_LETTER_J,
+    SMALL_LETTER_K,
+    SMALL_LETTER_L,
+    SMALL_LETTER_M,
+    SMALL_LETTER_N,
+    SMALL_LETTER_O,
+    SMALL_LETTER_P,
+    SMALL_LETTER_Q,
+    SMALL_LETTER_R,
+    SMALL_LETTER_S,
+    SMALL_LETTER_T,
+    SMALL_LETTER_U,
+    SMALL_LETTER_V,
+    SMALL_LETTER_W,
+    SMALL_LETTER_X,
+    SMALL_LETTER_Y,
+    SMALL_LETTER_Z,
+]);
+// Capital letters
+const CAPITAL_LETTER_A = 'A';
+const CAPITAL_LETTER_B = 'B';
+const CAPITAL_LETTER_C = 'C';
+const CAPITAL_LETTER_D = 'D';
+const CAPITAL_LETTER_E = 'E';
+const CAPITAL_LETTER_F = 'F';
+const CAPITAL_LETTER_G = 'G';
+const CAPITAL_LETTER_H = 'H';
+const CAPITAL_LETTER_I = 'I';
+const CAPITAL_LETTER_J = 'J';
+const CAPITAL_LETTER_K = 'K';
+const CAPITAL_LETTER_L = 'L';
+const CAPITAL_LETTER_M = 'M';
+const CAPITAL_LETTER_N = 'N';
+const CAPITAL_LETTER_O = 'O';
+const CAPITAL_LETTER_P = 'P';
+const CAPITAL_LETTER_Q = 'Q';
+const CAPITAL_LETTER_R = 'R';
+const CAPITAL_LETTER_S = 'S';
+const CAPITAL_LETTER_T = 'T';
+const CAPITAL_LETTER_U = 'U';
+const CAPITAL_LETTER_V = 'V';
+const CAPITAL_LETTER_W = 'W';
+const CAPITAL_LETTER_X = 'X';
+const CAPITAL_LETTER_Y = 'Y';
+const CAPITAL_LETTER_Z = 'Z';
+/**
+ * Set of all capital letters.
+ */
+const CAPITAL_LETTERS = new Set([
+    CAPITAL_LETTER_A,
+    CAPITAL_LETTER_B,
+    CAPITAL_LETTER_C,
+    CAPITAL_LETTER_D,
+    CAPITAL_LETTER_E,
+    CAPITAL_LETTER_F,
+    CAPITAL_LETTER_G,
+    CAPITAL_LETTER_H,
+    CAPITAL_LETTER_I,
+    CAPITAL_LETTER_J,
+    CAPITAL_LETTER_K,
+    CAPITAL_LETTER_L,
+    CAPITAL_LETTER_M,
+    CAPITAL_LETTER_N,
+    CAPITAL_LETTER_O,
+    CAPITAL_LETTER_P,
+    CAPITAL_LETTER_Q,
+    CAPITAL_LETTER_R,
+    CAPITAL_LETTER_S,
+    CAPITAL_LETTER_T,
+    CAPITAL_LETTER_U,
+    CAPITAL_LETTER_V,
+    CAPITAL_LETTER_W,
+    CAPITAL_LETTER_X,
+    CAPITAL_LETTER_Y,
+    CAPITAL_LETTER_Z,
+]);
+// Numbers as strings
+const NUMBER_0 = '0';
+const NUMBER_1 = '1';
+const NUMBER_2 = '2';
+const NUMBER_3 = '3';
+const NUMBER_4 = '4';
+const NUMBER_5 = '5';
+const NUMBER_6 = '6';
+const NUMBER_7 = '7';
+const NUMBER_8 = '8';
+const NUMBER_9 = '9';
+/**
+ * Set of all numbers as strings.
+ */
+const NUMBERS = new Set([
+    NUMBER_0,
+    NUMBER_1,
+    NUMBER_2,
+    NUMBER_3,
+    NUMBER_4,
+    NUMBER_5,
+    NUMBER_6,
+    NUMBER_7,
+    NUMBER_8,
+    NUMBER_9,
+]);
+const REGEX_MARKER = '/';
+const ADG_SCRIPTLET_MASK = '//scriptlet';
+const UBO_SCRIPTLET_MASK = '+js';
+const UBO_SCRIPTLET_MASK_LEGACY = 'script:inject';
+const UBO_HTML_MASK = '^';
+// Modifiers are separated by ",". For example: "script,domain=example.com"
+const MODIFIERS_SEPARATOR = ',';
+const MODIFIER_ASSIGN_OPERATOR = '=';
+const NEGATION_MARKER = '~';
+/**
+ * The wildcard symbol — `*`.
+ */
+const WILDCARD = ASTERISK;
+/**
+ * Classic domain separator.
+ *
+ * @example
+ * ```adblock
+ * ! Domains are separated by ",":
+ * example.com,~example.org##.ads
+ * ```
+ */
+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
+ * ```
+ */
+const PIPE_MODIFIER_SEPARATOR = '|';
+const CSS_MEDIA_MARKER = '@media';
+const CSS_NOT_PSEUDO = 'not';
+const HINT_MARKER = '!+';
+const HINT_MARKER_LEN = HINT_MARKER.length;
+const NETWORK_RULE_EXCEPTION_MARKER = '@@';
+const NETWORK_RULE_EXCEPTION_MARKER_LEN = NETWORK_RULE_EXCEPTION_MARKER.length;
+const NETWORK_RULE_SEPARATOR = '$';
+const AGLINT_COMMAND_PREFIX = 'aglint';
+const AGLINT_CONFIG_COMMENT_MARKER = '--';
+const PREPROCESSOR_MARKER = '!#';
+const PREPROCESSOR_MARKER_LEN = PREPROCESSOR_MARKER.length;
+const PREPROCESSOR_SEPARATOR = ' ';
+const SAFARI_CB_AFFINITY = 'safari_cb_affinity';
+const IF = 'if';
+const INCLUDE = 'include';
+const NULL = 0;
+const UINT8_MAX = 255;
+const UINT16_MAX = 65535;
+
+export { ADG_SCRIPTLET_MASK, AGLINT_COMMAND_PREFIX, AGLINT_CONFIG_COMMENT_MARKER, AMPERSAND, ASTERISK, AT_SIGN, BACKSLASH, BACKTICK_QUOTE, CAPITAL_LETTERS, CAPITAL_LETTER_A, CAPITAL_LETTER_B, CAPITAL_LETTER_C, CAPITAL_LETTER_D, CAPITAL_LETTER_E, CAPITAL_LETTER_F, CAPITAL_LETTER_G, CAPITAL_LETTER_H, CAPITAL_LETTER_I, CAPITAL_LETTER_J, CAPITAL_LETTER_K, CAPITAL_LETTER_L, CAPITAL_LETTER_M, CAPITAL_LETTER_N, CAPITAL_LETTER_O, CAPITAL_LETTER_P, CAPITAL_LETTER_Q, CAPITAL_LETTER_R, CAPITAL_LETTER_S, CAPITAL_LETTER_T, CAPITAL_LETTER_U, CAPITAL_LETTER_V, CAPITAL_LETTER_W, CAPITAL_LETTER_X, CAPITAL_LETTER_Y, CAPITAL_LETTER_Z, CARET, CLOSE_CURLY_BRACKET, CLOSE_PARENTHESIS, CLOSE_SQUARE_BRACKET, COLON, COMMA, COMMA_DOMAIN_LIST_SEPARATOR, CR, CRLF, CSS_MEDIA_MARKER, CSS_NOT_PSEUDO, DOLLAR_SIGN, DOT, DOUBLE_QUOTE, EMPTY, EQUALS, ESCAPE_CHARACTER, EXCLAMATION_MARK, FF, HASHMARK, HINT_MARKER, HINT_MARKER_LEN, IF, INCLUDE, LF, MODIFIERS_SEPARATOR, MODIFIER_ASSIGN_OPERATOR, NEGATION_MARKER, NETWORK_RULE_EXCEPTION_MARKER, NETWORK_RULE_EXCEPTION_MARKER_LEN, NETWORK_RULE_SEPARATOR, NEWLINE, NULL, NUMBERS, NUMBER_0, NUMBER_1, NUMBER_2, NUMBER_3, NUMBER_4, NUMBER_5, NUMBER_6, NUMBER_7, NUMBER_8, NUMBER_9, OPEN_CURLY_BRACKET, OPEN_PARENTHESIS, OPEN_SQUARE_BRACKET, PIPE, PIPE_MODIFIER_SEPARATOR, PLUS, PREPROCESSOR_MARKER, PREPROCESSOR_MARKER_LEN, PREPROCESSOR_SEPARATOR, QUESTION_MARK, REGEX_MARKER, SAFARI_CB_AFFINITY, SEMICOLON, SINGLE_QUOTE, SLASH, SMALL_LETTERS, SMALL_LETTER_A, SMALL_LETTER_B, SMALL_LETTER_C, SMALL_LETTER_D, SMALL_LETTER_E, SMALL_LETTER_F, SMALL_LETTER_G, SMALL_LETTER_H, SMALL_LETTER_I, SMALL_LETTER_J, SMALL_LETTER_K, SMALL_LETTER_L, SMALL_LETTER_M, SMALL_LETTER_N, SMALL_LETTER_O, SMALL_LETTER_P, SMALL_LETTER_Q, SMALL_LETTER_R, SMALL_LETTER_S, SMALL_LETTER_T, SMALL_LETTER_U, SMALL_LETTER_V, SMALL_LETTER_W, SMALL_LETTER_X, SMALL_LETTER_Y, SMALL_LETTER_Z, SPACE, TAB, UBO_HTML_MASK, UBO_SCRIPTLET_MASK, UBO_SCRIPTLET_MASK_LEGACY, UINT16_MAX, UINT8_MAX, UNDERSCORE, WILDCARD };

package/dist/utils/cosmetic-rule-separator.js

@@ -0,0 +1,127 @@
+/*
+ * AGTree v3.0.0-alpha.2 (build date: Tue, 17 Dec 2024 16:50:04 GMT)
+ * (c) 2024 Adguard Software Ltd.
+ * Released under the MIT license
+ * https://github.com/AdguardTeam/tsurlfilter/tree/master/packages/agtree#readme
+ */
+import { CosmeticRuleSeparator } from '../nodes/index.js';
+import { AT_SIGN, SPACE } from './constants.js';
+
+/**
+ * @file Cosmetic rule separator finder and categorizer
+ */
+/**
+ * Utility class for cosmetic rule separators.
+ */
+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) {
+        // Simply check the second character
+        return separator[1] === AT_SIGN;
+    }
+    /**
+     * 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) {
+        return (separator === CosmeticRuleSeparator.ExtendedElementHiding
+            || separator === CosmeticRuleSeparator.ExtendedElementHidingException
+            || separator === CosmeticRuleSeparator.AdgExtendedCssInjection
+            || separator === CosmeticRuleSeparator.AdgExtendedCssInjectionException);
+    }
+    /**
+     * 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) {
+        /**
+         * Helper function to create results of the `find` method.
+         *
+         * @param start Start position
+         * @param separator Separator type
+         * @returns Cosmetic rule separator node
+         */
+        // eslint-disable-next-line max-len
+        function createResult(start, separator) {
+            return {
+                separator,
+                start,
+                end: start + separator.length,
+            };
+        }
+        for (let i = 0; i < rule.length; i += 1) {
+            if (rule[i] === '#') {
+                if (rule[i + 1] === '#' && rule[i - 1] !== SPACE) {
+                    // ##
+                    return createResult(i, CosmeticRuleSeparator.ElementHiding);
+                }
+                if (rule[i + 1] === '?' && rule[i + 2] === '#') {
+                    // #?#
+                    return createResult(i, CosmeticRuleSeparator.ExtendedElementHiding);
+                }
+                if (rule[i + 1] === '%' && rule[i + 2] === '#') {
+                    // #%#
+                    return createResult(i, CosmeticRuleSeparator.AdgJsInjection);
+                }
+                if (rule[i + 1] === '$') {
+                    if (rule[i + 2] === '#') {
+                        // #$#
+                        return createResult(i, CosmeticRuleSeparator.AdgCssInjection);
+                    }
+                    if (rule[i + 2] === '?' && rule[i + 3] === '#') {
+                        // #$?#
+                        return createResult(i, CosmeticRuleSeparator.AdgExtendedCssInjection);
+                    }
+                }
+                // Exceptions
+                if (rule[i + 1] === '@') {
+                    if (rule[i + 2] === '#' && rule[i - 1] !== SPACE) {
+                        // #@#
+                        return createResult(i, CosmeticRuleSeparator.ElementHidingException);
+                    }
+                    if (rule[i + 2] === '?' && rule[i + 3] === '#') {
+                        // #@?#
+                        return createResult(i, CosmeticRuleSeparator.ExtendedElementHidingException);
+                    }
+                    if (rule[i + 2] === '%' && rule[i + 3] === '#') {
+                        // #@%#
+                        return createResult(i, CosmeticRuleSeparator.AdgJsInjectionException);
+                    }
+                    if (rule[i + 2] === '$') {
+                        if (rule[i + 3] === '#') {
+                            // #@$#
+                            return createResult(i, CosmeticRuleSeparator.AdgCssInjectionException);
+                        }
+                        if (rule[i + 3] === '?' && rule[i + 4] === '#') {
+                            // #@$?#
+                            return createResult(i, CosmeticRuleSeparator.AdgExtendedCssInjectionException);
+                        }
+                    }
+                }
+            }
+            if (rule[i] === '$') {
+                if (rule[i + 1] === '$') {
+                    // $$
+                    return createResult(i, CosmeticRuleSeparator.AdgHtmlFiltering);
+                }
+                if (rule[i + 1] === '@' && rule[i + 2] === '$') {
+                    // $@$
+                    return createResult(i, CosmeticRuleSeparator.AdgHtmlFilteringException);
+                }
+            }
+        }
+        return null;
+    }
+}
+
+export { CosmeticRuleSeparatorUtils };

package/dist/utils/deep-freeze.js

@@ -0,0 +1,32 @@
+/*
+ * AGTree v3.0.0-alpha.2 (build date: Tue, 17 Dec 2024 16:50:04 GMT)
+ * (c) 2024 Adguard Software Ltd.
+ * Released under the MIT license
+ * https://github.com/AdguardTeam/tsurlfilter/tree/master/packages/agtree#readme
+ */
+/**
+ * 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}
+ */
+const deepFreeze = (object) => {
+    // Retrieve the property names defined on object
+    const propNames = Reflect.ownKeys(object);
+    // Freeze properties before freezing self
+    for (const name of propNames) {
+        const value = object[name];
+        if ((value && typeof value === 'object') || typeof value === 'function') {
+            deepFreeze(value);
+        }
+    }
+    return Object.freeze(object);
+};
+
+export { deepFreeze };

package/dist/utils/domain.js

@@ -0,0 +1,59 @@
+/*
+ * AGTree v3.0.0-alpha.2 (build date: Tue, 17 Dec 2024 16:50:04 GMT)
+ * (c) 2024 Adguard Software Ltd.
+ * Released under the MIT license
+ * https://github.com/AdguardTeam/tsurlfilter/tree/master/packages/agtree#readme
+ */
+import { parse } from 'tldts';
+import { WILDCARD, DOT } from './constants.js';
+
+/**
+ * @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.
+ */
+const WILDCARD_TLD = DOT + WILDCARD;
+/**
+ * Marker for a wildcard subdomain — `*.`.
+ *
+ * @example
+ * `*.example.org` — matches with any subdomain, e.g. `foo.example.org` or `bar.example.org`
+ */
+const WILDCARD_SUBDOMAIN = WILDCARD + DOT;
+/**
+ * Utility functions for domain and hostname validation.
+ */
+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) {
+        let domainToCheck = domain;
+        // Wildcard-only domain, typically a generic rule
+        if (domainToCheck === WILDCARD) {
+            return true;
+        }
+        // https://adguard.com/kb/general/ad-filtering/create-own-filters/#wildcard-for-tld
+        if (domainToCheck.endsWith(WILDCARD_TLD)) {
+            // Remove the wildcard TLD
+            domainToCheck = domainToCheck.substring(0, domainToCheck.length - WILDCARD_TLD.length);
+        }
+        if (domainToCheck.startsWith(WILDCARD_SUBDOMAIN)) {
+            // Remove the wildcard subdomain
+            domainToCheck = domainToCheck.substring(WILDCARD_SUBDOMAIN.length);
+        }
+        // Parse the domain with tldts
+        const tldtsResult = parse(domainToCheck);
+        // Check if the domain is valid
+        return domainToCheck === tldtsResult.domain || domainToCheck === tldtsResult.hostname;
+    }
+}
+
+export { DomainUtils, WILDCARD_SUBDOMAIN, WILDCARD_TLD };

package/dist/utils/error.js

@@ -0,0 +1,49 @@
+/*
+ * AGTree v3.0.0-alpha.2 (build date: Tue, 17 Dec 2024 16:50:04 GMT)
+ * (c) 2024 Adguard Software Ltd.
+ * Released under the MIT license
+ * https://github.com/AdguardTeam/tsurlfilter/tree/master/packages/agtree#readme
+ */
+/**
+ * Checks if error has message.
+ *
+ * @param error Error object.
+ * @returns If param is error.
+ */
+function isErrorWithMessage(error) {
+    return (typeof error === 'object'
+        && error !== null
+        && 'message' in error
+        && typeof error.message === 'string');
+}
+/**
+ * Converts error to the error with message.
+ *
+ * @param maybeError Possible error.
+ * @returns Error with message.
+ */
+function toErrorWithMessage(maybeError) {
+    if (isErrorWithMessage(maybeError)) {
+        return maybeError;
+    }
+    try {
+        return new Error(JSON.stringify(maybeError));
+    }
+    catch {
+        // fallback in case there's an error stringifying the maybeError
+        // like with circular references for example.
+        return new Error(String(maybeError));
+    }
+}
+/**
+ * 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.
+ */
+function getErrorMessage(error) {
+    return toErrorWithMessage(error).message;
+}
+
+export { getErrorMessage };