pure-rand
Pure random number generator written in TypeScript
Getting started
In node
Install the module with: npm install pure-rand
Unlike classical random number generators, pure-rand
comes with a set of pure and seeded generators (implementing the interface RandomGenerator).
Each time a call to .next()
method is done, the generator provides both the generated value and the next generator.
As a consequence, a given generator will always produce the same value. It can be called as many times as required without impacting its state. This ability makes it easier to replay code section relying on random without having to re-seed a new generator and replay the whole path to be in the same state.
In a web-page
In order to use pure-rand
from a web-page, you have to reference the web-aware script as follow:
<script type="module">
import * as prand from "https://unpkg.com/pure-rand/lib/esm/pure-rand.js";
</script>
You can also reference a precise version by setting the version you want in the url:
<script type="module">
import * as prand from "https://unpkg.com/pure-rand@1.2.0/lib/esm/pure-rand.js";
</script>
Usage
import prand from 'pure-rand'
const seed = 42;
const gen1 = prand.mersenne(seed);
const [n, gen2] = gen1.next();
const [nRange, gen3] = prand.uniformIntDistribution(0, 9)(gen1);
const [nNoDistributionInstance, gen4] = prand.uniformIntDistribution(0, 9, gen3);
const gen4 = prand.xoroshiro128plus(seed);
const offsetGen4 = gen4.jump();
Module import can also be done using one of the following syntaxes:
import * as prand from 'pure-rand';
import { mersenne } from 'pure-rand';
const prand = require('pure-rand');
const { mersenne } = require('pure-rand');
Documentation
Random number generators
All the RandomGenerator provided by pure-rand
derive from the interface RandomGenerator and are pure and seeded as described above.
The following generators are available:
prand.xorshift128plus(seed: number)
: xorshift128+ generator whose values are within the range -0x80000000 to 0x7fffffffprand.xoroshiro128plus(seed: number)
: xoroshiro128+ generator whose values are within the range -0x80000000 to 0x7fffffffprand.mersenne(seed: number)
: Mersenne Twister generator whose values are within the range 0 to 0xffffffffprand.congruential(seed: number)
: Linear Congruential generator whose values are within the range 0 to 0x7fffprand.congruential32(seed: number)
: Linear Congruential generator whose values are within the range 0 to 0xffffffff
Some helpers are also provided in order to ease the use of RandomGenerator
instances:
prand.generateN(rng: RandomGenerator, num: number): [number[], RandomGenerator]
: generates num
random values using rng
and return the next RandomGenerator
prand.skipN(rng: RandomGenerator, num: number): RandomGenerator
: skips num
random values and return the next RandomGenerator
Distributions
All the Distribution take a RandomGenerator
as input and produce a couple (n: number, nextGenerator: RandomGenerator)
. A Distribution
is defined as type Distribution<T> = (rng: RandomGenerator) => [T, RandomGenerator];
.
For the moment, available Distribution
are:
prand.uniformIntDistribution(from: number, to: number): Distribution<number>
prand.uniformBigIntDistribution(from: bigint, to: bigint): Distribution<bigint>
*prand.uniformArrayIntDistribution(from: ArrayInt, to: ArrayInt): Distribution<ArrayInt>
**
*Requires your JavaScript interpreter to support bigint
**ArrayInt is an object having the structure {sign, data}
with sign being either 1 or -1 and data an array of numbers between 0 (included) and 0xffffffff (included)