random
    TypeScript icon, indicating that this package has built-in type declarations

    3.0.6 • Public • Published

    random

    Seedable random number generator supporting many common distributions.

    NPM Build Status Prettier Code Formatting

    Welcome to the most random module on npm! 😜

    Highlights

    • Simple API (make easy things easy and hard things possible)
    • TypeScript supported!
    • 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 via ow
    • Integrates with seedrandom
    • Supports node >= 6 and browser

    Install

    npm install --save random
    # or
    yarn add random

    Usage

    const random = require('random')
    // or
    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

    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('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, 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)

    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 twitter

    Install

    npm i random

    DownloadsWeekly Downloads

    32,419

    Version

    3.0.6

    License

    MIT

    Unpacked Size

    268 kB

    Total Files

    181

    Last publish

    Collaborators

    • avatar