@solana/codecs-core 6.3.1 → 6.3.2-canary-20260313112147

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@solana/codecs-core",
-  "version": "6.3.1",
+  "version": "6.3.2-canary-20260313112147",
   "description": "Core types and helpers for encoding and decoding byte arrays on Solana",
   "homepage": "https://www.solanakit.com/api#solanacodecs-core",
   "exports": {
@@ -33,7 +33,8 @@
   "types": "./dist/types/index.d.ts",
   "type": "commonjs",
   "files": [
-    "./dist/"
+    "./dist/",
+    "./src/"
   ],
   "sideEffects": false,
   "keywords": [
@@ -55,7 +56,7 @@
     "maintained node versions"
   ],
   "dependencies": {
-    "@solana/errors": "6.3.1"
+    "@solana/errors": "6.3.2-canary-20260313112147"
   },
   "peerDependencies": {
     "typescript": "^5.0.0"

package/src/add-codec-sentinel.ts

@@ -0,0 +1,186 @@
+import {
+    SOLANA_ERROR__CODECS__ENCODED_BYTES_MUST_NOT_INCLUDE_SENTINEL,
+    SOLANA_ERROR__CODECS__SENTINEL_MISSING_IN_DECODED_BYTES,
+    SolanaError,
+} from '@solana/errors';
+
+import { containsBytes } from './bytes';
+import {
+    Codec,
+    createDecoder,
+    createEncoder,
+    Decoder,
+    Encoder,
+    FixedSizeCodec,
+    FixedSizeDecoder,
+    FixedSizeEncoder,
+    isFixedSize,
+    VariableSizeCodec,
+    VariableSizeDecoder,
+    VariableSizeEncoder,
+} from './codec';
+import { combineCodec } from './combine-codec';
+import { ReadonlyUint8Array } from './readonly-uint8array';
+
+/**
+ * Creates an encoder that writes a `Uint8Array` sentinel after the encoded value.
+ * This is useful to delimit the encoded value when being read by a decoder.
+ *
+ * See {@link addCodecSentinel} for more information.
+ *
+ * @typeParam TFrom - The type of the value to encode.
+ *
+ * @see {@link addCodecSentinel}
+ */
+export function addEncoderSentinel<TFrom>(
+    encoder: FixedSizeEncoder<TFrom>,
+    sentinel: ReadonlyUint8Array,
+): FixedSizeEncoder<TFrom>;
+export function addEncoderSentinel<TFrom>(
+    encoder: Encoder<TFrom>,
+    sentinel: ReadonlyUint8Array,
+): VariableSizeEncoder<TFrom>;
+export function addEncoderSentinel<TFrom>(encoder: Encoder<TFrom>, sentinel: ReadonlyUint8Array): Encoder<TFrom> {
+    const write = ((value, bytes, offset) => {
+        // Here we exceptionally use the `encode` function instead of the `write`
+        // function to contain the content of the encoder within its own bounds
+        // and to avoid writing the sentinel as part of the encoded value.
+        const encoderBytes = encoder.encode(value);
+        if (findSentinelIndex(encoderBytes, sentinel) >= 0) {
+            throw new SolanaError(SOLANA_ERROR__CODECS__ENCODED_BYTES_MUST_NOT_INCLUDE_SENTINEL, {
+                encodedBytes: encoderBytes,
+                hexEncodedBytes: hexBytes(encoderBytes),
+                hexSentinel: hexBytes(sentinel),
+                sentinel,
+            });
+        }
+        bytes.set(encoderBytes, offset);
+        offset += encoderBytes.length;
+        bytes.set(sentinel, offset);
+        offset += sentinel.length;
+        return offset;
+    }) as Encoder<TFrom>['write'];
+
+    if (isFixedSize(encoder)) {
+        return createEncoder({ ...encoder, fixedSize: encoder.fixedSize + sentinel.length, write });
+    }
+
+    return createEncoder({
+        ...encoder,
+        ...(encoder.maxSize != null ? { maxSize: encoder.maxSize + sentinel.length } : {}),
+        getSizeFromValue: value => encoder.getSizeFromValue(value) + sentinel.length,
+        write,
+    });
+}
+
+/**
+ * Creates a decoder that continues reading until
+ * a given `Uint8Array` sentinel is found.
+ *
+ * See {@link addCodecSentinel} for more information.
+ *
+ * @typeParam TTo - The type of the decoded value.
+ *
+ * @see {@link addCodecSentinel}
+ */
+export function addDecoderSentinel<TTo>(
+    decoder: FixedSizeDecoder<TTo>,
+    sentinel: ReadonlyUint8Array,
+): FixedSizeDecoder<TTo>;
+export function addDecoderSentinel<TTo>(decoder: Decoder<TTo>, sentinel: ReadonlyUint8Array): VariableSizeDecoder<TTo>;
+export function addDecoderSentinel<TTo>(decoder: Decoder<TTo>, sentinel: ReadonlyUint8Array): Decoder<TTo> {
+    const read = ((bytes, offset) => {
+        const candidateBytes = offset === 0 ? bytes : bytes.slice(offset);
+        const sentinelIndex = findSentinelIndex(candidateBytes, sentinel);
+        if (sentinelIndex === -1) {
+            throw new SolanaError(SOLANA_ERROR__CODECS__SENTINEL_MISSING_IN_DECODED_BYTES, {
+                decodedBytes: candidateBytes,
+                hexDecodedBytes: hexBytes(candidateBytes),
+                hexSentinel: hexBytes(sentinel),
+                sentinel,
+            });
+        }
+        const preSentinelBytes = candidateBytes.slice(0, sentinelIndex);
+        // Here we exceptionally use the `decode` function instead of the `read`
+        // function to contain the content of the decoder within its own bounds
+        // and ensure that the sentinel is not part of the decoded value.
+        return [decoder.decode(preSentinelBytes), offset + preSentinelBytes.length + sentinel.length];
+    }) as Decoder<TTo>['read'];
+
+    if (isFixedSize(decoder)) {
+        return createDecoder({ ...decoder, fixedSize: decoder.fixedSize + sentinel.length, read });
+    }
+
+    return createDecoder({
+        ...decoder,
+        ...(decoder.maxSize != null ? { maxSize: decoder.maxSize + sentinel.length } : {}),
+        read,
+    });
+}
+
+/**
+ * Creates a Codec that writes a given `Uint8Array` sentinel after the encoded
+ * value and, when decoding, continues reading until the sentinel is found.
+ *
+ * This sets a limit on variable-size codecs and tells us when to stop decoding.
+ *
+ * @typeParam TFrom - The type of the value to encode.
+ * @typeParam TTo - The type of the decoded value.
+ *
+ * @example
+ * ```ts
+ * const codec = addCodecSentinel(getUtf8Codec(), new Uint8Array([255, 255]));
+ * codec.encode('hello');
+ * // 0x68656c6c6fffff
+ * //   |        └-- Our sentinel.
+ * //   └-- Our encoded string.
+ * ```
+ *
+ * @remarks
+ * Note that the sentinel _must not_ be present in the encoded data and
+ * _must_ be present in the decoded data for this to work.
+ * If this is not the case, dedicated errors will be thrown.
+ *
+ * ```ts
+ * const sentinel = new Uint8Array([108, 108]); // 'll'
+ * const codec = addCodecSentinel(getUtf8Codec(), sentinel);
+ *
+ * codec.encode('hello'); // Throws: sentinel is in encoded data.
+ * codec.decode(new Uint8Array([1, 2, 3])); // Throws: sentinel missing in decoded data.
+ * ```
+ *
+ * Separate {@link addEncoderSentinel} and {@link addDecoderSentinel} functions are also available.
+ *
+ * ```ts
+ * const bytes = addEncoderSentinel(getUtf8Encoder(), sentinel).encode('hello');
+ * const value = addDecoderSentinel(getUtf8Decoder(), sentinel).decode(bytes);
+ * ```
+ *
+ * @see {@link addEncoderSentinel}
+ * @see {@link addDecoderSentinel}
+ */
+export function addCodecSentinel<TFrom, TTo extends TFrom>(
+    codec: FixedSizeCodec<TFrom, TTo>,
+    sentinel: ReadonlyUint8Array,
+): FixedSizeCodec<TFrom, TTo>;
+export function addCodecSentinel<TFrom, TTo extends TFrom>(
+    codec: Codec<TFrom, TTo>,
+    sentinel: ReadonlyUint8Array,
+): VariableSizeCodec<TFrom, TTo>;
+export function addCodecSentinel<TFrom, TTo extends TFrom>(
+    codec: Codec<TFrom, TTo>,
+    sentinel: ReadonlyUint8Array,
+): Codec<TFrom, TTo> {
+    return combineCodec(addEncoderSentinel(codec, sentinel), addDecoderSentinel(codec, sentinel));
+}
+
+function findSentinelIndex(bytes: ReadonlyUint8Array, sentinel: ReadonlyUint8Array) {
+    return bytes.findIndex((byte, index, arr) => {
+        if (sentinel.length === 1) return byte === sentinel[0];
+        return containsBytes(arr, sentinel, index);
+    });
+}
+
+function hexBytes(bytes: ReadonlyUint8Array): string {
+    return bytes.reduce((str, byte) => str + byte.toString(16).padStart(2, '0'), '');
+}

package/src/add-codec-size-prefix.ts

@@ -0,0 +1,161 @@
+import { assertByteArrayHasEnoughBytesForCodec } from './assertions';
+import {
+    Codec,
+    createDecoder,
+    createEncoder,
+    Decoder,
+    Encoder,
+    FixedSizeCodec,
+    FixedSizeDecoder,
+    FixedSizeEncoder,
+    getEncodedSize,
+    isFixedSize,
+    VariableSizeCodec,
+    VariableSizeDecoder,
+    VariableSizeEncoder,
+} from './codec';
+import { combineCodec } from './combine-codec';
+
+type NumberEncoder = Encoder<bigint | number> | Encoder<number>;
+type FixedSizeNumberEncoder<TSize extends number = number> =
+    | FixedSizeEncoder<bigint | number, TSize>
+    | FixedSizeEncoder<number, TSize>;
+type NumberDecoder = Decoder<bigint> | Decoder<number>;
+type FixedSizeNumberDecoder<TSize extends number = number> =
+    | FixedSizeDecoder<bigint, TSize>
+    | FixedSizeDecoder<number, TSize>;
+type NumberCodec = Codec<bigint | number, bigint> | Codec<number>;
+type FixedSizeNumberCodec<TSize extends number = number> =
+    | FixedSizeCodec<bigint | number, bigint, TSize>
+    | FixedSizeCodec<number, number, TSize>;
+
+/**
+ * Stores the size of the `encoder` in bytes as a prefix using the `prefix` encoder.
+ *
+ * See {@link addCodecSizePrefix} for more information.
+ *
+ * @typeParam TFrom - The type of the value to encode.
+ *
+ * @see {@link addCodecSizePrefix}
+ */
+export function addEncoderSizePrefix<TFrom>(
+    encoder: FixedSizeEncoder<TFrom>,
+    prefix: FixedSizeNumberEncoder,
+): FixedSizeEncoder<TFrom>;
+export function addEncoderSizePrefix<TFrom>(encoder: Encoder<TFrom>, prefix: NumberEncoder): VariableSizeEncoder<TFrom>;
+export function addEncoderSizePrefix<TFrom>(encoder: Encoder<TFrom>, prefix: NumberEncoder): Encoder<TFrom> {
+    const write = ((value, bytes, offset) => {
+        // Here we exceptionally use the `encode` function instead of the `write`
+        // function to contain the content of the encoder within its own bounds.
+        const encoderBytes = encoder.encode(value);
+        offset = prefix.write(encoderBytes.length, bytes, offset);
+        bytes.set(encoderBytes, offset);
+        return offset + encoderBytes.length;
+    }) as Encoder<TFrom>['write'];
+
+    if (isFixedSize(prefix) && isFixedSize(encoder)) {
+        return createEncoder({ ...encoder, fixedSize: prefix.fixedSize + encoder.fixedSize, write });
+    }
+
+    const prefixMaxSize = isFixedSize(prefix) ? prefix.fixedSize : (prefix.maxSize ?? null);
+    const encoderMaxSize = isFixedSize(encoder) ? encoder.fixedSize : (encoder.maxSize ?? null);
+    const maxSize = prefixMaxSize !== null && encoderMaxSize !== null ? prefixMaxSize + encoderMaxSize : null;
+
+    return createEncoder({
+        ...encoder,
+        ...(maxSize !== null ? { maxSize } : {}),
+        getSizeFromValue: value => {
+            const encoderSize = getEncodedSize(value, encoder);
+            return getEncodedSize(encoderSize, prefix) + encoderSize;
+        },
+        write,
+    });
+}
+
+/**
+ * Bounds the size of the nested `decoder` by reading its encoded `prefix`.
+ *
+ * See {@link addCodecSizePrefix} for more information.
+ *
+ * @typeParam TTo - The type of the decoded value.
+ *
+ * @see {@link addCodecSizePrefix}
+ */
+export function addDecoderSizePrefix<TTo>(
+    decoder: FixedSizeDecoder<TTo>,
+    prefix: FixedSizeNumberDecoder,
+): FixedSizeDecoder<TTo>;
+export function addDecoderSizePrefix<TTo>(decoder: Decoder<TTo>, prefix: NumberDecoder): VariableSizeDecoder<TTo>;
+export function addDecoderSizePrefix<TTo>(decoder: Decoder<TTo>, prefix: NumberDecoder): Decoder<TTo> {
+    const read = ((bytes, offset) => {
+        const [bigintSize, decoderOffset] = prefix.read(bytes, offset);
+        const size = Number(bigintSize);
+        offset = decoderOffset;
+        // Slice the byte array to the contained size if necessary.
+        if (offset > 0 || bytes.length > size) {
+            bytes = bytes.slice(offset, offset + size);
+        }
+        assertByteArrayHasEnoughBytesForCodec('addDecoderSizePrefix', size, bytes);
+        // Here we exceptionally use the `decode` function instead of the `read`
+        // function to contain the content of the decoder within its own bounds.
+        return [decoder.decode(bytes), offset + size];
+    }) as Decoder<TTo>['read'];
+
+    if (isFixedSize(prefix) && isFixedSize(decoder)) {
+        return createDecoder({ ...decoder, fixedSize: prefix.fixedSize + decoder.fixedSize, read });
+    }
+
+    const prefixMaxSize = isFixedSize(prefix) ? prefix.fixedSize : (prefix.maxSize ?? null);
+    const decoderMaxSize = isFixedSize(decoder) ? decoder.fixedSize : (decoder.maxSize ?? null);
+    const maxSize = prefixMaxSize !== null && decoderMaxSize !== null ? prefixMaxSize + decoderMaxSize : null;
+    return createDecoder({ ...decoder, ...(maxSize !== null ? { maxSize } : {}), read });
+}
+
+/**
+ * Stores the byte size of any given codec as an encoded number prefix.
+ *
+ * This sets a limit on variable-size codecs and tells us when to stop decoding.
+ * When encoding, the size of the encoded data is stored before the encoded data itself.
+ * When decoding, the size is read first to know how many bytes to read next.
+ *
+ * @typeParam TFrom - The type of the value to encode.
+ * @typeParam TTo - The type of the decoded value.
+ *
+ * @example
+ * For example, say we want to bound a variable-size base-58 string using a `u32` size prefix.
+ * Here’s how you can use the `addCodecSizePrefix` function to achieve that.
+ *
+ * ```ts
+ * const getU32Base58Codec = () => addCodecSizePrefix(getBase58Codec(), getU32Codec());
+ *
+ * getU32Base58Codec().encode('hello world');
+ * // 0x0b00000068656c6c6f20776f726c64
+ * //   |       └-- Our encoded base-58 string.
+ * //   └-- Our encoded u32 size prefix.
+ * ```
+ *
+ * @remarks
+ * Separate {@link addEncoderSizePrefix} and {@link addDecoderSizePrefix} functions are also available.
+ *
+ * ```ts
+ * const bytes = addEncoderSizePrefix(getBase58Encoder(), getU32Encoder()).encode('hello');
+ * const value = addDecoderSizePrefix(getBase58Decoder(), getU32Decoder()).decode(bytes);
+ * ```
+ *
+ * @see {@link addEncoderSizePrefix}
+ * @see {@link addDecoderSizePrefix}
+ */
+export function addCodecSizePrefix<TFrom, TTo extends TFrom>(
+    codec: FixedSizeCodec<TFrom, TTo>,
+    prefix: FixedSizeNumberCodec,
+): FixedSizeCodec<TFrom, TTo>;
+export function addCodecSizePrefix<TFrom, TTo extends TFrom>(
+    codec: Codec<TFrom, TTo>,
+    prefix: NumberCodec,
+): VariableSizeCodec<TFrom, TTo>;
+export function addCodecSizePrefix<TFrom, TTo extends TFrom>(
+    codec: Codec<TFrom, TTo>,
+    prefix: NumberCodec,
+): Codec<TFrom, TTo> {
+    return combineCodec(addEncoderSizePrefix(codec, prefix), addDecoderSizePrefix(codec, prefix));
+}

package/src/array-buffers.ts

@@ -0,0 +1,25 @@
+import { ReadonlyUint8Array } from './readonly-uint8array';
+
+/**
+ * Converts a `Uint8Array` to an `ArrayBuffer`. If the underlying buffer is a `SharedArrayBuffer`,
+ * it will be copied to a non-shared buffer, for safety.
+ *
+ * @remarks
+ * Source: https://stackoverflow.com/questions/37228285/uint8array-to-arraybuffer
+ */
+export function toArrayBuffer(bytes: ReadonlyUint8Array | Uint8Array, offset?: number, length?: number): ArrayBuffer {
+    const bytesOffset = bytes.byteOffset + (offset ?? 0);
+    const bytesLength = length ?? bytes.byteLength;
+    let buffer: ArrayBuffer;
+    if (typeof SharedArrayBuffer === 'undefined') {
+        buffer = bytes.buffer as ArrayBuffer;
+    } else if (bytes.buffer instanceof SharedArrayBuffer) {
+        buffer = new ArrayBuffer(bytes.length);
+        new Uint8Array(buffer).set(new Uint8Array(bytes));
+    } else {
+        buffer = bytes.buffer;
+    }
+    return (bytesOffset === 0 || bytesOffset === -bytes.byteLength) && bytesLength === bytes.byteLength
+        ? buffer
+        : buffer.slice(bytesOffset, bytesOffset + bytesLength);
+}

package/src/assertions.ts

@@ -0,0 +1,103 @@
+import {
+    SOLANA_ERROR__CODECS__CANNOT_DECODE_EMPTY_BYTE_ARRAY,
+    SOLANA_ERROR__CODECS__INVALID_BYTE_LENGTH,
+    SOLANA_ERROR__CODECS__OFFSET_OUT_OF_RANGE,
+    SolanaError,
+} from '@solana/errors';
+
+import { ReadonlyUint8Array } from './readonly-uint8array';
+
+/**
+ * Asserts that a given byte array is not empty (after the optional provided offset).
+ *
+ * Returns void if the byte array is not empty but throws a {@link SolanaError} otherwise.
+ *
+ * @param codecDescription - A description of the codec used by the assertion error.
+ * @param bytes - The byte array to check.
+ * @param offset - The offset from which to start checking the byte array.
+ * If provided, the byte array is considered empty if it has no bytes after the offset.
+ *
+ * @example
+ * ```ts
+ * const bytes = new Uint8Array([0x01, 0x02, 0x03]);
+ * assertByteArrayIsNotEmptyForCodec('myCodec', bytes); // OK
+ * assertByteArrayIsNotEmptyForCodec('myCodec', bytes, 1); // OK
+ * assertByteArrayIsNotEmptyForCodec('myCodec', bytes, 3); // Throws
+ * ```
+ */
+export function assertByteArrayIsNotEmptyForCodec(
+    codecDescription: string,
+    bytes: ReadonlyUint8Array | Uint8Array,
+    offset = 0,
+) {
+    if (bytes.length - offset <= 0) {
+        throw new SolanaError(SOLANA_ERROR__CODECS__CANNOT_DECODE_EMPTY_BYTE_ARRAY, {
+            codecDescription,
+        });
+    }
+}
+
+/**
+ * Asserts that a given byte array has enough bytes to decode
+ * (after the optional provided offset).
+ *
+ * Returns void if the byte array has at least the expected number
+ * of bytes but throws a {@link SolanaError} otherwise.
+ *
+ * @param codecDescription - A description of the codec used by the assertion error.
+ * @param expected - The minimum number of bytes expected in the byte array.
+ * @param bytes - The byte array to check.
+ * @param offset - The offset from which to start checking the byte array.
+ *
+ * @example
+ * ```ts
+ * const bytes = new Uint8Array([0x01, 0x02, 0x03]);
+ * assertByteArrayHasEnoughBytesForCodec('myCodec', 3, bytes); // OK
+ * assertByteArrayHasEnoughBytesForCodec('myCodec', 4, bytes); // Throws
+ * assertByteArrayHasEnoughBytesForCodec('myCodec', 2, bytes, 1); // OK
+ * assertByteArrayHasEnoughBytesForCodec('myCodec', 3, bytes, 1); // Throws
+ * ```
+ */
+export function assertByteArrayHasEnoughBytesForCodec(
+    codecDescription: string,
+    expected: number,
+    bytes: ReadonlyUint8Array | Uint8Array,
+    offset = 0,
+) {
+    const bytesLength = bytes.length - offset;
+    if (bytesLength < expected) {
+        throw new SolanaError(SOLANA_ERROR__CODECS__INVALID_BYTE_LENGTH, {
+            bytesLength,
+            codecDescription,
+            expected,
+        });
+    }
+}
+
+/**
+ * Asserts that a given offset is within the byte array bounds.
+ * This range is between 0 and the byte array length and is inclusive.
+ * An offset equals to the byte array length is considered a valid offset
+ * as it allows the post-offset of codecs to signal the end of the byte array.
+ *
+ * @param codecDescription - A description of the codec used by the assertion error.
+ * @param offset - The offset to check.
+ * @param bytesLength - The length of the byte array from which the offset should be within bounds.
+ *
+ * @example
+ * ```ts
+ * const bytes = new Uint8Array([0x01, 0x02, 0x03]);
+ * assertByteArrayOffsetIsNotOutOfRange('myCodec', 0, bytes.length); // OK
+ * assertByteArrayOffsetIsNotOutOfRange('myCodec', 3, bytes.length); // OK
+ * assertByteArrayOffsetIsNotOutOfRange('myCodec', 4, bytes.length); // Throws
+ * ```
+ */
+export function assertByteArrayOffsetIsNotOutOfRange(codecDescription: string, offset: number, bytesLength: number) {
+    if (offset < 0 || offset > bytesLength) {
+        throw new SolanaError(SOLANA_ERROR__CODECS__OFFSET_OUT_OF_RANGE, {
+            bytesLength,
+            codecDescription,
+            offset,
+        });
+    }
+}

package/src/bytes.ts

@@ -0,0 +1,145 @@
+import { ReadonlyUint8Array } from './readonly-uint8array';
+
+/**
+ * Concatenates an array of `Uint8Array`s into a single `Uint8Array`.
+ * Reuses the original byte array when applicable.
+ *
+ * @param byteArrays - The array of byte arrays to concatenate.
+ *
+ * @example
+ * ```ts
+ * const bytes1 = new Uint8Array([0x01, 0x02]);
+ * const bytes2 = new Uint8Array([]);
+ * const bytes3 = new Uint8Array([0x03, 0x04]);
+ * const bytes = mergeBytes([bytes1, bytes2, bytes3]);
+ * //    ^ [0x01, 0x02, 0x03, 0x04]
+ * ```
+ */
+export const mergeBytes = (byteArrays: Uint8Array[]): Uint8Array => {
+    const nonEmptyByteArrays = byteArrays.filter(arr => arr.length);
+    if (nonEmptyByteArrays.length === 0) {
+        return byteArrays.length ? byteArrays[0] : new Uint8Array();
+    }
+
+    if (nonEmptyByteArrays.length === 1) {
+        return nonEmptyByteArrays[0];
+    }
+
+    const totalLength = nonEmptyByteArrays.reduce((total, arr) => total + arr.length, 0);
+    const result = new Uint8Array(totalLength);
+    let offset = 0;
+    nonEmptyByteArrays.forEach(arr => {
+        result.set(arr, offset);
+        offset += arr.length;
+    });
+    return result;
+};
+
+/**
+ * Pads a `Uint8Array` with zeroes to the specified length.
+ * If the array is longer than the specified length, it is returned as-is.
+ *
+ * @param bytes - The byte array to pad.
+ * @param length - The desired length of the byte array.
+ *
+ * @example
+ * Adds zeroes to the end of the byte array to reach the desired length.
+ * ```ts
+ * const bytes = new Uint8Array([0x01, 0x02]);
+ * const paddedBytes = padBytes(bytes, 4);
+ * //    ^ [0x01, 0x02, 0x00, 0x00]
+ * ```
+ *
+ * @example
+ * Returns the original byte array if it is already at the desired length.
+ * ```ts
+ * const bytes = new Uint8Array([0x01, 0x02]);
+ * const paddedBytes = padBytes(bytes, 2);
+ * // bytes === paddedBytes
+ * ```
+ */
+export function padBytes(bytes: Uint8Array, length: number): Uint8Array;
+export function padBytes(bytes: ReadonlyUint8Array, length: number): ReadonlyUint8Array;
+export function padBytes(bytes: ReadonlyUint8Array, length: number): ReadonlyUint8Array {
+    if (bytes.length >= length) return bytes;
+    const paddedBytes = new Uint8Array(length).fill(0);
+    paddedBytes.set(bytes);
+    return paddedBytes;
+}
+
+/**
+ * Fixes a `Uint8Array` to the specified length.
+ * If the array is longer than the specified length, it is truncated.
+ * If the array is shorter than the specified length, it is padded with zeroes.
+ *
+ * @param bytes - The byte array to truncate or pad.
+ * @param length - The desired length of the byte array.
+ *
+ * @example
+ * Truncates the byte array to the desired length.
+ * ```ts
+ * const bytes = new Uint8Array([0x01, 0x02, 0x03, 0x04]);
+ * const fixedBytes = fixBytes(bytes, 2);
+ * //    ^ [0x01, 0x02]
+ * ```
+ *
+ * @example
+ * Adds zeroes to the end of the byte array to reach the desired length.
+ * ```ts
+ * const bytes = new Uint8Array([0x01, 0x02]);
+ * const fixedBytes = fixBytes(bytes, 4);
+ * //    ^ [0x01, 0x02, 0x00, 0x00]
+ * ```
+ *
+ * @example
+ * Returns the original byte array if it is already at the desired length.
+ * ```ts
+ * const bytes = new Uint8Array([0x01, 0x02]);
+ * const fixedBytes = fixBytes(bytes, 2);
+ * // bytes === fixedBytes
+ * ```
+ */
+export const fixBytes = (bytes: ReadonlyUint8Array | Uint8Array, length: number): ReadonlyUint8Array | Uint8Array =>
+    padBytes(bytes.length <= length ? bytes : bytes.slice(0, length), length);
+
+/**
+ * Returns true if and only if the provided `data` byte array contains
+ * the provided `bytes` byte array at the specified `offset`.
+ *
+ * @param data - The byte sequence to search for.
+ * @param bytes - The byte array in which to search for `data`.
+ * @param offset - The position in `bytes` where the search begins.
+ *
+ * @example
+ * ```ts
+ * const bytes = new Uint8Array([0x01, 0x02, 0x03, 0x04]);
+ * const data = new Uint8Array([0x02, 0x03]);
+ * containsBytes(bytes, data, 1); // true
+ * containsBytes(bytes, data, 2); // false
+ * ```
+ */
+export function containsBytes(
+    data: ReadonlyUint8Array | Uint8Array,
+    bytes: ReadonlyUint8Array | Uint8Array,
+    offset: number,
+): boolean {
+    const slice = offset === 0 && data.length === bytes.length ? data : data.slice(offset, offset + bytes.length);
+    return bytesEqual(slice, bytes);
+}
+
+/**
+ * Returns true if and only if the provided `bytes1` and `bytes2` byte arrays are equal.
+ *
+ * @param bytes1 - The first byte array to compare.
+ * @param bytes2 - The second byte array to compare.
+ *
+ * @example
+ * ```ts
+ * const bytes1 = new Uint8Array([0x01, 0x02, 0x03, 0x04]);
+ * const bytes2 = new Uint8Array([0x01, 0x02, 0x03, 0x04]);
+ * bytesEqual(bytes1, bytes2); // true
+ * ```
+ */
+export function bytesEqual(bytes1: ReadonlyUint8Array | Uint8Array, bytes2: ReadonlyUint8Array | Uint8Array): boolean {
+    return bytes1.length === bytes2.length && bytes1.every((value, index) => value === bytes2[index]);
+}