npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@punkeel/random

v2.1.3

Published

Seedable random number generator supporting many common distributions.

Downloads

4

Readme

random

Seedable random number generator supporting many common distributions.

NPM Build Status JavaScript Style Guide

Welcome to the most random module on npm! 😜

Highlights

  • 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
    • uniform, normal, poisson, bernoulli, etc
  • Validates all user input via ow
  • Integrates with seedrandom
  • Supports node >= 6 and browser

Install

npm install --save random

Usage

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

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

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

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

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

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

Huge 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