bytes

Purpose

Low-level byte I/O for the Suaveplan monorepo. Provides lossless conversion between Uint8Array and the three ubiquitous text representations (hex, base64, UTF-8), ergonomic Uint8Array utilities (concat, slice, equality, format auto-detection, unified conversion façade), and UUID string ↔ 16-byte binary round-trip functions.

Requirements

encoding

bytesToHex(bytes: Uint8Array): string — lowercase hex, empty → ""
hexToBytes(hex: string): Uint8Array — case-insensitive; throws BYTES.ENCODE.INVALID_HEX on odd length or non-hex chars
bytesToBase64(bytes: Uint8Array): string — standard base64 with = padding
base64ToBytes(base64: string): Uint8Array — throws BYTES.ENCODE.INVALID_BASE64 on invalid input
bytesToUtf8(bytes: Uint8Array): string — TextDecoder("utf-8")
utf8ToBytes(str: string): Uint8Array — TextEncoder

uint8

concatUint8Arrays(...arrays: Uint8Array[]): Uint8Array
sliceUint8Array(arr, start, end?): Uint8Array
uint8ArraysEqual(a, b): boolean — not constant-time
detectInputFormat(input: BytesInput): InputFormat — heuristic: Uint8Array → "uint8array", even-length hex string → "hex", else "utf8"
inputToUint8Array(input, format?): Uint8Array
validateInputTypeFormat(input, format): void — throws BYTES.UINT8.FORMAT_MISMATCH
formatOutput(bytes, format): string | Uint8Array
convertDataFormat(input, outputFormat, inputFormat?): string | Uint8Array — OTel span

uuid

generateUuid(): string — UUIDv4 via crypto.randomUUID()
uuidToUint8Array(uuid: string): Uint8Array — 16 bytes; throws BYTES.UUID.INVALID_FORMAT
uint8ArrayToUuid(bytes: Uint8Array): string — canonical lowercase; throws BYTES.UUID.INVALID_LENGTH

Error codes

BYTES.ENCODE.INVALID_HEX, BYTES.ENCODE.INVALID_BASE64, BYTES.ENCODE.INVALID_UTF8 (reserved), BYTES.UINT8.INVALID_INPUT, BYTES.UINT8.FORMAT_MISMATCH, BYTES.UUID.INVALID_LENGTH, BYTES.UUID.INVALID_FORMAT

Version

Published: 0.1.0 (2026-04-20)

2.0 KiB Raw Blame History