@trinkets/random

Seeded, pseudorandom number generator. The main export is random which can be a drop in replacement for Math.random.

Good for simple video games, terrain generation, texture generation, or times when you need to make use of a random number generator that can produce the same results over different runs (via the initial seed).

Note from author: I do not know enough about cryptography to speak about the suitability of this code for that application. Let's say it's not suitable. Please don't use this for encryption. Please find another solution when you need strong, unpredictable hashing.

Installation

npm install @trinkets/random

Usage

import {choice, choices, create, random, randint, sample, seed, state} from '@trinkets/random'
// or import * as random from '@trinkets/random'

// Substitute for Math.random()
console.log(random())
// For when you want integers, here 1 <= result <= 10 (i.e. min <= x <= max)
console.log(randint(1, 2))

// Choose an element from a sequence.
console.log(choice(['cat', 42, 'cow']))
// Choose a random set of elements from a list (can have repeats).
console.log(choices(['cat', 42, 'cow'], 2))
// Choose a random set of weighted elements from a list (can have repeats).
console.log(choices(['cat', 42, 'cow'], 2, [10, 1, 2]))
// Choose a random set of elements from a list, no repeats.
console.log(sample(['cat', 42, 'cow'], 2))

// What is the initial seed used
console.log(seed.get())
// Reset the seed with a non-zero integer.
console.log(seed.set(132131232))

// Get the internal state as an object literal (`JSON.stringify`able).
const restorePoint = state.get()
// Make some random numbers or do other things.
// ...
// Restore the state back to whenever you took it. Any random numbers generated
// will be regenerated from the restorePoint.
state.set(restorePoint)

// When you need to manage the state of a separate random number generator.
const rng2 = create({
    // Optional: pass a function that will be called to generate the default
    // seed. The default uses Date.now().
    seedInitFn = () => Date.now()
})
// Same API.
console.log(rng2.random())
console.log(rng2.randint(1, 10))

Notes

This code originally started with an older version of the multiply-with-carry wikipedia article. The original code was:

m_w = /* choose some initializer, must not be zero */;
m_z = /* choose some initializer, must not be zero */;

uint get_random()
{
    m_z = 36969 * (m_z & 65535) + (m_z >> 16);
    m_w = 18000 * (m_w & 65535) + (m_w >> 16);
    return (m_z << 16) + m_w;  /* 32-bit result */
}

For the times I've needed to reproduce my number generation with a seed, this code has been good enough.

Some not-rigorous-tests on jsperf within my Chrome browser show this code to be about 20% faster than Math.random. Some additional not-rigorous-monte-carlo-tests (millions of runs) show the distribution of Math.random and this to have similar distributions of numbers.