parseHexString

Parses a value into a canonical lowercase hexadecimal string. This parser combines the validateHexString semantic validator and the normalizeHexString normalizer to ensure that only well‑formed, byte‑aligned hexadecimal data is accepted.

The parser never throws and never mutates input. It returns a structured ParseResult<string> describing success or failure.

Signature

function parseHexString(value: unknown): ParseResult<string>

Behavior

• Accepts raw hexadecimal strings containing only:
• Numeric digits (0-9).
• Uppercase or lowercase letters.
• Requires even-length (byte-aligned) hex data.
• Normalizes valid strings into lowercase canonical form.
• Rejects:
• malformed hex strings
• odd-length strings
• empty or whitespace-only strings
• non-string values
• Never throws or mutates input.

Returns

• ok: true: And the canonical lowercase hex string when parsing succeeds.
• ok: false, value: null: And a list of issues when parsing fails.

Examples

parseHexString("DEADBEEF")
// { ok: true, value: "deadbeef", issues: [] }

parseHexString("abc")
// { ok: false, value: null, issues: ["Value could not be normalized into a canonical hexadecimal string"] }

parseHexString("zzzz")
// { ok: false, value: null, issues: ["Value is not a valid hexadecimal string"] }

Notes

• Hex strings must be byte-aligned; odd-length inputs are rejected.
• Normalization enforces lowercase output for consistency.
• This parser is pure, side-effect-free, and safe for all runtime environments.