superrandom.js

Seedable random generator supporting many common distributions. Random numbers and string generation.

Usage no npm install needed!

<script type="module">
  import superrandomJs from 'https://cdn.skypack.dev/superrandom.js';
</script>

README

super-random.js

Seedable random generator supporting many common distributions. Random numbers and string generation.

Welcome to the most random module on npm!

Installation

npm install --save super-random.js

Usage

const random = require('super-random.js')

// quick uniform shortcuts
random.float(min = 0, max = 1) // uniform float in [ min, max )
random.int(min = 0, max = 1) // uniform integer in [ min, max ]
random.boolean() // true or false

// uniform
random.uniform(min = 0, max = 1) // () => [ min, max )
random.uniformInt(min = 0, max = 1) // () => [ min, max ]
random.uniformBoolean() // () => [ false, true ]

// normal
random.normal(mu = 0, sigma = 1)
random.logNormal(mu = 0, sigma = 1)

// bernoulli
random.bernoulli(p = 0.5)
random.binomial(n = 1, p = 0.5)
random.geometric(p = 0.5)

// poisson
random.poisson(lambda = 1)
random.exponential(lambda = 1)

// misc
random.irwinHall(n)
random.bates(n)
random.pareto(alpha)

For convenience, several common uniform samplers are exposed directly:

random.float()     // 0.2149383367670885
random.int(0, 100) // 72
random.boolean()   // true

All distribution methods return a thunk (function with no params), which will return a series of independent, identically distributed random variables from the specified distribution.

// create a normal distribution with default params (mu=1 and sigma=0)
const normal = random.normal()
normal() // 0.4855465422678824
normal() // -0.06696771815439678
normal() // 0.7350852689834705

// create a poisson distribution with default params (lambda=1)
const poisson = random.poisson()
poisson() // 0
poisson() // 4
poisson() // 1

Note that returning a thunk here is more efficient when generating multiple samples from the same distribution.

You can change the underlying PRNG or its seed as follows:

const seedrandom = require('seedrandom')

// change the underlying pseudo random number generator
// by default, Math.random is used as the underlying PRNG
random.use(seedrandom('foobar'))

// create a new independent random number generator (uses seedrandom under the hood)
const rng = random.clone('my-new-seed')

// create a second independent random number generator and use a seeded PRNG
const rng2 = random.clone(seedrandom('kittyfoo'))

// replace Math.random with rng.uniform
rng.patch()

// restore original Math.random
rng.unpatch()

API

Table of Contents

Random

Seedable random number generator supporting many common distributions.

Defaults to Math.random as its underlying pseudorandom number generator.

Type: function (rng)

  • rng (RNG | function) Underlying pseudorandom number generator. (optional, default Math.random)

rng

Type: function ()

clone

  • See: RNG.clone

Creates a new Random instance, optionally specifying parameters to set a new seed.

Type: function (args, seed, opts): Random

  • args ...any
  • seed string? Optional seed for new RNG.
  • opts object? Optional config for new RNG options.

use

Sets the underlying pseudorandom number generator used via either an instance of seedrandom, a custom instance of RNG (for PRNG plugins), or a string specifying the PRNG to use along with an optional seed and opts to initialize the RNG.

Type: function (args)

  • args ...any

Example:

const random = require('super-random.js')

random.use('example_seedrandom_string')
// or
random.use(seedrandom('kittens'))
// or
random.use(Math.random)

patch

Patches Math.random with this Random instance's PRNG.

Type: function ()

unpatch

Restores a previously patched Math.random to its original value.

Type: function ()

next

Convenience wrapper around this.rng.next()

Returns a floating point number in [0, 1).

Type: function (): number

float

Samples a uniform random floating point number, optionally specifying lower and upper bounds.

Convence wrapper around random.uniform()

Type: function (min, max): number

  • min number Lower bound (float, inclusive) (optional, default 0)
  • max number Upper bound (float, exclusive) (optional, default 1)

int

Samples a uniform random integer, optionally specifying lower and upper bounds.

Convence wrapper around random.uniformInt()

Type: function (min, max): number

  • min number Lower bound (integer, inclusive) (optional, default 0)
  • max number Upper bound (integer, inclusive) (optional, default 1)

integer

Samples a uniform random integer, optionally specifying lower and upper bounds.

Convence wrapper around random.uniformInt()

Type: function (min, max): number

  • min number Lower bound (integer, inclusive) (optional, default 0)
  • max number Upper bound (integer, inclusive) (optional, default 1)

bool

Samples a uniform random boolean value.

Convence wrapper around random.uniformBoolean()

Type: function (): boolean

boolean

Samples a uniform random boolean value.

Convence wrapper around random.uniformBoolean()

Type: function (): boolean

uniform

Generates a Continuous uniform distribution.

Type: function (min, max): function

  • min number Lower bound (float, inclusive) (optional, default 0)
  • max number Upper bound (float, exclusive) (optional, default 1)

uniformInt

Generates a Discrete uniform distribution.

Type: function (min, max): function

  • min number Lower bound (integer, inclusive) (optional, default 0)
  • max number Upper bound (integer, inclusive) (optional, default 1)

uniformBoolean

Generates a Discrete uniform distribution, with two possible outcomes, true or `false.

This method is analogous to flipping a coin.

Type: function (): function

normal

Generates a Normal distribution.

Type: function (mu, sigma): function

  • mu number Mean (optional, default 0)
  • sigma number Standard deviation (optional, default 1)

logNormal

Generates a Log-normal distribution.

Type: function (mu, sigma): function

  • mu number Mean of underlying normal distribution (optional, default 0)
  • sigma number Standard deviation of underlying normal distribution (optional, default 1)

bernoulli

Generates a Bernoulli distribution.

Type: function (p): function

  • p number Success probability of each trial. (optional, default 0.5)

binomial

Generates a Binomial distribution.

Type: function (n, p): function

  • n number Number of trials. (optional, default 1)
  • p number Success probability of each trial. (optional, default 0.5)

geometric

Generates a Geometric distribution.

Type: function (p): function

  • p number Success probability of each trial. (optional, default 0.5)

poisson

Generates a Poisson distribution.

Type: function (lambda): function

  • lambda number Mean (lambda > 0) (optional, default 1)

exponential

Generates an Exponential distribution.

Type: function (lambda): function

  • lambda number Inverse mean (lambda > 0) (optional, default 1)

irwinHall

Generates an Irwin Hall distribution.

Type: function (n): function

  • n number Number of uniform samples to sum (n >= 0) (optional, default 1)

bates

Generates a Bates distribution.

Type: function (n): function

  • n number Number of uniform samples to average (n >= 1) (optional, default 1)

pareto

Generates a Pareto distribution.

Type: function (alpha): function

  • alpha number Alpha (optional, default 1)