esm-seedrandom

Explicitly seeded random number generator for JavaScript, ported to ES Modules.

Unit tested for number generator compatability with original [seedrandom][] CommonJS NPM package.

* Version: 3.0.5
* Author: David Bau
* Date: 2019-09-14
* ES Modules port in 2020-12 by Shane Holloway

[seedrandom]: https://github.com/davidbau/seedrandom

Demo

Live demo

Use

Fast PRNG Algorithms

|PRNG name | Period | Author | BigCrush test results |
|------------------|-------------|----------------------|-----------------------|
|[prng_alea][] | ~2^116 | Baagøe | pass all
|[prng_xor128][] | 2^128-1 | Marsaglia | fail MatrixRank and LinearComp
|[prng_tychei][] | ~2^127 | Neves/Araujo (ChaCha)| pass all
|[prng_xorwow][] | 2^192-2^32 | Marsaglia | fail CollisionOver, SimpPoker, and LinearComp
|[prng_xor4096][] | 2^4096-2^32 | Brent (xorgens) | pass all
|[prng_xorshift7][]| 2^256-1 | Panneton/L'ecuyer | pass all
|[prng_arc4][] | ~2^1600 | Bau (ARC4) | unknown

[prng_alea]: ./docs/alea.md
[prng_xor128]: ./docs/xor128.md
[prng_tychei]: ./docs/tychei.md
[prng_xorwow]: ./docs/xorwow.md
[prng_xor4096]: ./docs/xor4096.md
[prng_xorshift7]: ./docs/xorshift7.md
[prng_arc4]: ./docs/arc4.md

To use Johannes Baagøe's extremely fast Alea PRNG:

``javascript
// Use alea for Johannes Baagøe's clever and fast floating-point RNG.
import {prng_alea} from 'esm-seedrandom';
let myrng = prng_alea('hello.');

// By default provides 32 bits of randomness in a float.
console.log(myrng()); // Always 0.4783254903741181 for this seed and sequence
console.log(myrng.quick()); // Always 0.8297006865032017 for this seed and sequence

// Use "double" to get 56 bits of randomness.
console.log(myrng.double()); // Always 0.4692433053279662 for this seed and sequence

// Use "int32" to get a 32 bit (signed) integer.
console.log(myrng.int32()); // Always 1350551666 for this seed and sequence
`

or direclty from HTML,

`html

`

Docs

See the API docs.

$3

From NodeJS,

`sh
npm install esm-seedrandom
`

or in HTML,

`html

`

#### Saving & Restoring PRNG state

`javascript
import {prng_alea} from 'esm-seedrandom';

let rng_first = prng_alea("secret-seed", {state: true});
let saved_state = rng_first.state()
for (let j = 0; j < 1e5; ++j)
rng_first();

// later

let rng_replica = prng_alea("", {state: saved_state});
for (let j = 0; j < 1e5; ++j)
rng_replica();

`

In normal use the prng is opaque and its internal state cannot be accessed.
However, if the state` option is provided, the prng gets a state() method
that returns a plain object the can be used to reconstruct a prng later in
the same state (by passing that saved object back as the state option).

Unit tests

Mocha-based live unittests
for reproducability and validation of state capture and restore.

In NodeJS [unittests][gh-actions-unittests], validation of state snapshot compatability with the original [seedrandom][] CommonJS implementation is performed.

[gh-actions-unittests]: https://github.com/shanewholloway/js-esm-seedrandom/actions?query=workflow%3A%22Node.js+CI%22

License (MIT)

MIT