Converts positive & negative float values from one base to another between bases 2-64, with support for custom alphabets
// Install it with `npm i baseroo`
import { convertBase } from 'baseroo'
// Basic numeric base conversion
const base16Value = '8f.3333333333'
const base10Value = convertBase(base16Value, 16, 10) // '143.1999999999'
// Custom alphabet conversion (new feature!)
const customBinary = convertBase('255', 10, 'AB') // 'BBBBBBBB' (using A=0, B=1)
const urlSafe = convertBase(
'hello',
'abcdefghijklmnopqrstuvwxyz',
'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_'
)
- β Standard base conversion between bases 2-64
- β Custom alphabets for specialized encoding needs
- β Floating-point precision up to 10 decimal places
- β Negative number support
- β BigInt support for large numbers
- β TypeScript support with full type safety
- β Zero dependencies and lightweight
- β 100% test coverage
Converts a numeric string from one base to another.
Parameters:
-
value: string
- The number to convert as a string -
fromBase: number | string
- Source base (2-64) or custom alphabet string -
toBase: number | string
- Target base (2-64) or custom alphabet string
Returns: string
- The converted number
Throws:
-
InvalidBaseError
- When base is invalid (< 2 for numeric, < 2 characters for custom) -
InvalidDigitError
- When input contains characters not in the source alphabet
import { convertBase } from 'baseroo'
// Hexadecimal to decimal
convertBase('ff', 16, 10) // '255'
// Binary to hexadecimal
convertBase('1010', 2, 16) // 'a'
// Decimal to binary
convertBase('255', 10, 2) // '11111111'
// Floating-point numbers
convertBase('10.5', 10, 2) // '1010.1'
convertBase('3.14', 10, 16) // '3.23d70a3d70a4'
// Negative numbers
convertBase('-255', 10, 16) // '-ff'
convertBase('-10.5', 10, 2) // '-1010.1'
Custom alphabets allow you to define your own character sets for specialized encoding needs.
// Custom binary using different characters
convertBase('1010', 2, 'AB') // 'BABA' (A=0, B=1)
convertBase('BABA', 'AB', 10) // '10'
// Custom base 12 (duodecimal)
const customBase12 = 'QWERTYUIOPAS'
convertBase('255', 10, customBase12) // 'QWP'
convertBase('QWP', customBase12, 10) // '255'
const urlSafe = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_'
convertBase('12345', 10, urlSafe) // 'dNh'
// Remove confusing characters: 0, O, 1, I, l
const clearAlphabet = '23456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz'
convertBase('12345', 10, clearAlphabet) // '7Ah'
// Use symbols for visual appeal
const symbols = 'β β£β₯β¦β
ββͺβ«'
convertBase('100', 10, symbols) // 'β β£β
β¦'
// 62-character alphabet (case-sensitive)
const base62 = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789'
convertBase('123456789', 10, base62) // '8M0kX'
const original = '123456789'
const alphabet = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ'
const encoded = convertBase(original, 10, alphabet) // 'FXSHRXW'
const decoded = convertBase(encoded, alphabet, 10) // '123456789'
// Binary fractions with custom alphabet
convertBase('3.25', 10, 'AB') // 'BB.AB' (11.01 in binary)
convertBase('BB.AB', 'AB', 10) // '3.25'
// Precision is maintained
convertBase('0.1', 10, 'AB') // 'A.AAAABABABB' (limited to 10 decimal places)
convertBase('-255', 10, 'XY') // '-YYYYYYYY'
convertBase('-YYYYYYYY', 'XY', 10) // '-255'
The library accepts both numeric and string parameters for bases:
// These are equivalent:
convertBase('ff', 16, 10) // Numeric base
convertBase('ff', '0123456789abcdef', 10) // Custom alphabet equivalent
// Type safety in TypeScript:
function myConverter(value: string, from: number | string, to: number | string) {
return convertBase(value, from, to) // β
Type-safe
}
try {
// Invalid character for base
convertBase('G', 16, 10)
} catch (error) {
console.log(error.message) // "Invalid digit 'G' for base 16."
}
try {
// Custom alphabet too short
convertBase('1', 'A', 10)
} catch (error) {
console.log(error.message) // "'fromBase' must be between 2 and 9007199254740991 not '1'."
}
try {
// Character not in custom alphabet
convertBase('C', 'AB', 10)
} catch (error) {
console.log(error.message) // "Invalid digit 'C' for base 2."
}
Custom alphabets maintain excellent performance with minimal overhead compared to numeric bases:
// Both of these perform similarly:
convertBase('12345.6789', 10, 16) // ~0.1ms
convertBase('12345.6789', 10, '0123456789ABCDEF') // ~0.1ms
// Large numbers are handled efficiently with BigInt:
convertBase('123456789012345678901234567890', 10, 'ABCDEFGHIJKLMNOPQRSTUVWXYZ') // <1ms
- Node.js: 18.x, 20.x, 22.x (LTS versions)
- TypeScript: 4.x, 5.x
- ES Modules: Full support
- CommonJS: Full support
- Browsers: Modern browsers with BigInt support
Baseroo was created from a 2015 Stack Overflow Answer from a question asking "How do you convert numbers between different bases in JavaScript?". This answer and the Gist code snippet received some comments requesting some changes, so it was converted to a package with tests and documentation in January 2023 to continue its development and make it easier to use as bug fixes and improvements are made.
The custom alphabet feature was added to support specialized encoding requirements while maintaining backward compatibility with all existing numeric base operations.