# 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)