@suaveplan/bytes - Low-level byte utilities: hex/base64/utf8 encoding, Uint8Array helpers, UUID conversion
Summary
Low-level byte utilities for Suaveplan: lossless hex/base64/UTF-8 encoding, Uint8Array manipulation, and UUID conversion. No native addons; depends only on platform globals (TextEncoder, atob/btoa, crypto.randomUUID) and @suaveplan/error for typed errors.
Documentation tree
- encoding — (no submodules)
- encoding — (no submodules)
- errors — (no submodules)
- bytes-error — (no submodules)
- types — (no submodules)
- types — (no submodules)
- uint8 — (no submodules)
- uint8 — (no submodules)
- uuid — (no submodules)
- uuid — (no submodules)
Install
bun add @suaveplan/bytes
Quick Start
import {
bytesToHex, hexToBytes,
bytesToBase64, base64ToBytes,
bytesToUtf8, utf8ToBytes,
concatUint8Arrays,
convertDataFormat,
generateUuid, uuidToUint8Array, uint8ArrayToUuid,
} from "@suaveplan/bytes";
// Encoding
const raw = utf8ToBytes("Hello"); // Uint8Array [72,101,108,108,111]
const hex = bytesToHex(raw); // "48656c6c6f"
const b64 = bytesToBase64(raw); // "SGVsbG8="
const text = bytesToUtf8(raw); // "Hello"
// Uint8 helpers
const frame = concatUint8Arrays(raw, new Uint8Array([0x21]));
// Unified conversion
const asBase64 = convertDataFormat("48656c6c6f", "base64", "hex"); // "SGVsbG8="
// UUID
const id = generateUuid(); // "550e8400-e29b-41d4-a716-446655440000"
const bytes = uuidToUint8Array(id); // Uint8Array (16 bytes)
const back = uint8ArrayToUuid(bytes); // → id
Modules
| Module | Description | Docs |
|---|---|---|
@suaveplan/bytes/encoding |
Hex, base64, UTF-8 encode/decode | encoding.md |
@suaveplan/bytes/uint8 |
Uint8Array utilities and format conversion | uint8.md |
@suaveplan/bytes/uuid |
UUID generation and binary conversion | uuid.md |
@suaveplan/bytes/errors |
BytesError, BYTES_CODES |
— |
@suaveplan/bytes/schemas |
Zod schemas (HexStringSchema, etc.) | — |
Benchmarks
Run with bun src/__benchmarks__/encoding.bench.ts.
clk: ~2.74 GHz
cpu: Intel(R) Xeon(R) CPU E5-2696 v4 @ 2.20GHz
runtime: bun 1.3.13 (x64-linux)
benchmark avg (min … max)
bytesToHex (32 bytes) 9.31 µs/iter
bytesToHex (64 KB) 5.42 ms/iter
hexToBytes (32 bytes) 7.43 µs/iter
bytesToBase64 (32 bytes) 4.29 µs/iter
bytesToBase64 (64 KB) 983.62 µs/iter
Error Codes
| Code | Thrown by |
|---|---|
BYTES.ENCODE.INVALID_HEX |
hexToBytes — odd length or non-hex chars |
BYTES.ENCODE.INVALID_BASE64 |
base64ToBytes — invalid base64 alphabet |
BYTES.ENCODE.INVALID_UTF8 |
Reserved |
BYTES.UINT8.INVALID_INPUT |
inputToUint8Array — unknown input type |
BYTES.UINT8.FORMAT_MISMATCH |
validateInputTypeFormat — type/format clash |
BYTES.UUID.INVALID_FORMAT |
uuidToUint8Array — malformed UUID string |
BYTES.UUID.INVALID_LENGTH |
uint8ArrayToUuid — not 16 bytes |