@adguard/agtree 2.2.0 → 3.0.0-alpha.2

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

@@ -0,0 +1,29 @@
+/**
+ * @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;
+/**
+ * Utility functions for domain and hostname validation.
+ */
+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;

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

@@ -0,0 +1,15 @@
+export { ADG_SCRIPTLET_MASK, AGLINT_COMMAND_PREFIX, COMMA_DOMAIN_LIST_SEPARATOR, NEGATION_MARKER, HINT_MARKER, IF, INCLUDE, MODIFIERS_SEPARATOR, MODIFIER_ASSIGN_OPERATOR, PIPE_MODIFIER_SEPARATOR, NETWORK_RULE_EXCEPTION_MARKER, NETWORK_RULE_SEPARATOR, PREPROCESSOR_MARKER, SAFARI_CB_AFFINITY, UBO_SCRIPTLET_MASK, } from './constants';
+export { BINARY_SCHEMA_VERSION } from './binary-schema-version';
+export { AdblockSyntax } from './adblockers';
+export { type CosmeticRuleSeparatorFinderResult, CosmeticRuleSeparatorUtils } from './cosmetic-rule-separator';
+export { DomainUtils } from './domain';
+export { type VariableTable, LogicalExpressionUtils } from './logical-expression';
+export { ADBLOCK_URL_START, ADBLOCK_URL_START_REGEX, ADBLOCK_URL_SEPARATOR, ADBLOCK_URL_SEPARATOR_REGEX, ADBLOCK_WILDCARD, ADBLOCK_WILDCARD_REGEX, SPECIAL_REGEX_SYMBOLS, RegExpUtils, } from './regexp';
+export { QuoteType, QuoteUtils, } from './quotes';
+export { type Position, PositionProvider } from './position-provider';
+export { OutputByteBuffer } from './output-byte-buffer';
+export { InputByteBuffer } from './input-byte-buffer';
+export { ByteBuffer } from './byte-buffer';
+export { encodeIntoPolyfill, type TextEncoderPolyfillResult } from './text-encoder-polyfill';
+export { decodeTextPolyfill } from './text-decoder-polyfill';
+export { RuleCategorizer } from './categorizer';

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

@@ -0,0 +1,146 @@
+/**
+ * @file Input byte buffer for reading binary data.
+ */
+import { ByteBuffer } from './byte-buffer';
+import { type Storage } from './storage-interface';
+/**
+ * Input byte buffer for reading binary data.
+ *
+ * @note Internally, this class uses a {@link ByteBuffer} instance, just providing a convenient API for reading data.
+ */
+export declare class InputByteBuffer extends ByteBuffer {
+    /**
+     * Current offset in the buffer for reading.
+     */
+    private offset;
+    /**
+     * Shared native decoder for decoding strings.
+     */
+    private readonly sharedNativeDecoder;
+    /**
+     * Flag indicating if the current environment is Chromium.
+     * This is used for performance optimizations, because Chromium's TextEncoder/TextDecoder has a relatively
+     * large marshalling overhead for small strings.
+     */
+    private readonly isChromium;
+    /**
+     * Constructs a new `InputByteBuffer` instance.
+     *
+     * @param chunks 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.
+     * @param initialOffset Initial offset in the buffer for reading.
+     *
+     * @throws If the specified chunks array is empty.
+     * @throws If the binary schema version in the buffer is not equal to the expected version.
+     * @throws If the initial offset is out of bounds.
+     */
+    constructor(chunks: Uint8Array[], cloneChunks?: boolean, initialOffset?: number);
+    /**
+     * Creates a new InputByteBuffer instance from a Storage instance by reading chunks from the storage.
+     *
+     * @param storage Storage instance.
+     * @param key Key to read from the storage.
+     * @returns New InputByteBuffer instance.
+     * @note For performance reasons, chunks are passed by reference and not copied.
+     */
+    static createFromStorage(storage: Storage, key: string): Promise<InputByteBuffer>;
+    /**
+     * Reads a 8-bit unsigned integer from the buffer.
+     *
+     * @returns 8-bit unsigned integer from the buffer.
+     */
+    readUint8(): number;
+    /**
+     * Reads a 16-bit unsigned integer from the buffer.
+     *
+     * @returns 16-bit unsigned integer from the buffer.
+     */
+    readUint16(): number;
+    /**
+     * Reads a 32-bit unsigned integer from the buffer at the specified index.
+     *
+     * @param index Index to read the 32-bit unsigned integer from.
+     *
+     * @returns 32-bit unsigned integer from the buffer.
+     */
+    private readUint32FromIndex;
+    /**
+     * Reads a 32-bit unsigned integer from the buffer.
+     *
+     * @returns 32-bit unsigned integer from the buffer.
+     */
+    readUint32(): number;
+    /**
+     * Reads schema version from the buffer.
+     *
+     * @returns 32-bit unsigned integer from the buffer.
+     * @note Schema version is always stored at the beginning of the buffer.
+     */
+    readSchemaVersion(): number;
+    /**
+     * Reads a 32-bit signed integer from the buffer.
+     *
+     * @returns 32-bit signed integer from the buffer.
+     */
+    readInt32(): number;
+    /**
+     * Reads an optimized unsigned integer from the buffer.
+     * 'Optimized' means that the integer is stored in a variable number of bytes, depending on its value,
+     * so that smaller numbers occupy less space.
+     *
+     * @returns Decoded unsigned integer from the buffer.
+     */
+    readOptimizedUint(): number;
+    /**
+     * Reads a string from the buffer.
+     *
+     * @returns Decoded string from the buffer.
+     */
+    readString(): string;
+    /**
+     * Reads a 8-bit unsigned integer from the buffer without advancing the offset.
+     *
+     * @returns 8-bit unsigned integer from the buffer.
+     */
+    peekUint8(): number;
+    /**
+     * Helper method for asserting the next 8-bit unsigned integer in the buffer.
+     *
+     * @param value Expected value.
+     * @throws If the next value in the buffer is not equal to the expected value.
+     */
+    assertUint8(value: number): void;
+    /**
+     * Creates a new `InputByteBuffer` instance with the given initial offset.
+     *
+     * @param initialOffset Initial offset for the new buffer.
+     * @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.
+     *
+     * @returns New `InputByteBuffer` instance with the given initial offset.
+     *
+     * @note This method is useful if you want to read some data from a specific index.
+     */
+    createCopyWithOffset(initialOffset: number, cloneChunks?: boolean): InputByteBuffer;
+    /**
+     * Gets the current offset in the buffer for reading.
+     *
+     * @returns Current offset in the buffer for reading.
+     */
+    get currentOffset(): number;
+    /**
+     * Gets the capacity of the buffer.
+     *
+     * @returns Capacity of the buffer.
+     */
+    get capacity(): number;
+    /**
+     * Gets the chunks of the buffer.
+     *
+     * @returns Chunks of the buffer.
+     */
+    getChunks(): Uint8Array[];
+}

package/dist/types/utils/is-chromium.d.ts

@@ -0,0 +1,7 @@
+/**
+ * A simple function to check if the current browser is Chromium-based.
+ *
+ * @returns `true` if the current browser is Chromium-based, `false` otherwise.
+ * @see {@link https://stackoverflow.com/a/62797156}
+ */
+export declare const isChromium: () => boolean;

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

@@ -0,0 +1,45 @@
+/**
+ * @file Utility functions for logical expression node.
+ */
+import { type AnyExpressionNode, type ExpressionVariableNode } from '../nodes';
+/**
+ * Variable table. Key is variable name, value is boolean.
+ */
+export type VariableTable = {
+    [key: string]: boolean;
+};
+/**
+ * Utility functions for logical expression node.
+ */
+export declare class LogicalExpressionUtils {
+    /**
+     * Get all variables in the expression.
+     *
+     * @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`.
+     */
+    static getVariables(node: AnyExpressionNode): ExpressionVariableNode[];
+    /**
+     * 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
+     * @example
+     * If the expression is `a && b`, and the variable table is
+     * `{ a: true, b: false }`, the result will be `false`.
+     *
+     * Example code:
+     * ```js
+     * LogicalExpressionUtils.evaluate(
+     *     LogicalExpressionParser.parse('a && b'),
+     *     { a: true, b: false }
+     * );
+     * ```
+     */
+    static evaluate(node: AnyExpressionNode, table: VariableTable): boolean;
+}

package/dist/types/utils/multi-value-map.d.ts

@@ -0,0 +1,16 @@
+/**
+ * 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
+ */
+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
+     */
+    add(key: K, ...values: V[]): void;
+}

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

@@ -0,0 +1,132 @@
+import { ByteBuffer } from './byte-buffer';
+import { type Storage } from './storage-interface';
+/**
+ * Output byte buffer for writing binary data.
+ *
+ * @note Internally, this class uses a {@link ByteBuffer} instance, just providing a convenient API for reading data.
+ */
+export declare class OutputByteBuffer extends ByteBuffer {
+    /**
+     * Current offset in the buffer for writing.
+     */
+    private offset;
+    /**
+     * Size of the shared buffer for encoding strings in bytes.
+     * This is a divisor of ByteBuffer.CHUNK_SIZE and experience shows that this value works optimally.
+     * This is sufficient for most strings that occur in filter lists (we checked average string length in popular
+     * filter lists).
+     */
+    private static readonly ENCODER_BUFFER_SIZE;
+    /**
+     * Length threshold for using a shared buffer for encoding strings.
+     * This temp buffer is needed because we write the short strings in it
+     * (so there is no need to constantly allocate a new buffer).
+     * The reason for dividing ENCODER_BUFFER_SIZE by 4 is to ensure that the encoded string fits in the buffer,
+     * if we also take into account the worst possible case (each character is encoded with 4 bytes).
+     */
+    private static readonly SHORT_STRING_THRESHOLD;
+    /**
+     * Represents the maximum value that can be written as a 'storage optimized' unsigned integer.
+     * 0x1FFFFFFF means 29 bits — 32 bits minus 3 bits — because the last bit in each byte is a flag indicating
+     * if there are more bytes (except for the last byte).
+     */
+    static MAX_OPTIMIZED_UINT: number;
+    /**
+     * Shared buffer for encoding strings.
+     */
+    private readonly sharedBuffer;
+    /**
+     * Shared native encoder for encoding strings.
+     */
+    private readonly sharedNativeEncoder;
+    /**
+     * Flag indicating if the current environment is Chromium.
+     * This is used for performance optimizations, because Chromium's TextEncoder/TextDecoder has a relatively
+     * large marshalling overhead for small strings.
+     */
+    private readonly isChromium;
+    /**
+     * Constructs a new OutputByteBuffer instance.
+     */
+    constructor();
+    /**
+     * Writes a 8-bit unsigned integer to the buffer.
+     *
+     * @param value Value to write.
+     * @returns Number of bytes written to the buffer.
+     */
+    writeUint8(value: number): number;
+    /**
+     * Writes a 16-bit unsigned integer to the buffer.
+     *
+     * @param value Value to write.
+     * @returns Number of bytes written to the buffer.
+     */
+    writeUint16(value: number): number;
+    /**
+     * Writes a 32-bit unsigned integer to the buffer at a specific index.
+     *
+     * @param value Value to write.
+     * @param index Index to write the value to.
+     * @returns Number of bytes written to the buffer.
+     */
+    private writeUint32ToIndex;
+    /**
+     * Writes a 32-bit unsigned integer to the buffer.
+     *
+     * @param value Value to write.
+     * @returns Number of bytes written to the buffer.
+     */
+    writeUint32(value: number): number;
+    /**
+     * Writes a 32-bit signed integer to the buffer.
+     *
+     * @param value Value to write.
+     * @returns Number of bytes written to the buffer.
+     */
+    writeInt32(value: number): number;
+    /**
+     * Writes a Uint8Array to the byte buffer.
+     *
+     * @param buffer Buffer to write.
+     */
+    private writeBuffer;
+    /**
+     * Writes a string to the buffer.
+     *
+     * @param value Value to write.
+     * @returns Number of bytes written to the buffer.
+     */
+    writeString(value: string): number;
+    /**
+     * Writes chunks to the storage.
+     *
+     * @param storage Storage to write the chunks to.
+     * @param key Key to write the chunks to.
+     * @note For performance reasons, chunks are passed by reference and not copied.
+     * @throws If the storage write operation throws.
+     */
+    writeChunksToStorage(storage: Storage, key: string): Promise<void>;
+    /**
+     * Writes an 'optimized' unsigned integer to the buffer.
+     * 'Optimized' means smaller storage usage for smaller numbers.
+     * Except for the last byte, each byte's most significant bit is a flag indicating if there are more bytes.
+     *
+     * @param value Value to write.
+     * @returns Number of bytes written to the buffer.
+     * @throws If the value exceeds the 29-bit limit.
+     */
+    writeOptimizedUint(value: number): number;
+    /**
+     * Gets the current offset in the buffer for writing.
+     *
+     * @returns Current offset in the buffer for writing.
+     */
+    get currentOffset(): number;
+    /**
+     * Gets the chunks of the buffer.
+     *
+     * @returns Chunks of the buffer.
+     */
+    getChunks(): Uint8Array[];
+}

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

@@ -0,0 +1,46 @@
+/**
+ * @file Position provider class.
+ */
+/**
+ * Represents a position in the source code.
+ */
+export interface Position {
+    /**
+     * 1-based line number
+     */
+    line: number;
+    /**
+     * 1-based column number
+     */
+    column: number;
+}
+/**
+ * Class responsible for converting a character offset in source code into a line and column position.
+ * This conversion is particularly needed in linters and VSCode extensions,
+ * where line and column numbers are more human-friendly and intuitive than character offsets.
+ * Moreover, the VSCode diagnostics API does not directly support character offsets,
+ * it also requires line and column numbers.
+ */
+export declare class PositionProvider {
+    /**
+     * Maps a character offset to a line number.
+     */
+    private offsetToLine;
+    /**
+     * Maps a line number to the starting character offset of that line.
+     */
+    private lineStartOffsets;
+    /**
+     * Constructs a new PositionProvider instance.
+     *
+     * @param sourceCode The source code as a string.
+     */
+    constructor(sourceCode: string);
+    /**
+     * 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

@@ -0,0 +1,94 @@
+/**
+ * @file Utility functions for working with quotes
+ */
+/**
+ * Set of all possible quote characters supported by the library
+ */
+export declare const QUOTE_SET: Set<string>;
+/**
+ * Possible quote types for scriptlet parameters
+ */
+export declare const QuoteType: {
+    /**
+     * No quotes at all
+     */
+    readonly None: "none";
+    /**
+     * Single quotes (`'`)
+     */
+    readonly Single: "single";
+    /**
+     * Double quotes (`"`)
+     */
+    readonly Double: "double";
+    /**
+     * Backtick quotes (`` ` ``)
+     */
+    readonly Backtick: "backtick";
+};
+export type QuoteType = typeof QuoteType[keyof typeof QuoteType];
+/**
+ * Utility functions for working with quotes
+ */
+export declare class QuoteUtils {
+    /**
+     * Escape all unescaped occurrences of the character
+     *
+     * @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
+     *
+     * @param string String to unescape
+     * @param char Character to unescape
+     * @returns Unescaped string
+     */
+    static unescapeSingleEscapedOccurrences(string: string, char: string): string;
+    /**
+     * Get quote type of the string
+     *
+     * @param string String to check
+     * @returns Quote type of the string
+     */
+    static getStringQuoteType(string: string): QuoteType;
+    /**
+     * 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
+     */
+    static setStringQuoteType(string: string, quoteType: QuoteType): string;
+    /**
+     * Removes bounding quotes from a string, if any
+     *
+     * @param string Input string
+     * @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
+     */
+    static removeQuotesAndUnescape(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;
+}

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

@@ -0,0 +1,54 @@
+/**
+ * @file Regular expression utilities
+ */
+export declare const REGEX_START = "^";
+export declare const REGEX_END = "$";
+export declare const REGEX_ANY_CHARACTERS: string;
+export declare const ADBLOCK_URL_START: string;
+export declare const ADBLOCK_URL_START_REGEX = "^(http|https|ws|wss)://([a-z0-9-_.]+\\.)?";
+export declare const ADBLOCK_URL_SEPARATOR = "^";
+export declare const ADBLOCK_URL_SEPARATOR_REGEX = "([^ a-zA-Z0-9.%_-]|$)";
+export declare const ADBLOCK_WILDCARD = "*";
+export declare const ADBLOCK_WILDCARD_REGEX: string;
+export declare const REGEX_NEGATION_PREFIX = "^((?!";
+export declare const REGEX_NEGATION_SUFFIX = ").)*$";
+/**
+ * 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
+ */
+export declare class RegExpUtils {
+    /**
+     * Checks whether a string possibly is a RegExp pattern.
+     * Flags are not supported.
+     *
+     * 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
+     */
+    static isRegexPattern(pattern: string): boolean;
+    /**
+     * Negates a RegExp pattern. Technically, this method wraps the pattern in `^((?!` and `).)*$`.
+     *
+     * RegExp modifiers are not supported.
+     *
+     * @param pattern Pattern to negate (can be wrapped in slashes or not)
+     * @returns Negated RegExp pattern
+     */
+    static negateRegexPattern(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
+     *
+     * @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}
+     */
+    static patternToRegexp(pattern: string): string;
+}

package/dist/types/utils/storage-interface.d.ts

@@ -0,0 +1,23 @@
+/**
+ * @file Represents a storage interface for reading and writing data.
+ */
+/**
+ * Represents a storage interface for reading and writing data.
+ */
+export interface Storage<K = string, V = unknown> {
+    /**
+     * Writes the given data to the storage with the specified key.
+     *
+     * @param key The key to identify the data in the storage.
+     * @param chunks The data to write to the storage.
+     * @returns A promise that resolves when the write operation is complete.
+     */
+    set(key: K, data: V): Promise<void>;
+    /**
+     * Reads the data from the storage with the specified key.
+     *
+     * @param key The key to identify the data in the storage.
+     * @returns A promise that resolves with the data read from the storage.
+     */
+    get(key: K): Promise<V | undefined>;
+}