@unikvs/hex

Explains how to use the Transformer plugin that transparently converts byte sequences to hex strings represented as bytes.

Overview

@unikvs/hex is a Transformer plugin that converts byte sequences to bytes representing a hex string. Transformer

Writes hex-encode with encode and reads restore the original bytes with decode, so you can read and write without thinking about conversion details. Use it for inspecting hash values and binary content, for debug output, and for storing data in destinations that only accept text.

Both input and output are Uint8Array<ArrayBuffer>. Output is always lowercase (0-9, a-f), while input accepts both uppercase and lowercase. The converted size is exactly twice the original size.

It is always open. No explicit open or close is needed; isOpen always returns true and name is always "Hex".

Install it as follows.

npm install @unikvs/hex

pnpm add @unikvs/hex

yarn add @unikvs/hex

bun add @unikvs/hex

nub add @unikvs/hex

aube add @unikvs/hex

Usage

Normally create it with no arguments. Pass HexOptions only when you want to replace the instances used for UTF-8 conversion.

import { Hex } from "@unikvs/hex";

const hex = new Hex();

import { Hex, type HexOptions } from "@unikvs/hex";
import { FastUtf8 } from "fast-utf8";

const options: HexOptions = {
  encoder: new FastUtf8(),
  decoder: new FastUtf8({ strict: true }),
};

const hex = new Hex(options);

HexOptions is as follows. Normally omit it and use the defaults. When a decoder instance with strict: false is injected, invalid UTF-8 is thrown as HexDecodeError. See Errors for details.

type HexOptions = {
  readonly encoder?: FastUtf8 | undefined;
  readonly decoder?: FastUtf8 | undefined;
};

Its main members are as follows.

Here is a one-shot conversion example. Interpreting the encode result as a UTF-8 string yields lowercase hex.

import { Hex } from "@unikvs/hex";

const hex = new Hex();

const encoded = hex.encode({ data: Uint8Array.from([0xde, 0xad, 0xbe, 0xef]) });
console.log(new TextDecoder().decode(encoded)); // "deadbeef"

const decoded = hex.decode({ data: new TextEncoder().encode("DEADBEEF") });
console.log(decoded); // Uint8Array(4) [ 222, 173, 190, 239 ]

Register it with UniKvs via appendTransformer. It becomes the upstream of subsequently registered storages.

import { Hex } from "@unikvs/hex";
import UniKvs from "unikvs";

const kvs = UniKvs.config()
  .appendTransformer(new Hex())
  .appendStorage(storage)
  .create();

await kvs.open();

await kvs.set("data", input);

const output = await kvs.get("data");

set stores values hex-encoded, and get restores them to the original bytes automatically.

Streams

Supports both single values and streams.

• Single values are converted with encode and decode.
• Stream values are converted with the TransformStream from getEncodable and getDecodable.

getEncodable hex-encodes each input chunk independently and emits them in order.

getDecodable correctly restores hex split across chunk boundaries.

• An empty stream and zero-length chunks produce zero values and no error.
• If a single trailing half character remains when the stream ends, it throws HexDecodeError.
• If the input contains a character that is not valid hex, it throws HexDecodeError at that point.
• By default, invalid UTF-8 or a truncated multi-byte character throws a native TypeError. See Errors for details.

import { Hex } from "@unikvs/hex";

const hex = new Hex();

const source = new ReadableStream({
  start(controller) {
    controller.enqueue(Uint8Array.from([0xde, 0xad]));
    controller.enqueue(Uint8Array.from([0xbe, 0xef]));
    controller.close();
  },
});

const decoded = source.pipeThrough(hex.getEncodable()).pipeThrough(hex.getDecodable());

Notes

The format handling is as follows.

• No 0x prefix is added or removed. Passing "0x..." rejects x as an invalid character. Add or strip the prefix on the caller side when needed.
• Separators such as whitespace, newlines, and colons are not skipped. They are rejected as invalid characters.
• Empty input produces empty output. Passing new Uint8Array(0) is not an error.

The size in bytes becomes exactly twice the original size. Do not use it for compression, encryption, or tamper detection.

Errors

The errors this package throws are as follows.

By default (for both one-shot and stream conversion), byte sequences that are invalid as UTF-8 propagate as a native TypeError, not as HexDecodeError. When a decoder with strict: false is injected via HexOptions, they are thrown as HexDecodeError.

import { Hex, HexDecodeError } from "@unikvs/hex";

const hex = new Hex();

try {
  hex.decode({ data: new TextEncoder().encode("abc") });
} catch (error) {
  if (error instanceof HexDecodeError) {
    console.log("Cannot be interpreted as hex.");
  } else {
    throw error;
  }
}

Examples

A minimal example with Memory storage. Written values are stored hex-encoded and automatically restored to the original bytes on reads.

import { Hex } from "@unikvs/hex";
import { Memory } from "@unikvs/memory";
import UniKvs, { type PlainValue } from "unikvs";

const kvs = UniKvs.config<{ data: PlainValue<Uint8Array<ArrayBuffer>> }>()
  .appendTransformer(new Hex())
  .appendStorage(new Memory())
  .create();

await kvs.open();

const input = Uint8Array.from([0xde, 0xad, 0xbe, 0xef]);
await kvs.set("data", input);

const output = await kvs.get("data");
console.log(output.length === input.length);

await kvs.close();