@adguard/agtree 3.4.1 → 4.0.0

package/dist/utils/input-byte-buffer.js

@@ -1,266 +0,0 @@
-/*
- * AGTree v3.4.1 (build date: Fri, 28 Nov 2025 11:48:53 GMT)
- * (c) 2025 Adguard Software Ltd.
- * Released under the MIT license
- * https://github.com/AdguardTeam/tsurlfilter/tree/master/packages/agtree#readme
- */
-import { ByteBuffer } from './byte-buffer.js';
-import { isArrayOfUint8Arrays } from './type-guards.js';
-import { isChromium } from './is-chromium.js';
-import { decodeTextPolyfill } from './text-decoder-polyfill.js';
-import { BINARY_SCHEMA_VERSION } from './binary-schema-version.js';
-import { BinarySchemaMismatchError } from '../errors/binary-schema-mismatch-error.js';
-
-/* eslint-disable max-len */
-/* eslint-disable no-plusplus */
-/* eslint-disable no-bitwise */
-/**
- * @file Input byte buffer for reading binary data.
- */
-/**
- * Input byte buffer for reading binary data.
- *
- * @note Internally, this class uses a {@link ByteBuffer} instance, just providing a convenient API for reading data.
- */
-class InputByteBuffer extends ByteBuffer {
-    /**
-     * Current offset in the buffer for reading.
-     */
-    offset;
-    /**
-     * Shared native decoder for decoding strings.
-     */
-    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.
-     */
-    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, cloneChunks = false, initialOffset = 0) {
-        super(chunks, cloneChunks);
-        // TODO: Consider accepting an empty array of chunks
-        // Check binary schema version
-        if (chunks.length === 0) {
-            throw new Error('No data in the buffer');
-        }
-        const actualVersion = this.readSchemaVersion();
-        if (actualVersion !== BINARY_SCHEMA_VERSION) {
-            throw new BinarySchemaMismatchError(BINARY_SCHEMA_VERSION, actualVersion);
-        }
-        // Throw an error if the initial offset is out of bounds
-        if (initialOffset < 0 || initialOffset > this.chunks.length * ByteBuffer.CHUNK_SIZE) {
-            throw new Error(`Invalid offset: ${initialOffset}`);
-        }
-        // Schema version is always stored at the beginning of the buffer - skip it, because it is already processed
-        this.offset = Math.max(4, initialOffset);
-        this.sharedNativeDecoder = new TextDecoder();
-        this.isChromium = isChromium();
-    }
-    /**
-     * 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 async createFromStorage(storage, key) {
-        const chunks = await storage.get(key);
-        if (!isArrayOfUint8Arrays(chunks)) {
-            throw new Error('The data from storage is not an array of Uint8Arrays');
-        }
-        return new InputByteBuffer(chunks);
-    }
-    /**
-     * Reads a 8-bit unsigned integer from the buffer.
-     *
-     * @returns 8-bit unsigned integer from the buffer.
-     */
-    readUint8() {
-        const result = this.readByte(this.offset++) ?? 0;
-        return result;
-    }
-    /**
-     * Reads a 16-bit unsigned integer from the buffer.
-     *
-     * @returns 16-bit unsigned integer from the buffer.
-     */
-    readUint16() {
-        const result = (((this.readByte(this.offset++) ?? 0) << 8)
-            | ((this.readByte(this.offset++) ?? 0))) >>> 0;
-        return result;
-    }
-    /**
-     * 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.
-     */
-    readUint32FromIndex(index) {
-        const result = (((this.readByte(index) ?? 0) << 24)
-            | ((this.readByte(index + 1) ?? 0) << 16)
-            | ((this.readByte(index + 2) ?? 0) << 8)
-            | ((this.readByte(index + 3) ?? 0))) >>> 0;
-        return result;
-    }
-    /**
-     * Reads a 32-bit unsigned integer from the buffer.
-     *
-     * @returns 32-bit unsigned integer from the buffer.
-     */
-    readUint32() {
-        const result = this.readUint32FromIndex(this.offset);
-        this.offset += 4;
-        return result;
-    }
-    /**
-     * 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() {
-        return this.readUint32FromIndex(0);
-    }
-    /**
-     * Reads a 32-bit signed integer from the buffer.
-     *
-     * @returns 32-bit signed integer from the buffer.
-     */
-    readInt32() {
-        const result = this.readUint32();
-        return result > 0x7fffffff ? result - 0x100000000 : result;
-    }
-    /**
-     * 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() {
-        let result = 0;
-        let shift = 0;
-        while (shift <= 28) {
-            const byteValue = this.readByte(this.offset++) ?? 0;
-            result |= (byteValue & 0x7F) << shift;
-            shift += 7;
-            if ((byteValue & 0x80) === 0) {
-                break;
-            }
-        }
-        return result;
-    }
-    /**
-     * Reads a string from the buffer.
-     *
-     * @returns Decoded string from the buffer.
-     */
-    readString() {
-        const length = this.readOptimizedUint();
-        let chunkIndex = this.offset >>> 0x000F;
-        const chunkOffset = this.offset & 0x7FFF; // offset is only relevant for the first chunk
-        const endOffset = chunkOffset + length;
-        // In most cases, the string is stored in the current chunk
-        if (endOffset < ByteBuffer.CHUNK_SIZE) {
-            this.offset += length;
-            if (this.isChromium) {
-                return decodeTextPolyfill(this.chunks[chunkIndex], chunkOffset, endOffset);
-            }
-            return this.sharedNativeDecoder.decode(this.chunks[chunkIndex].subarray(chunkOffset, endOffset));
-        }
-        const result = [];
-        result.push(this.sharedNativeDecoder.decode(this.chunks[chunkIndex++].subarray(chunkOffset), { stream: true }));
-        let remaining = length - (ByteBuffer.CHUNK_SIZE - chunkOffset);
-        while (remaining) {
-            const chunk = this.chunks[chunkIndex];
-            if (!chunk) {
-                break;
-            }
-            const toRead = Math.min(remaining, ByteBuffer.CHUNK_SIZE);
-            result.push(this.sharedNativeDecoder.decode(chunk.subarray(0, toRead), { stream: true }));
-            remaining -= toRead;
-            chunkIndex += 1;
-        }
-        // Finish decoding, if something is left
-        result.push(this.sharedNativeDecoder.decode());
-        this.offset += length;
-        return result.join('');
-    }
-    /**
-     * Reads a 8-bit unsigned integer from the buffer without advancing the offset.
-     *
-     * @returns 8-bit unsigned integer from the buffer.
-     */
-    peekUint8() {
-        return this.readByte(this.offset) ?? 0;
-    }
-    /**
-     * 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) {
-        const result = this.readUint8();
-        if (result !== value) {
-            throw new Error(`Expected ${value}, but got ${result}`);
-        }
-    }
-    /**
-     * 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, cloneChunks = false) {
-        return new InputByteBuffer(this.chunks, cloneChunks, initialOffset);
-    }
-    /**
-     * Gets the current offset in the buffer for reading.
-     *
-     * @returns Current offset in the buffer for reading.
-     */
-    get currentOffset() {
-        return this.offset;
-    }
-    /**
-     * Gets the capacity of the buffer.
-     *
-     * @returns Capacity of the buffer.
-     */
-    get capacity() {
-        return this.chunks.length * ByteBuffer.CHUNK_SIZE;
-    }
-    /**
-     * Gets the chunks of the buffer.
-     *
-     * @returns Chunks of the buffer.
-     */
-    getChunks() {
-        return this.chunks;
-    }
-}
-
-export { InputByteBuffer };

package/dist/utils/is-chromium.js

@@ -1,20 +0,0 @@
-/*
- * AGTree v3.4.1 (build date: Fri, 28 Nov 2025 11:48:53 GMT)
- * (c) 2025 Adguard Software Ltd.
- * Released under the MIT license
- * https://github.com/AdguardTeam/tsurlfilter/tree/master/packages/agtree#readme
- */
-/**
- * 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}
- */
-const isChromium = () => {
-    return typeof window !== 'undefined'
-        && (Object.prototype.hasOwnProperty.call(window, 'chrome')
-            || (typeof window.navigator !== 'undefined'
-                && /chrome/i.test(window.navigator.userAgent)));
-};
-
-export { isChromium };

package/dist/utils/output-byte-buffer.js

@@ -1,231 +0,0 @@
-/*
- * AGTree v3.4.1 (build date: Fri, 28 Nov 2025 11:48:53 GMT)
- * (c) 2025 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.js';
-import { ByteBuffer } from './byte-buffer.js';
-import { isChromium } from './is-chromium.js';
-import { encodeIntoPolyfill } from './text-encoder-polyfill.js';
-
-/* 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;
-    }
-    /**
-     * Gets the chunks of the buffer.
-     *
-     * @returns Chunks of the buffer.
-     */
-    getChunks() {
-        return this.chunks;
-    }
-}
-
-export { OutputByteBuffer };

package/dist/utils/text-decoder-polyfill.js

@@ -1,107 +0,0 @@
-/*
- * AGTree v3.4.1 (build date: Fri, 28 Nov 2025 11:48:53 GMT)
- * (c) 2025 Adguard Software Ltd.
- * Released under the MIT license
- * https://github.com/AdguardTeam/tsurlfilter/tree/master/packages/agtree#readme
- */
-import { EMPTY } from './constants.js';
-
-/* eslint-disable no-plusplus */
-/* eslint-disable no-bitwise */
-/**
- * @file Optimized utility for decoding strings from byte sequences.
- */
-const REPLACEMENT_CHAR = String.fromCodePoint(0xFFFD);
-/**
- * Decodes a byte sequence into an UTF-8 string according to the WHATWG spec.
- * Optimized for performance.
- *
- * @param buffer Buffer to read the bytes from.
- * @param start Start offset in the buffer.
- * @param end End offset in the buffer.
- * @returns Decoded string.
- * @see {@link https://encoding.spec.whatwg.org/#utf-8-decoder}
- */
-const decodeTextPolyfill = (buffer, start = 0, end = -1) => {
-    let codePoint = 0;
-    let bytesSeen = 0;
-    let bytesNeeded = 0;
-    let lowerBoundary = 0x0080;
-    let upperBoundary = 0x00BF;
-    let i = start;
-    const { length } = buffer;
-    const realEnd = end === -1 ? length : Math.min(end, length);
-    const result = new Array(realEnd - start);
-    let resIdx = 0;
-    for (; i < realEnd; i += 1) {
-        const byte = buffer[i];
-        if (bytesNeeded === 0) {
-            if (byte <= 0x007F) {
-                codePoint = byte & 0x00FF;
-            }
-            else if (byte >= 0x00C2 && byte <= 0x00DF) {
-                bytesNeeded = 1;
-                codePoint = byte & 0x001F;
-            }
-            else if (byte >= 0x00E0 && byte <= 0x00EF) {
-                bytesNeeded = 2;
-                codePoint = byte & 0x000F;
-                if (byte === 0x00E0) {
-                    // Adjust lower boundary for exclusion of overlong sequences
-                    lowerBoundary = 0x00A0;
-                }
-                else if (byte === 0x00ED) {
-                    // Adjust upper boundary to exclude surrogates
-                    upperBoundary = 0x009F;
-                }
-            }
-            else if (byte >= 0x00F0 && byte <= 0x00F4) {
-                bytesNeeded = 3;
-                codePoint = byte & 0x0007;
-                if (byte === 0x00F0) {
-                    // Adjust lower boundary for exclusion of overlong sequences
-                    lowerBoundary = 0x0090;
-                }
-                else if (byte === 0x00F4) {
-                    // Adjust upper boundary to limit to valid Unicode range
-                    upperBoundary = 0x008F;
-                }
-            }
-            else {
-                // For bytes that are not valid initial bytes of UTF-8 sequences, add replacement character
-                result[resIdx++] = REPLACEMENT_CHAR;
-                continue;
-            }
-        }
-        else {
-            // For subsequent bytes in a multibyte sequence, check if the byte is in the expected range
-            if (!(byte >= lowerBoundary && byte <= upperBoundary)) {
-                // Reset the state for illegal sequences and add replacement character
-                bytesNeeded = 0;
-                bytesSeen = 0;
-                lowerBoundary = 0x0080;
-                upperBoundary = 0x00BF;
-                result[resIdx++] = REPLACEMENT_CHAR;
-                // Decrement `i` to re-evaluate this byte as the start of a new sequence
-                i -= 1;
-                continue;
-            }
-            codePoint = (codePoint << 6) | (byte & 0x003F);
-            // Reset boundaries for next bytes
-            lowerBoundary = 0x0080;
-            upperBoundary = 0x00BF;
-            bytesSeen += 1;
-        }
-        if (bytesSeen === bytesNeeded) {
-            // Complete the code point assembly and add it to the result
-            result[resIdx++] = String.fromCodePoint(codePoint);
-            // Reset for the next character
-            bytesNeeded = 0;
-            bytesSeen = 0;
-            codePoint = 0;
-        }
-    }
-    return result.join(EMPTY);
-};
-
-export { decodeTextPolyfill };