generate short and reversible IDs as a replacement for numerical or hex IDs

  • base-n

Downloads in past


1103.0.03 years ago8 years agoMinified + gzip package size for base-n in KB


NPM Version Build Status Coverage Status Dependency Status
A utility for encoding/decoding base10 integers into a URL safe base-n string

Getting Started

Install the module with: npm install base-n


The primary use case for this module is to shorten numerical IDs in terms of number of characters for URL usage, and then to easily decode those again at a later point in time. For example, base10 only supports up to 100 unique IDs in a two character space. By contrast, base64 supports up to (64^2 =) 4096 unique IDs in the same two character space.
It should be noted that the encoding does not use a random number generater or a salt, so if cryptographic security is of importance, this probably won't meet your needs.
base-n supports encoding base10 integers into a non base10 encoded string, where n can be any value between 2 and 64. By default, the utility supports up to base64, using the following URL safe characters:


To use the lib, simply create an encoder instance:
var baseN = require('base-n');
var b64 = baseN.create();

// => 'a'
// => '1a'
// => '3dKN'

To decode, you can use the same object:
// => 35
// => 146897

Choosing a different base simply uses a subset of these available characters. Should you need to use a completely different set of characters (e.g., if you have no need for URL safe characters), you can pass in your own custom set of characters.
var baseN = require('base-n');
var b2 = baseN.create({
    characters: ['$', '*']

// => '*$*$'

For URL usage, it may be useful to generated a fixed length output. You can specify the fixed length to the constructor, and the output will be padded with leading 0's to match that length:
var b64 = baseN.create({
    length: 4

// => '000a'

// You can also indirectly specify max length by specifying the maximum integer
// value acceptable to the encoder:

var b64 = baseN.create({
    max: 4096
// => results in a length of 3, because it requires 3 characters to safely
//    represent 4096 ('100'). Note however, that the encoder will continue to
//    safely encode base10 values greater than 4096, so long as they can be
//    represented by 3 characters.

Multi-character dictionaries

Multi-character dictionaries can be used to go beyond base64:
var b128 = baseN.create({
    characters: ['00', '01', ... '77', '7F']

// => '0200'

Error cases

Should you attempt to encode a value that's greater than can be represented by the fixed length, base-n will throw an error:
var b64 = baseN.create({
    length: 2

// the max space available for two characters is 4096 (0-4095), so this will
// fail, since the encoded value for 4096 is '100'
// => Error: base10 value of 4096 (encoded: 100) exceeds maximum length of 2

If base-n comes across an unknown character while decoding, base-n will throw an error:
var b64 = baseN.create();

// => Error: unknown $ character encountered



Create an encoder/decoder object.
  • options.max {Number} - Set maximum input integer. Mutually exclusive with length option.
  • options.length {Number} - Set maximum output length of encoded value. Mutually exclusive with max option.
  • options.base {Number} - Set the base-n value of the encoder. Mutually exclusive with characters option.
  • options.characters {Array} - Custom character dictionary. The length of the array becomes the base. Multi-character dictionaries can be used. Mutually exclusive with base option.

Returns: {Object} encoder object
The returned encoder object has the following methods


  • num {Number} - any base10 integer value

Returns: {String} string encoded value


  • stringVal {String} - any value encoded by base-n

Returns: {Number} base10 integer


To start contributing, install the git pre-push hooks:
make githooks

Before committing, lint and test your code using the included Makefile:
make prepush


Copyright (c) 2018 Alex Liu.
Licensed under the MIT license.