well1024a.js

This is a Javascript implementation of the WELL-1024a pseudorandom number generation algorithm.

Javascript's built-in Math.random() function is implementation-dependent and therefore of limited usefulness if your program depends on random numbers, as you risk running into crappy implementations. Even the V8 engine (used by Node.js) only provides 32-bit entropy, and is based on the platform-dependent C++ rand() function.

This module is very bare-bones. I have also written a randomness library called randy that provides useful functions like RandInt(min, max), shuffle(array) etc., based on this module.

Quick Example

var rng = well1024a();
var number = rng.getUInt32();
var coin = ['heads', 'tails'][number % 2];
// coin == 'heads'

For Node.js, use npm:

npm install prng-well1024a

Download and include as a <script>. The module will be available as the global object randy.

Development: well1024a.js - 2Kb Uncompressed

Production: well1024a.min.js - < 1Kb Minified

Example

<script src="well1024a.min.js"></script>

I am <span id="age"></span> years old!

<script>
    var n = document.getElementById("age");
    var myAge = well1024a.getUInt32();
    n.innerText = myAge.toString();
</script>

Documentation

Constructor

• well1024a

Instance Functions

• getUInt32
• getState
• setState

Returns a new well1024a instance, which is an object with 3 functions:

• getUInt32
• getState
• setState

The instance will use Math.random() to fill out the initial seed state.

Arguments

• entropy - default=[]. Array of numbers to add to the initial seed. These should be based on environmental values that are likely to be different on each run such as system time, process ID, browser window height, values from /dev/urandom etc.

Example

var w = well1024a([
    Date.now(),
    os.freemem(),
    process.pid
]);

Returns a random positive integer less than 2^32.

Example

var w = well1024a();

console.log('For Christmas this year, I want ' + w.getUInt32().toString() + ' ponies!');

Returns an array of 32-bit unsigned integers, of length 32. This represents the current state of the random number generator.

This array can be used as a parameter to setState.

Sets the random number generator to a specific state, allowing for replay of random values.

General use case is to give it a value previously received by calling getState().

Arguments

• state - Must be an array of 32-bit unsigned integers, of length 32.

Example

This will flip a pair of coins, reset the generator state, and flip the coins again with the exact same output.

var w = well1024a();
var coins = ['heads', 'tails'];

console.log("Flippin' the coins:");
var state = w.getState();
var d1 = coins[w.getUInt32() % 2];
var d2 = coins[w.getUInt32() % 2];
console.log(d1 + " and " + d2);

console.log("Instant replay:");
w.setState(state);
d1 = coins[w.getUInt32() % 2];
d2 = coins[w.getUInt32() % 2];
console.log(d1 + " and " + d2);

Notes

No functions rely on this, so it's safe to e.g. assign randy.good.randInt to a variable or pass it around as a parameter.