@endo/hex

@endo/hex

@endo/hex encodes and decodes between Uint8Array and hexadecimal strings. It is a ponyfill for the TC39 Uint8Array.prototype.toHex and Uint8Array.fromHex intrinsics (proposal-arraybuffer-base64, Stage 4), but for errors provides a consistent diagnostic optionally including a name to identify the file the source material came from, which can be instrumental for debugging.

On engines that ship the native intrinsics, encodeHex and decodeHex dispatch to them at module load time. On older engines, and in SES-locked-down compartments where a realm has removed the intrinsics, the package falls through to a portable pure-JavaScript implementation.

Install

npm install @endo/hex

Usage

import { encodeHex } from '@endo/hex/encode.js';
import { decodeHex } from '@endo/hex/decode.js';

// Or, if you genuinely need to entrain both implementations:
// import { encodeHex, decodeHex } from '@endo/hex';

encodeHex(new Uint8Array([0xb0, 0xb5, 0xc4, 0xfe])); // 'b0b5c4fe'
decodeHex('b0b5c4fe'); // Uint8Array(4) [0xb0, 0xb5, 0xc4, 0xfe]

API

encodeHex(bytes) -> string

Encodes a Uint8Array as a lowercase hex string. Callers that need uppercase can call .toUpperCase() on the result.

decodeHex(string, name?) -> Uint8Array

Decodes a hex string to a Uint8Array. Accepts both upper- and lowercase input. Throws on odd-length strings and on characters outside [0-9a-fA-F]. The optional name parameter is included in error messages for diagnostic context.

Hardened JavaScript

The native intrinsic reference is captured once at module load, before any caller can reach the exported functions and before SES lockdown freezes Uint8Array. Post-lockdown mutation of Uint8Array cannot redirect the dispatched bindings.

In a post-lockdown environment, this module hardens its interfaces to reduce supply chain attack exposure.