Statistical random distributions and UUID generation for simulations, testing, and procedural content.

• 👉 See documentation • 👉 See guides & tutorials

What is @hyperfrontend/random-generator-utils?

@hyperfrontend/random-generator-utils provides random number generators beyond JavaScript's basic Math.random(), focusing on statistical distributions used in simulations, load testing, and procedural generation. It includes Gaussian (normal), exponential, power law, and logarithmic distributions, plus UUID v4 generation and a seeded generator that replays every one of them from a single number.

Unlike cryptographic random generators (like Web Crypto API), these utilities prioritize reproducibility and distribution shapes over security. createRandomGenerator(seed) turns one number into a deterministic stream of every distribution for tests and procedural scenes, while the same distributions model real-world phenomena like response times, user behavior, and natural variation.

Key Features

• Statistical distributions: Gaussian, exponential, power law, logarithmic, uniform
• Seeded streams: createRandomGenerator(seed) replays every distribution and UUID from one seed
• Pluggable source: every distribution accepts a () => number source, so any generator can drive it
• UUID v4 generation with validation (uuidV4(), isUuidV4())
• Stateless seeded hash (randomPseudo()) for one-off reproducible values
• Time-based seeding for pseudo-random variations
• No third-party dependencies: at runtime it imports only JavaScript built-ins and @hyperfrontend utilities
• Pure functions for functional composition

Architecture Highlights

Every distribution is a mathematical transform over a unit draw. The draw comes from a source that defaults to Math.random() and can be any () => number; createRandomGenerator supplies a mulberry32 stream, a 32-bit generator with a period of 2^32 draws. Gaussian uses the polar form of the Box-Muller transform, exponential uses inverse transform sampling, and randomPseudo is a stateless sine hash.

Why Use @hyperfrontend/random-generator-utils?

Realistic Load Testing and Simulations

Math.random() generates uniform distributions, but real-world events follow different patterns. User response times cluster around an average (Gaussian), server failures often show exponential decay, and popularity follows power law distributions (80/20 rule). These generators let you model realistic scenarios in load tests and simulations.

Reproducible Pseudo-Random Sequences for Testing

createRandomGenerator(seed) returns a stream whose every method (uniform, gaussian, exponential, powerLaw, logarithmic, uuidV4) replays exactly for the same seed. Log the seed when a property test fails and pass it back in to reproduce the input, or derive it from a record id so every visitor sees the same procedural scene. For a single reproducible value with no stream to carry, randomPseudo(seed) hashes a number straight to a result, and randomPseudoTimeBased() does the same for a date, which gives daily or hourly variations that stay stable within their window.

UUID Generation Without External Dependencies

Many projects pull in the uuid package (500KB+) just for v4 UUIDs. This library provides a lightweight alternative with both generation and validation. Ideal for test fixtures, trace IDs, or non-security-critical unique identifiers without bloating bundles.

Functional Composition for Data Pipelines

All generators are pure functions accepting parameters and returning numbers. This makes them composable in data generation pipelines, Array methods (Array.from({ length: 100 }, () => randomGaussian(0, 100))), or streaming data generators for charts and visualizations.

Installation

npm install @hyperfrontend/random-generator-utils

Quick Start

import {
  createRandomGenerator,
  randomGaussian,
  randomExponential,
  randomPowerLaw,
  randomUniform,
  randomPseudo,
  uuidV4,
  isUuidV4,
} from '@hyperfrontend/random-generator-utils'

// Gaussian (normal) distribution - ideal for modeling natural variation
const responseTime = randomGaussian(100, 300) // ms, centered around 200ms
const userHeight = randomGaussian(160, 180) // cm, most values near 170cm

// Exponential distribution - models time between independent events
const timeBetweenRequests = randomExponential(0.5) // λ=0.5, mean=2 seconds
const failureRate = randomExponential(0.1) // λ=0.1, mean=10 units

// Power law distribution - models "rich get richer" phenomena
const popularity = randomPowerLaw(2, 1, 1000) // Few items very popular
const citySize = randomPowerLaw(1.1, 100, 1000000) // Zipf's law for cities

// Uniform distribution - flat probability across range
const randomDelay = randomUniform(0, 1000) // Any value 0-1000ms equally likely

// Seeded stream - every distribution replays from one number
const stream = createRandomGenerator(2026)
const size = stream.gaussian(24, 96) // Same value on every run that seeds 2026
const gap = stream.exponential(0.5) // ...and the next draw, and the next
const fixtureId = stream.uuidV4() // Stable ids for snapshot fixtures

// Any distribution can draw from the stream directly
const angle = randomUniform(0, 360, stream.next)

// Stateless seeded hash for a one-off reproducible value
const seed = 42
const value1 = randomPseudo(seed) // Always same output for seed=42
const value2 = randomPseudo(seed) // Identical to value1

// UUID generation
const id = uuidV4() // "a3bb189e-8bf9-4558-9e3e-e7b9a9e7b8c1"
console.log(isUuidV4(id)) // true
console.log(isUuidV4('not-a-uuid')) // false

API Overview

Five distributions, one call shape: parameters that describe the shape go in, a single number comes out. randomGaussian(min, max) clusters draws around the midpoint of a bounded range and never leaves it, randomExponential(lambda) decays with a mean of 1 / lambda, and randomPowerLaw(alpha, min, max) piles most of its mass near min while keeping a long tail out to max; randomLogarithmic and randomUniform cover the skewed and the flat cases. Every one of them ends with an optional source: () => number that defaults to Math.random, and that last parameter is the seam the rest of the package plugs into.

createRandomGenerator(seed) fills the seam. It returns a frozen object carrying the seed it was opened with, a next() that draws the stream's unit values, and one method per distribution, so a whole procedural scene or fixture set becomes a function of one number and replays draw for draw on any machine. The methods share a single stream, which means the order of the calls is part of what the seed reproduces. next is a plain function and detaches cleanly, so randomUniform(0, 360, stream.next) puts a free-standing distribution on the same stream.

Two smaller pieces sit outside the stream. randomPseudo(seed) is a stateless hash rather than a generator: one seed maps to one value forever, which is what you want for a single reproducible number and not what you want for a sequence (randomPseudoTimeBased is the same hash over a Date, which is how you get a variation that holds steady for a day or an hour). And uuidV4() generates a version 4 id, drawing from a seeded source when you hand it one, with isUuidV4 to check a string coming back the other way.

Every parameter, bound and return type is in the API reference.

Use Cases

Load Testing

// Model realistic user behavior with varying response times
const users = Array.from({ length: 1000 }, () => ({
  thinkTime: randomExponential(0.5), // Time between actions
  responseTime: randomGaussian(50, 200), // Server response latency
  requestCount: Math.floor(randomPowerLaw(2, 1, 100)), // Request frequency
}))

Test Data Generation

// Generate reproducible test datasets: log stream.seed, replay the run
const stream = createRandomGenerator(Date.now())
const testData = Array.from({ length: 50 }, () => ({
  id: stream.uuidV4(),
  score: stream.gaussian(0, 100),
  timestamp: new Date(Date.now() + stream.uniform(0, 86400000)),
}))

Procedural Content

// Generate varied but natural-looking values
const terrain = {
  height: randomGaussian(0, 100), // Centered around 50
  vegetation: randomUniform(0, 1), // Uniform coverage
  populationDensity: randomPowerLaw(2, 1, 1000), // Power law distribution
}

Compatibility

Output Formats

| Format | File | Tree-Shakeable | | ------ | -------------------------- | :------------: | | ESM | index.esm.js | ✅ | | CJS | index.cjs.js | ❌ | | IIFE | bundle/index.iife.min.js | ❌ | | UMD | bundle/index.umd.min.js | ❌ |

CDN Usage

<!-- unpkg -->
<script src="https://unpkg.com/@hyperfrontend/random-generator-utils"></script>

<!-- jsDelivr -->
<script src="https://cdn.jsdelivr.net/npm/@hyperfrontend/random-generator-utils"></script>

<script>
  const { randomGaussian, randomUniform, uuid4 } = HyperfrontendRandomGenerator
</script>

Global variable: HyperfrontendRandomGenerator

Part of hyperfrontend

This library is part of the hyperfrontend monorepo.

📖 Full documentation

• Used by @hyperfrontend/cryptography for secure random generation

License

MIT