Nurturing Palpable Magnificence

    base-n

    3.0.0 • Public • Published

    base-n

    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

    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

    Copyright (c) 2018 Alex Liu.

    Licensed under the MIT license.

    Install

    npm i base-n

    DownloadsWeekly Downloads

    677

    Version

    3.0.0

    License

    MIT

    Unpacked Size

    38.4 kB

    Total Files

    16

    Last publish

    Collaborators

    • donutespresso