Guide

Encoding and Decoding

Two calls by name. A codec object per encoding and a subpath per family. Strings are UTF-8 and bytes stay bytes

By name

ts
import { decode, encode } from "@agntn/encodings";

encode("hex", "gm");             // "676d"
encode("hex", "gm", { upper: true });
decode("hex", "0x67 6D").bytes;  // Uint8Array [103, 109]

The name is forgiving. Base 64, base_64 and b64 all find base64. qp finds quoted-printable, b58 finds base58. A name nobody knows throws UnknownEncodingError. The message lists every name, so you don't guess twice.

Options are checked against what the encoding declares. Pass upper to base64 and you get InvalidOptionError, not a silent nothing. Most encodings take none at all.

EncodingOptions
hexupper
binaryseparate, symbols, bits, order
base32alphabet, padding
base58alphabet, check, blocks
base64alphabet, padding
base85alphabet, delimiters
base256alphabet, symbols, sample, multibase
bech32prefix, limit, m
uuencodename, mode

Variants are options, not names. alphabet picks one, check adds Base58Check, m is Bech32m. They change how the text reads, so decode takes them too. Read base32hex without its alphabet and you get other bytes, or an error if you're lucky:

ts
decode("base32", "CPNMUOJ1E8", { alphabet: "hex" }).bytes;  // "foobar"
decode("base32", "CPNMUOJ1E8");  // DecodeError: "1" (U+0031) at index 7 is not in the alphabet

decode takes one more, canonical on base32 and base64, below. That's the whole list. padding there is an InvalidOptionError, since decoding reads the text with or without it. A choice outside the list is one too, and the message names the list.

What comes back

decode returns { bytes, details }. The bytes are a Uint8Array, always. Want text? Run them through TextDecoder yourself. The library won't guess that your bytes are UTF-8.

And details? That's the part of the text that isn't data.

ts
decode("bech32", "bc1qw508d6qejxtdg4y5r3zarvary0c5xw7kv8f3t4").details;
// { prefix: "bc", witnessVersion: 0 }

decode("uuencode", "begin 644 cat.txt\n#0V%T\n`\nend\n").details;
// { mode: "644", name: "cat.txt" }

Codec objects

Every family is also a plain object with encode and decode. No registry involved. Same options, same names.

ts
import { base58, hex } from "@agntn/encodings";

base58.encode(new TextEncoder().encode("hello world"));  // "StV1DL6CwTryKyV"
base58.decode("1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa", { check: true });
// 21 bytes: version 0x00, then the HASH160

These work on bytes. hex.decode returns a Uint8Array, base58.encode wants one. Hand it a string anyway? You get an EncodingError, not a polite row of zeros. The registry just wraps them. It takes text too, as UTF-8.

Subpaths

Each family has its own entry. Pulling base58 into a bundle doesn't drag the registry along. Or identify. Or every other alphabet.

ts
import { base58, createBase58check } from "@agntn/encodings/base58";
import { bech32, segwit } from "@agntn/encodings/bech32";

One subpath per family. A test bundles every one of them and fails if another family's code sneaks in.

Decoding is strict, mostly

Where a spec says something is wrong, decoding says so. It names the offending character and its index.

text
base58: "0" (U+0030) at index 0 is not in the alphabet
base64: 1 padding characters where the length needs 2

Real text often comes wrapped, though. So decoding reads through the wrapping. Base64 and base32 skip line breaks and spaces, and a MIME body decodes as it is. Hex takes either case, spaces and a 0x. Crockford reads O as 0 and I or L as 1. That's the whole point of Crockford. The index in an error still counts the text you passed, line breaks and 0x included. Decoding skipped them. Your editor didn't. Want the rules per encoding? Every encoding page lists them.

One thing slips through on purpose. The last base32 or base64 character often holds a few bits past the last byte, and decoding ignores them. YQ== and YR== both come back as a. Fine for a pasted email. For a key, one stray bit is one too many:

ts
decode("base64", "YR==", { canonical: true });
// DecodeError: "R" (U+0052) at index 1 leaves non-zero bits after the last byte

It checks those bits and nothing else. Lowercase, line breaks and a missing = still read fine. encode refuses it, since its spare bits are always zero. identify doesn't try it either. It can only say no.

An invisible character never reaches the message raw. A U+2028 shows up as U+2028. Not as a line break that rewrites the error under your feet.