random

Most distribution methods in random return a thunk (a function with no parameters). Calling this thunk returns a series of independent, identically distributed random variables. This pattern is more efficient when generating multiple samples from the same distribution.

Supported Distributions

Uniform Distributions (return thunks):

• random.uniform(min, max): [min, max)
• random.uniformInt(min, max): [min, max]
• random.uniformBoolean(): [false, true]

Normal Distributions (return thunks):

• random.normal(mu, sigma)
• random.logNormal(mu, sigma)

Bernoulli Distributions (return thunks):

• random.bernoulli(p)
• random.binomial(n, p)
• random.geometric(p)

Poisson Distributions (return thunks):

• random.poisson(lambda)
• random.exponential(lambda)

Misc Distributions (return thunks):

• random.irwinHall(n)
• random.bates(n)
• random.pareto(alpha)

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

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

By default, random uses Math.random(), which is not seedable. If a seed is provided, it uses xoshiro128**.

Global Configuration

Use random.use(seed) to change the seed for the global instance.

Creating Independent Instances

• random.clone(seedOrPrng): Creates a new independent generator with a specific seed or a custom PRNG.
• new Random(seedOrPrng): Manually instantiate a Random class instance.

Custom PRNGs and Stability

For cryptographic purposes, do not use these generators. For simulation stability across major versions, explicitly choose your RNG engine:

• Xoshiro128StarStarRNG: A high-quality generator.
• ARC4RNG: Used to reproduce legacy seeded sequences from random v5 and seedrandom.

Note: seedOrPrng can be a string (for seeding) or a function () => number (for a custom PRNG).

import { Random, Xoshiro128StarStarRNG, ARC4RNG } from 'random'

// change the underlying pseudo random number generator seed globally
random.use('my-seed')

// create a new independent random number generator with a different seed
const rng = random.clone('my-new-seed')

// instantiate a fresh instance of Random
const rng2 = new Random('my-seed-string')
const rng3 = new Random(() => Math.random())

// For stable sequences, use explicit engines
const stableRng = new Random(new Xoshiro128StarStarRNG('my-seed'))

// Reproduce legacy sequences (v5/seedrandom)
const legacyRng = new Random(new ARC4RNG('my-seed'))

The random module provides utilities for working with arrays:

• random.choice(array, weights?): Picks a random item from an array. If weights is provided, it performs weighted selection.
• random.sample(array, k): Returns an array of k items sampled from the input array without replacement.
• random.sampler(array, k): Returns a thunk that, when called, returns a sample of k items without replacement.
• random.shuffle(array): Shuffles the input array in place.
• random.shuffler(array): Returns a thunk that, when called, returns a shuffled version of the array.

import random from 'random'

// random array item
random.choice([1, true, 'foo']) // 'foo'

// random array item with weights
random.choice([1, true, 'foo'], [8, 1, 1]) // 1 (80% of the time)

// sample multiple items without replacement
random.sample([1, true, 'foo'], 2) // [true, 'foo']

const dist = random.sampler([1, true, 'foo'], 2)
dist() // [true, 'foo']

// shuffle arrays
random.shuffle([1, true, 'foo']) // ['foo', 1, true]

const distShuffler = random.shuffler([1, true, 'foo'])
distShuffler() // [true, 'foo', 1]

The random library provides factory functions to generate samplers for many common statistical distributions. Calling these functions returns a function that, when executed, produces a sample from that distribution.

Continuous Distributions

• uniform(min, max): Continuous uniform distribution.
• normal(mu, sigma): Normal distribution with mean mu and standard deviation sigma.
• logNormal(mu, sigma): Log-normal distribution.
• exponential(lambda): Exponential distribution with inverse mean lambda.
• irwinHall(n): Irwin Hall distribution (sum of n uniform samples).
• bates(n): Bates distribution (average of n uniform samples).
• pareto(alpha): Pareto distribution with parameter alpha.
• weibull(lambda, k): Weibull distribution with scale lambda and shape k.

Discrete Distributions

• uniformInt(min, max): Discrete uniform distribution.
• uniformBoolean(): Discrete uniform distribution with two outcomes (true/false).
• bernoulli(p): Bernoulli distribution with success probability p.
• binomial(n, p): Binomial distribution with n trials and success probability p.
• geometric(p): Geometric distribution with success probability p.
• poisson(lambda): Poisson distribution with mean lambda.

// Example: Create a normal distribution sampler
const normalSampler = random.normal(0, 1);
const sample = normalSampler();

// Example: Create a Poisson distribution sampler
const poissonSampler = random.poisson(5);
const count = poissonSampler();