or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

distributions.md generators.md index.md utilities.md

tile.json

tessl/npm-pure-rand

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

Workspace: tessl
Visibility: Public
Created: 3 months ago
Last updated: 3 months ago
Describes: pkg:npm/pure-rand@6.1.x

To install, run

npx @tessl/cli install tessl/npm-pure-rand@6.1.0

Pure Rand

Pure Rand is a TypeScript library that provides fast pseudorandom number generators (PRNGs) with purity in mind. It offers multiple high-quality algorithms with immutable state management, ensuring deterministic and reproducible random number generation while maintaining excellent performance and randomness quality.

Package Information

Package Name: pure-rand
Package Type: npm
Language: TypeScript
Installation: npm install pure-rand or yarn add pure-rand

Core Imports

ESM imports:

import prand from 'pure-rand';
import { xoroshiro128plus, uniformIntDistribution, RandomGenerator, Distribution } from 'pure-rand';

CommonJS:

const prand = require('pure-rand');
const { xoroshiro128plus, uniformIntDistribution } = require('pure-rand');

Browser (ESM):

import * as prand from 'https://unpkg.com/pure-rand/lib/esm/pure-rand.js';

Basic Usage

Simple (Unsafe) 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

Pure (Immutable) Usage

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

Independent Simulations with Jump

import prand from 'pure-rand';

const seed = 42;
const rngSimulation1 = prand.xoroshiro128plus(seed);
const rngSimulation2 = rngSimulation1.jump(); // Creates independent sequence
const rngSimulation3 = rngSimulation2.jump();

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

Architecture

Pure Rand is built around several key components:

Pure Functions: All operations return new instances without modifying the original generator
Unsafe Functions: High-performance in-place operations that mutate the generator state
Multiple PRNG Algorithms: Linear Congruential, Mersenne Twister, XorShift128+, Xoroshiro128+
Uniform Distributions: Ensure equal probability across value ranges for integers, bigints, and arbitrary precision
Jump Functionality: Create independent subsequences for parallel simulations
State Management: Serializable state for reproducibility and persistence

Core Types

interface RandomGenerator {
  /** Produce a fully independent clone of the current instance */
  clone(): RandomGenerator;
  /** 
   * Generate next random value along with the next generator (immutable).
   * Values uniform in range -0x8000_0000 (included) to 0x7fff_ffff (included)
   */
  next(): [number, RandomGenerator];
  /** Generate next value BUT alters current generator (mutable) */
  unsafeNext(): number;
  /** Compute the jumped generator (immutable, optional) */
  jump?(): RandomGenerator;
  /** Jump current generator (mutable, optional) */
  unsafeJump?(): void;
  /** Access to the internal state in a read-only fashion (optional) */
  getState?(): readonly number[];
}

/**
 * Distribution function type that generates random values of type T.
 * Takes a RandomGenerator and returns both the generated value and a new generator.
 */
type Distribution<T> = (rng: RandomGenerator) => [T, RandomGenerator];

/**
 * ArrayInt represents arbitrary precision integers larger than JavaScript's safe integer range.
 * The data array contains numbers in range [0, 0xffffffff] representing the integer in base 2^32.
 */
type ArrayInt = {
  /** Sign of the represented number */
  sign: -1 | 1;
  /** Value components, each must be in range [0, 0xffffffff] */
  data: number[];
};

Capabilities

Random Number Generators

High-quality pseudorandom number generators with different performance and statistical characteristics. All generators support both pure (immutable) and unsafe (mutable) operations.

function congruential32(seed: number): RandomGenerator;
function mersenne(seed: number): RandomGenerator;
function xorshift128plus(seed: number): RandomGenerator;
function xoroshiro128plus(seed: number): RandomGenerator;

Generators

Distribution Functions

Uniform distribution functions that ensure equal probability across value ranges. Available for integers, bigints, and arbitrary precision numbers with both pure and unsafe variants.

function uniformIntDistribution(from: number, to: number): Distribution<number>;
function uniformIntDistribution(from: number, to: number, rng: RandomGenerator): [number, RandomGenerator];
function unsafeUniformIntDistribution(from: number, to: number, rng: RandomGenerator): number;

function uniformBigIntDistribution(from: bigint, to: bigint): Distribution<bigint>;
function uniformBigIntDistribution(from: bigint, to: bigint, rng: RandomGenerator): [bigint, RandomGenerator];
function unsafeUniformBigIntDistribution(from: bigint, to: bigint, rng: RandomGenerator): bigint;

function uniformArrayIntDistribution(from: ArrayInt, to: ArrayInt): Distribution<ArrayInt>;
function uniformArrayIntDistribution(from: ArrayInt, to: ArrayInt, rng: RandomGenerator): [ArrayInt, RandomGenerator];
function unsafeUniformArrayIntDistribution(from: ArrayInt, to: ArrayInt, rng: RandomGenerator): ArrayInt;

Distributions

Utility Functions

Helper functions for generating multiple values, skipping generations, and working with generator sequences.

function generateN(rng: RandomGenerator, num: number): [number[], RandomGenerator];
function unsafeGenerateN(rng: RandomGenerator, num: number): number[];
function skipN(rng: RandomGenerator, num: number): RandomGenerator;
function unsafeSkipN(rng: RandomGenerator, num: number): void;

Utilities

Package Metadata

const __type: string;        // Package type identifier
const __version: string;     // Package version
const __commitHash: string;  // Git commit hash

Key Features

Purity: All generators support both pure (immutable) and unsafe (mutating) operations
Reproducibility: Deterministic sequences with seed-based initialization
Performance: Optimized algorithms with optional unsafe variants for maximum throughput
Jump Functionality: Independent subsequences for parallel simulations (XorShift128+, Xoroshiro128+)
State Management: Serializable internal state for persistence and reconstruction
Multiple Precision: Support for standard integers, bigints, and arbitrary precision numbers