random
Seedable random number generator supporting many common distributions.
Welcome to the most random module on npm! 😜
Highlights
- Simple API (make easy things easy and hard things possible)
- TypeScript support
- Supports node >= 14 and browser
- Seedable based on entropy or user input
- Plugin support for different pseudo random number generators (PRNGs)
- Sample from many common distributions
- uniform, normal, poisson, bernoulli, etc
- Validates all user input
- Integrates with seedrandom
Install
npm install --save random
# or
yarn add random
# or
pnpm add random
Note: this package uses ESM and no longer provides a CommonJS export. See here for more info on how to use ESM modules.
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'
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:
import seedrandom from '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()
You can also instantiate a fresh instance of Random
:
import { Random } from 'random'
import seedrandom from 'seedrandom'
const rng = new Random()
const rng2 = new Random(seedrandom('tinykittens'))
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, defaultMath.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)
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, default0
) -
max
number Upper bound (float, exclusive) (optional, default1
)
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, default0
) -
max
number Upper bound (integer, inclusive) (optional, default1
)
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, default0
) -
max
number Upper bound (integer, inclusive) (optional, default1
)
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 trandom from the given array.
Convence wrapper around random.uniformInt()
Type: function choice <T> (array: Array<T>): T | undefined
-
array
Array Array of items to sample from
uniform
Generates a Continuous uniform distribution.
Type: function (min, max): function
-
min
number Lower bound (float, inclusive) (optional, default0
) -
max
number Upper bound (float, exclusive) (optional, default1
)
uniformInt
Generates a Discrete uniform distribution.
Type: function (min, max): function
-
min
number Lower bound (integer, inclusive) (optional, default0
) -
max
number Upper bound (integer, inclusive) (optional, default1
)
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
logNormal
Generates a Log-normal distribution.
Type: function (mu, sigma): function
-
mu
number Mean of underlying normal distribution (optional, default0
) -
sigma
number Standard deviation of underlying normal distribution (optional, default1
)
bernoulli
Generates a Bernoulli distribution.
Type: function (p): function
-
p
number Success probability of each trial. (optional, default0.5
)
binomial
Generates a Binomial distribution.
Type: function (n, p): function
-
n
number Number of trials. (optional, default1
) -
p
number Success probability of each trial. (optional, default0.5
)
geometric
Generates a Geometric distribution.
Type: function (p): function
-
p
number Success probability of each trial. (optional, default0.5
)
poisson
Generates a Poisson distribution.
Type: function (lambda): function
-
lambda
number Mean (lambda > 0) (optional, default1
)
exponential
Generates an Exponential distribution.
Type: function (lambda): function
-
lambda
number Inverse mean (lambda > 0) (optional, default1
)
irwinHall
Generates an Irwin Hall distribution.
Type: function (n): function
-
n
number Number of uniform samples to sum (n >= 0) (optional, default1
)
bates
Generates a Bates distribution.
Type: function (n): function
-
n
number Number of uniform samples to average (n >= 1) (optional, default1
)
pareto
Generates a Pareto distribution.
Type: function (alpha): function
-
alpha
number Alpha (optional, default1
)
Todo
-
Distributions
- [x] uniform
- [x] uniformInt
- [x] uniformBoolean
- [x] normal
- [x] logNormal
- [ ] chiSquared
- [ ] cauchy
- [ ] fischerF
- [ ] studentT
- [x] bernoulli
- [x] binomial
- [ ] negativeBinomial
- [x] geometric
- [x] poisson
- [x] exponential
- [ ] gamma
- [ ] hyperExponential
- [ ] weibull
- [ ] beta
- [ ] laplace
- [x] irwinHall
- [x] bates
- [x] pareto
-
Generators
- [x] pluggable prng
- [ ] port more prng from boost
- [ ] custom entropy
-
Misc
- [x] browser support via rollup
- [x] basic docs
- [x] basic tests
- [x] test suite
- [x] initial release!
- [x] typescript support
Related
- d3-random - D3's excellent random number generation library.
- seedrandom - Seedable pseudo random number generator.
- random-int - For the common use case of generating uniform random ints.
- random-float - For the common use case of generating uniform random floats.
- randombytes - Random crypto bytes for Node.js and the browser.
Credit
Thanks go to Andrew Moss for the TypeScript port and for helping to maintain this package!
Shoutout to Roger Combs for donating the random
npm package for this project!
Lots of inspiration from d3-random (@mbostock and @svanschooten).
Some distributions and PRNGs are ported from C++ boost::random.
License
MIT © Travis Fischer
Support my OSS work by following me on twitter