@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