0
# seedrandom
1

2
seedrandom is a comprehensive seeded random number generation library for JavaScript that enables developers to create predictable pseudorandom number sequences using string or numeric seeds. It provides multiple high-quality PRNG algorithms with different performance characteristics and statistical properties, supporting browser environments, Node.js, and AMD module systems.
3

4
## Package Information
5

6
- **Package Name**: seedrandom
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install seedrandom`
10

11
## Core Imports
12

13
```javascript
14
var seedrandom = require('seedrandom');
15
```
16

17
For ES modules:
18

19
```javascript
20
import seedrandom from 'seedrandom';
21
```
22

23
For AMD/Require.js:
24

25
```javascript
26
require(['seedrandom'], function(seedrandom) {
27
  var rng = seedrandom('hello.');
28
  console.log(rng()); // Always 0.9282578795792454
29
});
30
```
31

32
For browser usage:
33

34
```html
35
<script src="//cdnjs.cloudflare.com/ajax/libs/seedrandom/3.0.5/seedrandom.min.js"></script>
36
<!-- Creates Math.seedrandom global -->
37
```
38

39
## Basic Usage
40

41
### Node.js/CommonJS Usage
42

43
```javascript
44
var seedrandom = require('seedrandom');
45

46
// Create a seeded PRNG - always produces the same sequence
47
var rng = seedrandom('hello.');
48
console.log(rng());     // Always 0.9282578795792454
49
console.log(rng());     // Always 0.3752569768646784
50

51
// Get different precisions
52
console.log(rng.quick());  // Faster 32-bit precision: 0.7316977467853576
53
console.log(rng.int32());  // 32-bit signed integer: 1966374204
54

55
// Auto-seeded PRNG for unpredictable results
56
var autoRng = seedrandom();
57
console.log(autoRng());    // Unpredictable
58

59
// Replace Math.random globally (for testing)
60
seedrandom('test-seed', { global: true });
61
console.log(Math.random()); // Now predictable
62
```
63

64
### Browser/Script Tag Usage
65

66
```javascript
67
// Create predictable PRNG (modifies Math.random)
68
Math.seedrandom('hello.');
69
console.log(Math.random());     // Always 0.9282578795792454
70
console.log(Math.random());     // Always 0.3752569768646784
71

72
// Create local PRNG (recommended)
73
var myrng = new Math.seedrandom('hello.');
74
console.log(myrng());           // Always 0.9282578795792454
75
console.log(myrng.quick());     // Always 0.7316977467853576
76
console.log(myrng.int32());     // Always 1966374204
77

78
// Auto-seeded PRNG
79
var prng = new Math.seedrandom();
80
console.log(prng());            // Reasonably unpredictable
81
```
82

83
## Architecture
84

85
seedrandom is built around several key components:
86

87
- **Main Algorithm**: ARC4-based PRNG with ~2^1600 period and automatic entropy collection  
88
- **Alternative Algorithms**: 6 additional fast PRNGs with different statistical properties
89
- **Seeding System**: Supports string, numeric, and automatic entropy-based seeding  
90
- **State Management**: Optional save/restore functionality for PRNG internal state
91
- **Cross-platform**: Identical results across JavaScript environments
92
- **Multiple Loading**: CommonJS, AMD, and UMD module support
93

94
## Capabilities
95

96
### Main PRNG Function
97

98
Core seeded random number generator using ARC4 algorithm with automatic entropy collection and cross-platform compatibility.
99

100
```javascript { .api }
101
/**
102
 * Creates a seeded pseudorandom number generator
103
 * @param {string|number|null|undefined} seed - Seed value for deterministic generation  
104
 * @param {object|boolean} options - Configuration options or legacy entropy flag
105
 * @param {function} [callback] - Legacy callback function (use options.pass instead)
106
 * @returns {function|*} PRNG function or result from options.pass callback
107
 */
108
function seedrandom(seed, options, callback);
109

110
// Options object
111
interface Options {
112
  /** Mix in additional entropy from current state */
113
  entropy?: boolean;
114
  /** Replace Math.random with this PRNG */  
115
  global?: boolean;
116
  /** Enable state save/restore functionality or restore from saved state */
117
  state?: boolean | object;
118
  /** Custom callback for handling prng and seed */
119
  pass?: (prng: function, seed: string, global?: any) => any;
120
}
121

122
// Returned PRNG function interface
123
interface PRNG {
124
  /** Returns random float [0, 1) with 53-bit mantissa precision */
125
  (): number;
126
  /** Returns random float [0, 1) with 32-bit precision (faster) */
127
  quick(): number;
128
  /** Returns random 32-bit signed integer */
129
  int32(): number;
130
  /** Alias for main function (53-bit precision) */
131
  double(): number;
132
  /** Returns internal state object (only available if state option was true) */
133
  state?(): object;
134
}
135
```
136

137
### Alternative PRNG Algorithms
138

139
High-performance alternative pseudorandom number generators with different statistical properties and performance characteristics. Each algorithm provides the same interface as the main function but with different internal implementations.
140

141
```javascript { .api }
142
/**
143
 * Alternative PRNG algorithms - all return PRNG function with same interface
144
 * Note: Alternative PRNGs require explicit seeds (no auto-seeding)
145
 */
146
seedrandom.alea(seed, options);     // Multiply-with-carry, ~2^116 period
147
seedrandom.xor128(seed, options);   // XOR-shift, 2^128-1 period  
148
seedrandom.xorwow(seed, options);   // XOR-shift + Weyl, 2^192-2^32 period
149
seedrandom.xorshift7(seed, options); // 7-shift generator, 2^256-1 period
150
seedrandom.xor4096(seed, options);  // 4096-bit XOR-shift, 2^4128-2^32 period
151
seedrandom.tychei(seed, options);   // ChaCha-derived, ~2^127 period
152
```
153

154
[Alternative PRNGs](./alternative-prngs.md)
155

156
## Common Types
157

158
```javascript { .api }
159
/**
160
 * Seed can be string, number, or null for auto-seeding
161
 */
162
type Seed = string | number | null;
163

164
/**
165
 * Options for configuring PRNG behavior
166
 */  
167
interface Options {
168
  entropy?: boolean;    // Mix additional entropy
169
  global?: boolean;     // Replace Math.random
170
  state?: boolean | object; // Enable/restore state  
171
  pass?: function;      // Custom result handler
172
}
173

174
/**
175
 * All PRNG functions return this interface
176
 */
177
interface PRNG {
178
  (): number;           // Main random function [0, 1)
179
  quick(): number;      // 32-bit precision [0, 1)  
180
  int32(): number;      // 32-bit signed integer
181
  double(): number;     // Alias for main function
182
  state?(): object;     // State management (optional)
183
}
184
```
185

186
## Usage Patterns
187

188
### State Management
189

190
```javascript
191
var seedrandom = require('seedrandom');
192

193
// Enable state functionality
194
var rng = seedrandom('secret-seed', { state: true });
195

196
// Generate some numbers
197
for (var i = 0; i < 100000; i++) rng();
198

199
// Save current state
200
var saved = rng.state();
201

202
// Create replica from saved state
203
var replica = seedrandom('', { state: saved });
204

205
// Both generators now produce identical sequences
206
console.log(replica() === rng()); // true
207
```
208

209
### Entropy Mixing
210

211
```javascript
212
// Mix additional entropy with seed
213
var rng = seedrandom('base-seed', { entropy: true });
214

215
// Auto-seed with maximum entropy  
216
var autoRng = seedrandom(null, { entropy: true });
217
```
218

219
### Custom Result Handling
220

221
```javascript
222
// Get both PRNG and processed seed
223
var obj = seedrandom('my-seed', { 
224
  pass: function(prng, seed) {
225
    return { random: prng, seed: seed };
226
  }
227
});
228

229
console.log(obj.random()); // Use the PRNG
230
console.log(obj.seed);     // Access the processed seed
231
```
232

233
## Error Handling and Important Notes
234

235
### Security Warning
236

237
```javascript
238
// DANGEROUS: Never use this pattern in production libraries
239
Math.seedrandom('predictable-seed');
240
// This makes Math.random() globally predictable!
241

242
// SAFE: Always use local PRNGs in libraries
243
var localRng = seedrandom('seed');
244
var result = localRng(); // Safe, doesn't affect global state
245
```
246

247
### Seed Requirements for Alternative PRNGs
248

249
```javascript
250
// Alternative PRNGs require explicit seeds
251
try {
252
  var rng = seedrandom.alea(); // Will throw or produce poor randomness
253
} catch (e) {
254
  console.log('Alternative PRNGs require explicit seeds');
255
}
256

257
// Correct usage
258
var rng = seedrandom.alea('proper-seed');
259
```
260

261
### Entropy Collection Details
262

263
```javascript
264
// Auto-seeding uses multiple entropy sources:
265
// - window.crypto (browser) or crypto.randomBytes (Node.js)
266
// - Current time
267
// - DOM state (browser only)
268
// - Previous seeds (accumulated entropy pool)
269

270
var autoRng = seedrandom(); // Uses all available entropy
271
var mixedRng = seedrandom('base-seed', { entropy: true }); // Mixes seed with entropy
272
```