A mathematically correct random number generator library for JavaScript. 

ckknight

random-js

- Provide a binding for `try`-`catch` to help parsing issues [#30](https://github.com/ckknight/random-js/issues/30)

- Exposed `createEntropy` function, which can be used when seeding a Mersenne Twister

- Changed `browserCrypto` to no longer be `null` if outside of a browser context, instead `throw`ing on first use.

- Converted to TypeScript, with type definitions available.

- Using ESNext-style modules (though still available as UMD)

- Changed exports so that they are not available on the `Random` class, but instead in a flat hierarchy.

- add `getUseCount()` to the `mt19937` engine, which returns how many requests or discards have occurred.

- the current time is now used in `Random.generateEntropyArray`

- removed the optionalDependencies in package.json "benchmark" and "microtime".

- `sample()` results are no longer biased toward the final element.

- `discard(count)` on the `mt19937` engine properly works when count is less than 625

- Clarify that the built-in engines return signed 32-bit integers (not unsigned).

- `hex(upper)` now returns a cached function, for efficiency.

- add `int32()`, which returns an integer from `-0x80000000` to `0x7fffffff`.

- add benchmark suite, covers engines, integer, bool, and real.

- add `date(start, end)`, which returns a Date within a uniform distribution.

- `Random` no longer needs to be called with new, allowing `var r = require('random-js')()`

- Add `begin` and `end` arguments to `pick` and `picker`.

- Even if `shuffle` receives an empty array, it should return that same array.

- Fix `sample` and `shuffle` when they are passed an empty array.

- Include `-c` (compress) option when uglifying.

  typeof exports === 'object' && typeof module !== 'undefined' ? factory(exports) :

  typeof define === 'function' && define.amd ? define(['exports'], factory) :

  (global = global || self, factory(global.Random = {}));

}(this, function (exports) { 'use strict';

   * Returns a value within [-0x80000000, 0x7fffffff]

          return function (engine) { return distribution(engine) + addend; };

   * Returns a value within [-0x20000000000000, 0x1fffffffffffff]

      return ((high & 0x1fffff) * 0x100000000 +

          (high & 0x200000 ? -0x20000000000000 : 0));

   * Returns a value within [-0x20000000000000, 0x20000000000000]

              if ((high & 0x7fffff) === 0x400000 && (engine.next() | 0) === 0) {

                  return 0x20000000000000;

              var low = engine.next() >>> 0;

              return ((high & 0x1fffff) * 0x100000000 +

                  (high & 0x200000 ? -0x20000000000000 : 0));

   * Returns a value within [0, 0xffffffff]

   * Returns a value within [0, 0x1fffffffffffff]

      var high = engine.next() & 0x1fffff;

   * Returns a value within [0, 0x20000000000000]

              if ((high & 0x3fffff) === 0x200000 && (engine.next() | 0) === 0) {

              return (high & 0x1fffff) * 0x100000000 + low;

      return ((value + 1) & value) === 0;

      return function (engine) { return engine.next() & masking; };

  function downscaleToLoopCheckedRange(range) {

      var maximum = extendedRange * Math.floor(0x100000000 / extendedRange);

              value = engine.next() >>> 0;

      return stringRepeat("0", zeroCount - text.length) + text;

   * Returns a Universally Unique Identifier Version 4.

   * See http://en.wikipedia.org/wiki/Universally_unique_identifier

      return (zeroPad(a.toString(16), 8) +

          zeroPad((b & 0xffff).toString(16), 4) +

          zeroPad((((b >> 4) & 0x0fff) | 0x4000).toString(16), 4) +

          zeroPad(((c & 0x3fff) | 0x8000).toString(16), 4) +

          zeroPad(((c >> 4) & 0xffff).toString(16), 4) +

   * An int32-producing Engine that uses `Math.random()`

      next: function () { return (Math.random() * 0x100000000) | 0; }

   * A wrapper around an Engine that provides easy-to-use methods for

   * producing values based on known distributions

  var Random = /** @class */ (function () {

       * @param engine The engine to use (defaults to a `Math.random`-based implementation)

          if (engine === void 0) { engine = nativeMath; }

       * Returns a value within [-0x80000000, 0x7fffffff]

      Random.prototype.int32 = function () {

       * Returns a value within [0, 0xffffffff]

      Random.prototype.uint32 = function () {

       * Returns a value within [0, 0x1fffffffffffff]

      Random.prototype.uint53 = function () {

       * Returns a value within [0, 0x20000000000000]

      Random.prototype.uint53Full = function () {

          return uint53Full(this.engine);

       * Returns a value within [-0x20000000000000, 0x1fffffffffffff]

      Random.prototype.int53 = function () {

       * Returns a value within [-0x20000000000000, 0x20000000000000]

      Random.prototype.int53Full = function () {

       * Returns a value within [min, max]

       * @param min The minimum integer value, inclusive. No less than -0x20000000000000.

       * @param max The maximum integer value, inclusive. No greater than 0x20000000000000.

   * An Engine that relies on the globally-available `crypto.getRandomValues`,

   * which is typically available in modern browsers.

   * See https://developer.mozilla.org/en-US/docs/Web/API/Crypto/getRandomValues

   * If unavailable or otherwise non-functioning, then `browserCrypto` will

   * likely `throw` on the first call to `next()`.

                      data = new I32Array(COUNT);

                  crypto.getRandomValues(data);

   * Returns an array of random int32 values, based on current time

   * @param engine an Engine to pull random values from, default `nativeMath`

   * @param length the length of the Array, minimum 1, default 16

  function createEntropy(engine, length) {

      if (engine === void 0) { engine = nativeMath; }

      if (length === void 0) { length = 16; }

      array.push(new Date().getTime() | 0);

   * See https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/imul

  var imul = typeof Math.imul === "function" &&

          // the shift by 0 fixes the sign on the high part

          // the final |0 converts the unsigned value into a signed value

          return (al * bl + (((ah * bl + al * bh) << 16) >>> 0)) | 0;

   * An Engine that is a pseudorandom number generator using the Mersenne

   * Twister algorithm based on the prime 2**19937 − 1

   * See http://en.wikipedia.org/wiki/Mersenne_twister

  var MersenneTwister19937 = /** @class */ (function () {

       * MersenneTwister19937 should not be instantiated directly.

       * Instead, use the static methods `seed`, `seedWithArray`, or `autoSeed`.

          this.index = 0; // integer within [0, 624]

       * Returns a MersenneTwister19937 seeded with an initial int32 value

       * @param initial the initial seed value

      MersenneTwister19937.seed = function (initial) {

          return new MersenneTwister19937().seed(initial);

       * Returns a MersenneTwister19937 seeded with zero or more int32 values

       * @param source A series of int32 values

      MersenneTwister19937.seedWithArray = function (source) {

          return new MersenneTwister19937().seedWithArray(source);

       * Returns a MersenneTwister19937 seeded with the current time and

       * a series of natively-generated random values

      MersenneTwister19937.autoSeed = function () {

  "description": "A mathematically correct random number generator library for JavaScript.",

  "homepage": "https://github.com/ckknight/random-js",

  "bugs": "https://github.com/ckknight/random-js/issues",

  "repository": "git://github.com/ckknight/random-js",

    "rollup-plugin-typescript": "^1.0.0",

    "rollup-plugin-typescript2": "^0.19.2",

    "build:umd": "rollup -c rollup.config.es3.js --format umd -o dist/random-js.js --name Random",

    "build:esm": "rollup -c rollup.config.js --format esm -o dist/random-js.mjs",

    "build": "yarn build:umd && yarn build:esm",

    "minify": "terser --compress --mangle --output dist/random-js.min.js dist/random-js.js",

    "benchmark": "for k in benchmark/*.js; do node $k; done",

    "prepublish": "yarn clean && yarn lint && yarn test && yarn build"

[![Build Status](https://travis-ci.org/ckknight/random-js.svg?branch=master)](https://travis-ci.org/ckknight/random-js)

This is designed to be a mathematically correct random number generator library for JavaScript.

Inspiration was primarily taken from C++11's `<random>`.

Upgrading from 1.0 to 2.0 is a major, breaking change. For the most part, the way exports are defined is different. Instead of everything being available as static properties on a class-like function, random-js 2.0 exports each binding in accordance with current ECMAScript standards.

Despite `Math.random()` being capable of producing numbers within [0, 1), there are a few downsides to doing so:

- It is inconsistent between engines as to how many bits of randomness:

- It is non-deterministic, which means you can't replay results consistently

- In older browsers, there can be manipulation through cross-frame random polling. _This is mostly fixed in newer browsers and is required to be fixed in ECMAScript 6._

Also, and most crucially, most developers tend to use improper and biased logic as to generating integers within a uniform distribution.

## How does Random.js alleviate these problems?

Random.js provides a set of "engines" for producing random integers, which consistently provide values within [0, 4294967295], i.e. 32 bits of randomness.

- `nativeMath`: Utilizes [`Math.random()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/random) and converts its result to a signed integer. This is appropriate to use if you do not care for a deterministic implementation. Based on the implementation (which is hidden to you as a developer), the period may be shorter than expected and start repeating itself.

- `browserCrypto`: Utilizes [`crypto.getRandomValues(Int32Array)`](https://developer.mozilla.org/en-US/docs/Web/API/window.crypto.getRandomValues). Only supported on newer browsers, but promises cryptographically random numbers.

- `nodeCrypto`: Utilizes [`require('crypto').randomBytes(size)`](https://nodejs.org/api/crypto.html#crypto_crypto_randombytes_size_callback). Only supported on node.

- `MersenneTwister19937`: An implementation of the [Mersenne Twister](http://en.wikipedia.org/wiki/Mersenne_twister) algorithm. Not cryptographically secure, but its results are repeatable. Must be seeded with a single integer or an array of integers or call `.autoSeed()` to automatically seed initial data. Guaranteed to produce consistent results across all JavaScript implementations assuming the same seed.

One is also free to implement their own engine as long as it returns 32-bit integers, either signed or unsigned.

Some common, biased, _incorrect_ tool for generating random integers is as follows:

      return Math.floor(Math.random() * (max - min)) + min;

    // DO NOT USE, BIASED LOGIC (typical C-like implementation)

    function randomIntByModulo(min, max) {

      var i = (Math.random() * 32768) >>> 0;

The problem with both of these approaches is that the distribution of integers that it returns is not uniform. That is, it might be more biased to return `0` rather than `1`, making it inherently broken.

`randomInt` may more evenly distribute its biased, but it is still wrong. `randomIntByModulo`, at least in the example given, is heavily biased to return [0, 67] over [68, 99].

In order to eliminate bias, sometimes the engine which random data is pulled from may need to be used more than once.

Random.js provides a series of distributions to alleviate this.

- `browserCrypto`: Utilizes `crypto.getRandomValues()`

- `nodeCrypto`: Utilizes `require('crypto').randomBytes()`

- `MersenneTwister19937`: Produces a new Mersenne Twister. Must be seeded before use.

Any object that fulfills that interface is an `Engine`.

- `const mt = MersenneTwister19937.seed(value)`: Seed the twister with an initial 32-bit integer.

- `const mt = MersenneTwister19937.seedWithArray(array)`: Seed the twister with an array of 32-bit integers.

- `const mt = MersenneTwister19937.autoSeed()`: Seed the twister with automatic information. This uses the current Date and other entropy sources.

- `mt.next()`: Produce a 32-bit signed integer.

- `mt.discard(count)`: Discard `count` random values. More efficient than running `mt.next()` repeatedly.

- `mt.getUseCount()`: Return the number of times the engine has been used plus the number of discarded values.

One can seed a Mersenne Twister with the same value (`MersenneTwister19937.seed(value)`) or values (`MersenneTwister19937.seedWithArray(array)`) and discard the number of uses (`mt.getUseCount()`) to achieve the exact same state.

If you wish to know the initial seed of `MersenneTwister19937.autoSeed()`, it is recommended to use the `createEntropy()` function to create the seed manually (this is what `autoSeed` does under-the-hood).

const mt = MersenneTwister19937.seedWithArray(seed);

useTwisterALot(mt); // you'll have to implement this yourself

const clone = MersenneTwister19937.seedWithArray(seed).discard(

// at this point, `mt` and `clone` will produce equivalent values

Random.js also provides a set of methods for producing useful data from an engine.

- `integer(min, max)(engine)`: Produce an integer within the inclusive range [`min`, `max`]. `min` can be at its minimum -9007199254740992 (-2 ** 53). `max` can be at its maximum 9007199254740992 (2 ** 53).

- `real(min, max, inclusive)(engine)`: Produce a floating point number within the range [`min`, `max`) or [`min`, `max`]. Uses 53 bits of randomness.

- `bool()(engine)`: Produce a boolean with a 50% chance of it being `true`.

- `bool(percentage)(engine)`: Produce a boolean with the specified chance causing it to be `true`.

- `bool(numerator, denominator)(engine)`: Produce a boolean with `numerator`/`denominator` chance of it being true.

- `pick(engine, array[, begin[, end]])`: Return a random value within the provided `array` within the sliced bounds of `begin` and `end`.

- `picker(array[, begin[, end]])(engine)`: Same as `pick(engine, array, begin, end)`.

- `shuffle(engine, array)`: Shuffle the provided `array` (in-place). Similar to `.sort()`.

- `sample(engine, population, sampleSize)`: From the `population` array, produce an array with `sampleSize` elements that are randomly chosen without repeats.

- `die(sideCount)(engine)`: Same as `integer(1, sideCount)(engine)`

- `dice(sideCount, dieCount)(engine)`: Produce an array of length `dieCount` with as many `die` rolls.

- `uuid4(engine)`: Produce a [Universally Unique Identifier](http://en.wikipedia.org/wiki/Universally_unique_identifier) Version 4.

- `string()(engine, length)`: Produce a random string using numbers, uppercase and lowercase letters, `_`, and `-` of length `length`.

- `string(pool)(engine, length)`: Produce a random string using the provided string `pool` as the possible characters to choose from of length `length`.

- `hex()(engine, length)` or `hex(false)(engine, length)`: Produce a random string comprised of numbers or the characters `abcdef` of length `length`.

- `hex(true)(engine, length)`: Produce a random string comprised of numbers or the characters `ABCDEF` of length `length`.

- `date(start, end)(engine)`: Produce a random `Date` within the inclusive range of [`start`, `end`]. `start` and `end` must both be `Date`s.

An example of using `integer` would be as such:

// create a Mersenne Twister-19937 that is auto-seeded based on time and other random values

const engine = MersenneTwister19937.autoSeed();

// create a distribution that will consistently produce integers within inclusive range [0, 99].

// generate a number that is guaranteed to be within [0, 99] without any particular bias.

Producing a distribution should be considered a cheap operation, but producing a new Mersenne Twister can be expensive.

An example of producing a random SHA1 hash:

There is an alternate API which may be easier to use, but may be less performant. In scenarios where performance is paramount, it is recommended to use the aforementioned API.

  MersenneTwister19937.seedWithArray([0x12345678, 0x90abcdef])

const otherRandom = new Random(); // same as new Random(nativeMath)

This abstracts the concepts of engines and distributions.

		@@ -0,1 +1,5 @@
		# 2.0.0-rc3 (2019-03-10)

		- Provide a binding for `try`-`catch` to help parsing issues [#30](https://github.com/ckknight/random-js/issues/30)

		# 2.0.0-rc2 (2019-02-20)
		@@ -2,0 +6,0 @@

		@@ -470,3 +470,3 @@ (function (global, factory) {
		}
		catch (_a) {
		catch (_) {
		// nothing to do here
		@@ -686,3 +686,3 @@ }
		}
		catch (_a) {
		catch (_) {
		// nothing to do here
		@@ -689,0 +689,0 @@ }

		{
		"name": "random-js",
		"description": "A mathematically correct random number generator library for JavaScript.",
		"version": "2.0.0-rc2",
		"version": "2.0.0-rc3",
		"author": {
		@@ -6,0 +6,0 @@ "name": "Cameron Kenneth Knight",

		# Random.js

		[![Build Status](https://travis-ci.org/ckknight/random-js.svg?branch=master)](https://travis-ci.org/ckknight/random-js)

		This is designed to be a mathematically correct random number generator library for JavaScript.
		@@ -7,2 +9,5 @@

		## Upgrading from 1.0
		Upgrading from 1.0 to 2.0 is a major, breaking change. For the most part, the way exports are defined is different. Instead of everything being available as static properties on a class-like function, random-js 2.0 exports each binding in accordance with current ECMAScript standards.

		## Why is this needed?
		@@ -83,2 +88,14 @@

		If you wish to know the initial seed of `MersenneTwister19937.autoSeed()`, it is recommended to use the `createEntropy()` function to create the seed manually (this is what `autoSeed` does under-the-hood).

		```js
		const seed = createEntropy();
		const mt = MersenneTwister19937.seedWithArray(seed);
		useTwisterALot(mt); // you'll have to implement this yourself
		const clone = MersenneTwister19937.seedWithArray(seed).discard(
		mt.getUseCount()
		);
		// at this point, `mt` and `clone` will produce equivalent values
		```

		### Distributions
		@@ -85,0 +102,0 @@

Improved metrics