20 lines
2.1 KiB
Markdown
20 lines
2.1 KiB
Markdown
# Proposal: @suaveplan/bytes
|
|
|
|
## Why This Package
|
|
|
|
Low-level byte manipulation — converting between hex, base64, UTF-8, and raw `Uint8Array`; concatenating and slicing typed arrays; round-tripping UUID strings to 16-byte buffers — is a recurring primitive across the entire monorepo. Today every package that needs these operations duplicates ad-hoc helpers or reaches into `@suaveplan/crypto-utils`, which bundles encoding utilities alongside cryptographic concerns. Separating them into a dedicated `@suaveplan/bytes` package gives the monorepo a single, well-tested, zero-cryptographic-dependency source of truth for byte I/O.
|
|
|
|
## What It Provides
|
|
|
|
The package ships three focused modules under `universal/primitives/bytes`:
|
|
|
|
- **encoding** — `bytesToHex`/`hexToBytes`, `bytesToBase64`/`base64ToBytes`, `bytesToUtf8`/`utf8ToBytes`; strict validation with typed `BytesError` codes; OTel spans on every public function; Zod schemas for hex and base64 strings; fast-check property tests verifying lossless round-trips for arbitrary byte sequences.
|
|
- **uint8** — `concatUint8Arrays`, `sliceUint8Array`, `uint8ArraysEqual`, `inputToUint8Array`, `detectInputFormat`, `validateInputTypeFormat`, `formatOutput`, `convertDataFormat`; a uniform `convertDataFormat(input, outputFormat, inputFormat?)` façade that auto-detects the input format when the caller omits it.
|
|
- **uuid** — `generateUuid` (UUIDv4 via `crypto.randomUUID()`), `uuidToUint8Array` (16-byte canonical parse), `uint8ArrayToUuid` (reformat bytes to canonical string); Zod UUID schema.
|
|
|
|
All three modules depend only on `@suaveplan/error`, `zod`, and `@opentelemetry/api`. There are no external encoding libraries and no native addons.
|
|
|
|
## Impact
|
|
|
|
`@suaveplan/crypto-utils` will be able to import `@suaveplan/bytes` for its encoding helpers in a follow-up refactor, eliminating internal duplication. Application packages that today copy-paste `bytesToHex` or import it from crypto-scoped modules will have a direct, semantically correct dependency target. The UUID utilities unblock `@suaveplan/idempotency` and any package that stores entity identifiers as binary blobs.
|