balanced-random

A stateful random generator that maintains a target probability distribution over a sequence of draws, providing a more stable user experience (UX) compared to pure random (less likely to get "unreasonable" streaks).

Problem

Pure random (Math.random()) can produce long streaks that feel "unfair" to users — like getting 10 heads in a row in a 50/50 coin flip, or seeing the same item appear repeatedly in a card draw.

Solution

balanced-random tracks the historical distribution and gently adjusts the probability of each outcome to prevent extreme streaks, while still maintaining the target probability over the long run.

Features

• Built-in Typescript support
• Isomorphic package: works in Node.js and browsers
• Configurable balance factor (0 = pure random, 1 = round-robin)
• Works with any number of choices, with custom weights

Installation

npm install balanced-random

You can also install balanced-random with pnpm, yarn, or slnpm

Usage Examples

Boolean (Coin Flip)

import { createRandomBoolean } from 'balanced-random'

// 50/50 by default
const coin = createRandomBoolean()

// Bias with probability of true (0-1); false gets the remainder
const mostlyTrue = createRandomBoolean({ true_weight: 0.8 })

// Or give both sides explicit weights (any non-negative ratio)
const loaded = createRandomBoolean({ true_weight: 8, false_weight: 2 })

for (let i = 0; i < 100; i++) {
  console.log(coin.next()) // true or false
}

Multiple Outcomes (Loot Box)

import { createRandom } from 'balanced-random'

const loot = createRandom({
  elements: [
    { value: 'common', weight: 80 },
    { value: 'rare', weight: 15 },
    { value: 'epic', weight: 4 },
    { value: 'legendary', weight: 1 },
  ],
})

for (let i = 0; i < 100; i++) {
  console.log(loot.next()) // weighted random with balance
}

Custom Random Generator

import { createRandom } from 'balanced-random'
import seedrandom from 'seedrandom'

const rng = createRandom({
  elements: [
    { value: 'A', weight: 1 },
    { value: 'B', weight: 1 },
  ],
  random_generator: seedrandom('my-seed'),
})

Balance Factor

const balanced = createRandom({
  elements: [
    { value: 'heads', weight: 1 },
    { value: 'tails', weight: 1 },
  ],
  balance_factor: 0.5, // default
  // 0 = pure random (no balance)
  // 1 = aggressive balance (round-robin for under-represented outcomes)
})

API

createRandomBoolean(options?)

Creates a balanced random boolean generator.

Options:

| Option | Type | Default | Description | | ------------------ | -------------- | ------------- | ------------------------------------------------------------------------------------------------ | | true_weight | number | 0.5 | Weight for true. Alone, must be 0-1 (probability); with false_weight, any non-negative ratio | | false_weight | number | 0.5 | Weight for false. If omitted and true_weight is set, defaults to 1 - true_weight | | random_generator | () => number | Math.random | Custom random number generator (returns 0-1) |

createRandom(options)

Creates a balanced random generator for any number of outcomes.

Options:

| Option | Type | Default | Description | | ------------------ | -------------------------------- | ------------- | ------------------------------------------------------------- | | elements | { value: T, weight: number }[] | required | Array of possible outcomes with their target weights | | random_generator | () => number | Math.random | Custom random number generator (returns 0-1) | | balance_factor | number (0-1) | 0.5 | How aggressively to balance. 0 = pure random, 1 = round-robin |

Instance Properties:

| Property | Type | Description | | ------------ | ----------- | ------------------------------------ | | next() | T | Returns the next random value | | draw_count | number | Total number of draws so far | | elements | Element[] | Array of elements with current state |

Element Properties:

| Property | Type | Description | | --------------- | -------- | ------------------------------------------ | | value | T | The outcome value | | target_weight | number | Normalized target probability | | acc_count | number | How many times this element has been drawn | | draw_weight | number | Adjusted probability for next draw |

How It Works

The algorithm tracks "owed draws" — how many times each outcome is under-represented relative to its target probability. Each call to next() runs one cycle:

1. Select an outcome using the current draw_weight values
2. Increment the selected element's acc_count
3. Calculate owe_count = target_count - acc_count for each element (target_count = target_weight × total draws)
4. Blend the target probability with the owed ratio for the next draw:
   • draw_weight = target_weight * (1 - balance_factor) + (owe_count / total_owe) * balance_factor
5. Normalize so draw_weight sums to 1

This creates a distribution that:

• Maintains the target probability over time
• Prevents extreme streaks by favoring under-represented outcomes
• Feels more "fairly random" to users without being deterministic

License

This project is licensed with BSD-2-Clause

This is free, libre, and open-source software. It comes down to four essential freedoms [ref]:

• The freedom to run the program as you wish, for any purpose
• The freedom to study how the program works, and change it so it does your computing as you wish
• The freedom to redistribute copies so you can help others
• The freedom to distribute copies of your modified versions to others