@pfeiferio/custom-base

Custom base encoding and decoding for numbers and BigInts using arbitrary charsets.

This library allows you to encode and decode numeric values using any character set.
It supports both JavaScript number and bigint types and is fully ESM-based with no dependencies.

---

Features

- Encode / decode number and bigint
- Arbitrary custom charsets
- Built-in presets (base2, base16, base42, base128)
- Cached and validated charset handling
- Zero dependencies
- Native Node.js test runner

---

Installation

``bash
npm install @pfeiferio/custom-base
``

---

Usage

$3

`js
import { encodeNumber, decodeNumber, presets } from '@pfeiferio/custom-base'

const encoded = encodeNumber(255, presets.base16)
const decoded = decodeNumber(encoded, presets.base16)

console.log(encoded) // "ff"
console.log(decoded) // 255
`

---

$3

`js
import { encodeBigInt, decodeBigInt, presets } from '@pfeiferio/custom-base'

const value = 12345678901234567890n

const encoded = encodeBigInt(value, presets.base42)
const decoded = decodeBigInt(encoded, presets.base42)

console.log(decoded === value) // true
`

---

$3

You can provide your own charset as a string:

`js
import { encodeNumber } from '@pfeiferio/custom-base'

const charset = 'ABCDEFG123456'
const encoded = encodeNumber(1337, charset)
`

---

$3

Internally, charsets are compiled, validated and cached.
You can normalize inputs manually if needed:

`js
import { ensureCharset, presets } from '@pfeiferio/custom-base'

const charset = ensureCharset(presets.base2)
`

The returned Charset object is immutable and guaranteed to be valid.

---

Presets

`js
import { presets } from '@pfeiferio/custom-base'

presets.base2
presets.base16
presets.base42
presets.base128
``

All presets are non-standard and provided purely for convenience.

---

Node.js Support

* Node.js ≥ 18
* ESM only

---

License

MIT