API reference › @evolu/common › Bytes

Bytes: Uint8Array helpers, the Buffer codec, and byte sizes.

Sizes follow the same pattern as durations in Time.ts:

• ByteLength is the canonical unit, a validated number of bytes.
• ByteSizeLiteral is the human-readable form, such as "10MiB", validated at compile time and runtime.
• ByteSize is what APIs accept: ByteSizeLiteral | ByteLength.
• byteSizeToByteLength normalizes a ByteSize to a ByteLength.
• ByteLengthFromString parses either form from text.

Buffer-based decoding functions throw instead of returning Result. Result is not slow, but every successful decode would allocate one, and a protocol message decodes many values. Throwing is the safe bet for that hot path until benchmarks cover the alternatives. Callers convert a thrown error into a Result once, at the boundary, as parseProtocolHeader in Protocol.ts does.

Classes

Class	Description
BufferError	Custom error for Buffer-related failures like premature end of data. Provides better stack traces for debugging binary protocol issues.

Functions

Function	Description
byteSizeToByteLength	Converts a ByteSize to a ByteLength. A ByteLength is returned unchanged.
bytesToHex	Convert byte array to hex string. Uses built-in function, when available.
bytesToUtf8	Converts bytes to string using UTF8 encoding.
concatBytes	Copies several Uint8Arrays into one.
createBuffer	Creates a Buffer for efficient byte operations.
createRunLengthEncoder	Creates an incremental run-length encoder.
decodeFlags	Decodes a byte into an array of boolean flags.
decodeJsonValue	Decodes a JsonValue using the MessagePack format.
decodeNonNegativeInt	Decodes a non-negative integer from a variable-length integer format.
decodeNumber	-
decodeRle	Decodes a run-length encoded sequence.
decodeString	Decodes a length-prefixed UTF-8 string.
encodeFlags	Encodes an array of boolean flags into a single byte.
encodeJsonValue	Encodes a JsonValue using the MessagePack format.
encodeLength	Encodes the length of an array-like value.
encodeNonNegativeInt	Encodes a non-negative integer into a variable-length integer format. It's more efficient than encoding via encodeNumber.
encodeNumber	Evolu uses MessagePack to handle finite numbers except for NonNegativeInt. For NonNegativeInt, Evolu provides more efficient encoding.
encodeString	Encodes a length-prefixed UTF-8 string.
hexToBytes	Convert hex string to byte array. Uses built-in function, when available.
utf8ToBytes	Converts string to bytes using UTF8 encoding.

Interfaces

Interface	Description
Buffer	A Buffer is a dynamic, resizable container for binary data, optimized for scenarios where the final size is unknown. It grows exponentially (doubling its capacity) to minimize memory reallocations and uses subarray for efficient, copy-free data access in methods like unwrap and shift.
ByteLengthError	Error returned when ByteLength rejects negative zero.
ByteLengthFromStringError	Error returned when a string is neither a number of bytes nor a ByteSizeLiteral.
ByteSizeLiteralError	Error returned when ByteSizeLiteral rejects a value.
RunLengthEncoder	Incrementally encodes consecutive equal values using run-length encoding.

Type Aliases

Type Alias	Description
ByteLength	Non-negative safe integer number of bytes.
ByteSize	ByteSizeLiteral or ByteLength.
ByteSizeLiteral	Byte length literal Type with compile-time and runtime validation.
ByteSizeLiteralBytes	Bytes: "0B" to "1023B". See ByteSizeLiteral.
ByteSizeLiteralGiB	GiB: "1GiB" to "1023GiB" or "1.5GiB" to "1023.5GiB". See ByteSizeLiteral.
ByteSizeLiteralKiB	KiB: "1KiB" to "1023KiB" or "1.5KiB" to "1023.5KiB". See ByteSizeLiteral.
ByteSizeLiteralMiB	MiB: "1MiB" to "1023MiB" or "1.5MiB" to "1023.5MiB". See ByteSizeLiteral.
ByteSizeLiteralTiB	TiB: "1TiB" to "1023TiB" or "1.5TiB" to "1023.5TiB". See ByteSizeLiteral.

Variables

Variable	Description
ByteLength	Non-negative safe integer number of bytes.
ByteLengthFromString	Transforms a number of bytes or a ByteSizeLiteral in text into a ByteLength.
ByteSizeLiteral	Byte length literal Type with compile-time and runtime validation.
ByteSizeLiteralBytes	Bytes: "0B" to "1023B". See ByteSizeLiteral.
ByteSizeLiteralGiB	GiB: "1GiB" to "1023GiB" or "1.5GiB" to "1023.5GiB". See ByteSizeLiteral.
ByteSizeLiteralKiB	KiB: "1KiB" to "1023KiB" or "1.5KiB" to "1023.5KiB". See ByteSizeLiteral.
ByteSizeLiteralMiB	MiB: "1MiB" to "1023MiB" or "1.5MiB" to "1023.5MiB". See ByteSizeLiteral.
ByteSizeLiteralTiB	TiB: "1TiB" to "1023TiB" or "1.5TiB" to "1023.5TiB". See ByteSizeLiteral.
decodeLength	Decodes an array-like value length.