---
title: "Encoding and Decoding"
description: "Two calls by name. A codec object per encoding and a subpath per family. Strings are UTF-8 and bytes stay bytes"
canonical_url: "https://encodings.agntn.dev/guide/encoding"
---
# 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.

<table>
<thead>
  <tr>
    <th>
      Encoding
    </th>
    
    <th>
      Options
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        hex
      </code>
    </td>
    
    <td>
      <code>
        upper
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        binary
      </code>
    </td>
    
    <td>
      <code>
        separate
      </code>
      
      , <code>
        symbols
      </code>
      
      , <code>
        bits
      </code>
      
      , <code>
        order
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        base32
      </code>
    </td>
    
    <td>
      <code>
        alphabet
      </code>
      
      , <code>
        padding
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        base58
      </code>
    </td>
    
    <td>
      <code>
        alphabet
      </code>
      
      , <code>
        check
      </code>
      
      , <code>
        blocks
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        base64
      </code>
    </td>
    
    <td>
      <code>
        alphabet
      </code>
      
      , <code>
        padding
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        base85
      </code>
    </td>
    
    <td>
      <code>
        alphabet
      </code>
      
      , <code>
        delimiters
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        base256
      </code>
    </td>
    
    <td>
      <code>
        alphabet
      </code>
      
      , <code>
        symbols
      </code>
      
      , <code>
        sample
      </code>
      
      , <code>
        multibase
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        bech32
      </code>
    </td>
    
    <td>
      <code>
        prefix
      </code>
      
      , <code>
        limit
      </code>
      
      , <code>
        m
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        uuencode
      </code>
    </td>
    
    <td>
      <code>
        name
      </code>
      
      , <code>
        mode
      </code>
    </td>
  </tr>
</tbody>
</table>

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](#decoding-is-strict-mostly). 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](https://encodings.agntn.dev/encodings) 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.


## Sitemap

See the full [sitemap](https://encodings.agntn.dev/sitemap.md) for all pages.
