0
# Pure Rand
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: pure-rand
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install pure-rand` or `yarn add pure-rand`
10

11
## Core Imports
12

13
ESM imports:
14

15
```typescript
16
import prand from 'pure-rand';
17
import { xoroshiro128plus, uniformIntDistribution, RandomGenerator, Distribution } from 'pure-rand';
18
```
19

20
CommonJS:
21

22
```javascript
23
const prand = require('pure-rand');
24
const { xoroshiro128plus, uniformIntDistribution } = require('pure-rand');
25
```
26

27
Browser (ESM):
28

29
```typescript
30
import * as prand from 'https://unpkg.com/pure-rand/lib/esm/pure-rand.js';
31
```
32

33
## Basic Usage
34

35
### Simple (Unsafe) Usage
36

37
```typescript
38
import prand from 'pure-rand';
39

40
const seed = 42;
41
const rng = prand.xoroshiro128plus(seed);
42
const firstDiceValue = prand.unsafeUniformIntDistribution(1, 6, rng); // value in {1..6}, here: 2
43
const secondDiceValue = prand.unsafeUniformIntDistribution(1, 6, rng); // value in {1..6}, here: 4
44
```
45

46
### Pure (Immutable) Usage
47

48
```typescript
49
import prand from 'pure-rand';
50

51
const seed = 42;
52
const rng1 = prand.xoroshiro128plus(seed);
53
const [firstDiceValue, rng2] = prand.uniformIntDistribution(1, 6, rng1); // value in {1..6}, here: 2
54
const [secondDiceValue, rng3] = prand.uniformIntDistribution(1, 6, rng2); // value in {1..6}, here: 4
55
const [thirdDiceValue, rng4] = prand.uniformIntDistribution(1, 6, rng3); // value in {1..6}, here: 6
56
```
57

58
### Independent Simulations with Jump
59

60
```typescript
61
import prand from 'pure-rand';
62

63
const seed = 42;
64
const rngSimulation1 = prand.xoroshiro128plus(seed);
65
const rngSimulation2 = rngSimulation1.jump(); // Creates independent sequence
66
const rngSimulation3 = rngSimulation2.jump();
67

68
const diceSim1Value = prand.unsafeUniformIntDistribution(1, 6, rngSimulation1); // value in {1..6}, here: 2
69
const diceSim2Value = prand.unsafeUniformIntDistribution(1, 6, rngSimulation2); // value in {1..6}, here: 5
70
const diceSim3Value = prand.unsafeUniformIntDistribution(1, 6, rngSimulation3); // value in {1..6}, here: 6
71
```
72

73
## Architecture
74

75
Pure Rand is built around several key components:
76

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

84
## Core Types
85

86
```typescript { .api }
87
interface RandomGenerator {
88
  /** Produce a fully independent clone of the current instance */
89
  clone(): RandomGenerator;
90
  /** 
91
   * Generate next random value along with the next generator (immutable).
92
   * Values uniform in range -0x8000_0000 (included) to 0x7fff_ffff (included)
93
   */
94
  next(): [number, RandomGenerator];
95
  /** Generate next value BUT alters current generator (mutable) */
96
  unsafeNext(): number;
97
  /** Compute the jumped generator (immutable, optional) */
98
  jump?(): RandomGenerator;
99
  /** Jump current generator (mutable, optional) */
100
  unsafeJump?(): void;
101
  /** Access to the internal state in a read-only fashion (optional) */
102
  getState?(): readonly number[];
103
}
104

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

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

123
## Capabilities
124

125
### Random Number Generators
126

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

129
```typescript { .api }
130
function congruential32(seed: number): RandomGenerator;
131
function mersenne(seed: number): RandomGenerator;
132
function xorshift128plus(seed: number): RandomGenerator;
133
function xoroshiro128plus(seed: number): RandomGenerator;
134
```
135

136
[Generators](./generators.md)
137

138
### Distribution Functions
139

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

142
```typescript { .api }
143
function uniformIntDistribution(from: number, to: number): Distribution<number>;
144
function uniformIntDistribution(from: number, to: number, rng: RandomGenerator): [number, RandomGenerator];
145
function unsafeUniformIntDistribution(from: number, to: number, rng: RandomGenerator): number;
146

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

151
function uniformArrayIntDistribution(from: ArrayInt, to: ArrayInt): Distribution<ArrayInt>;
152
function uniformArrayIntDistribution(from: ArrayInt, to: ArrayInt, rng: RandomGenerator): [ArrayInt, RandomGenerator];
153
function unsafeUniformArrayIntDistribution(from: ArrayInt, to: ArrayInt, rng: RandomGenerator): ArrayInt;
154
```
155

156
[Distributions](./distributions.md)
157

158
### Utility Functions
159

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

162
```typescript { .api }
163
function generateN(rng: RandomGenerator, num: number): [number[], RandomGenerator];
164
function unsafeGenerateN(rng: RandomGenerator, num: number): number[];
165
function skipN(rng: RandomGenerator, num: number): RandomGenerator;
166
function unsafeSkipN(rng: RandomGenerator, num: number): void;
167
```
168

169
[Utilities](./utilities.md)
170

171
## Package Metadata
172

173
```typescript { .api }
174
const __type: string;        // Package type identifier
175
const __version: string;     // Package version
176
const __commitHash: string;  // Git commit hash
177
```
178

179
## Key Features
180

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