simplified-random

Python-style random utilities for JavaScript/TypeScript

Stop writing Math.floor(Math.random() * (max - min + 1)) + min everywhere.

The Problem

// JavaScript's Math.random() is painful 😫
const dice = Math.floor(Math.random() * 6) + 1;
const item = array[Math.floor(Math.random() * array.length)];
const shuffled = array.sort(() => Math.random() - 0.5); // wrong algorithm!

The Solution

import { random } from 'simplified-random';

const dice = random.randint(1, 6);
const item = random.choice(array);
random.shuffle(array); // proper Fisher-Yates

Clean, intuitive, correct.

Install

npm install simplified-random

Usage

import { random, secure } from 'simplified-random';

// Random integer (inclusive both ends)
random.randint(1, 100)

// Random choice from array
random.choice(['apple', 'banana', 'cherry'])

// Shuffle in-place
random.shuffle(myArray)

// Sample without replacement
random.sample([1, 2, 3, 4, 5], 3)  // [2, 5, 1]

// Weighted random
random.choices(['a', 'b', 'c'], [0.5, 0.3, 0.2], 10)

// Random float
random.uniform(1.5, 10.5)

// Normal distribution
random.gauss(0, 1)

// Python-style range
random.randrange(10)          // 0-9
random.randrange(1, 10)       // 1-9
random.randrange(0, 100, 10)  // 0, 10, 20, ..., 90

// Cryptographically secure (for tokens, passwords)
secure.randint(100000, 999999)
secure.choice(myArray)
secure.bytes(32)

Why This Package?

✅ Intuitive API - If you know Python's random module, you already know this
✅ Type-safe - Full TypeScript support with generics
✅ Correct algorithms - Proper Fisher-Yates shuffle, unbiased sampling
✅ Crypto-secure option - Built-in secure random for sensitive use cases
✅ Zero dependencies - Lightweight and fast
✅ Dual format - Works with both ESM and CommonJS

When to Use Secure Random

Use secure.* for:

• Authentication tokens
• Session IDs
• Password reset codes
• API keys
• Lottery/gambling

Use random.* for:

• Games
• Simulations
• UI effects
• Non-security randomness

License

MIT