Random-extra NPM

random-extra

Seedable random number generator supporting many common distributions.

this module fork from transitive-bullshit/random, with typescript support and some other change (include breaking change)

Welcome to the most random module on npm! 😜

Highlights

Wellcome send PR for more API support or performance up

Simple API (make easy things easy and hard things possible)
Seedable based on entropy or user input
Plugin support for different pseudo random number generators (PRNGs)
Sample from many common distributions
- dfUniform, dfNormal, dfPoisson, dfBernoulli, etc see distributions
Validates all user input via chai
Integrates with seedrandom
Supports node.js >= 7 and browser (if here has no break)

breaking change: v2.x to v3.x

for more easy know what api do by method name
all (distribution function) method rename and add prefix df
(ex: itemByWeight => dfItemByWeight)
when run in loop, or wanna performance, pls use (distribution function) version
remove shortid

Install

npm install random-extra seedrandom

benchmark

random.d.ts

Usage (new)

import random from 'random-extra';
import random = require('random-extra');

`.use` vs `.newUse`

.use will change current random object
.newUse will create new random object

preset

seedrandom

use seedrandom for make seed-able

import seedrandom from 'random-extra/preset/seedrandom';
import { seedrandom } from 'random-extra/preset/seedrandom';

when use seedrandom, srand will able use

seedrandom.rand() // use current seed
seedrandom.srand() // every time call srand will make new seed
seedrandom.rand() // use new seed

other way make seedrandom

import random from 'random-extra';
const seedrandom = random.newUse('seedrandom')

import _seedrandom = require('seedrandom')

random.newUse(_seedrandom('hello.', { entropy: true }))
random.newUse(_seedrandom('hello.', { entropy: false }))

random.newUse(_seedrandom('hello.'))

Usage (original)

const random = require('random-extra')

// 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.dfUniform(min = 0, max = 1) // () => [ min, max )
random.dfUniformInt(min = 0, max = 1) // () => [ min, max ]
random.dfUniformBoolean() // () => [ false, true ]

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

// bernoulli
random.dfBernoulli(p = 0.5)
random.dfBinomial(n = 1, p = 0.5)
random.dfGeometric(p = 0.5)

// poisson
random.dfPoisson(lambda = 1)
random.dfExponential(lambda = 1)

// misc
random.dfIrwinHall(n)
random.dfBates(n)
random.dfPareto(alpha)

For convenience, several common dfUniform 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.dfNormal()
normal() // 0.4855465422678824
normal() // -0.06696771815439678
normal() // 0.7350852689834705

// create a poisson distribution with default params (lambda=1)
const poisson = random.dfPoisson()
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
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

Random

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)

Todo

Distributions
- dfUniform
- dfUniformInt
- dfUniformBoolean
- dfNormal
- dfLogNormal
- chiSquared
- cauchy
- fischerF
- studentT
- dfBernoulli
- dfBinomial
- negativeBinomial
- dfGeometric
- dfPoisson
- dfExponential
- gamma
- hyperExponential
- weibull
- beta
- laplace
- dfIrwinHall
- dfBates
- dfPareto
Generators
- pluggable prng
- port more prng from boost
- custom entropy
Misc
- browser support via rollup
- basic docs
- basic tests
- full test suite
- initial release!