Encoding and Decoding
By name
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.
| Encoding | Options |
|---|---|
hex | upper |
binary | separate, symbols, bits, order |
base32 | alphabet, padding |
base58 | alphabet, check, blocks |
base64 | alphabet, padding |
base85 | alphabet, delimiters |
base256 | alphabet, symbols, sample, multibase |
bech32 | prefix, limit, m |
uuencode | name, 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:
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.
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.
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.
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.
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:
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.