@fimbul-works/futhark

Futhark (Old Norse for alphabet) is a tiny, zero-dependency utility for encoding and decoding numbers, BigInts, byte buffers, and strings using configurable alphabets — bundling 15 built-in alphabets ranging from compact practical standards (Base-62, Base-58, Crockford Base-32) to historical scripts (Elder Futhark, Ogham, Glagolitic) and esoteric ciphers (I Ching, Braille, Zodiac).

Features

• ⚡ Ultra-lightweight & Tree-shakeable: Pure arithmetic, zero dependencies — import only the alphabets and utilities you use.
• 🔢 Number & BigInt Support: Encode standard numbers or arbitrary-precision bigints (Snowflake IDs, UUIDs, hashes).
• 💾 Buffer & String Encoding: Encode and decode Uint8Array buffers and UTF-8 strings into any alphabet (lossless binary-to-text with leading zero preservation).
• 🔤 Alphabet-agnostic: Encode and decode with any custom ordered character set you define.
• 📦 15 Built-in Alphabets: Compact ID compressors, historical runes, and esoteric ciphers.
• 🔁 Fully Reversible: Lossless round-trips guaranteed.

Installation

pnpm add @fimbul-works/futhark
# or
npm install @fimbul-works/futhark
# or
yarn add @fimbul-works/futhark

Quick Start

Numbers & BigInts

import {
  encodeBase62,
  decodeBase62,
  encodeBigBase62,
  decodeBigBase62,
  encodeFuthark,
  decodeFuthark,
} from '@fimbul-works/futhark';

// Base-62 ID encoding
encodeBase62(123456789); // "8m0Kx"
decodeBase62("8m0Kx");   // 123456789

// 64-bit / 128-bit BigInt support
encodeBigBase62(18446744073709551615n); // "lYGhA16ahyf"
decodeBigBase62("lYGhA16ahyf");          // 18446744073709551615n

// Elder Futhark runes
encodeFuthark(999);      // "ᚢᛒᛊ"
decodeFuthark("ᚢᛒᛊ");    // 999

Buffers & Strings

Encode arbitrary binary payloads (Uint8Array) or UTF-8 text strings into any alphabet using universal radix conversion (with lossless leading zero preservation):

import {
  encodeString,
  decodeString,
  encodeBuffer,
  decodeBuffer,
  FUTHARK_ALPHABET,
  BASE58_ALPHABET,
} from '@fimbul-works/futhark';

// Secret messages & easter eggs in Elder Futhark runes
const encoded = encodeString("This is a secret message", FUTHARK_ALPHABET);
// "ᚲᚺᚢᛒᚱᚦᚾᚷᛃᛜᛃᚺᚢᛞᛃᛏᛉᚷᛁᚾᛜᚲᛚᛖᛏᚷᛞᛊᚨᛒᚾᛚᛜᛉᛗᚺᛒᚨᚨᚾᛇᚲ"

decodeString(encoded, FUTHARK_ALPHABET);
// "This is a secret message"

// Binary buffers (lossless with leading zero preservation)
const bytes = new Uint8Array([0x00, 0x00, 0xca, 0xfe, 0xba, 0xbe]);
const encodedBytes = encodeBuffer(bytes, BASE58_ALPHABET);
decodeBuffer(encodedBytes, BASE58_ALPHABET);
// Uint8Array [0, 0, 202, 254, 186, 190]

[!NOTE] Buffer and string encoding uses arbitrary-precision BigInt under the hood ($O(n^2)$ time complexity). It is designed for tokens, IDs, hashes, keys, and text strings up to several kilobytes.

Custom Alphabet

Bring your own character set for domain-specific encodings:

import { encodeNumber, decodeNumber, encodeBigInt, decodeBigInt } from '@fimbul-works/futhark';

const FINGERS = "👌☝️✌️🤟🖖";

encodeNumber(255, FINGERS);        // "☝️☝️👌🤟"
decodeNumber("☝️☝️👌🤟", FINGERS); // 255

encodeBigInt(1000000000000n, FINGERS);                      // "✌️👌🖖🤟✌️✌️☝️👌☝️👌🤟👌☝️🤟🖖🖖"
decodeBigInt("✌️👌🖖🤟✌️✌️☝️👌☝️👌🤟👌☝️🤟🖖🖖", FINGERS); // 1000000000000n

Built-in Alphabets

Each alphabet provides a constant and convenience functions for both number and bigint following the naming pattern:

• encode<Name>(num: number): string / decode<Name>(str: string): number
• encodeBig<Name>(num: bigint): string / decodeBig<Name>(str: string): bigint

| Alphabet | Base | Sample Glyphs / Range | Constant | |---|---|---|---| | Base-62 | 62 | 0–9, a–z, A–Z | BASE62_ALPHABET | | Base-64 | 64 | Standard Base-64 (+, /) | BASE64_ALPHABET | | URL-Safe Base-64 | 64 | URL-safe Base-64 (-, _) | URL_SAFE_BASE64_ALPHABET | | Base-58 | 58 | Bitcoin / IPFS (no 0, O, I, l) | BASE58_ALPHABET | | Crockford Base-32 | 32 | Unambiguous uppercase (no I, L, O, U) | CROCKFORD_BASE32_ALPHABET | | Z85 | 85 | ZeroMQ string-safe printable ASCII | Z85_ALPHABET | | Elder Futhark | 24 | Norse runes (ᚠᚢᚦᚨᚱᚲ...) | FUTHARK_ALPHABET | | Ogham | 20 | Early Medieval Celtic script (ᚁᚂᚃᚄᚅ...) | OGHAM_ALPHABET | | Glagolitic | 41 | Old Church Slavonic script (ⰀⰁⰂ...) | GLAGOLITIC_ALPHABET | | Zodiac | 12 | Astrological signs (♈♉♊♋...) | ZODIAC_ALPHABET | | I Ching Trigrams | 8 | Taoist Bagua trigrams (☰☱☲...) | TRIGRAM_ALPHABET | | I Ching Hexagrams | 64 | Full divination set (䷀䷁䷂...) | HEXAGRAM_ALPHABET | | Braille | 64 | 6-dot Braille patterns (⠀⠁⠂...) | BRAILLE_ALPHABET | | Dice | 6 | Dice faces (⚀⚁⚂⚃⚄⚅) | DICE_ALPHABET | | DNA | 4 | Nucleotide bases (ACGT) | DNA_ALPHABET |

Documentation

Full TypeScript signatures, parameters, return types, and constants are documented in the API Reference.

License

MIT License — see LICENSE for details.

Built with ⚡ by FimbulWorks