@justkd/roll

Class representing a pseudorandom number manager. Includes Mersenne Twister uniform distribution, Box Mueller gaussian distribution, n-sided die rolling, history of variable max size, elementary statistics, and scale/clip/round convenience functions. Each instance can be seeded but also automatically generates its own random seed on creation.

Notes and Todo

• .random - add tests for optional gaussian functionality
• does setting maxHistory reset the history array? should it? if not how should it handle truncating?
• audit/optimize tests - originally (mostly) for older version are they all still valid?

Install

npm i @justkd/roll

yarn add @justkd/roll

Exports

import { Roll } from '@justkd/roll';
import type { Seed } from '@justkd/roll';

Basic Use - Static Methods

Use the static method .random to generate a random number in the range 0-1.

const rand = Roll.random(); // float 0-1

Use the static method .d to generate a random integer in the range 1-n.

const d20 = Roll.d(20); // int 1-20

Basic Use - Instance Methods

Use instance methods to track history and expose statistic functions.

const roll = new Roll();

let i = 10;
while (i--) roll.random();

const history = roll.history(); // retrieve the internal history
const avg = roll.mean();        // retrieve the current average

Extended Use

Roll can use either uniform (normal) or gaussian distribution.

const roll = new Roll();

/* convenience function, same as `.uniform()` */
const random = roll.random();         

/* random number in the range 0-1, uniform (normal) distribution */ 
const uniform = roll.uniform();        

/* random number in the range 0-1, gaussian distribution, undefined skew (same as 0 skew) */
const gaussian = roll.gaussian();        

/* random number in the range 0-1, gaussian distribution, skewed RIGHT (normalized -1 to 1) */
const gaussianSkew = roll.gaussian(0.15); 

Roll can use either uniform (normal) or gaussian distribution (part II).

const roll = new Roll();

/* random integer in the range 1-6, uniform (normal) distribution */
const d6 = roll.d(6);                     

/* random integer in the range 1-8, gaussian distribution, no skew */
const d8 = roll.d(8, 0);   

/* random integer in the range 1-12, gaussian distribution, skewed LEFT (normalized -1 to 1) */
const d12 = roll.d(12, 0.85);

/* random integer in the range 1-20, gaussian distribution, skewed RIGHT (normalized -1 to 1) */
const d20 = roll.d(20, -0.35);

Each instance of Roll can be given a maxHistory.

const roll = new Roll({ maxHistory: 1000 });

let i = roll.maxHistory();
while (i--) roll.random();

const stats = {
    history: roll.history(),
    mean:    roll.mean(),
    median:  roll.median(),
    modes:   roll.modes(),
    stdDev:  roll.stdDev(), // standard deviation normalized 0-1
};

Note: While each instance of Roll will allow using both normal and gaussian distribution, you should use different instances if you need to track the distribution over time.

const maxHistory = 1000;

const uniformRoll = new Roll({ maxHistory });
const gaussianRoll = new Roll({ maxHistory });

let i = maxHistory;
while (i--) {
    uniformRoll.d(10);
    gaussianRoll.d(31, 0.24);
};

const uniformStats = {
    history: uniformRoll.history(),
    mean:    uniformRoll.mean(),
    median:  uniformRoll.median(),
    modes:   uniformRoll.modes(),
    stdDev:  uniformRoll.stdDev(),
};

const gaussianStats = {
    history: gaussianRoll.history(),
    mean:    gaussianRoll.mean(),
    median:  gaussianRoll.median(),
    modes:   gaussianRoll.modes(),
    stdDev:  gaussianRoll.stdDev(),
};

Set the max history in the constructor or with the instance method.

/* set the initial `maxHistory` to `99`, default is `maxHistory === Infinity` */
const roll = new Roll({ maxHistory: 99 });

/* returns the current `maxHistory` if no param is given */
console.log(roll.maxHistory()); // `maxHistory === 99`

roll.maxHistory(10);            // set instance `maxHistory` to `10`
console.log(roll.maxHistory()); // `maxHistory === 10`

Giving Roll a max history will allow you to calculate rolling statistics.

const roll = new Roll({ maxHistory: 10 });

setInterval(() => {
    const rand = roll.d(6);
    const avg = roll.mean();
    const history = roll.history();
    console.log(rand, avg, history);
}, 1000);

Round to n decimal places using the static method Roll.round().

const roll = new Roll();

const rand = roll.random();
const n = 2;
const rounded = Roll.round(rand, n);
const whole = Roll.round(rand * 100, 0)

// Roll.round(0.75, 0) === 1
// Roll.round(0.5, 0) === 1
// Roll.round(0.49, 0) === 0
// Roll.round(0.75, 1) === 0.8
// Roll.round(0.424242, 3) === 0.424

Numbers can be scaled from any known range to another using the static method Roll.scale().

const n = Roll.random();
const r1 = [0, 1];  // initial range
const r2 = [5, 72]; // target range
const scaled = Roll.scale(n, r1, r2); // if `n === 0.5` then `scaled === 33.5`

// Roll.scale(0.5, [0, 1], [-1, 1]) === 0
// Roll.scale(0.75, [0, 1], [0, 2]) === 1.5
// Roll.scale(55, [2.3, 98.6], [33.42, 87.55]) === 63.04254413291797
// Roll.scale(12975.2123, [0, 9001], [0, 1]) === 1.4415300855460504

Numbers can be clipped to a minimum and maximum allowed value using the static method Roll.clip().

const n = Roll.random();
const min = 0.2;
const max = 0.8;
const clipped = Roll.clip(n, [min, max]);

// Roll.clip(1, [0, 0.5]) === 0.5
// Roll.clip(-1, [1.5, 10]) === 1.5
// Roll.clip(0.5, [0, 1]) === 0.5

Generate a whole number between 1 and MAX_SAFE_INTEGER using gaussian distribution.

const getGaussianWhole = () => {
    const n = Roll.random(0);
    const scaled = Roll.scale(n, [0, 1], [1, Number.MAX_SAFE_INTEGER]);
    const whole = Roll.round(scaled, 0);
    return whole;
}
console.log(getGaussianWhole())

Generate and set a new random seed with the static method Roll.createRandomSeed() and instance method roll.seed().

const roll = new Roll();

/* returns the current `seed` if no param is given */
console.log(roll.seed());

const newSeed = Roll.createRandomSeed();

/* set the seed for the given instance (this will clear the history) */
roll.seed(newSeed);

API - Instance Methods

/**
 * Allowed seed types. 
 * A `number`, `number[]`, `Uint32Array`, or `undefined` representing a seed value.
 * @typedef {( number | number[] | Uint32Array | undefined )} Seed
 */
 type Seed = number | number[] | Uint32Array | undefined

/**
 * Generates a 53-bit random real in the interval [0, 1] with uniform distribution.
 * @returns {number}
 * @readonly
 */
 readonly uniform: () => number

/**
 * Generates a 53-bit random real in the interval [0, 1] with gaussian distribution.
 * @param {number} [skew=0] - In the range [-1,1]. Negative values skew data RIGHT, 
 * and positive values skew data LEFT. 
 * @returns {number}
 * @readonly
 */
readonly gaussian: (skew: number = 0) => number

/**
 * Convenience function. Same as `.gaussian` if `skew` is a `number`, same as 
 * `.uniform` if `skew` is `undefined`.
 * @param {number} [skew] - In the range [-1, 1]. Negative values skew data RIGHT, 
 * positive values skew data LEFT.
 * @note Pass `0` to use gaussian distribution without skew.
 * @returns {number}
 * @readonly
 */
readonly random: (skew?: number) => number

/**
 * Simulates a die-rolling metaphor. First generates a 53-bit random real in the 
 * interval [0, 1] with uniform or gaussian distribution, then scales it to a range 
 * `[1, n]` where `n` is the number of sides, then rounds to whole number.
 * @param {number} sides - The number of sides the die should represent. 
 * Allows but ignores decimal places.
 * @param {number} [skew] - In the range [-1, 1]. Negative values skew data RIGHT, 
 * positive values skew data LEFT.
 * @note Pass `0` to use gaussian distribution without skew.
 * @returns {number}
 * @readonly
 */
readonly d: (sides: number, skew?: number) => number

/**
 * Set the seed or get the current seed if no param is given. Automatically 
 * clears `history` when setting a new seed.
 * @param {Seed} [seed] - Unsigned 32-bit integer or number array of arbitrary size/values.
 * @returns {Seed} Returns the current seed.
 * @readonly
 */
readonly seed: (seed?: Seed) => Seed

/**
 * Retrieve a copy of the internal history array with no references.
 * @returns {number[]} Returns the current `history`.
 * @readonly
 */
readonly history: () => number[]

/**
 * Set the maximum `history` size or get the current size if no param is given. 
 * Default on instance creation is `Infinity`.
 * @param {number} [size] - The desired maximum history size.
 * @returns {number} Returns the current `maxHistory`.
 * @readonly
 */
readonly maxHistory: (size?: number) => number

/**
 * Reset the internal `history` array. Does not change current `maxHistory`.
 * @readonly
 */
readonly clearHistory: () => void

/**
 * Calculate the statistical mean of a given `number[]` or the current `history`.
 * @param {number[]} [arr] - Target array on which to operate. 
 * Defaults to the current `history` if `arr` is `undefined`.
 * @returns {number}
 * @readonly
 */
readonly mean: (arr?: number[]) => number

/**
 * Calculate the statistical median of a given `number[]` or the current `history`.
 * @param {number[]} [arr] -  Target array on which to operate. 
 * Defaults to the current `history` if `arr` is `undefined`.
 * @returns {number}
 * @readonly
 */
readonly median: (arr?: number[]) => number

/**
 * Calculate the statistical modes of a given `number[]` or the current `history`.
 * @param {number[]} [arr] - Target array on which to operate. 
 * Defaults to the current `history` if `arr` is `undefined`.
 * @returns {number[]}
 * @readonly
 */
readonly modes: (arr?: number[]) => number[]

/**
 * Calculate the standard deviation of a given `number[]` or the current `history`.
 * @param {number[]} [arr] - Target array on which to operate. 
 * Defaults to the current `history` if `arr` is `undefined`.
 * @returns {number} Standard deviation normalized [0, 1].
 * @readonly
 */
readonly stdDev: (arr?: number[]) => number

API - Static Methods

/**
 * Convenience function. Same as `.gaussian` if `skew` is a `number`, 
 * same as `.uniform` if `skew` is `undefined`.
 * @param {number} [skew] - In the range [-1, 1]. Negative values skew data RIGHT, 
 * positive values skew data LEFT.
 * @note Pass `0` to use gaussian distribution without skew.
 * @returns {number}
 * @static
 */
static random(skew?: number): number

/**
 * Convenience function to generate a randomly seeded random number
 * in the range 1-sides.
 * @param {number} sides - The desired number of sides to simulate.
 * @param {number} [skew] - In the range [-1,1]. If `skew` is a number,
 * `Roll.d` will use gaussian distribution instead of normal distribution.
 * @note Pass `0` to use gaussian distribution without skew.
 * @returns {number}
 * @static
 */
static d(sides: number, skew?: number): number

/**
 * Generate a random seed array using `window.crypto`. Falls back to `node.crypto` 
 * or a final fallback to using `Math.random()` to fill an array.
 * @return {number[]} Randomly generated `number[]` of random size [20,623] and values.
 * @static
 */
static createRandomSeed(): number[]

/**
 * Scale a value from a known range to a new range.
 * @param {number} value - The initial value.
 * @param {[number, number]} r1 - The initial range [min, max].
 * @param {[number, number]} [r2] - The target range [min, max].
 * @note Shorthand: If `r1` is not `[0, 1]` and `r2` is `undefined`,
 * the actual `r1` is assumed to be `[0, 1]` and the actual `r2`
 * is assumed to be the given `r1`.
 * @returns {number}
 * @static
 * @example
 * const n = 50
 * const scaled = Roll.scale(n, [0, 100], [0, 1]) // scaled === 0.5
 * @example
 * // we can use the shorthand when we know the input value is in the range [0, 1]
 * const n = Roll.random()
 * const scaled = Roll.scale(n, [0, 10]) // scaled === 5
 */
static scale(
    value: number,
    r1: [number, number],
    r2: [number, number],
): number

/**
 * Limit a value to a hard minimum and maximum.
 * @param {number} value - The initial value.
 * @param {[number, number]} range - Two-element array containing 
 * the minimum and maximum possible values.
 * @returns {number}
 * @static
 */
static clip(
    value: number, 
    range: [number, number],
): number

/**
 * Round a value to a specific number of places. 
 * Decimal values < 5 (for any given place) are rounded down.
 * @param {number} value - The initial value.
 * @param {number} [places=0] - The desired number of decimal places.
 * `0` results in a whole number. Default is `places=0`.
 * @returns {number}
 * @static
 */
static round(
    value: number, 
    places: number
): number