npmpackage.info

Gathering detailed insights and metrics for pure-rand

Other packages similar to pure-rand

pure-random-number

3.2.1

A cryptographically secure generator for random numbers in a range.

pure-randombytes

1.0.1

Random bytes without node:buffer

pure-random

0.1.1

A purely functional random number generator

@purescript/random

3.0.0

Random value generation

Gathering detailed insights and metrics for pure-rand

pure-rand - 7.0.1 | npmpackage.info

pure-rand

Pure random number generator written in TypeScript

7.0.1

MIT

TypeScript

83.24 kB

Installations

npm install pure-rand

Developer Guide

BETA

Typescript

Yes

Module System

CommonJS, ESM

Node Version

18.20.6

NPM Version

10.9.2 Pull Requests

Open

8

Total

770

Closed

158

Merged

604

Issues

Open

7

Total

18

Closed

11

Releases

Unable to fetch releases

Languages

TypeScript

JavaScript

TypeScript (88.08%)

JavaScript (11.92%)

Developer

dubzzz

Download Statistics

Total Downloads

Last Day

Last Week

Last Month

Last Year

GitHub Statistics

MIT License

88 Stars

772 Commits

4 Forks

2 Watchers

11 Branches

1 Contributors

Updated on Jun 26, 2025

Sponsor this package

https://github.com/sponsors/dubzzz https://opencollective.com/fast-check

Maintainers

View All 1 Contributors

Package Meta Information

Latest Version

7.0.1

Package Id

pure-rand@7.0.1

Unpacked Size

83.24 kB

Size

18.27 kB

File Count

NPM Version

10.9.2

Node Version

18.20.6

Published on

Feb 07, 2025

Total Downloads

Cumulative downloads

Total Downloads

NaN

Last Day

NaN

Compared to previous day

Last Week

NaN

Compared to previous week

Last Month

NaN

Compared to previous month

Last Year

NaN

Compared to previous year

Weekly Downloads

Monthly Downloads

Yearly Downloads

Dev Dependencies

@types/jest @types/node cross-env fast-check jest prettier replace-in-file source-map-support tinybench ts-jest ts-node typescript

Fast Pseudorandom number generators (aka PRNG) with purity in mind!

Getting started

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';

Usage

Simple usage

1import prand from 'pure-rand';
2
3const seed = 42;
4const rng = prand.xoroshiro128plus(seed);
5const firstDiceValue = prand.unsafeUniformIntDistribution(1, 6, rng); // value in {1..6}, here: 2
6const secondDiceValue = prand.unsafeUniformIntDistribution(1, 6, rng); // value in {1..6}, here: 4
7const 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:

1import prand from 'pure-rand';
2
3const seed = 42;
4const rng1 = prand.xoroshiro128plus(seed);
5const [firstDiceValue, rng2] = prand.uniformIntDistribution(1, 6, rng1); // value in {1..6}, here: 2
6const [secondDiceValue, rng3] = prand.uniformIntDistribution(1, 6, rng2); // value in {1..6}, here: 4
7const [thirdDiceValue, rng4] = prand.uniformIntDistribution(1, 6, rng3); // value in {1..6}, here: 6
8
9// You can call: prand.uniformIntDistribution(1, 6, rng1);
10// 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 2⁶⁴ generations away from the current one on a generator having a sequence of 2¹²⁸ elements).

1import prand from 'pure-rand';
2
3const seed = 42;
4const rngSimulation1 = prand.xoroshiro128plus(seed);
5const rngSimulation2 = rngSimulation1.jump(); // not in-place, creates a new instance
6const rngSimulation3 = rngSimulation2.jump(); // not in-place, creates a new instance
7
8const diceSim1Value = prand.unsafeUniformIntDistribution(1, 6, rngSimulation1); // value in {1..6}, here: 2
9const diceSim2Value = prand.unsafeUniformIntDistribution(1, 6, rngSimulation2); // value in {1..6}, here: 5
10const 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.

1import prand from 'pure-rand';
2
3const seed = 42;
4const rng = prand.xoroshiro128plus(seed);
5const rand = (min, max) => {
6  const out = (rng.unsafeNext() >>> 0) / 0x100000000;
7  return min + Math.floor(out * (max - min + 1));
8};
9const 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.

1const seed = Date.now() ^ (Math.random() * 0x100000000);

Documentation

Pseudorandom number generators

In computer science most random number generators⁽¹⁾ 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⁽²⁾... 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.

Distributions

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⁽³⁾ 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.

Extra helpers

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

Comparison

Summary

The chart has been split into three sections:

section 1: native Math.random()
section 2: without uniform distribution of values
section 3: with uniform distribution of values (not supported by all libraries)

Process

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:

one for non-uniform distributions — known to be slower as it implies re-asking for other values to the PRNG until the produced value fall into the acceptable range of values
one for uniform distributions

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.

Performance

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

Advanced patterns

Generate 32-bit floating point numbers

The following snippet is responsible for generating 32-bit floating point numbers that spread uniformly between 0 (included) and 1 (excluded).

1import prand from 'pure-rand';
2
3function generateFloat32(rng) {
4  const g1 = prand.unsafeUniformIntDistribution(0, (1 << 24) - 1, rng);
5  const value = g1 / (1 << 24);
6  return value;
7}
8
9const seed = 42;
10const rng = prand.xoroshiro128plus(seed);
11
12const float32Bits1 = generateFloat32(rng);
13const float32Bits2 = generateFloat32(rng);

Generate 64-bit floating point numbers

The following snippet is responsible for generating 64-bit floating point numbers that spread uniformly between 0 (included) and 1 (excluded).

1import prand from 'pure-rand';
2
3function generateFloat64(rng) {
4  const g1 = prand.unsafeUniformIntDistribution(0, (1 << 26) - 1, rng);
5  const g2 = prand.unsafeUniformIntDistribution(0, (1 << 27) - 1, rng);
6  const value = (g1 * Math.pow(2, 27) + g2) * Math.pow(2, -53);
7  return value;
8}
9
10const seed = 42;
11const rng = prand.xoroshiro128plus(seed);
12
13const float64Bits1 = generateFloat64(rng);
14const float64Bits2 = generateFloat64(rng);

No vulnerabilities found.

10

Dangerous-Workflow

Determines if the project's GitHub Action workflows avoid dangerous patterns.

10

Binary-Artifacts

Determines if the project has generated executable (binary) artifacts in the source repository.

10

License

Determines if the project has defined a license.

10

Fuzzing

Determines if the project uses fuzzing.

Reason

project is fuzzed

Details

Info: TypeScriptPropertyBasedTesting integration found: test/unit/distribution/UniformArrayIntDistribution.noreg.spec.ts:1
Info: TypeScriptPropertyBasedTesting integration found: test/unit/distribution/UniformArrayIntDistribution.spec.ts:1
Info: TypeScriptPropertyBasedTesting integration found: test/unit/distribution/UniformBigIntDistribution.spec.ts:2
Info: TypeScriptPropertyBasedTesting integration found: test/unit/distribution/UniformIntDistribution.noreg.spec.ts:1
Info: TypeScriptPropertyBasedTesting integration found: test/unit/distribution/UniformIntDistribution.spec.ts:1
Info: TypeScriptPropertyBasedTesting integration found: test/unit/distribution/internals/ArrayInt.spec.ts:1
Info: TypeScriptPropertyBasedTesting integration found: test/unit/distribution/internals/ArrayInt64.spec.ts:1
Info: TypeScriptPropertyBasedTesting integration found: test/unit/distribution/internals/UnsafeUniformArrayIntDistributionInternal.spec.ts:1
Info: TypeScriptPropertyBasedTesting integration found: test/unit/distribution/internals/UnsafeUniformIntDistributionInternal.spec.ts:1
Info: TypeScriptPropertyBasedTesting integration found: test/unit/generator/LinearCongruencial.spec.ts:2
Info: TypeScriptPropertyBasedTesting integration found: test/unit/generator/MersenneTwister.spec.ts:2
Info: TypeScriptPropertyBasedTesting integration found: test/unit/generator/RandomGenerator.properties.ts:2
Info: TypeScriptPropertyBasedTesting integration found: test/unit/generator/XorShift.spec.ts:2
Info: TypeScriptPropertyBasedTesting integration found: test/unit/generator/XoroShiro.spec.ts:2
Info: TypeScriptPropertyBasedTesting integration found: test/unit/distribution/UniformArrayIntDistribution.noreg.spec.ts:1
Info: TypeScriptPropertyBasedTesting integration found: test/unit/distribution/UniformArrayIntDistribution.spec.ts:1
Info: TypeScriptPropertyBasedTesting integration found: test/unit/distribution/UniformBigIntDistribution.spec.ts:2
Info: TypeScriptPropertyBasedTesting integration found: test/unit/distribution/UniformIntDistribution.noreg.spec.ts:1
Info: TypeScriptPropertyBasedTesting integration found: test/unit/distribution/UniformIntDistribution.spec.ts:1
Info: TypeScriptPropertyBasedTesting integration found: test/unit/distribution/internals/ArrayInt.spec.ts:1
Info: TypeScriptPropertyBasedTesting integration found: test/unit/distribution/internals/ArrayInt64.spec.ts:1
Info: TypeScriptPropertyBasedTesting integration found: test/unit/distribution/internals/UnsafeUniformArrayIntDistributionInternal.spec.ts:1
Info: TypeScriptPropertyBasedTesting integration found: test/unit/distribution/internals/UnsafeUniformIntDistributionInternal.spec.ts:1
Info: TypeScriptPropertyBasedTesting integration found: test/unit/generator/LinearCongruencial.spec.ts:2
Info: TypeScriptPropertyBasedTesting integration found: test/unit/generator/MersenneTwister.spec.ts:2
Info: TypeScriptPropertyBasedTesting integration found: test/unit/generator/RandomGenerator.properties.ts:2
Info: TypeScriptPropertyBasedTesting integration found: test/unit/generator/XorShift.spec.ts:2
Info: TypeScriptPropertyBasedTesting integration found: test/unit/generator/XoroShiro.spec.ts:2

10

Packaging

Determines if the project is published as a package that others can easily download, install, easily update, and uninstall.

5

Maintained

Determines if the project is "actively maintained".

0

Code-Review

Determines if the project requires human code review before pull requests (aka merge requests) are merged.

0

Token-Permissions

Determines if the project's workflows follow the principle of least privilege.

0

CII-Best-Practices

Determines if the project has an OpenSSF (formerly CII) Best Practices Badge.

0

Pinned-Dependencies

Determines if the project has declared and pinned the dependencies of its build process.

Reason

dependency not pinned by hash detected -- score normalized to 0

Details

Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/benchmark.yml:26: update your workflow using https://app.stepsecurity.io/secureworkflow/dubzzz/pure-rand/benchmark.yml/main?enable=pin
Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/benchmark.yml:28: update your workflow using https://app.stepsecurity.io/secureworkflow/dubzzz/pure-rand/benchmark.yml/main?enable=pin
Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/build-status.yml:148: update your workflow using https://app.stepsecurity.io/secureworkflow/dubzzz/pure-rand/build-status.yml/main?enable=pin
Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/build-status.yml:155: update your workflow using https://app.stepsecurity.io/secureworkflow/dubzzz/pure-rand/build-status.yml/main?enable=pin
Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/build-status.yml:22: update your workflow using https://app.stepsecurity.io/secureworkflow/dubzzz/pure-rand/build-status.yml/main?enable=pin
Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/build-status.yml:24: update your workflow using https://app.stepsecurity.io/secureworkflow/dubzzz/pure-rand/build-status.yml/main?enable=pin
Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/build-status.yml:40: update your workflow using https://app.stepsecurity.io/secureworkflow/dubzzz/pure-rand/build-status.yml/main?enable=pin
Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/build-status.yml:42: update your workflow using https://app.stepsecurity.io/secureworkflow/dubzzz/pure-rand/build-status.yml/main?enable=pin
Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/build-status.yml:58: update your workflow using https://app.stepsecurity.io/secureworkflow/dubzzz/pure-rand/build-status.yml/main?enable=pin
Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/build-status.yml:60: update your workflow using https://app.stepsecurity.io/secureworkflow/dubzzz/pure-rand/build-status.yml/main?enable=pin
Warn: third-party GitHubAction not pinned by hash: .github/workflows/build-status.yml:71: update your workflow using https://app.stepsecurity.io/secureworkflow/dubzzz/pure-rand/build-status.yml/main?enable=pin
Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/build-status.yml:82: update your workflow using https://app.stepsecurity.io/secureworkflow/dubzzz/pure-rand/build-status.yml/main?enable=pin
Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/build-status.yml:84: update your workflow using https://app.stepsecurity.io/secureworkflow/dubzzz/pure-rand/build-status.yml/main?enable=pin
Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/build-status.yml:95: update your workflow using https://app.stepsecurity.io/secureworkflow/dubzzz/pure-rand/build-status.yml/main?enable=pin
Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/build-status.yml:97: update your workflow using https://app.stepsecurity.io/secureworkflow/dubzzz/pure-rand/build-status.yml/main?enable=pin
Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/build-status.yml:108: update your workflow using https://app.stepsecurity.io/secureworkflow/dubzzz/pure-rand/build-status.yml/main?enable=pin
Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/build-status.yml:119: update your workflow using https://app.stepsecurity.io/secureworkflow/dubzzz/pure-rand/build-status.yml/main?enable=pin
Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/build-status.yml:124: update your workflow using https://app.stepsecurity.io/secureworkflow/dubzzz/pure-rand/build-status.yml/main?enable=pin
Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/compare.yml:8: update your workflow using https://app.stepsecurity.io/secureworkflow/dubzzz/pure-rand/compare.yml/main?enable=pin
Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/compare.yml:10: update your workflow using https://app.stepsecurity.io/secureworkflow/dubzzz/pure-rand/compare.yml/main?enable=pin
Warn: npmCommand not pinned by hash: .github/workflows/build-status.yml:154
Info: 0 out of 19 GitHub-owned GitHubAction dependencies pinned
Info: 0 out of 1 third-party GitHubAction dependencies pinned
Info: 0 out of 1 npmCommand dependencies pinned

0

Security-Policy

Determines if the project has published a security policy.

0

Branch-Protection

Determines if the default and release branches are protected with GitHub's branch protection settings.

0

SAST

Determines if the project uses static code analysis.

0

Vulnerabilities

Determines if the project has open, known unfixed vulnerabilities.

Score

4

/10

Last Scanned on 2025-07-07

The Open Source Security Foundation is a cross-industry collaboration to improve the security of open source software (OSS). The Scorecard provides security health metrics for open source projects.

Learn More