TOOSOON Pseudo-Random Number Generator (PRNG)

This project provides PRNG functions for generating pseudo-random values using a seed-based approach. These are particularly useful for applications requiring deterministic randomization, such as procedural generation or simulations.

Installation

Yarn:

$ yarn add toosoon-prng

NPM:

$ npm install toosoon-prng

Usage

Using default PRNG instance.

import prng from 'toosoon-prng';

prng.setSeed('seed');

prng.randomFloat('angle', 0, Math.PI); // Pseudo-random number in the interval [0, PI)

Using PRNG class constructor.

import { PRNG } from 'toosoon-prng';

const prng = new PRNG('seed');

prng.randomFloat('angle', 0, Math.PI); // Pseudo-random number in the interval [0, PI)

API

PRNG

Utility class for generating pseudo-random values.

• new PRNG(seed?, generator?)
  • .seed: string
  • .generator: Function
  • .setSeed(seed?): void
  • .random(subseed): number
  • .randomBoolean(subseed, probability?): boolean
  • .randomSign(subseed, probability?): number
  • .randomFloat(subseed, min?, max?, precision?): number
  • .randomInt(subseed, min, max): number
  • .randomHexColor(subseed): string
  • .randomItem(subseed, array): unknown|undefined
  • .randomObjectProperty(subseed, object): unknown|undefined
  • .randomIndex(subseed, weights): number
  • .randomGaussian(subseed, mean?, spread?): number

Types

type Seed = string | number;

type Generator = (...hashes: number[]) => number;

Constructor

| Parameter | Type | Default | Description | | ----------- | ----------- | ------- | ------------------------------------------------------ | | [seed] | Seed | | Seed string used for pseudo-random generations. | | [generator] | Generator | sfc32 | Generator function used for pseudo-random generations. |

Properties

.seed

Seed string used for pseudo-random generations.

PRNG.seed: string;

.generator

Generator function used for pseudo-random generations.

PRNG.generator: Generator;

Methods

.setSeed(seed)

Set the PRNG instance seed.

• seed

PRNG.setSeed(seed: Seed): void;

.random(subseed)

Generate a pseudo-random number between 0 and 1 (0 inclusive, 1 exclusive). Pseudo-random equivalent of Math.random().

• subseed

PRNG.random(subseed: Seed): number;

.randomBoolean(subseed, probability?)

Generate a pseudo-random boolean (true or false).

• subseed
• [probability=0.5]: Probability to get true.

PRNG.randomBoolean(subseed: Seed, probability?: number): boolean;

.randomSign(subseed, probability?)

Generate a pseudo-random sign (1 or -1).

• subseed
• [probability=0.5]: Probability to get 1.

PRNG.randomSign(subseed: Seed, probability?: number): number;

.randomFloat(subseed, min?, max?, precision?)

Generate a pseudo-random floating-point number within a specified range.

• subseed
• [min=0]: Minimum boundary.
• [max=1]: Maximum boundary.
• [precison=2]: Number of digits after the decimal point.

PRNG.randomFloat(subseed: Seed, min?: number, max?: number1, precision?: number): number;

.randomInt(subseed, min, max)

Generate a pseudo-random integer number within a specified range.

• subseed
• min: Minimum boundary.
• max: Maximum boundary.

PRNG.randomInt(subseed: Seed, min: number, max: number): void;

.randomHexColor(subseed)

Generate a pseudo-random hexadecimal color.

• subseed

PRNG.randomHexColor(subseed: Seed): string;

.randomItem(subseed, array)

Pseudo-randomly pick an item from an array.

• subseed
• array: Array to pick the item from.

PRNG.randomItem<T>(subseed: Seed, array: T[]): T | undefined;

.randomObjectProperty(subseed, object)

Pseudo-randomly pick a property value from an object.

• subseed
• object: Object to pick the property from.

PRNG.randomObjectProperty<T>(subseed: Seed, object: Record<string, T>): T | undefined;

.randomIndex(subseed, weights)

Select a pseudo-random index from an array of weighted items.

• subseed
• weights: Array of weights.

PRNG.randomIndex(subseed: Seed, weights: number[]): number;

.randomGaussian(subseed, mean?, spread?)

Generate a pseudo-random number fitting a Gaussian (normal) distribution.

• subseed
• [mean=0]: Mean (central) value of the distribution.
• [spread=1]: Spread (standard deviation) of the distribution.

PRNG.randomGaussian(subseed: Seed, mean?: number, spread?: number): number;

Generators

By default, the library is using SplitMix32 generator for generating the pseudo-random values but it is possible to change the generator used by one of the following:

• sfc32: Simple Fast Counter, Generator with a 128-bit state.
• jsf32: Jenkins' Small Fast, Generator with a 128-bit state.
• xoshiro128ss: xoshiro128**, Generator with a 128-bit state.
• mulberry32: Mulberry32, Generator with a 32-bit state.
• splitmix32: SplitMix32, Generator with a 32-bit state.

import { PRNG, sfc32 } from 'toosoon-prng';

const prng = new PRNG('seed', { generator: sfc32 });

Utils

randomSeed(length?)

Generate a random string that can be used as a seed.

• [length=64]: Length of the generated seed string.

randomSeed(length?: number): string;

Constants

DEFAULT_SEED

License

MIT License, see LICENSE for details.