@chaisser/random-seed

Seeded random number generator

Deterministic, reproducible random number generation using a seed. Generate numbers, booleans, dates, strings, UUIDs, colors, coordinates, and more — all reproducible from a seed value.

---

Installation

npm install @chaisser/random-seed
# or
yarn add @chaisser/random-seed
# or
pnpm add @chaisser/random-seed

---

Quick Start

import { createRNG } from '@chaisser/random-seed';

const rng = createRNG(42);

rng.nextInt(1, 100);        // deterministic integer
rng.nextFloat(0, 10);       // deterministic float
rng.nextBool(0.3);          // deterministic boolean
rng.uuid();                 // deterministic UUID
rng.shuffle([1, 2, 3, 4]); // deterministic shuffle
rng.pick(['a', 'b', 'c']); // deterministic pick

// Same seed always produces same sequence
const a = createRNG(42);
const b = createRNG(42);
a.nextInt(1, 100) === b.nextInt(1, 100); // true

---

API Reference

createRNG(seed?)

Creates a seeded random number generator. Accepts number or string seeds. Returns a SeededRNG object.

RNG Methods

Method	Description
next()	Float in [0, 1)
nextInt(min, max)	Integer in [min, max]
nextFloat(min?, max?)	Float in [min, max] (default 0, 1)
nextBool(probability?)	Boolean (default p=0.5)
nextDate(start, end)	Random Date in range
pick(array)	Random element
pickMultiple(array, count)	Multiple random elements (with replacement)
shuffle(array)	Shuffled copy (Fisher-Yates)
weighted(items)	Weighted random pick
uuid()	UUID v4 string
hex(bytes?)	Hex string (default 8 bytes = 16 chars)
alpha(length)	Alphabetic string
alphanumeric(length)	Alphanumeric string
reset()	Reset to initial seed state
getSeed()	Return the seed value

One-shot Helpers

Each method has a seeded* helper that creates a temporary RNG, calls once, and returns:

Function	Description
seededRandom(seed?)	Single float [0, 1)
seededInt(min, max, seed?)	Single int
seededFloat(min, max, seed?)	Single float
seededBool(probability, seed?)	Single bool
seededPick(array, seed?)	Single pick
seededPickMultiple(array, count, seed?)	Multiple picks
seededShuffle(array, seed?)	Shuffled copy
seededWeighted(items, seed?)	Weighted pick
seededUuid(seed?)	UUID
seededHex(bytes, seed?)	Hex string
seededAlpha(length, seed?)	Alpha string
seededAlphanumeric(length, seed?)	Alphanumeric string
seededDate(start, end, seed?)	Random date

Distributions

Function	Description
gaussian(mean?, stdDev?, rng?)	Box-Muller normal distribution
gaussianArray(count, mean?, stdDev?, rng?)	Array of gaussian values
exponential(lambda?, rng?)	Exponential distribution

Array Generators

Function	Description
intArray(min, max, count, rng?)	Array of random ints
floatArray(min, max, count, rng?)	Array of random floats
boolArray(count, probability?, rng?)	Array of random bools
uniqueInts(min, max, count, rng?)	Array of unique random ints

Color

Function	Description
randomColor(rng?)	Hex color string (#rrggbb)
randomRgb(rng?)	{ r, g, b } (0-255)
randomHsl(rng?)	{ h, s, l } (h: 0-360, s/l: 0-100)

Coordinates & Network

Function	Description
randomCoordinate(latRange, lngRange, rng?)	{ lat, lng }
randomIP(rng?)	IPv4 string

Dice

Function	Description
randomDice(sides?, rng?)	Roll one die (default 6 sides)
randomCoin(rng?)	'heads' or 'tails'
rollDice(count, sides, rng?)	Roll N dice
rollDiceSum(count, sides, rng?)	Sum of N dice

---

Examples

Reproducible Test Data

import { createRNG } from '@chaisser/random-seed';

function generateTestUsers(count: number, seed = 42) {
  const rng = createRNG(seed);
  return Array.from({ length: count }, (_, i) => ({
    id: i + 1,
    name: rng.alpha(8),
    score: rng.nextInt(0, 100),
    active: rng.nextBool(0.7)
  }));
}

// Same data every time
const users = generateTestUsers(100);

Shuffle a Playlist

import { createRNG } from '@chaisser/random-seed';

function shufflePlaylist(tracks: string[], seed: number) {
  return createRNG(seed).shuffle(tracks);
}

// Same seed = same order
const shuffled = shufflePlaylist(['song1', 'song2', 'song3', 'song4'], 42);

Weighted Random Selection

import { createRNG } from '@chaisser/random-seed';

const rng = createRNG(42);

const loot = rng.weighted([
  { value: 'common', weight: 60 },
  { value: 'uncommon', weight: 25 },
  { value: 'rare', weight: 10 },
  { value: 'legendary', weight: 5 }
]);

Generate Test IDs

import { createRNG } from '@chaisser/random-seed';

const rng = createRNG(42);

const id1 = rng.uuid();       // 'a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d'
const id2 = rng.hex(16);      // 32-char hex string
const code = rng.alphanumeric(8); // 8-char alphanumeric

Statistical Distributions

import { createRNG, gaussian, intArray } from '@chaisser/random-seed';

const rng = createRNG(42);

// Normal distribution (mean=100, stdDev=15)
const iq = gaussian(100, 15, rng);

// 1000 IQ scores
const scores = gaussianArray(1000, 100, 15, rng);

// 10 unique lottery numbers
const lottery = intArray(1, 49, 6, rng);

---

License

MIT