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 26 or later (CI tests OTP 26, 27, 28)

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(Base64(Standard), encoded)
  // _decoded == <<"Hello":utf8>>
}

Supported encodings

Core

Additional

Big-integer encodings (Base8, Base10, Base36, Base58, Base62, Crockford Base32) preserve leading zero bytes: each leading 0x00 byte encodes as the alphabet’s zero character, and decoding reverses this. For example, base10.decode("001") returns Ok(<<0, 0, 1>>).

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:

• Start with yabase/facade – one function per encoding, no type parameters. Covers most use cases.
• Use the unified API (yabase) when you need to select an encoding at runtime (e.g. user config, multibase auto-detection).
• Use low-level modules (yabase/base64/standard, etc.) when you need full control over a specific codec.

1. Low-level modules (direct usage)

Each encoding is accessible directly:

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

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(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, Decoded}

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

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

Multibase prefix coverage

yabase supports the following multibase prefixes. “encode + decode” means encode_multibase emits this prefix and decode_multibase recognizes it. “decode only” means decode_multibase recognizes the prefix but encode_multibase uses the canonical form.

Bech32 / Bech32m (BIP 173, BIP 350)

Byte-payload convenience API. Takes raw bytes, handles 8-to-5-bit conversion internally, and produces the checksummed Bech32 string. Does not validate SegWit address semantics (witness version, program length):

import yabase/bech32
import yabase/core/encoding.{Bech32}

// Bech32 encode
let assert Ok(encoded) = bech32.encode(Bech32, "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:

Examples

The examples/ directory contains runnable use-case examples:

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