Security News
tea.xyz Spam Plagues npm and RubyGems Package Registries
Tea.xyz, a crypto project aimed at rewarding open source contributions, is once again facing backlash due to an influx of spam packages flooding public package registries.
pure-rand
Advanced tools
Changelog
Readme
Fast Pseudorandom number generators (aka PRNG) with purity in mind!
Install it in node via:
npm install pure-rand
or yarn add pure-rand
Use it in browser by doing:
import * as prand from 'https://unpkg.com/pure-rand/lib/esm/pure-rand.js';
Simple usage
import prand from 'pure-rand';
const seed = 42;
const rng = prand.xoroshiro128plus(seed);
const firstDiceValue = prand.unsafeUniformIntDistribution(1, 6, rng); // value in {1..6}, here: 2
const secondDiceValue = prand.unsafeUniformIntDistribution(1, 6, rng); // value in {1..6}, here: 4
const thirdDiceValue = prand.unsafeUniformIntDistribution(1, 6, rng); // value in {1..6}, here: 6
Pure usage
Pure means that the instance rng
will never be altered in-place. It can be called again and again and it will always return the same value. But it will also return the next rng
. Here is an example showing how the code above can be translated into its pure version:
import prand from 'pure-rand';
const seed = 42;
const rng1 = prand.xoroshiro128plus(seed);
const [firstDiceValue, rng2] = prand.uniformIntDistribution(1, 6, rng1); // value in {1..6}, here: 2
const [secondDiceValue, rng3] = prand.uniformIntDistribution(1, 6, rng2); // value in {1..6}, here: 4
const [thirdDiceValue, rng4] = prand.uniformIntDistribution(1, 6, rng3); // value in {1..6}, here: 6
// You can call: prand.uniformIntDistribution(1, 6, rng1);
// over and over it will always give you back the same value along with a new rng (always producing the same values too).
Independent simulations
In order to produce independent simulations it can be tempting to instanciate several PRNG based on totally different seeds. While it would produce distinct set of values, the best way to ensure fully unrelated sequences is rather to use jumps. Jump just consists into moving far away from the current position in the generator (eg.: jumping in Xoroshiro 128+ will move you 264 generations away from the current one on a generator having a sequence of 2128 elements).
import prand from 'pure-rand';
const seed = 42;
const rngSimulation1 = prand.xoroshiro128plus(seed);
const rngSimulation2 = rngSimulation1.jump(); // not in-place, creates a new instance
const rngSimulation3 = rngSimulation2.jump(); // not in-place, creates a new instance
const diceSim1Value = prand.unsafeUniformIntDistribution(1, 6, rngSimulation1); // value in {1..6}, here: 2
const diceSim2Value = prand.unsafeUniformIntDistribution(1, 6, rngSimulation2); // value in {1..6}, here: 5
const diceSim3Value = prand.unsafeUniformIntDistribution(1, 6, rngSimulation3); // value in {1..6}, here: 6
Non-uniform usage
While not recommended as non-uniform distribution implies that one or several values from the range will be more likely than others, it might be tempting for people wanting to maximize the throughput.
import prand from 'pure-rand';
const seed = 42;
const rng = prand.xoroshiro128plus(seed);
const rand = (min, max) => {
const out = (rng.unsafeNext() >>> 0) / 0x100000000;
return min + Math.floor(out * (max - min + 1));
};
const firstDiceValue = rand(1, 6); // value in {1..6}, here: 6
Select your seed
While not perfect, here is a rather simple way to generate a seed for your PNRG.
const seed = Date.now() ^ (Math.random() * 0x100000000);
In computer science most random number generators(1) are pseudorandom number generators (abbreviated: PRNG). In other words, they are fully deterministic and given the original seed one can rebuild the whole sequence.
Each PRNG algorithm has to deal with tradeoffs in terms of randomness quality, speed, length of the sequence(2)... In other words, it's important to compare relative speed of libraries with that in mind. Indeed, a Mersenne Twister PRNG will not have the same strenghts and weaknesses as a Xoroshiro PRNG, so depending on what you need exactly you might prefer one PRNG over another even if it will be slower.
4 PRNGs come with pure-rand:
congruential32
: Linear Congruential generator — [more]mersenne
: Mersenne Twister generator — [more]xorshift128plus
: Xorshift 128+ generator — [more]xoroshiro128plus
: Xoroshiro 128+ generator — [more]Our recommendation is xoroshiro128plus
. But if you want to use another one, you can replace it by any other PRNG provided by pure-rand in the examples above.
Once you are able to generate random values, next step is to scale them into the range you want. Indeed, you probably don't want a floating point value between 0 (included) and 1 (excluded) but rather an integer value between 1 and 6 if you emulate a dice or any other range based on your needs.
At this point, simple way would be to do min + floor(random() * (max - min + 1))
but actually it will not generate the values with equal probabilities even if you use the best PRNG in the world to back random()
. In order to have equal probabilities you need to rely on uniform distributions(3) which comes built-in in some PNRG libraries.
pure-rand provides 3 built-in functions for uniform distributions of values:
uniformIntDistribution(min, max, rng)
uniformBigIntDistribution(min, max, rng)
- with min
and max
being bigint
uniformArrayIntDistribution(min, max, rng)
- with min
and max
being instances of ArrayInt = {sign, data}
ie. sign either 1 or -1 and data an array of numbers between 0 (included) and 0xffffffff (included)And their unsafe equivalents to change the PRNG in-place.
Some helpers are also provided in order to ease the use of RandomGenerator
instances:
prand.generateN(rng: RandomGenerator, num: number): [number[], RandomGenerator]
: generates num
random values using rng
and return the next RandomGenerator
prand.skipN(rng: RandomGenerator, num: number): RandomGenerator
: skips num
random values and return the next RandomGenerator
The chart has been split into three sections:
Math.random()
In order to compare the performance of the libraries, we aked them to shuffle an array containing 1,000,000 items (see code).
We then split the measurements into two sections:
The recommended setup for pure-rand is to rely on our Xoroshiro128+. It provides a long enough sequence of random values, has built-in support for jump, is really efficient while providing a very good quality of randomness.
Non-Uniform
Library | Algorithm | Mean time (ms) | Compared to pure-rand |
---|---|---|---|
native (node 16.19.1) | Xorshift128+ | 33.3 | 1.4x slower |
pure-rand @6.0.0 | Xoroshiro128+ | 24.5 | reference |
pure-rand @6.0.0 | Xorshift128+ | 25.0 | similar |
pure-rand @6.0.0 | Mersenne Twister | 30.8 | 1.3x slower |
pure-rand @6.0.0 | Congruential | 22.6 | 1.1x faster |
seedrandom @3.0.5 | Alea | 28.1 | 1.1x slower |
seedrandom @3.0.5 | Xorshift128 | 28.8 | 1.2x slower |
seedrandom @3.0.5 | Tyche-i | 28.6 | 1.2x slower |
seedrandom @3.0.5 | Xorwow | 32.0 | 1.3x slower |
seedrandom @3.0.5 | Xor4096 | 32.2 | 1.3x slower |
seedrandom @3.0.5 | Xorshift7 | 33.5 | 1.4x slower |
@faker-js/faker @7.6.0 | Mersenne Twister | 109.1 | 4.5x slower |
chance @1.1.10 | Mersenne Twister | 142.9 | 5.8x slower |
Uniform
Library | Algorithm | Mean time (ms) | Compared to pure-rand |
---|---|---|---|
pure-rand @6.0.0 | Xoroshiro128+ | 53.5 | reference |
pure-rand @6.0.0 | Xorshift128+ | 52.2 | similar |
pure-rand @6.0.0 | Mersenne Twister | 61.6 | 1.2x slower |
pure-rand @6.0.0 | Congruential | 57.6 | 1.1x slower |
random-js @2.1.0 | Mersenne Twister | 119.6 | 2.2x slower |
System details:
- OS: Linux 5.15 Ubuntu 22.04.2 LTS 22.04.2 LTS (Jammy Jellyfish)
- CPU: (2) x64 Intel(R) Xeon(R) Platinum 8272CL CPU @ 2.60GHz
- Memory: 5.88 GB / 6.78 GB
- Container: Yes
- Node: 16.19.1 - /opt/hostedtoolcache/node/16.19.1/x64/bin/node
Executed on default runners provided by GitHub Actions
(1) — Not all as there are also hardware-based random number generator.
(2) — How long it takes to reapeat itself?
(3) — While most users don't really think of it, uniform distribution is key! Without it entries might be biased towards some values and make some others less probable. The naive rand() % numValues
is a good example of biased version as if rand()
is uniform in 0, 1, 2
and numValues
is 2
, the probabilities are: P(0) = 67%
, P(1) = 33%
causing 1
to be less probable than 0
FAQs
Pure random number generator written in TypeScript
The npm package pure-rand receives a total of 9,822,624 weekly downloads. As such, pure-rand popularity was classified as popular.
We found that pure-rand demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Tea.xyz, a crypto project aimed at rewarding open source contributions, is once again facing backlash due to an influx of spam packages flooding public package registries.
Security News
As cyber threats become more autonomous, AI-powered defenses are crucial for businesses to stay ahead of attackers who can exploit software vulnerabilities at scale.
Security News
UnitedHealth Group disclosed that the ransomware attack on Change Healthcare compromised protected health information for millions in the U.S., with estimated costs to the company expected to reach $1 billion.