engines

const engines: object

Defined in: src/engine/index.ts:42

Every engine ransu ships, as seedable factories.

Type Declaration

chacha20

chacha20: (seed?) => ChaCha20

ChaCha20 — a cryptographic stream cipher used as a generator.

The only engine that is both seedable and unpredictable: knowing any number of outputs does not reveal the rest. Use it when a stream must be reproducible and resistant to prediction; for secrets with no reproducibility requirement, ransu/secure is simpler.

Parameters

seed?

Seed

Returns

ChaCha20

Example

const source = chacha20(12345);
source.nextUint32(); // 1274611588

// Reproducible, unlike the platform CSPRNG.
chacha20(1).nextUint32() === chacha20(1).nextUint32(); // true

cryptoRandom

cryptoRandom: CryptoEngine

The platform CSPRNG, wrapped as an engine.

crypto.getRandomValues in browsers, workers and edge runtimes; node:crypto on Node. Unpredictable, and for that reason not seedable — which is what backs ransu/secure and the identifier functions.

Example

cryptoRandom.nextUint32(); // unpredictable
cryptoRandom.seedable;     // false

new Random(cryptoRandom).pick(["a", "b", "c"]);

mt19937

mt19937: typeof mt19937

mulberry32

mulberry32: (seed?) => Mulberry32

mulberry32 — 32 bits of state, a dozen lines of arithmetic.

The smallest engine here. Its 2^32 period is short enough to matter in a long run, so prefer it only where the state size is the constraint.

Parameters

seed?

Seed

Returns

Mulberry32

Example

const source = mulberry32(42);
source.nextUint32(); // 2744357186

nativeMath

nativeMath: NativeMathEngine

Math.random, wrapped as an engine.

Not seedable and not reproducible: the host owns the state. This is what the global functions draw from until you call seed().

Example

nativeMath.nextUint32();  // 2166136261
nativeMath.seedable;      // false

pcg32

pcg32: (seed?) => Pcg32

PCG32 — a 64-bit LCG whose output is permuted before it is returned.

Statistically excellent for its size, and it supports multiple independent streams from one seed.

Parameters

seed?

Seed

Returns

Pcg32

Example

const source = pcg32(42);
source.nextUint32(); // 2722782280

sfc32

sfc32: (seed?) => Sfc32

sfc32 — Small Fast Counting, 128 bits of state.

About as fast as anything here and very small. Chosen when speed matters more than a proven period.

Parameters

seed?

Seed

Returns

Sfc32

Example

const source = sfc32(42);
source.nextUint32(); // 261194151

xoshiro128pp

xoshiro128pp: (seed?) => Xoshiro128pp

xoshiro128++ — 128 bits of state, the default engine.

Fast, small, and passes BigCrush. Its period of 2^128-1 is far more than any single program will draw, but it is not cryptographic: a few outputs are enough to recover the state and predict the rest.

Parameters

seed?

Seed

Returns

Xoshiro128pp

Example

const source = xoshiro128pp(42);
source.nextUint32(); // 167929222

new Random(source).integer(1, 6); // 3

xoshiro256pp

xoshiro256pp: (seed?) => Xoshiro256pp

xoshiro256++ — 256 bits of state.

The same family as xoshiro128pp with a longer period, and the one to pick when you need jump() to hand disjoint streams to parallel workers.

Parameters

seed?

Seed

Returns

Xoshiro256pp

Example

const source = xoshiro256pp(42);
source.nextUint32(); // 1573169414

// Non-overlapping streams for parallel work.
const [a, b, c] = source.split(3);

Example

// Pick one for a Random, or for the global stream.
new Random(42, { engine: engines.pcg32 });

// Or build one directly and hand it around.
const source = engines.xoshiro256pp(42);
source.nextUint32(); // 1573169414

engines.mt19937(42);     // for reproducing another language's stream
engines.chacha20(42);    // cryptographic, and still reproducible
engines.cryptoRandom;    // the platform CSPRNG, not seedable
engines.nativeMath;      // Math.random, not seedable