yabase

Yet Another Base -- a unified, type-safe interface for multiple binary-to-text encodings in Gleam.

• Encoding schemes are first-class values.
• Both low-level (direct module) and high-level (unified dispatch) APIs.
• Multibase prefix support for auto-detection.
• Pure Gleam implementation, no external dependencies.

Requirements

• Gleam 1.15 or later
• Erlang/OTP 27 or later

Install

gleam add yabase

Quick start

import yabase
import yabase/core/encoding.{Base64, Standard}

pub fn main() {
  // Unified API
  let assert Ok(encoded) = yabase.encode(Base64(Standard), <<"Hello":utf8>>)
  // encoded == "SGVsbG8="

  let assert Ok(decoded) = yabase.decode_as(Base64(Standard), encoded)
  // decoded == <<"Hello":utf8>>
}

Supported encodings

Core

Additional

Checksum-bearing (separate API)

These encodings carry metadata (version bytes, checksums, HRP) and have their own API outside the Encoding ADT.

API layers

yabase provides three API layers. Choose the one that fits your use case.

1. Low-level modules (direct usage)

Each encoding is accessible directly:

import yabase/base64/standard
import yabase/base32/clockwork
import yabase/base45

let encoded = standard.encode(<<"Hello":utf8>>)
// "SGVsbG8="

let assert Ok(data) = clockwork.decode("91JPRV3F41BPYWKCCGGG")

2. Unified API (dispatch by Encoding type)

import yabase
import yabase/core/encoding.{Base32, Clockwork}

let assert Ok(encoded) = yabase.encode(Base32(Clockwork), <<"Hello":utf8>>)
let assert Ok(decoded) = yabase.decode_as(Base32(Clockwork), encoded)

3. Facade (developer-friendly shortcuts)

import yabase/facade

let encoded = facade.encode_base64(<<"Hello":utf8>>)
let assert Ok(decoded) = facade.decode_base64(encoded)

Multibase support

Prefix-based encoding and auto-detection:

import yabase
import yabase/core/encoding.{Base16, Base58, Decoded}

// Encode with multibase prefix
let assert Ok(prefixed) = yabase.encode_with_prefix(Base16, <<"Hello":utf8>>)
// "f48656c6c6f"

// Decode with auto-detection
let assert Ok(Decoded(encoding: Base16, data: data)) = yabase.decode(prefixed)

Bech32 / Bech32m (BIP 173, BIP 350)

Raw Bech32 framing and checksum. Does not validate SegWit address semantics (witness version, program length):

import yabase/bech32

// Bech32 encode
let assert Ok(encoded) = bech32.encode("bc", <<0, 14, 20, 15>>)
// "bc1..." with 6-char checksum

// Auto-detect Bech32 vs Bech32m on decode
let assert Ok(decoded) = bech32.decode(encoded)
// decoded.hrp == "bc", decoded.variant == Bech32

Base58Check (Bitcoin)

import yabase/base58check

// Encode with version byte 0 (Bitcoin mainnet P2PKH)
let assert Ok(encoded) = base58check.encode(0, <<0xab, 0xcd>>)
// Base58 string with 4-byte SHA-256 checksum

// Decode and verify checksum
let assert Ok(decoded) = base58check.decode(encoded)
// decoded.version == 0, decoded.payload == <<0xab, 0xcd>>

Modules

Error handling

Encode and decode functions that can fail return Result(_, CodecError). The concrete return types vary by API:

The CodecError type provides specific error information:

Development

This project uses mise to manage Gleam and Erlang versions, and just as a task runner.

mise install    # install Gleam and Erlang
just ci         # format check, typecheck, build, test
just test       # gleam test
just format     # gleam format
just check      # all checks without deps download

Contributing

Contributions are welcome. See CONTRIBUTING.md for details.

License

MIT