tessl/npm-pure-rand

Pure pseudorandom number generators with immutable state management and uniform distribution functions

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview

Eval results

Files

Random Number Generators

Name: tessl/npm-pure-rand
Author: tessl

Pure Rand provides four high-quality pseudorandom number generators, each with different performance characteristics and statistical properties. All generators implement the RandomGenerator interface and support both pure (immutable) and unsafe (mutable) operations.

Capabilities

Xoroshiro128+

The recommended high-quality, very fast generator with excellent statistical properties. Supports jump functionality for independent subsequences.

/**
 * Create a Xoroshiro128+ pseudorandom number generator
 * @param seed - 32-bit seed value for initialization
 * @returns RandomGenerator instance
 */
function xoroshiro128plus(seed: number): RandomGenerator;

/** 
 * Create a Xoroshiro128+ generator from existing state
 * @param state - Previously exported state array
 * @returns RandomGenerator instance
 */
xoroshiro128plus.fromState(state: readonly number[]): RandomGenerator;

Usage Examples:

import { xoroshiro128plus } from 'pure-rand';

// Create generator with seed
const rng = xoroshiro128plus(42);

// Generate value (pure)
const [value, nextRng] = rng.next();

// Generate value (unsafe)
const value2 = rng.unsafeNext();

// Jump for independent subsequence (2^64 generations ahead)
const independentRng = rng.jump();

// Export and restore state
const state = rng.getState();
const restoredRng = xoroshiro128plus.fromState(state);

XorShift128+

Fast generator with good statistical properties and jump functionality for independent subsequences.

/**
 * Create a XorShift128+ pseudorandom number generator with parameters a=23, b=18, c=5
 * @param seed - 32-bit seed value for initialization
 * @returns RandomGenerator instance
 */
function xorshift128plus(seed: number): RandomGenerator;

/** 
 * Create a XorShift128+ generator from existing state
 * @param state - Previously exported state array
 * @returns RandomGenerator instance
 */
xorshift128plus.fromState(state: readonly number[]): RandomGenerator;

Usage Examples:

import { xorshift128plus } from 'pure-rand';

// Create generator with seed
const rng = xorshift128plus(12345);

// Generate multiple values
const [values, finalRng] = generateN(rng, 5);

// Jump for parallel simulations
const parallelRng = rng.jump();

Mersenne Twister

Well-known, extensively tested generator with a very long period (2^19937-1). Suitable when statistical quality is paramount.

/**
 * Create a Mersenne Twister MT19937 pseudorandom number generator
 * @param seed - 32-bit seed value for initialization
 * @returns RandomGenerator instance
 */
function mersenne(seed: number): RandomGenerator;

/** 
 * Create a Mersenne Twister generator from existing state
 * @param state - Previously exported state array
 * @returns RandomGenerator instance
 */
mersenne.fromState(state: readonly number[]): RandomGenerator;

Usage Examples:

import { mersenne } from 'pure-rand';

// Create generator with seed
const rng = mersenne(98765);

// Clone for separate usage
const clonedRng = rng.clone();

// Access internal state
const state = rng.getState();
const reconstructed = mersenne.fromState(state);

Linear Congruential Generator

Simple, fast generator based on Java's implementation. Suitable for applications where speed is more important than statistical quality.

/**
 * Create a Linear Congruential Generator based on Java's implementation
 * @param seed - 32-bit seed value for initialization
 * @returns RandomGenerator instance
 */
function congruential32(seed: number): RandomGenerator;

/** 
 * Create a Linear Congruential generator from existing state
 * @param state - Previously exported state array
 * @returns RandomGenerator instance
 */
congruential32.fromState(state: readonly number[]): RandomGenerator;

Usage Examples:

import { congruential32 } from 'pure-rand';

// Create generator with seed
const rng = congruential32(1);

// Simple value generation
const value = rng.unsafeNext();

// State management
const state = rng.getState();
const newRng = congruential32.fromState(state);

Generator Selection Guide

Xoroshiro128+: Best overall choice for most applications - high quality, very fast, supports jumps
XorShift128+: Good alternative with jump support, slightly different statistical properties
Mersenne Twister: When maximum statistical quality is required, traditional choice for simulations
Linear Congruential: When maximum speed is needed and statistical quality is less critical

Jump Functionality

Only Xoroshiro128+ and XorShift128+ support jump operations, which move the generator 2^64 positions ahead in the sequence. This enables creation of independent subsequences for parallel simulations.

// Create independent generators for parallel work
const mainRng = xoroshiro128plus(42);
const worker1Rng = mainRng.jump();
const worker2Rng = worker1Rng.jump();
const worker3Rng = worker2Rng.jump();

// Each worker can generate values independently
// without overlap in their sequences

State Management

All generators support state export and reconstruction:

// Export state
const currentState = rng.getState();

// Later, reconstruct exact same generator
const restoredRng = xoroshiro128plus.fromState(currentState);

// Restored generator will produce identical sequences

This enables: