@adguard/agtree 2.2.0 → 3.0.0-alpha.2

package/dist/serializer/invalid-rule-error-node-serializer.js

@@ -0,0 +1,41 @@
+/*
+ * 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 { BaseSerializer } from './base-serializer.js';
+import { isUndefined } from '../utils/type-guards.js';
+import { NULL } from '../utils/constants.js';
+import { InvalidRuleErrorNodeMarshallingMap } from '../marshalling-utils/invalid-rule-error-node-common.js';
+import { BinaryTypeMarshallingMap } from '../marshalling-utils/misc/binary-type-common.js';
+
+/**
+ * Serializer for invalid rule error nodes.
+ */
+class InvalidRuleErrorNodeSerializer extends BaseSerializer {
+    /**
+     * Serializes an invalid rule error node to binary format.
+     *
+     * @param node Node to serialize.
+     * @param buffer ByteBuffer for writing binary data.
+     */
+    static serialize(node, buffer) {
+        buffer.writeUint8(BinaryTypeMarshallingMap.InvalidRuleErrorNode);
+        buffer.writeUint8(InvalidRuleErrorNodeMarshallingMap.Name);
+        buffer.writeString(node.name);
+        buffer.writeUint8(InvalidRuleErrorNodeMarshallingMap.Message);
+        buffer.writeString(node.message);
+        if (!isUndefined(node.start)) {
+            buffer.writeUint8(InvalidRuleErrorNodeMarshallingMap.Start);
+            buffer.writeUint32(node.start);
+        }
+        if (!isUndefined(node.end)) {
+            buffer.writeUint8(InvalidRuleErrorNodeMarshallingMap.End);
+            buffer.writeUint32(node.end);
+        }
+        buffer.writeUint8(NULL);
+    }
+}
+
+export { InvalidRuleErrorNodeSerializer };

package/dist/serializer/invalid-rule-serializer.js

@@ -0,0 +1,40 @@
+/*
+ * 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 { BaseSerializer } from './base-serializer.js';
+import { isUndefined } from '../utils/type-guards.js';
+import { NULL } from '../utils/constants.js';
+import { InvalidRuleErrorNodeSerializer } from './invalid-rule-error-node-serializer.js';
+import { InvalidRuleMarshallingMap } from '../marshalling-utils/invalid-rule-common.js';
+import { BinaryTypeMarshallingMap } from '../marshalling-utils/misc/binary-type-common.js';
+
+/**
+ * Serializer for invalid rule nodes.
+ */
+class InvalidRuleSerializer extends BaseSerializer {
+    /**
+     * Serializes an invalid rule node to binary format.
+     *
+     * @param node Node to serialize.
+     * @param buffer ByteBuffer for writing binary data.
+     */
+    static serialize(node, buffer) {
+        buffer.writeUint8(BinaryTypeMarshallingMap.InvalidRule);
+        buffer.writeUint8(InvalidRuleMarshallingMap.Error);
+        InvalidRuleErrorNodeSerializer.serialize(node.error, buffer);
+        if (!isUndefined(node.start)) {
+            buffer.writeUint8(InvalidRuleMarshallingMap.Start);
+            buffer.writeUint32(node.start);
+        }
+        if (!isUndefined(node.end)) {
+            buffer.writeUint8(InvalidRuleMarshallingMap.End);
+            buffer.writeUint32(node.end);
+        }
+        buffer.writeUint8(NULL);
+    }
+}
+
+export { InvalidRuleSerializer };

package/dist/serializer/misc/domain-list-serializer.js

@@ -0,0 +1,64 @@
+/*
+ * 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 { NULL, COMMA, PIPE } from '../../utils/constants.js';
+import { isUndefined } from '../../utils/type-guards.js';
+import { BaseSerializer } from '../base-serializer.js';
+import { ListItemsSerializer } from './list-items-serializer.js';
+import { DomainListMarshallingMap } from '../../marshalling-utils/misc/domain-list-common.js';
+import { BinaryTypeMarshallingMap } from '../../marshalling-utils/misc/binary-type-common.js';
+
+/**
+ * Value map for binary serialization. This helps to reduce the size of the serialized data,
+ * as it allows us to use a single byte to represent frequently used values.
+ *
+ * ! IMPORTANT: If you change values here, please update the {@link BINARY_SCHEMA_VERSION}!
+ *
+ * @note Only 256 values can be represented this way.
+ */
+const SEPARATOR_SERIALIZATION_MAP = new Map([
+    [COMMA, 0],
+    [PIPE, 1],
+]);
+/**
+ * `DomainListSerializer` is responsible for serializing a domain list.
+ *
+ * @example
+ * - If the rule is `example.com,~example.net##.ads`, the domain list is `example.com,~example.net`.
+ * - If the rule is `ads.js^$script,domains=example.com|~example.org`, the domain list is `example.com|~example.org`.
+ * This serializer is responsible for serializing these domain lists.
+ * @see {@link https://help.eyeo.com/adblockplus/how-to-write-filters#elemhide_domains}
+ */
+class DomainListSerializer extends BaseSerializer {
+    /**
+     * Serializes a domain list node to binary format.
+     *
+     * @param node Node to serialize.
+     * @param buffer ByteBuffer for writing binary data.
+     */
+    static serialize(node, buffer) {
+        buffer.writeUint8(BinaryTypeMarshallingMap.DomainListNode);
+        const separator = SEPARATOR_SERIALIZATION_MAP.get(node.separator);
+        if (isUndefined(separator)) {
+            throw new Error(`Invalid separator: ${node.separator}`);
+        }
+        buffer.writeUint8(DomainListMarshallingMap.Separator);
+        buffer.writeUint8(separator);
+        buffer.writeUint8(DomainListMarshallingMap.Children);
+        ListItemsSerializer.serialize(node.children, buffer);
+        if (!isUndefined(node.start)) {
+            buffer.writeUint8(DomainListMarshallingMap.Start);
+            buffer.writeUint32(node.start);
+        }
+        if (!isUndefined(node.end)) {
+            buffer.writeUint8(DomainListMarshallingMap.End);
+            buffer.writeUint32(node.end);
+        }
+        buffer.writeUint8(NULL);
+    }
+}
+
+export { DomainListSerializer };

package/dist/serializer/misc/list-item-serializer.js

@@ -0,0 +1,58 @@
+/*
+ * 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 { BaseSerializer } from '../base-serializer.js';
+import { ListItemNodeType } from '../../nodes/index.js';
+import { isUndefined } from '../../utils/type-guards.js';
+import { NULL } from '../../utils/constants.js';
+import { ListItemMarshallingMap } from '../../marshalling-utils/misc/list-item-common.js';
+import { BinaryTypeMarshallingMap } from '../../marshalling-utils/misc/binary-type-common.js';
+
+/**
+ * Serializer for list item nodes.
+ */
+class ListItemSerializer extends BaseSerializer {
+    /**
+     * Serializes a list item to binary format.
+     *
+     * @param item List item to serialize.
+     * @param buffer Output byte buffer.
+     * @template T Type of the list item.
+     */
+    static serialize(item, buffer) {
+        switch (item.type) {
+            case ListItemNodeType.App:
+                buffer.writeUint8(BinaryTypeMarshallingMap.AppNode);
+                break;
+            case ListItemNodeType.Domain:
+                buffer.writeUint8(BinaryTypeMarshallingMap.DomainNode);
+                break;
+            case ListItemNodeType.Method:
+                buffer.writeUint8(BinaryTypeMarshallingMap.MethodNode);
+                break;
+            case ListItemNodeType.StealthOption:
+                buffer.writeUint8(BinaryTypeMarshallingMap.StealthOptionNode);
+                break;
+            default:
+                throw new Error(`Invalid list item type: ${item.type}`);
+        }
+        buffer.writeUint8(ListItemMarshallingMap.Exception);
+        buffer.writeUint8(item.exception ? 1 : 0);
+        buffer.writeUint8(ListItemMarshallingMap.Value);
+        buffer.writeString(item.value);
+        if (!isUndefined(item.start)) {
+            buffer.writeUint8(ListItemMarshallingMap.Start);
+            buffer.writeUint32(item.start);
+        }
+        if (!isUndefined(item.end)) {
+            buffer.writeUint8(ListItemMarshallingMap.End);
+            buffer.writeUint32(item.end);
+        }
+        buffer.writeUint8(NULL);
+    }
+}
+
+export { ListItemSerializer };

package/dist/serializer/misc/list-items-serializer.js

@@ -0,0 +1,29 @@
+/*
+ * 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 { ListItemSerializer } from './list-item-serializer.js';
+
+/**
+ * Serializer for list items.
+ */
+class ListItemsSerializer {
+    /**
+     * Serializes a list of items to binary format.
+     *
+     * @param items List of items to serialize.
+     * @param buffer Output byte buffer.
+     * @template T Type of the list items.
+     */
+    static serialize(items, buffer) {
+        const { length } = items;
+        buffer.writeUint16(length);
+        for (let i = 0; i < length; i += 1) {
+            ListItemSerializer.serialize(items[i], buffer);
+        }
+    }
+}
+
+export { ListItemsSerializer };

package/dist/serializer/misc/logical-expression-serializer.js

@@ -0,0 +1,136 @@
+/*
+ * 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 { NULL } from '../../utils/constants.js';
+import { isUndefined } from '../../utils/type-guards.js';
+import { BaseSerializer } from '../base-serializer.js';
+import { KNOWN_VARIABLES_SERIALIZATION_MAP, VariableNodeBinaryPropMarshallingMap, ParenthesisNodeBinaryPropMarshallingMap, OperatorNodeBinaryPropMarshallingMap, LOGICAL_EXPRESSION_OPERATOR_SERIALISATION_MAP } from '../../marshalling-utils/misc/logical-expression-common.js';
+import { BinaryTypeMarshallingMap } from '../../marshalling-utils/misc/binary-type-common.js';
+
+/**
+ * Possible node types in the logical expression.
+ */
+const NodeType = {
+    Variable: 'Variable',
+    Operator: 'Operator',
+    Parenthesis: 'Parenthesis',
+};
+/**
+ * `LogicalExpressionSerializer` is responsible for serializing logical expressions.
+ *
+ * @example
+ * From the following rule:
+ * ```adblock
+ * !#if (adguard_ext_android_cb || adguard_ext_safari)
+ * ```
+ * this parser will parse the expression `(adguard_ext_android_cb || adguard_ext_safari)`.
+ */
+// TODO: Refactor this class
+class LogicalExpressionSerializer extends BaseSerializer {
+    /**
+     * Serializes a variable node to binary format.
+     *
+     * @param node Node to serialize.
+     * @param buffer ByteBuffer for writing binary data.
+     */
+    // TODO: create a common serialize / deserialize interface for such nodes (Variable, Value, Parameter, etc.)
+    static serializeVariableNode(node, buffer) {
+        buffer.writeUint8(BinaryTypeMarshallingMap.ExpressionVariableNode);
+        const frequentName = KNOWN_VARIABLES_SERIALIZATION_MAP.get(node.name);
+        if (!isUndefined(frequentName)) {
+            buffer.writeUint8(VariableNodeBinaryPropMarshallingMap.FrequentName);
+            buffer.writeUint8(frequentName);
+        }
+        else {
+            buffer.writeUint8(VariableNodeBinaryPropMarshallingMap.Name);
+            buffer.writeString(node.name);
+        }
+        if (!isUndefined(node.start)) {
+            buffer.writeUint8(VariableNodeBinaryPropMarshallingMap.Start);
+            buffer.writeUint32(node.start);
+        }
+        if (!isUndefined(node.end)) {
+            buffer.writeUint8(VariableNodeBinaryPropMarshallingMap.End);
+            buffer.writeUint32(node.end);
+        }
+        buffer.writeUint8(NULL);
+    }
+    /**
+     * Serializes a parenthesis node to binary format.
+     *
+     * @param node Node to serialize.
+     * @param buffer ByteBuffer for writing binary data.
+     */
+    static serializeParenthesisNode(node, buffer) {
+        buffer.writeUint8(BinaryTypeMarshallingMap.ExpressionParenthesisNode);
+        buffer.writeUint8(ParenthesisNodeBinaryPropMarshallingMap.Expression);
+        LogicalExpressionSerializer.serialize(node.expression, buffer);
+        if (!isUndefined(node.start)) {
+            buffer.writeUint8(ParenthesisNodeBinaryPropMarshallingMap.Start);
+            buffer.writeUint32(node.start);
+        }
+        if (!isUndefined(node.end)) {
+            buffer.writeUint8(ParenthesisNodeBinaryPropMarshallingMap.End);
+            buffer.writeUint32(node.end);
+        }
+        buffer.writeUint8(NULL);
+    }
+    /**
+     * Serializes an operator node to binary format.
+     *
+     * @param node Node to serialize.
+     * @param buffer ByteBuffer for writing binary data.
+     */
+    static serializeOperatorNode(node, buffer) {
+        buffer.writeUint8(BinaryTypeMarshallingMap.ExpressionOperatorNode);
+        buffer.writeUint8(OperatorNodeBinaryPropMarshallingMap.Operator);
+        const operatorBinary = LOGICAL_EXPRESSION_OPERATOR_SERIALISATION_MAP.get(node.operator);
+        if (isUndefined(operatorBinary)) {
+            throw new Error(`Unknown operator: ${node.operator}`);
+        }
+        buffer.writeUint8(operatorBinary);
+        buffer.writeUint8(OperatorNodeBinaryPropMarshallingMap.Left);
+        LogicalExpressionSerializer.serialize(node.left, buffer);
+        if (node.right) {
+            buffer.writeUint8(OperatorNodeBinaryPropMarshallingMap.Right);
+            LogicalExpressionSerializer.serialize(node.right, buffer);
+        }
+        if (!isUndefined(node.start)) {
+            buffer.writeUint8(OperatorNodeBinaryPropMarshallingMap.Start);
+            buffer.writeUint32(node.start);
+        }
+        if (!isUndefined(node.end)) {
+            buffer.writeUint8(OperatorNodeBinaryPropMarshallingMap.End);
+            buffer.writeUint32(node.end);
+        }
+        buffer.writeUint8(NULL);
+    }
+    /**
+     * Serializes a logical expression node to binary format.
+     *
+     * @param node Node to serialize.
+     * @param buffer ByteBuffer for writing binary data.
+     */
+    static serialize(node, buffer) {
+        switch (node.type) {
+            case NodeType.Variable:
+                LogicalExpressionSerializer.serializeVariableNode(node, buffer);
+                break;
+            case NodeType.Operator:
+                LogicalExpressionSerializer.serializeOperatorNode(node, buffer);
+                break;
+            case NodeType.Parenthesis:
+                LogicalExpressionSerializer.serializeParenthesisNode(node, buffer);
+                break;
+            default:
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                throw new Error(`Unexpected node type: ${node.type}`);
+        }
+        buffer.writeUint8(NULL);
+    }
+}
+
+export { LogicalExpressionSerializer, NodeType };

package/dist/serializer/misc/modifier-list-serializer.js

@@ -0,0 +1,58 @@
+/*
+ * 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 { UINT16_MAX, NULL } from '../../utils/constants.js';
+import { isUndefined } from '../../utils/type-guards.js';
+import { BaseSerializer } from '../base-serializer.js';
+import { ModifierSerializer } from './modifier-serializer.js';
+import { ModifierListNodeMarshallingMap } from '../../marshalling-utils/misc/modifier-list-common.js';
+import { BinaryTypeMarshallingMap } from '../../marshalling-utils/misc/binary-type-common.js';
+
+/**
+ * `ModifierListSerializer` is responsible for serializing modifier lists. Please note that the name is not
+ * uniform, "modifiers" are also known as "options".
+ *
+ * @see {@link https://kb.adguard.com/en/general/how-to-create-your-own-ad-filters#basic-rules-modifiers}
+ * @see {@link https://kb.adguard.com/en/general/how-to-create-your-own-ad-filters#non-basic-rules-modifiers}
+ * @see {@link https://help.eyeo.com/adblockplus/how-to-write-filters#options}
+ */
+class ModifierListSerializer extends BaseSerializer {
+    /**
+     * Serializes a modifier list node to binary format.
+     *
+     * @param node Node to serialize.
+     * @param buffer ByteBuffer for writing binary data.
+     */
+    static serialize(node, buffer) {
+        buffer.writeUint8(BinaryTypeMarshallingMap.ModifierListNode);
+        const count = node.children.length;
+        // If there are no children, we do not write any data related to them, to avoid using unnecessary storage,
+        // but children is a required field, so during deserialization we should initialize it as an empty array,
+        // if there are no children in the binary data.
+        if (count) {
+            buffer.writeUint8(ModifierListNodeMarshallingMap.Children);
+            // note: we store the count, because re-construction of the array is faster if we know the length
+            if (count > UINT16_MAX) {
+                throw new Error(`Too many modifiers: ${count}, the limit is ${UINT16_MAX}`);
+            }
+            buffer.writeUint16(count);
+            for (let i = 0; i < count; i += 1) {
+                ModifierSerializer.serialize(node.children[i], buffer);
+            }
+        }
+        if (!isUndefined(node.start)) {
+            buffer.writeUint8(ModifierListNodeMarshallingMap.Start);
+            buffer.writeUint32(node.start);
+        }
+        if (!isUndefined(node.end)) {
+            buffer.writeUint8(ModifierListNodeMarshallingMap.End);
+            buffer.writeUint32(node.end);
+        }
+        buffer.writeUint8(NULL);
+    }
+}
+
+export { ModifierListSerializer };

package/dist/serializer/misc/modifier-serializer.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
+ */
+import { NULL } from '../../utils/constants.js';
+import { ValueSerializer } from './value-serializer.js';
+import { isUndefined } from '../../utils/type-guards.js';
+import { BaseSerializer } from '../base-serializer.js';
+import { ModifierNodeMarshallingMap, FREQUENT_MODIFIERS_SERIALIZATION_MAP, FREQUENT_REDIRECT_MODIFIERS_SERIALIZATION_MAP } from '../../marshalling-utils/misc/modifier-common.js';
+import { BinaryTypeMarshallingMap } from '../../marshalling-utils/misc/binary-type-common.js';
+
+/**
+ * `ModifierSerializer` is responsible for serializing modifiers.
+ *
+ * @example
+ * `match-case`, `~third-party`, `domain=example.com|~example.org`
+ */
+class ModifierSerializer extends BaseSerializer {
+    /**
+     * Serializes a modifier node to binary format.
+     *
+     * @param node Node to serialize.
+     * @param buffer ByteBuffer for writing binary data.
+     */
+    static serialize(node, buffer) {
+        buffer.writeUint8(BinaryTypeMarshallingMap.ModifierNode);
+        buffer.writeUint8(ModifierNodeMarshallingMap.Name);
+        ValueSerializer.serialize(node.name, buffer, FREQUENT_MODIFIERS_SERIALIZATION_MAP);
+        if (!isUndefined(node.value)) {
+            buffer.writeUint8(ModifierNodeMarshallingMap.Value);
+            ValueSerializer.serialize(node.value, buffer, FREQUENT_REDIRECT_MODIFIERS_SERIALIZATION_MAP.get(node.name.value));
+        }
+        buffer.writeUint8(ModifierNodeMarshallingMap.Exception);
+        buffer.writeUint8(node.exception ? 1 : 0);
+        if (!isUndefined(node.start)) {
+            buffer.writeUint8(ModifierNodeMarshallingMap.Start);
+            buffer.writeUint32(node.start);
+        }
+        if (!isUndefined(node.end)) {
+            buffer.writeUint8(ModifierNodeMarshallingMap.End);
+            buffer.writeUint32(node.end);
+        }
+        buffer.writeUint8(NULL);
+    }
+}
+
+export { ModifierSerializer };

package/dist/serializer/misc/parameter-list-serializer.js

@@ -0,0 +1,52 @@
+/*
+ * 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 { NULL } from '../../utils/constants.js';
+import { ValueSerializer } from './value-serializer.js';
+import { isNull, isUndefined } from '../../utils/type-guards.js';
+import { BaseSerializer } from '../base-serializer.js';
+import { ParameterListNodeMarshallingMap } from '../../marshalling-utils/misc/parameter-list-common.js';
+import { BinaryTypeMarshallingMap } from '../../marshalling-utils/misc/binary-type-common.js';
+
+/**
+ * Serializer for parameter list nodes.
+ */
+class ParameterListSerializer extends BaseSerializer {
+    /**
+     * Serializes a parameter list node to binary format.
+     *
+     * @param node Node to serialize.
+     * @param buffer ByteBuffer for writing binary data.
+     * @param frequentValuesMap Optional map of frequent values.
+     * @param toLower Whether to lowercase the value before the frequent value match (defaults to `false`).
+     */
+    static serialize(node, buffer, frequentValuesMap, toLower = false) {
+        buffer.writeUint8(BinaryTypeMarshallingMap.ParameterListNode);
+        const count = node.children.length;
+        buffer.writeUint8(ParameterListNodeMarshallingMap.Children);
+        // note: we store the count, because re-construction of the array is faster if we know the length
+        buffer.writeUint32(count);
+        for (let i = 0; i < count; i += 1) {
+            const child = node.children[i];
+            if (isNull(child)) {
+                buffer.writeUint8(BinaryTypeMarshallingMap.Null);
+                continue;
+            }
+            ValueSerializer.serialize(child, buffer, frequentValuesMap, toLower);
+        }
+        if (!isUndefined(node.start)) {
+            buffer.writeUint8(ParameterListNodeMarshallingMap.Start);
+            buffer.writeUint32(node.start);
+        }
+        if (!isUndefined(node.end)) {
+            buffer.writeUint8(ParameterListNodeMarshallingMap.End);
+            buffer.writeUint32(node.end);
+        }
+        buffer.writeUint8(NULL);
+    }
+}
+
+export { ParameterListSerializer };

package/dist/serializer/misc/value-serializer.js

@@ -0,0 +1,50 @@
+/*
+ * 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 { NULL } from '../../utils/constants.js';
+import { isUndefined } from '../../utils/type-guards.js';
+import { BaseSerializer } from '../base-serializer.js';
+import { ValueNodeMarshallingMap } from '../../marshalling-utils/misc/value-common.js';
+import { BinaryTypeMarshallingMap } from '../../marshalling-utils/misc/binary-type-common.js';
+
+/**
+ * Value serializer.
+ */
+class ValueSerializer extends BaseSerializer {
+    /**
+     * Serializes a value node to binary format.
+     *
+     * @param node Node to serialize.
+     * @param buffer ByteBuffer for writing binary data.
+     * @param frequentValuesMap Optional map of frequent values.
+     * @param toLower Whether to lowercase the value before the frequent value match (defaults to `false`).
+     */
+    static serialize(node, buffer, frequentValuesMap, toLower = false) {
+        buffer.writeUint8(BinaryTypeMarshallingMap.ValueNode);
+        const frequentValue = frequentValuesMap?.get(toLower ? node.value.toLowerCase() : node.value);
+        // note: do not use just `if (frequentValue)` because it can be 0
+        if (!isUndefined(frequentValue)) {
+            buffer.writeUint8(ValueNodeMarshallingMap.FrequentValue);
+            buffer.writeUint8(frequentValue);
+        }
+        else {
+            buffer.writeUint8(ValueNodeMarshallingMap.Value);
+            buffer.writeString(node.value);
+        }
+        // note: do not use just `if (node.start)` because it can be 0
+        if (!isUndefined(node.start)) {
+            buffer.writeUint8(ValueNodeMarshallingMap.Start);
+            buffer.writeUint32(node.start);
+        }
+        if (!isUndefined(node.end)) {
+            buffer.writeUint8(ValueNodeMarshallingMap.End);
+            buffer.writeUint32(node.end);
+        }
+        buffer.writeUint8(NULL);
+    }
+}
+
+export { ValueSerializer };

package/dist/serializer/network/host-rule-serializer.js

@@ -0,0 +1,70 @@
+/*
+ * 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 { NULL } from '../../utils/constants.js';
+import { ValueSerializer } from '../misc/value-serializer.js';
+import { isUndefined } from '../../utils/type-guards.js';
+import { HostnameListSerializer } from './hostname-list-serializer.js';
+import { BaseSerializer } from '../base-serializer.js';
+import { HostRuleMarshallingMap } from '../../marshalling-utils/misc/host-rule-common.js';
+import { BinaryTypeMarshallingMap } from '../../marshalling-utils/misc/binary-type-common.js';
+import { getSyntaxSerializationMap } from '../../marshalling-utils/syntax-serialization-map.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}
+ */
+class HostRuleSerializer extends BaseSerializer {
+    /**
+     * Serializes a host rule node to binary format.
+     *
+     * @param node Node to serialize.
+     * @param buffer ByteBuffer for writing binary data.
+     */
+    // TODO: add support for raws, if ever needed
+    static serialize(node, buffer) {
+        buffer.writeUint8(BinaryTypeMarshallingMap.HostRuleNode);
+        buffer.writeUint8(HostRuleMarshallingMap.Syntax);
+        buffer.writeUint8(getSyntaxSerializationMap().get(node.syntax) ?? 0);
+        if (node.ip) {
+            buffer.writeUint8(HostRuleMarshallingMap.Ip);
+            ValueSerializer.serialize(node.ip, buffer);
+        }
+        if (node.hostnames) {
+            buffer.writeUint8(HostRuleMarshallingMap.HostnameList);
+            HostnameListSerializer.serialize(node.hostnames, buffer);
+        }
+        if (node.comment) {
+            buffer.writeUint8(HostRuleMarshallingMap.Comment);
+            ValueSerializer.serialize(node.comment, buffer);
+        }
+        if (!isUndefined(node.start)) {
+            buffer.writeUint8(HostRuleMarshallingMap.Start);
+            buffer.writeUint32(node.start);
+        }
+        if (!isUndefined(node.end)) {
+            buffer.writeUint8(HostRuleMarshallingMap.End);
+            buffer.writeUint32(node.end);
+        }
+        buffer.writeUint8(NULL);
+    }
+}
+
+export { HostRuleSerializer };