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:

``properties
$ yarn add toosoon-prng
`

NPM:

`properties
$ npm install toosoon-prng
`

Usage

Using default PRNG instance.

`ts
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.

`ts
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

$3

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

`ts
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.

`ts
PRNG.seed: string;
`

##### .generator

Generator function used for pseudo-random generations.

`ts
PRNG.generator: Generator;
`

#### Methods

##### .setSeed(seed)

Set the PRNG instance seed.

- seed

`ts
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

`ts
PRNG.random(subseed: Seed): number;
`

##### .randomBoolean(subseed, probability?)

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

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

`ts
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.

`ts
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.

`ts
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.

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

##### .randomHexColor(subseed)

Generate a pseudo-random hexadecimal color.

- subseed

`ts
PRNG.randomHexColor(subseed: Seed): string;
`

##### .randomItem(subseed, array)

Pseudo-randomly pick an item from an array.

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

`ts
PRNG.randomItem(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.

`ts
PRNG.randomObjectProperty(subseed: Seed, object: Record): T | undefined;
`

##### .randomIndex(subseed, weights)

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

- subseed
- weights: Array of weights.

`ts
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.

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

$3

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.

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

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

$3

##### randomSeed(length?)

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

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

`ts
randomSeed(length?: number): string;
`

$3

DEFAULT_SEED`

License

MIT License, see LICENSE for details.