pure-rand

What is pure-rand?

The pure-rand npm package is a library designed for generating random numbers in a pure and functional way. It supports various types of random number generation methods and can be used in scenarios where deterministic results are needed from random inputs by providing seed-based generation.

What are pure-rand's main functionalities?

Generating random integers

This feature allows the generation of random integers within a specified range. The example shows how to generate a random integer between 1 and 100 using a seeded Mersenne Twister algorithm.

import { Random, MersenneTwister19937 } from 'pure-rand';
const randomGenerator = MersenneTwister19937.seed(1234);
const randomInt = Random.integer(1, 100)(randomGenerator);
console.log(randomInt);

Generating random arrays

This feature enables the creation of arrays filled with random integers. The code sample demonstrates generating an array of 10 random integers, each between 1 and 100.

import { Random, MersenneTwister19937 } from 'pure-rand';
const randomGenerator = MersenneTwister19937.seed(5678);
const randomArray = Random.array(Random.integer(1, 100), 10)(randomGenerator);
console.log(randomArray);

Other packages similar to pure-rand

random-js

random-js is a mathematically correct random number generator library for JavaScript. It offers a similar range of features as pure-rand, including seed-based generation, but with additional utilities for generating random values of more complex types and distributions.

seedrandom

seedrandom is another popular random number generation library that provides seeded random number generators. It is simpler and smaller than pure-rand but lacks some of the advanced features like generating random arrays or using different algorithms.

README

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";
   // prand is now available
</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";
   // prand is now available
</script>

Usage

import prand from 'pure-rand'

const seed = 42;

// Instanciates a Mersenne Twister
// random number generator with the seed=42
const gen1 = prand.mersenne(seed);

// Build a random value `n` and the next generator `gen2`
// the random value `n` is within the range:
// gen1.min() (included) to gen1.max() (included)
const [n, gen2] = gen1.next();
// Calling again next on gen1 will provide the very same output:
// `n: number` and `gen2: RandomGenerator`

// In order to generate values within range,
// distributions are provided by the pure-rand

// Like `.next()` method,
// distributions take an incoming generator and extract a couple:
// (n: number, nextGenerator: RandomGenerator)

// The distribution built by the call to prand.uniformIntDistribution(0, 9)
// generates uniformly integers within 0 (included) and 9 (included)
const [nRange, gen3] = prand.uniformIntDistribution(0, 9)(gen1);
// Calling again the same Distribution with the same RandomGenerator
// will provide the same output

// Whenever you want to use the distribution only once you can directly call
// prand.uniformIntDistribution(from, to, rng) which is totally equivalent to prand.uniformIntDistribution(from, to)(rng)
// In terms of performances, the 3 parameters version is faster
const [nNoDistributionInstance, gen4] = prand.uniformIntDistribution(0, 9, gen3);

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 0x7fffffff
• prand.mersenne(seed: number): Mersenne Twister generator whose values are within the range 0 to 0xffffffff
• prand.congruential(seed: number): Linear Congruential generator whose values are within the range 0 to 0x7fff
• prand.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>*

*Requires your JavaScript interpreter to support bigint