# allbases
[![Build Status][travis-image]][travis-url] [![npm version][npm-image]][npm-url]

[![Sauce Test Status](https://saucelabs.com/browser-matrix/efuquen_allbases.svg)](https://saucelabs.com/u/efuquen_allbases)

  Allow *safe* transformations on arbitrary bases with inputs of arbitrary length.

## Getting Started
```
var allbases = require("allbases");

var num = new allbases.BigNumber("90813095330284320");
var hex = allbases.encode(num); //142a207701d8320
console.log(allbases.decode(hex)); //90813095330284320
var b62 = allbases.encodeBase62(num); //6HVlt7fNpS
console.log(allbases.decode(b62)); //90813095330284320

var randHex = allbases.random(32); //ce82f9fbf8d7d7d4ce05815e5632e32d
var randBase62 = allbases.randomBase62(10); //SrfxoMwKqQ
```

## Why?

  There are a few other projects in node that deal with encoding and decoding of
  numbers into different representations (octal, hex, base 64, etc.). However all
  the major libraries in use rely upon regular javascript integers to for these
  transformations.  While this works fine for data that can reliably fit within
  a `Number` it becomes a problem when dealing with much larger values.

  Therefor the goal of this library is to allow arbritrary base transformations, 
  using arbritrary groups of characters, with an arbritrary level of precision.

## Known Limitations

  In order to calculate the bits needed for a random number we use Math.pow
  to generate combos of values as a floating point and then Math.log to get
  number of bits.  This will break as soon as combo hits the largest number
  that Math.pow can handle.  For a base62 value this will happen after 171
  characters.  Current implemntation will detect when combos has exhausted
  floating point maximum and throw an appropriate error during random number
  generation.

  The cause of limitation is we are using Math.log, which the big.js library has
  no equivalent function for.  We must use some numerical method that will
  allow use to calculate log's for arbritrary large numbers, or find another
  way to estimate number of random bits needed.  Whatever method used does
  not need to be exact but must be computationally practical.

  *Note*: Another Idea I'm just documenting here.  We can use big.js to get
  the true number of combos, then we can detect if it will overflow JS Number
  and break it down to calculate number of bits until we reach a number less
  then Number.MAX_VALUE.

## TODO

* Add all major encodings.
* Allow ignoring of case (i.e. to handle uppercase and lowercae hex).
* Create new object for random generation, will allow optimization so we don't perform duplicate operations when not needed.
* Probably need to add opts param to tweak things in encode & decode
* Other style/performance optimizations documented in code.
* emphasize must use `allbases.bignum` or will get type errors.


[npm-image]: https://badge.fury.io/js/allbases.svg
[npm-url]: https://www.npmjs.com/package/allbases
[travis-image]: https://api.travis-ci.org/somespider/allbases.svg?branch=master
[travis-url]: https://travis-ci.org/somespider/allbases