README

base-n

A utility for encoding/decoding base10 integers into a URL safe base-n string

Getting Started

Install the module with: npm install base-n

Why?

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:

0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ_-

Usage

To use the lib, simply create an encoder instance:

var baseN = require('base-n');
var b64 = baseN.create();

b64.encode(10);
// => 'a'
b64.encode(100);
// => '1a'
b64.encode(842673);
// => '3dKN'

To decode, you can use the same object:

b64.decode('z');
// => 35
b64.decode('zTh');
// => 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: ['

, '*']
});

b2.encode(10);
// => '*$*

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
});

b64.encode(10);
// => '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']
});

b128.encode(256);
// => '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'
b64.encode(4096);
// => 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();

b64.decode('

);
// => Error: unknown $ character encountered

API

create([options])

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

encode(num)

num {Number} - any base10 integer value

Returns: {String} string encoded value

decode(stringVal)

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

Returns: {Number} base10 integer

Contributing

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

make githooks

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

make prepush

License

Licensed under the MIT license.

Usage no npm install needed!