Home

Awesome

Random Namespace and Functions

Historically, JS has offered a very simple API for randomness: a Math.random() function that returns a random value from a uniform distribution in the range [0,1), with no further details. This is a perfectly adequate primitive, but most actual applications end up having to wrap this into other functions to do something useful, such as obtaining random integers in a particular range, or sampling a normal distribution. While it's not hard to write many of these utility functions, doing so correctly can be non-trivial: off-by-one errors are easy to hit even in simple "simulate a die roll" cases.

This proposal aims to introduces a number of convenient functions for dealing with random values, to make common random-related code both easier to use and less suseptable to errors.

Goals:

Details

This proposal suggests that all new Random-related functions be accessible from a global Random namespace.

This does not impact either the Crypto methods or Math.random, which would remain as-are.

The current state of Random

As of today the main way to generate a random number (outside of library inclusion) is by direclty manipulating the output of Math.random().

The common pattern for an integer is Math.floor(Math.random()*(maxValue-MinValue)+maxValue). This is, at best, cumbersome. This proposal would tidy it up to something closer to Random.integerBetween(minValue,maxValue).

(This is akin to how we can use Array.at(-1) rather than Array[Array.length-1] to convey the intent of the code.)

Example methods that may warrant inclusion

This is neither exhaustive, concrete concrete or yet well-researched, but merely serves as an example.

Single randoms

FunctionDescription
random()return a random decimal value in the range [0,1)
integerBetween( x, y )return a random integer between x and y
boolean()randomly returns either true or false

Lists of randoms

FunctionDescription
randomList( size )return a size sized list of decimal values in the range [0,1)
integerBetweenList( size, x, y )return a size sized list of random integers in the range [x,y)
booleanList( size )return a size sized list of random boolean values

array methods

FunctionDescription
pickFromList( array )return a random element from the array
shuffle( array )perform an in-place random shuffle of the array
asShuffled( array )return a copy of the the provided array with the elements randomly shuffled

There might also be a good case to include a method for generating Normal Distributions.

Q&A

Why use a new Random namespace?

Firstly the reason is to avoid polluting the existing Math namespace with a set of collective methods related to randomness.

Secondly...

Why should the methods be symmetric with the Seeded Random proposal?

There are some strong benefits in keeping these methods synchronised with the Seeded PRNG.

For methods or classes which require some element of randomness, test suites could take a fixed-seed PRNG with certain outcomes. And then, for the application itself, passing in Random should yield the same set of methods but with a random seed.

Couldn't you just intantiate a Seeded PRNG with Math.random()?

I expect you could absolutely do that. It would be more verbose and remove some of the ease-of-use of this proposal however.

It would also require a new proposal to add these methods to the Seeded PRNG, as this wouldn't solve some of the original issues.

Interaction With Other Proposals

It is intended that this proposal and the Seeded Random proposal expose the same APIs. Either proposal can advance ahead of the other, however. This proposal is intentionally not touching seeded randomness, instead focusing on functions that are agnostic as to their random source.

Prior Art