# encoding

<!-- begin:auto-docs -->
_(no submodules)_
<!-- end:auto-docs -->
## Purpose

The `encoding` module provides lossless, bidirectional conversion between raw `Uint8Array` byte sequences and three ubiquitous text representations: lowercase hexadecimal, standard base64, and UTF-8. It is the lowest-level I/O surface in `@suaveplan/bytes` and is intentionally free of any dependency beyond `@opentelemetry/api` and the `@suaveplan/error` error substrate.

Every conversion function validates its input strictly and throws a typed `BytesError` on malformed data, making it safe to use directly in protocol parsers, cryptographic pipelines, and data serialisation layers without additional guard code at the call site.

## Features

- **Hex encoding/decoding** — `bytesToHex` emits lowercase two-character hex pairs; `hexToBytes` accepts both upper- and lowercase and rejects odd-length or non-hex inputs with `BYTES.ENCODE.INVALID_HEX`.
- **Base64 encoding/decoding** — `bytesToBase64` uses the standard (non-URL-safe) alphabet; `base64ToBytes` validates the input against the standard alphabet before delegating to `atob`, rethrowing any decode error as `BYTES.ENCODE.INVALID_BASE64`.
- **UTF-8 encoding/decoding** — `utf8ToBytes` uses `TextEncoder` and `bytesToUtf8` uses `TextDecoder`, both handling multi-byte Unicode code points correctly.
- **OTel tracing** — every exported function wraps its body in a named active span under the `@suaveplan/bytes` tracer so encoding operations appear in distributed traces.
- **Zod schemas** — `HexStringSchema` and `Base64StringSchema` are exported from `encoding.schemas.ts` for use in Zod-based validation pipelines.
- **Property-tested** — fast-check verifies lossless round-trips for arbitrary byte sequences for all three codecs.

## Usage: Basic Example

```ts
import { bytesToHex, hexToBytes, bytesToBase64, base64ToBytes, utf8ToBytes, bytesToUtf8 } from "@suaveplan/bytes/encoding";

const raw = new Uint8Array([72, 101, 108, 108, 111]);

// Hex
const hex = bytesToHex(raw);        // "48656c6c6f"
const back = hexToBytes(hex);       // Uint8Array [72, 101, 108, 108, 111]

// Base64
const b64 = bytesToBase64(raw);     // "SGVsbG8="
const back2 = base64ToBytes(b64);  // Uint8Array [72, 101, 108, 108, 111]

// UTF-8
const text = bytesToUtf8(raw);      // "Hello"
const back3 = utf8ToBytes(text);   // Uint8Array [72, 101, 108, 108, 111]
```

## Usage: Advanced Example

```ts
import { hexToBytes, bytesToBase64, BytesError } from "@suaveplan/bytes";

// Safely parse an untrusted hex payload from an HTTP header
function parseHexHeader(value: string): Uint8Array {
    try {
        return hexToBytes(value.trim().toLowerCase());
    } catch (err) {
        if (err instanceof BytesError) {
            // err.code === "BYTES.ENCODE.INVALID_HEX"
            throw new Error(`Malformed X-Signature header: ${err.message}`);
        }
        throw err;
    }
}

// Convert the raw bytes to base64 for JSON transport
const signature = parseHexHeader("deadbeef");
const forJson = bytesToBase64(signature); // "3q2+7w=="
```

## API Reference

### `bytesToHex(bytes: Uint8Array): string`

Converts `bytes` to a lowercase hexadecimal string. Each byte becomes exactly two hex characters. Returns `""` for an empty array.

### `hexToBytes(hex: string): Uint8Array`

Converts a hex string to a `Uint8Array`. Accepts upper- and lowercase characters. Returns an empty array for an empty string.

**Throws** `BytesError(BYTES.ENCODE.INVALID_HEX)` when:

- `hex.length` is odd.
- `hex` contains characters outside `[0-9a-fA-F]`.

### `bytesToBase64(bytes: Uint8Array): string`

Converts `bytes` to a standard base64 string (with `=` padding). Returns `""` for an empty array.

### `base64ToBytes(base64: string): Uint8Array`

Converts a standard base64 string to a `Uint8Array`. Returns an empty array for an empty string.

**Throws** `BytesError(BYTES.ENCODE.INVALID_BASE64)` when `base64` contains characters outside the standard base64 alphabet or the decode otherwise fails.

### `bytesToUtf8(bytes: Uint8Array): string`

Decodes `bytes` as a UTF-8 string using `TextDecoder`. Invalid sequences are replaced with the Unicode replacement character (U+FFFD) per platform behaviour.

### `utf8ToBytes(str: string): Uint8Array`

Encodes `str` as UTF-8 bytes using `TextEncoder`. Every Unicode code point, including surrogate pairs and multi-byte characters, is encoded correctly.

## Implementation Notes

The hex codec avoids regular-expression replacement in the hot encode path in favour of a simple loop over byte values with `toString(16).padStart(2, "0")`, which is both readable and cache-friendly on V8/JavaScriptCore. The decode path uses a single `HEX_RE.test()` validation pass before looping — this avoids per-character error checking while still catching all invalid inputs in one branch.

The base64 codec delegates to the platform `btoa`/`atob` globals (available natively in Node 18+ and Bun), avoiding any third-party encoding library. The encode path materialises a binary string from the byte array; the decode path pre-validates with a regex before calling `atob` and wraps any thrown exception in a `BytesError` so callers never see a raw `DOMException`.

OTel spans are started synchronously and ended in `finally` blocks, ensuring spans are always closed even when an exception propagates. The tracer is module-level so instrumentation is zero-cost when no SDK is installed (the `@opentelemetry/api` noop tracer is used automatically).