Socket
Socket
Sign inDemoInstall

base-n

Package Overview
Dependencies
1
Maintainers
1
Versions
3
Alerts
File Explorer

Advanced tools

Install Socket

Detect and block malicious and high-risk dependencies

Install

base-n

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


Version published
Maintainers
1
Created

Changelog

Source

3.0.0 (2020-07-05)

Bug Fixes
  • documented type of base option (#6) (aa317a68)
  • cli name to base-n (#5) (3b4cc027)
Breaking Changes
  • characters option is now an array of string instead of a string. (1abf960a)

Readme

Source

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.

Keywords

FAQs

Package last updated on 06 Jul 2020

Did you know?

Socket

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install

Related posts

SocketSocket SOC 2 Logo

Product

  • Package Alerts
  • Integrations
  • Docs
  • Pricing
  • FAQ
  • Roadmap

Packages

Stay in touch

Get open source security insights delivered straight into your inbox.


  • Terms
  • Privacy
  • Security

Made with ⚡️ by Socket Inc