@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

npm install @pfeiferio/custom-base

Usage

Encoding and decoding numbers

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

Encoding and decoding BigInts

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

Custom charsets

You can provide your own charset as a string:

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

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

Charset normalization

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

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

const charset = ensureCharset(presets.base2)

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

Presets

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