🎲 @codecaven/random-utils

High-quality random number generation utilities for JavaScript.
Integers, decimals, CSPRNG, distributions (Normal, Poisson), BigInt, and digit-string modes.
100 % client-side — works in any modern browser. No dependencies.

npm install @codecaven/random-utils

Quick Start

import { randomInt, randomDigitString, randomNormal } from '@codecaven/random-utils';

// Roll a die
randomInt(1, 6);               // → 4

// 64-digit crypto-random string (great for tokens)
randomDigitString(64, true);   // → "8372914655…"

// Normally-distributed test score
randomNormal(70, 10);          // → 73.4281…

// Poisson-distributed event count
randomPoisson(4);              // → 3

API Reference

randomInt(min, max, useCrypto?)

Returns a uniformly distributed integer in [min, max] (inclusive).

| Param | Type | Default | Description | |-------|------|---------|-------------| | min | number | — | Lower bound | | max | number | — | Upper bound | | useCrypto | boolean | false | Use crypto.getRandomValues() for secure randomness |

Examples

randomInt(1, 100);            // PRNG, 1–100
randomInt(1, 6, true);        // CSPRNG, 1–6 (cryptographically secure)

randomDigitString(digits, useCrypto?)

Generates a string containing exactly digits digits. The first digit is never zero, so the output length always equals digits.

| Param | Type | Default | Description | |-------|------|---------|-------------| | digits | number | — | Number of digits (≥ 1) | | useCrypto | boolean | false | Use CSPRNG |

Examples

randomDigitString(10);         // → "4839201756"
randomDigitString(64, true);   // → "1928374655647382910…" (64 digits)

randomDecimalString(intDigits, decDigits, useCrypto?)

Generates a decimal string with a specified number of integer digits and decimal places.

| Param | Type | Default | Description | |-------|------|---------|-------------| | intDigits | number | — | Integer part digits (0 → "0") | | decDigits | number | — | Decimal places (0 → integer) | | useCrypto | boolean | false | Use CSPRNG |

Examples

randomDecimalString(3, 0);     // → "483" (integer)
randomDecimalString(2, 4);     // → "37.9281"
randomDecimalString(0, 3);     // → "0.456"

randomBigInt(min, max)

Returns a uniformly distributed BigInt in [min, max]. Always uses crypto.getRandomValues() — BigInt arithmetic has no PRNG fallback.

| Param | Type | Description | |-------|------|-------------| | min | bigint | Lower bound | | max | bigint | Upper bound |

Examples

randomBigInt(0n, 10n ** 100n); // → 489273645… (100+ digit BigInt)

randomNormal(mean, stddev)

Returns a normally-distributed (Gaussian) random number using the Box-Muller transform.

| Param | Type | Description | |-------|------|-------------| | mean | number | Mean (μ) | | stddev | number | Standard deviation (σ) |

Examples

randomNormal(50, 15);          // → 62.4 (clustered around 50)
randomNormal(100, 10);         // → 104.2

randomPoisson(lambda)

Returns a Poisson-distributed random integer using Knuth's algorithm.

| Param | Type | Description | |-------|------|-------------| | lambda | number | Rate parameter (λ) |

Examples

randomPoisson(4);              // → 3
randomPoisson(0.5);            // → 0

digitFrequency(str)

Analyzes how often each digit (0–9) appears in a string. Useful for randomness quality checks.

| Param | Type | Description | |-------|------|-------------| | str | string | Input string |

Returns

[
  { digit: "0", count: 10, pct: 10.0 },
  { digit: "1", count: 12, pct: 12.0 },
  // …
]

Examples

const freq = digitFrequency("1234567890");
// Each digit appears ~10 % of the time

Demo

Open the live demo
Or run locally:

# Navigate to the demo directory
cd packages/random-utils/demo/

# Start a local server using npx
npx serve .

The demo uses Import Maps — no build step required.
Open demo/index.html directly in your browser.

Tests

cd public/random-number-generator
node test/index.test.js

Browser Support

All functions use standard Web APIs (crypto.getRandomValues, Math.random, Uint8Array, BigInt).
Compatible with Chrome, Firefox, Safari, Edge — no polyfills needed.

| Feature | Support | |---------|---------| | randomInt (PRNG) | ✅ All browsers | | randomInt (CSPRNG) | ✅ All modern browsers | | randomDigitString | ✅ All browsers | | randomDecimalString | ✅ All browsers | | randomBigInt | ✅ Chrome 67+, Firefox 68+, Safari 14+ | | randomNormal | ✅ All browsers | | randomPoisson | ✅ All browsers | | digitFrequency | ✅ All browsers |

License

MIT © CodeCaven

GitHub

This package is part of the Caven-Utils monorepo.
Source code: packages/random-utils/