@adguard/agtree 3.4.3 → 4.0.0

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

@@ -1,30 +0,0 @@
-import { type HostRule } from '../../nodes/index.js';
-import { type OutputByteBuffer } from '../../utils/output-byte-buffer.js';
-import { BaseSerializer } from '../base-serializer.js';
-/**
- * `HostRuleSerializer` is responsible for serializing hosts-like rules.
- *
- * HostRule is a structure for simple host-level rules (i.e. /etc/hosts syntax).
- * It also supports "just domain" syntax. In this case, the IP will be set to 0.0.0.0.
- *
- * Rules syntax looks like this:
- * ```text
- * IP_address canonical_hostname [aliases...]
- * ```
- *
- * @example
- * `192.168.1.13 bar.mydomain.org bar` -- ipv4
- * `ff02::1 ip6-allnodes` -- ipv6
- * `::1 localhost ip6-localhost ip6-loopback` -- ipv6 aliases
- * `example.org` -- "just domain" syntax
- * @see {@link http://man7.org/linux/man-pages/man5/hosts.5.html}
- */
-export declare class HostRuleSerializer extends BaseSerializer {
-    /**
-     * Serializes a host rule node to binary format.
-     *
-     * @param node Node to serialize.
-     * @param buffer ByteBuffer for writing binary data.
-     */
-    static serialize(node: HostRule, buffer: OutputByteBuffer): void;
-}

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

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

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

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

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

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

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

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

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

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

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

@@ -1,146 +0,0 @@
-/**
- * @file Input byte buffer for reading binary data.
- */
-import { ByteBuffer } from './byte-buffer.js';
-import { type Storage } from './storage-interface.js';
-/**
- * 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

@@ -1,7 +0,0 @@
-/**
- * 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/output-byte-buffer.d.ts

@@ -1,132 +0,0 @@
-import { ByteBuffer } from './byte-buffer.js';
-import { type Storage } from './storage-interface.js';
-/**
- * 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/storage-interface.d.ts

@@ -1,23 +0,0 @@
-/**
- * @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 data 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>;
-}

package/dist/types/utils/text-decoder-polyfill.d.ts

@@ -1,14 +0,0 @@
-/**
- * @file Optimized utility for decoding strings from byte sequences.
- */
-/**
- * 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}
- */
-export declare const decodeTextPolyfill: (buffer: Uint8Array, start?: number, end?: number) => string;

package/dist/types/utils/text-encoder-polyfill.d.ts

@@ -1,18 +0,0 @@
-/**
- * @file Utility for encoding strings to byte sequences.
- */
-export interface TextEncoderPolyfillResult {
-    readonly written: number;
-    readonly read: number;
-}
-/**
- * Encodes an UTF-8 string into a byte sequence according to the WHATWG spec.
- *
- * @param str String to encode.
- * @param buffer Buffer to write the encoded bytes to.
- * @returns Number of bytes written to the buffer.
- * @see {@link https://encoding.spec.whatwg.org/#utf-8-encoder}
- * @note Bytes written maybe larger than the string length, but never smaller.
- * For example, the string '你好' has a length of 2, but its byte representation has a length of 6.
- */
-export declare const encodeIntoPolyfill: (str: string, buffer: Uint8Array) => TextEncoderPolyfillResult;

package/dist/utils/binary-schema-version.js

@@ -1,17 +0,0 @@
-/*
- * AGTree v3.4.3 (build date: Thu, 11 Dec 2025 13:43:19 GMT)
- * (c) 2025 Adguard Software Ltd.
- * Released under the MIT license
- * https://github.com/AdguardTeam/tsurlfilter/tree/master/packages/agtree#readme
- */
-/**
- * @file Binary schema version.
- */
-/**
- * Binary schema version.
- * This version number is used to ensure that the binary format is compatible with the current library version.
- * We increment this number if the serialized format changes in a way that is not backwards-compatible.
- */
-const BINARY_SCHEMA_VERSION = 1;
-
-export { BINARY_SCHEMA_VERSION };

package/dist/utils/byte-buffer.js

@@ -1,91 +0,0 @@
-/*
- * AGTree v3.4.3 (build date: Thu, 11 Dec 2025 13:43:19 GMT)
- * (c) 2025 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 };