@adguard/agtree 2.2.0 → 3.0.0-alpha.2

package/dist/utils/index.js

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

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

@@ -0,0 +1,265 @@
+/*
+ * 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 { 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);
+        // 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

@@ -0,0 +1,20 @@
+/*
+ * 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
+ */
+/**
+ * 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/logical-expression.js

@@ -0,0 +1,92 @@
+/*
+ * 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 { OperatorValue } from '../nodes/index.js';
+import { NodeType } from '../parser/misc/logical-expression-parser.js';
+
+/**
+ * @file Utility functions for logical expression node.
+ */
+const ERROR_PREFIX = {
+    UNEXPECTED_NODE_TYPE: 'Unexpected node type',
+    UNEXPECTED_OPERATOR: 'Unexpected operator',
+};
+/**
+ * Utility functions for logical expression node.
+ */
+class LogicalExpressionUtils {
+    /**
+     * Get all variables in the expression.
+     *
+     * @param node Logical expression node
+     * @returns List of variables in the expression (nodes)
+     * @example
+     * If the expression is `a && b || c`, the returned list will be
+     * nodes for `a`, `b`, and `c`.
+     */
+    static getVariables(node) {
+        if (node.type === NodeType.Variable) {
+            return [node];
+        }
+        if (node.type === NodeType.Operator) {
+            const leftVars = LogicalExpressionUtils.getVariables(node.left);
+            const rightVars = node.right ? LogicalExpressionUtils.getVariables(node.right) : [];
+            return [...leftVars, ...rightVars];
+        }
+        if (node.type === NodeType.Parenthesis) {
+            return LogicalExpressionUtils.getVariables(node.expression);
+        }
+        throw new Error(ERROR_PREFIX.UNEXPECTED_NODE_TYPE);
+    }
+    /**
+     * Evaluate the parsed logical expression. You'll need to provide a
+     * variable table.
+     *
+     * @param node Logical expression node
+     * @param table Variable table (key: variable name, value: boolean)
+     * @returns Evaluation result
+     * @example
+     * If the expression is `a && b`, and the variable table is
+     * `{ a: true, b: false }`, the result will be `false`.
+     *
+     * Example code:
+     * ```js
+     * LogicalExpressionUtils.evaluate(
+     *     LogicalExpressionParser.parse('a && b'),
+     *     { a: true, b: false }
+     * );
+     * ```
+     */
+    static evaluate(node, table) {
+        if (node.type === NodeType.Variable) {
+            return !!table[node.name];
+        }
+        if (node.type === NodeType.Operator) {
+            if (node.operator === OperatorValue.And || node.operator === OperatorValue.Or) {
+                if (!node.right) {
+                    throw new Error(`${ERROR_PREFIX.UNEXPECTED_OPERATOR} '${node.operator}'`);
+                }
+                if (node.operator === OperatorValue.And) {
+                    // eslint-disable-next-line max-len
+                    return LogicalExpressionUtils.evaluate(node.left, table) && LogicalExpressionUtils.evaluate(node.right, table);
+                }
+                if (node.operator === OperatorValue.Or) {
+                    // eslint-disable-next-line max-len
+                    return LogicalExpressionUtils.evaluate(node.left, table) || LogicalExpressionUtils.evaluate(node.right, table);
+                }
+            }
+            else if (node.operator === OperatorValue.Not) {
+                return !LogicalExpressionUtils.evaluate(node.left, table);
+            }
+        }
+        else if (node.type === NodeType.Parenthesis) {
+            return LogicalExpressionUtils.evaluate(node.expression, table);
+        }
+        throw new Error(`${ERROR_PREFIX.UNEXPECTED_NODE_TYPE} '${node.type}'`);
+    }
+}
+
+export { LogicalExpressionUtils };

package/dist/utils/multi-value-map.js

@@ -0,0 +1,33 @@
+/*
+ * 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 { isUndefined } from './type-guards.js';
+
+/**
+ * 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/utils/output-byte-buffer.js

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