@adguard/agtree 2.1.2 → 3.0.0-alpha.1

package/dist/esm/utils/multi-value-map.mjs

@@ -0,0 +1,33 @@
+/*
+ * AGTree v3.0.0-alpha.1 (build date: Tue, 12 Nov 2024 16:11:58 GMT)
+ * (c) 2024 Adguard Software Ltd.
+ * Released under the MIT license
+ * https://github.com/AdguardTeam/tsurlfilter/tree/master/packages/agtree#readme
+ */
+import { isUndefined } from './type-guards.mjs';
+
+/**
+ * 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
+ */
+class MultiValueMap extends Map {
+    /**
+     * 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, ...values) {
+        let currentValues = super.get(key);
+        if (isUndefined(currentValues)) {
+            currentValues = [];
+            super.set(key, values);
+        }
+        currentValues.push(...values);
+    }
+}
+
+export { MultiValueMap };

package/dist/esm/utils/output-byte-buffer.mjs

@@ -0,0 +1,223 @@
+/*
+ * AGTree v3.0.0-alpha.1 (build date: Tue, 12 Nov 2024 16:11:58 GMT)
+ * (c) 2024 Adguard Software Ltd.
+ * Released under the MIT license
+ * https://github.com/AdguardTeam/tsurlfilter/tree/master/packages/agtree#readme
+ */
+import { BINARY_SCHEMA_VERSION } from './binary-schema-version.mjs';
+import { ByteBuffer } from './byte-buffer.mjs';
+import { isChromium } from './is-chromium.mjs';
+import { encodeIntoPolyfill } from './text-encoder-polyfill.mjs';
+
+/* eslint-disable no-plusplus */
+/* eslint-disable no-bitwise */
+/**
+ * @file Output byte buffer for writing binary data.
+ */
+/**
+ * Output byte buffer for writing binary data.
+ *
+ * @note Internally, this class uses a {@link ByteBuffer} instance, just providing a convenient API for reading data.
+ */
+class OutputByteBuffer extends ByteBuffer {
+    /**
+     * Current offset in the buffer for writing.
+     */
+    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).
+     */
+    static ENCODER_BUFFER_SIZE = 8192;
+    /**
+     * 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).
+     */
+    static SHORT_STRING_THRESHOLD = 2048; // 8192 / 4
+    /**
+     * 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 = 0x1FFFFFFF;
+    /**
+     * Shared buffer for encoding strings.
+     */
+    sharedBuffer;
+    /**
+     * Shared native encoder for encoding strings.
+     */
+    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.
+     */
+    isChromium;
+    /**
+     * Constructs a new OutputByteBuffer instance.
+     */
+    // TODO: add chunks as a parameter, if ever needed
+    constructor() {
+        super();
+        this.sharedBuffer = new Uint8Array(OutputByteBuffer.ENCODER_BUFFER_SIZE);
+        this.sharedNativeEncoder = new TextEncoder();
+        this.isChromium = isChromium();
+        // write the schema version at the beginning of the buffer
+        this.writeUint32ToIndex(BINARY_SCHEMA_VERSION, 0);
+        this.offset = 4; // schema version is already written
+    }
+    /**
+     * Writes a 8-bit unsigned integer to the buffer.
+     *
+     * @param value Value to write.
+     * @returns Number of bytes written to the buffer.
+     */
+    writeUint8(value) {
+        this.writeByte(this.offset++, value);
+        return 1;
+    }
+    /**
+     * Writes a 16-bit unsigned integer to the buffer.
+     *
+     * @param value Value to write.
+     * @returns Number of bytes written to the buffer.
+     */
+    writeUint16(value) {
+        this.writeByte(this.offset++, value >> 8);
+        this.writeByte(this.offset++, value);
+        return 2;
+    }
+    /**
+     * 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.
+     */
+    writeUint32ToIndex(value, index) {
+        this.writeByte(index, value >> 24);
+        this.writeByte(index + 1, value >> 16);
+        this.writeByte(index + 2, value >> 8);
+        this.writeByte(index + 3, value);
+        return 4;
+    }
+    /**
+     * Writes a 32-bit unsigned integer to the buffer.
+     *
+     * @param value Value to write.
+     * @returns Number of bytes written to the buffer.
+     */
+    writeUint32(value) {
+        this.writeUint32ToIndex(value, this.offset);
+        this.offset += 4;
+        return 4;
+    }
+    /**
+     * Writes a 32-bit signed integer to the buffer.
+     *
+     * @param value Value to write.
+     * @returns Number of bytes written to the buffer.
+     */
+    writeInt32(value) {
+        return this.writeUint32(value ? value >>> 0 : 0);
+    }
+    /**
+     * Writes a Uint8Array to the byte buffer.
+     *
+     * @param buffer Buffer to write.
+     */
+    writeBuffer(buffer) {
+        const { length } = buffer;
+        this.ensureCapacity(this.offset + length);
+        let chunkIndex = this.offset >>> 0x000F;
+        let chunkOffset = this.offset & 0x7FFF;
+        let remainingBytes = length;
+        while (remainingBytes) {
+            const leftInChunk = ByteBuffer.CHUNK_SIZE - chunkOffset;
+            const bytesToWrite = Math.min(remainingBytes, leftInChunk);
+            this.chunks[chunkIndex].set(buffer.subarray(length - remainingBytes, length - remainingBytes + bytesToWrite), chunkOffset);
+            remainingBytes -= bytesToWrite;
+            chunkIndex += 1;
+            chunkOffset = 0;
+        }
+    }
+    /**
+     * Writes a string to the buffer.
+     *
+     * @param value Value to write.
+     * @returns Number of bytes written to the buffer.
+     */
+    writeString(value) {
+        const start = this.offset;
+        if (value.length <= OutputByteBuffer.SHORT_STRING_THRESHOLD) {
+            let bytesWritten;
+            if (this.isChromium) {
+                bytesWritten = encodeIntoPolyfill(value, this.sharedBuffer).written ?? 0;
+            }
+            else {
+                bytesWritten = this.sharedNativeEncoder.encodeInto(value, this.sharedBuffer).written ?? 0;
+            }
+            this.writeOptimizedUint(bytesWritten);
+            this.writeBuffer(this.sharedBuffer.subarray(0, bytesWritten));
+            this.offset += bytesWritten;
+            return this.offset - start;
+        }
+        // TODO: Optimize for long strings, if needed. Not a common case for our use case
+        const buffer = this.sharedNativeEncoder.encode(value);
+        const bytesWritten = buffer.length;
+        this.writeOptimizedUint(bytesWritten);
+        this.writeBuffer(buffer);
+        this.offset += bytesWritten;
+        return this.offset - start;
+    }
+    /**
+     * 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.
+     */
+    async writeChunksToStorage(storage, key) {
+        await storage.set(key, this.chunks);
+    }
+    /**
+     * 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) {
+        if (value < 0 || value > OutputByteBuffer.MAX_OPTIMIZED_UINT) {
+            throw new Error('Value exceeds 29-bit limit');
+        }
+        let remainingValue = value;
+        const startOffset = this.offset;
+        while (remainingValue >= 0x80) {
+            const byteValue = remainingValue & 0x7F;
+            remainingValue >>>= 7;
+            this.writeByte(this.offset++, byteValue | 0x80);
+        }
+        this.writeByte(this.offset++, remainingValue);
+        return this.offset - startOffset;
+    }
+    /**
+     * Gets the current offset in the buffer for writing.
+     *
+     * @returns Current offset in the buffer for writing.
+     */
+    get currentOffset() {
+        return this.offset;
+    }
+}
+
+export { OutputByteBuffer };

package/dist/esm/utils/position-provider.mjs

@@ -0,0 +1,73 @@
+/*
+ * AGTree v3.0.0-alpha.1 (build date: Tue, 12 Nov 2024 16:11:58 GMT)
+ * (c) 2024 Adguard Software Ltd.
+ * Released under the MIT license
+ * https://github.com/AdguardTeam/tsurlfilter/tree/master/packages/agtree#readme
+ */
+import { LF, FF, CR } from './constants.mjs';
+
+/**
+ * @file Position provider class.
+ */
+/**
+ * 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.
+ */
+class PositionProvider {
+    /**
+     * Maps a character offset to a line number.
+     */
+    offsetToLine;
+    /**
+     * Maps a line number to the starting character offset of that line.
+     */
+    lineStartOffsets;
+    /**
+     * Constructs a new PositionProvider instance.
+     *
+     * @param sourceCode The source code as a string.
+     */
+    constructor(sourceCode) {
+        this.offsetToLine = [];
+        this.lineStartOffsets = [0];
+        let currentLine = 0;
+        for (let i = 0; i < sourceCode.length; i += 1) {
+            this.offsetToLine[i] = currentLine;
+            // Handle different types of line breaks: LF, FF, and CR
+            if (sourceCode[i] === LF || sourceCode[i] === FF || sourceCode[i] === CR) {
+                currentLine += 1;
+                this.lineStartOffsets[currentLine] = (sourceCode[i] === CR && sourceCode[i + 1] === LF)
+                    ? i + 2
+                    : i + 1;
+                if (sourceCode[i] === CR && sourceCode[i + 1] === LF) {
+                    // Skip the '\n' in a '\r\n' sequence
+                    i += 1;
+                }
+            }
+        }
+        // Handle the case where the last offset is at the end of the source code
+        this.offsetToLine[sourceCode.length] = currentLine;
+    }
+    /**
+     * 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) {
+        if (offset < 0 || offset > this.offsetToLine.length - 1) {
+            return null;
+        }
+        const line = this.offsetToLine[offset];
+        const lineStartOffset = this.lineStartOffsets[line];
+        return {
+            line: line + 1,
+            column: offset - lineStartOffset + 1,
+        };
+    }
+}
+
+export { PositionProvider };

package/dist/esm/utils/quotes.mjs

@@ -0,0 +1,215 @@
+/*
+ * AGTree v3.0.0-alpha.1 (build date: Tue, 12 Nov 2024 16:11:58 GMT)
+ * (c) 2024 Adguard Software Ltd.
+ * Released under the MIT license
+ * https://github.com/AdguardTeam/tsurlfilter/tree/master/packages/agtree#readme
+ */
+import { ESCAPE_CHARACTER, SINGLE_QUOTE, DOUBLE_QUOTE, BACKTICK_QUOTE, COMMA, SPACE, EMPTY } from './constants.mjs';
+
+/**
+ * @file Utility functions for working with quotes
+ */
+/**
+ * Set of all possible quote characters supported by the library
+ */
+const QUOTE_SET = new Set([
+    SINGLE_QUOTE,
+    DOUBLE_QUOTE,
+    BACKTICK_QUOTE,
+]);
+/**
+ * Possible quote types for scriptlet parameters
+ */
+var QuoteType;
+(function (QuoteType) {
+    /**
+     * No quotes at all
+     */
+    QuoteType["None"] = "none";
+    /**
+     * Single quotes (`'`)
+     */
+    QuoteType["Single"] = "single";
+    /**
+     * Double quotes (`"`)
+     */
+    QuoteType["Double"] = "double";
+    /**
+     * Backtick quotes (`` ` ``)
+     */
+    QuoteType["Backtick"] = "backtick";
+})(QuoteType || (QuoteType = {}));
+/**
+ * Utility functions for working with quotes
+ */
+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, char) {
+        let result = EMPTY;
+        for (let i = 0; i < string.length; i += 1) {
+            if (string[i] === char && (i === 0 || string[i - 1] !== ESCAPE_CHARACTER)) {
+                result += ESCAPE_CHARACTER;
+            }
+            result += string[i];
+        }
+        return result;
+    }
+    /**
+     * Unescape all single escaped occurrences of the character
+     *
+     * @param string String to unescape
+     * @param char Character to unescape
+     * @returns Unescaped string
+     */
+    static unescapeSingleEscapedOccurrences(string, char) {
+        let result = EMPTY;
+        for (let i = 0; i < string.length; i += 1) {
+            if (string[i] === char
+                && string[i - 1] === ESCAPE_CHARACTER
+                && (i === 1 || string[i - 2] !== ESCAPE_CHARACTER)) {
+                result = result.slice(0, -1);
+            }
+            result += string[i];
+        }
+        return result;
+    }
+    /**
+     * Get quote type of the string
+     *
+     * @param string String to check
+     * @returns Quote type of the string
+     */
+    static getStringQuoteType(string) {
+        // Don't check 1-character strings to avoid false positives
+        if (string.length > 1) {
+            if (string.startsWith(SINGLE_QUOTE) && string.endsWith(SINGLE_QUOTE)) {
+                return QuoteType.Single;
+            }
+            if (string.startsWith(DOUBLE_QUOTE) && string.endsWith(DOUBLE_QUOTE)) {
+                return QuoteType.Double;
+            }
+            if (string.startsWith(BACKTICK_QUOTE) && string.endsWith(BACKTICK_QUOTE)) {
+                return QuoteType.Backtick;
+            }
+        }
+        return QuoteType.None;
+    }
+    /**
+     * 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, quoteType) {
+        const actualQuoteType = QuoteUtils.getStringQuoteType(string);
+        switch (quoteType) {
+            case QuoteType.None:
+                if (actualQuoteType === QuoteType.Single) {
+                    return QuoteUtils.escapeUnescapedOccurrences(string.slice(1, -1), SINGLE_QUOTE);
+                }
+                if (actualQuoteType === QuoteType.Double) {
+                    return QuoteUtils.escapeUnescapedOccurrences(string.slice(1, -1), DOUBLE_QUOTE);
+                }
+                if (actualQuoteType === QuoteType.Backtick) {
+                    return QuoteUtils.escapeUnescapedOccurrences(string.slice(1, -1), BACKTICK_QUOTE);
+                }
+                return string;
+            case QuoteType.Single:
+                if (actualQuoteType === QuoteType.None) {
+                    return SINGLE_QUOTE + QuoteUtils.escapeUnescapedOccurrences(string, SINGLE_QUOTE) + SINGLE_QUOTE;
+                }
+                if (actualQuoteType === QuoteType.Double) {
+                    return SINGLE_QUOTE
+                        + QuoteUtils.escapeUnescapedOccurrences(QuoteUtils.unescapeSingleEscapedOccurrences(string.slice(1, -1), DOUBLE_QUOTE), SINGLE_QUOTE) + SINGLE_QUOTE;
+                }
+                if (actualQuoteType === QuoteType.Backtick) {
+                    return SINGLE_QUOTE
+                        + QuoteUtils.escapeUnescapedOccurrences(QuoteUtils.unescapeSingleEscapedOccurrences(string.slice(1, -1), BACKTICK_QUOTE), SINGLE_QUOTE) + SINGLE_QUOTE;
+                }
+                return string;
+            case QuoteType.Double:
+                if (actualQuoteType === QuoteType.None) {
+                    return DOUBLE_QUOTE + QuoteUtils.escapeUnescapedOccurrences(string, DOUBLE_QUOTE) + DOUBLE_QUOTE;
+                }
+                if (actualQuoteType !== QuoteType.Double) {
+                    // eslint-disable-next-line max-len
+                    return DOUBLE_QUOTE
+                        + QuoteUtils.escapeUnescapedOccurrences(QuoteUtils.unescapeSingleEscapedOccurrences(string.slice(1, -1), SINGLE_QUOTE), DOUBLE_QUOTE) + DOUBLE_QUOTE;
+                }
+                return string;
+            case QuoteType.Backtick:
+                if (actualQuoteType === QuoteType.None) {
+                    // eslint-disable-next-line max-len
+                    return BACKTICK_QUOTE + QuoteUtils.escapeUnescapedOccurrences(string, BACKTICK_QUOTE) + BACKTICK_QUOTE;
+                }
+                if (actualQuoteType !== QuoteType.Backtick) {
+                    // eslint-disable-next-line max-len
+                    return BACKTICK_QUOTE
+                        + QuoteUtils.escapeUnescapedOccurrences(QuoteUtils.unescapeSingleEscapedOccurrences(string.slice(1, -1), SINGLE_QUOTE), BACKTICK_QUOTE) + BACKTICK_QUOTE;
+                }
+                return string;
+            default:
+                return string;
+        }
+    }
+    /**
+     * Removes bounding quotes from a string, if any
+     *
+     * @param string Input string
+     * @returns String without quotes
+     */
+    static removeQuotes(string) {
+        if (
+        // We should check for string length to avoid false positives
+        string.length > 1
+            && (string[0] === SINGLE_QUOTE || string[0] === DOUBLE_QUOTE || string[0] === BACKTICK_QUOTE)
+            && string[0] === string[string.length - 1]) {
+            return string.slice(1, -1);
+        }
+        return 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) {
+        if (
+        // We should check for string length to avoid false positives
+        string.length > 1
+            && (string[0] === SINGLE_QUOTE || string[0] === DOUBLE_QUOTE || string[0] === BACKTICK_QUOTE)
+            && string[0] === string[string.length - 1]) {
+            return QuoteUtils.unescapeSingleEscapedOccurrences(string.slice(1, -1), string[0]);
+        }
+        return 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, quoteType = QuoteType.Single, separator = `${COMMA}${SPACE}`) {
+        return strings
+            .map((s) => QuoteUtils.setStringQuoteType(s, quoteType))
+            .join(separator);
+    }
+}
+
+export { QUOTE_SET, QuoteType, QuoteUtils };