jsrand a.k.a. seeded-rand

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), shuffle and 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

See changelog

Table of contents

• Install
  • NPM
  • Plain script
• Usage
  • Examples
• API
  • choice
  • choices
  • exponential
  • gaussian
  • getState
  • inRange
  • intInRange
  • noConflict
  • poisson
  • random
  • randomize
  • sample
  • seed
  • setState
  • shuffle
  • weightedChoice
• Performance
• License

Install

NPM

$ npm install seeded-rand

Plain script

Just download dist/jsrand.min.js and (optionally) dist/jsrand.min.js.map and include it in your app.

Usage

<script src="jsrand.min.js"></script>

This will define a global Srand object. If the name Srand is already taken, see noConflict.

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.4569510892033577

or instantiating a new generator:

const rnd = new Srand(10);
rnd.random(); // 0.4569510892033577

const othr = new Srand(rnd.seed());
othr.random(); // 0.4569510892033577

Examples

const 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); // 18

The 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

API

choice(arr: Array<T>): T

Returns a random element from arr.

If arr is empty, an exception is thrown.

choices(arr: Array<T>, k: number): Array<T>

Returns a k-sized array sampled with replacement from arr, i.e. each element can be sampled more than once.

If k > 0 and arr is empty, throws an exception.

For an alternative without replacement, see sample.

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:

• lambda - The rate parameter (lambda > 0). Higher values produce smaller numbers.

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:

• mean - The mean (center) of the distribution (default: 0)
• stddev - The standard deviation (spread) of the distribution (default: 1)

Example:

// IQ scores: mean=100, stddev=15
const iq = Srand.gaussian(100, 15);

Useful for simulations, procedural generation, and statistical modeling.

getState(): State

Use setState to resume the state.

inRange(a: number, b: number): number

Returns a pseudo-random float number between a inclusive and b exclusive.

intInRange(min: number, max: number): number

Returns a psuedo-random integer between min and max inclusive.

noConflict(): Srand

Only available when using Srand as a plain script.

In the uncommon case the name Srand is already taken, restores its initial value and return the Srand object.

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:

• lambda - The expected number of events (lambda > 0)

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

sample(arr: Array<T>, k: number): Array<T>

Returns a k-sized array sampled without replacement from arr.

If k > arr.length, an exception is thrown.

For an alternative with replacement, see choices.

seed(seed?: number): number

The seed can be any float or integer number.

setState(state: State): void

Resume a state previously returned by getState.

shuffle(arr: Array<T>): Array<T>

Shuffles arr in-place using the Fisher-Yates algorithm and returns it (arr is modified).

weightedChoice(arr: Array<T>, weights: Array<number>): T

Returns a random element from arr based on the provided weights.

Weights should be positive numbers and will be normalized internally, so [1, 2, 3] is equivalent to [0.166, 0.333, 0.5].

Example:

// 90% common, 10% rare loot drops
const loot = Srand.weightedChoice(
  ['common', 'rare', 'legendary'],
  [90, 9, 1]
);

If arr is empty, weights length doesn't match arr length, or all weights are zero/negative, an exception is thrown.

Performance

Run benchmarks with:

npm run benchmark

While 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).

License

Copyright © 2014-2025, Domenico De Felice.

Provided under the terms of the MIT License.