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

The simplest entry point is the facade module: one function per encoding. encode_* returns a plain String because the encodings covered here cannot fail on a valid BitArray; decode_* returns Result because a malformed input is a real error.

import yabase/facade

pub fn main() {
  let encoded = facade.encode_base64(<<"Hello":utf8>>)
  // encoded == "SGVsbG8="

  let assert Ok(_decoded) = facade.decode_base64(encoded)
  // _decoded == <<"Hello":utf8>>
}

Why not let assert on encode? yabase's own gleam.toml enables glinter's assert_ok_pattern = "error" rule, so the recommended shape in production code is to avoid let assert Ok(_) for cases that cannot meaningfully fail. The facade returns plain String for infallible encodings and only the decode side is Result-shaped — there let assert is fine in a README snippet but real code should propagate the error. If you need to pick an encoding at runtime, see the unified API in API layers; yabase.encode is Result-shaped for every variant because the Encoding ADT erases per-variant error possibilities.

Integer IDs

Short URL-safe identifiers — DB autoincrement ids, sequence numbers, hash truncations — usually want Int -> compact string rather than BitArray -> String. The yabase/intid module provides this directly so callers do not have to write the Int -> big-endian bytes -> trim-leading-zero shim themselves.

import yabase/intid

pub fn main() {
  let token = intid.encode_int_base58(42)
  // token == "j"

  let assert Ok(_n) = intid.decode_int_base58(token)
  // _n == 42
}

Available: encode_int_base32_rfc4648, encode_int_base32_crockford, encode_int_base36, encode_int_base58, encode_int_base58_flickr, encode_int_base62 and their matching decode_int_* (returning Result(Int, CodecError)).

encode_int_* emits canonical form. decode_int_* is tolerant of leading zero characters (decode_int_base58("0042") and decode_int_base58("42") return the same Int). Negative inputs are normalized via int.absolute_value before encoding.

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         # download deps and run all checks, including glinter
just lint       # run glinter with the repo config
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