5.5.1 • Published 1 month ago

random

Licence

MIT

Version

5.5.1

Deps

Size

101 kB

Vulns

Weekly

Stars

219

Summary Dependency Versions

random

Seedable random number generator supporting many common distributions.

Welcome to the most random module on npm!

Highlights

Simple TS API with zero dependencies
Seedable
Plugin support for different pseudo random number generators
Includes many common distributions
- uniform, normal, poisson, bernoulli, etc
Replacement for seedrandom which is no longer maintained
Supports all modern JS/TS runtimes

Install

npm install random

Usage

import random from 'random'

// 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 distribution
random.uniform((min = 0), (max = 1)) // () => [ min, max )
random.uniformInt((min = 0), (max = 1)) // () => [ min, max ]
random.uniformBoolean() // () => [ false, true ]

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

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

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

// misc distribution
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

// 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']
dist() // ['foo', 1]
dist() // [1, true]

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

const dist = random.shuffler([1, true, 'foo'])
dist() // [true, 'foo', 1]
dist() // ['foo', true, 1]
dist() // [1, 'foo', 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=0 and sigma=1)
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:

// change the underlying pseudo random number generator seed.
// by default, Math.random is used as the underlying PRNG, but it is not seedable,
// so if a seed is given, we use `xoshiro128**`.
random.use('my-seed')

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

// create a third independent random number generator using a custom PRNG
import seedrandom from 'seedrandom'
const rng2 = random.clone(seedrandom('kitty-seed'))

You can also instantiate a fresh instance of Random:

import { Random } from 'random'

const rng = new Random() // (uses Math.random)
const rng2 = new Random('my-seed-string')
const rng3 = new Random(() => {
  /* custom PRNG */ return Math.random()
})

The built-in generators are intended for simulation and general-purpose use, not cryptography. The seeded default may change between major versions. If an exact sequence must remain stable, choose the generator explicitly:

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

const rng = new Random(new Xoshiro128StarStarRNG('my-seed'))

// Reproduce the seeded sequence used by random v5 and seedrandom:
const legacyRng = new Random(new ARC4RNG('my-seed'))

API

Random
- rng
- clone
- use
- next
- float
- int
- integer
- bool
- boolean
- choice
- uniform
- uniformInt
- uniformBoolean
- normal
- logNormal
- bernoulli
- binomial
- geometric
- poisson
- exponential
- irwinHall
- bates
- pareto
- weibull

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:

import random from 'random'

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

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

choice

Returns an item chosen uniformly at random from the given array.

Convence wrapper around random.uniformInt()

Type: function choice <T> (array: Array<T>, weights?: Array<number>): T | undefined

array Array Array of items to sample from
weights Array Optional weights for each item (must be same length as array)

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)