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:
Array.toSorted, Aray.at, Object.fromEntries)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.
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.)
This is neither exhaustive, concrete concrete or yet well-researched, but merely serves as an example.
|Function | Description| |——————-|————| 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 |
|Function | Description|
|—————————-|————|
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 |
|Function | Description| |———————|————| 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.
Random namespace?Firstly the reason is to avoid polluting the existing Math namespace with a set of collective methods related to randomness.
Secondly…
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.
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.
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.
random module
Random class
RandomGen interface
(seeded-random use-case)
Random class
(random n) function
Random class
genTest library