Codetalker

BaseN encoding of 53-bit Integers using character sets of arbitrary length and order

Install

$ npm install codetalker

Usage

This module aims to keep things very simple.

Require and acquire the default export.

const Codetalker = require('codetalker').default;

Create a new instance of Codetalker, passing in your character set.

const base38 = '0123456789abcdefghijklmnopqrstuvwxyz_-'
const talker = new Codetalker(base38);

Encode some integers.

const encoded = talker.encode(302087868);

Decode some strings.

const encoded = '3uxc4s';
const decoded = talker.decode(encoded);

Translate either.

const _99 = talker.translate(talker.translate(99));
const _string = talker.translate(talker.translate('string'));

Yep. That's it.

Errors

The Codetalker constructor will throw a TypeError if given a character Array that contains non-characters, and an Error if your set contains duplicates.

const talker = new Codetalker(['a', 'b', 'c', 4]);
// TypeError: Codetalker character sets must only contain characters.
const talker2 = new Codetalker('aabbcc');
// Error: Codetalker character sets must not contain duplicates.

The encode method will throw a RangeError if the given integer is greater than MAX_SAFE_INT (9007199254740991), or less than zero.

talker.encode(9007199254740992);
// RangeError: 9007199254740992 exceeds maximum 53-bit integer size of 9007199254740991.
 
talker.encode(-51);
// RangeError: Integer input should not be negative.

The decode method will throw a TypeError if the given input is an Array, and contains a non-character value, and an Error if the given input contains a character not found in the character set. It will also throw a RangeError if the decoded string produces a value which exceeds MAX_SAFE_INT (9007199254740991).

const talker = new Codetalker('qwertyuiopasdfghjklzxcvbnm$');
 
talker.decode(['q', 'w', 3]);
// TypeError: Iterable must contain only characters.
 
talker.decode('***');
// Error: * does not exist in character set.
 
talker.decode('$$$$$$$$$$$$')
// RangeError: Decoded integer exceeds logical encoding size.

The translate method will throw a TypeError if the given value is not a Number, String, or Array.

talker.translate([1, 2, 3, 4]);
// TypeError: Translation requires a Number, String, or Array type.

Notes

While expected as a String value, characters sets (constructor) and values to be decoded (decode, translate) are permitted as an Array of characters.

Strings are easier on the eyes.

Unicode is a no-go.

License

MIT

Enjoy!

Colin 'Oka' Hall-Coates

oka.io | @Okahyphen