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);
b64.encode(100);
b64.encode(842673);
To decode, you can use the same object:
b64.decode('z');
b64.decode('zTh');
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);
var b64 = baseN.create({
max: 4096
});
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);
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
});
b64.encode(4096);
If base-n comes across an unknown character while decoding, base-n will throw
an error:
var b64 = baseN.create();
b64.decode('$');
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
Copyright (c) 2018 Alex Liu.
Licensed under the MIT license.