A seeded pseudo-random number generator for JavaScript.
It can be used as either a plain script or as a Node.js module.
Numbers are generated using a one-seeded version of the multiply-with-carry method by George Marsaglia. While this method is okay for most applications, it is not cryptographically strong.
Features:
- ✅ Seeded PRNG, giving you deterministic reproducibility of sequences
- ✅ Ability to save and restore the generator state
- ✅ Common operations on arrays like
choice(pick a random element),choices(pick elements at random),sample(pick elements at random without repetition),shuffleand more - ✅ Probability-weighted selections (
weightedChoice) - ✅ Statistical distributions (
exponential,gaussian,poisson) - ✅ Full TypeScript support with type definitions
- ✅ ES Module and CommonJS support
- ✅ Tree-shakeable
- ✅ Comprehensive test coverage
- ✅ Works in browser and Node.js
$ npm install seeded-rand
Just download dist/jsrand.min.js and (optionally) dist/jsrand.min.js.map and include it in your app.
| Plain script | CommonJS | ES Module |
|---|---|---|
<script src="jsrand.min.js"></script>This will define a global |
const Srand = require('seeded-rand'); |
import Srand from 'seeded-rand'; |
TypeScript definitions are included automatically.
All methods can be used either statically:
Srand.seed(10); // 10
Srand.random(); // 0.4569510892033577or instantiating a new generator:
const rnd = new Srand(10);
rnd.random(); // 0.4569510892033577
const othr = new Srand(rnd.seed());
othr.random(); // 0.4569510892033577const rnd = new Srand(); // Initiate with random seed
rnd.seed(); // 1836504610 Read the seed
rnd.randomize(); // 3409024789 Random seed is set and returned
rnd.seed(1836504610); // 1836504610 Set a seed
rnd.inRange(0, 10); // 6.866552880965173
rnd.intInRange(0, 10); // 1
rnd.choice([1, 2, 3]); // 3
rnd.choices([1, 2, 3], 3); // [3, 3, 1] possible repetitions
rnd.choices([1, 2, 3], 3); // [2, 2, 3] possible repetitions
rnd.sample([1, 2, 3], 2); // [1, 2] no repetitions
rnd.sample([1, 2, 3], 2); // [1, 2] no repetitions
const state = rnd.getState();
rnd.intInRange(1, 50); // 39
rnd.intInRange(1, 50); // 24
rnd.intInRange(1, 50); // 18
rnd.setState(state); // Resumes previous state, regenerating same random sequence
rnd.intInRange(1, 50); // 39
rnd.intInRange(1, 50); // 24
rnd.intInRange(1, 50); // 18The same sequence of operations can be repeated with equal results using the static methods of Srand:
Srand.seed(1836504610); // 1836504610 Set the seed
Srand.inRange(0, 10); // 6.866552880965173
Srand.intInRange(0, 10); // 1
Srand.choice([1, 2, 3]); // 3
Srand.choices([1, 2, 3], 3); // [3, 3, 1] possible repetitions
Srand.choices([1, 2, 3], 3); // [2, 2, 3] possible repetitions
Srand.sample([1, 2, 3], 2); // [1, 2] no repetitions
Srand.sample([1, 2, 3], 2); // [1, 2] no repetitions
const state = Srand.getState();
Srand.intInRange(1, 50); // 39
Srand.intInRange(1, 50); // 24
Srand.intInRange(1, 50); // 18
Srand.setState(state); // Resumes previous state, regenerating same random sequence
Srand.intInRange(1, 50); // 39
Srand.intInRange(1, 50); // 24
Srand.intInRange(1, 50); // 18| Method | Doc |
|---|---|
choice(arr: Array<T>): T |
Returns a random element from If |
choices(arr: Array<T>, k: number): Array<T> |
Returns a If For an alternative without replacement, see |
exponential(lambda: number): number |
Returns a random number from an exponential distribution. Useful for modeling time between events in a Poisson process (e.g., time between arrivals, radioactive decay). Parameters:
Example: // Average 5 events per second → lambda=5
// Time until next event in seconds
const timeUntilNext = Srand.exponential(5); |
gaussian(mean?: number, stddev?: number): number |
Returns a random number from a Gaussian (normal) distribution. Uses the Box-Muller transform to generate normally distributed values. Parameters:
Example: // IQ scores: mean=100, stddev=15
const iq = Srand.gaussian(100, 15);Useful for simulations, procedural generation, and statistical modeling. |
getState(): State |
Returns an object with the state of the generator.
Use |
inRange(a: number, b: number): number |
Returns a pseudo-random float number between |
intInRange(min: number, max: number): number |
Returns a psuedo-random integer between |
noConflict(): Srand |
Only available when using Srand as a plain script. In the uncommon case the name Srand = "my value";
// .. jsrand is loaded ...
const mySrand = Srand.noConflict();
Srand; // "my value" |
poisson(lambda: number): number |
Returns a random integer from a Poisson distribution. Useful for modeling the number of events occurring in a fixed interval (e.g., number of calls per hour, bugs per line of code). Parameters:
Example: // Average 3 customers per hour
const customers = Srand.poisson(3);Uses Knuth's algorithm for generating Poisson-distributed values. |
random(): number |
Returns a pseudo-random float number between 0 inclusive and 1 exclusive. The algorithm used is a one-seeded version of the multiply-with-carry method by George Marsaglia. |
randomize(): number |
Sets and returns a random seed. |
sample(arr: Array<T>, k: number): Array<T> |
Returns a If For an alternative with replacement, see |
seed(seed?: number): number |
Sets or gets (if no argument is given) the seed.
The seed can be any float or integer number. |
setState(state: State): void |
Resume a state previously returned by |
shuffle(arr: Array<T>): Array<T> |
Shuffles |
weightedChoice(arr: Array<T>, weights: Array<number>): T |
Returns a random element from Weights should be positive numbers and will be normalized internally, so Example: // 90% common, 10% rare loot drops
const loot = Srand.weightedChoice(
['common', 'rare', 'legendary'],
[90, 9, 1]
);If |
Run benchmarks with:
npm run benchmarkWhile jsrand is optimized for deterministic reproducibility rather than raw speed, the benchmarks (see the benchmarks results and script) show Srand.random() is approximately 20-30% faster than Math.random() (YMMV depending on the machine).
Copyright © 2014-2025, Domenico De Felice.
Provided under the terms of the MIT License.