toosoon-prng-controllers/README.md

This project provides PRNG functions with a set of controllers for generating pseudo-random values using a seed-based approach

# TOOSOON Pseudo-Random Number Generator (PRNG) — Controllers

This project provides PRNG functions with a set of controllers for generating pseudo-random values using a seed-based approach.

It adds additionnal features to the main library: [toosoon-prng](https://github.com/toosoon-dev/toosoon-prng).

[![NPM](https://nodei.co/npm/toosoon-prng-controllers.png)](https://nodei.co/npm/toosoon-prng-controllers/)

## Installation

Yarn:

```properties
$ yarn add toosoon-prng-controllers
```

NPM:

```properties
$ npm install toosoon-prng-controllers
```

## Usage

```ts
import { IntController, IntGroupController } from 'toosoon-prng-controllers';

const config = {
  count: new IntController('count', 0, 10),
  counts: new IntGroupController('counts', 5, 10)
};

config.count.getValue(); // Pseudo-random integer in the interval [0, 10)

for (let i = 0; i < 5; i++) {
  config.counts.getValueAt(i); // Pseudo-random integers in the interval [5, 10)
}
```

## Controllers

### PRNGController <a id="prng-controller"></a>

Utility abstract class for generating pseudo-random values.

- new PRNGController\<T\>(seed)
  - [.seed](#prng-controller-seed): `string`
  - [.value](#prng-controller-value): `T`
  - [.getValue()](#prng-controller-get-value-method): `T`
  - [.dispose()](#prng-controller-dispose-method): `void`

#### Properties

##### .`seed` <a id="prng-controller-seed"></a>

Seed string used for pseudo-random generations.

```ts
PRNGController.seed: string;
```

##### .`value` <a id="prng-controller-value"></a>

Pseudo-random value generated by the controller.

```ts
PRNGController<T>.value: T;
```

#### Methods

##### .`getValue()` <a id="prng-controller-get-value-method"></a>

Generate the controller pseudo-random value.

```ts
PRNGController<T>.getValue(): T;
```

##### .`dispose()` <a id="prng-controller-dispose-method"></a>

Dispose the controller.

```ts
PRNGController.dispose(): void;
```

### BooleanController <a id="boolean-controller"></a>

Utility class extending [PRNGController](#prng-controller) for generating pseudo-random boolean values.

- [new BooleanController(seed, probability?)](#boolean-controller-constructor)
  - [.value](#boolean-controller-value): `boolean`
  - [.probability](#boolean-controller-probability): `number`

#### Constructor <a id="boolean-controller-constructor"></a>

| Parameter     | Type     | Default | Description                                     |
| ------------- | ---------| ------- | ----------------------------------------------- |
| seed          | `Seed`   |         | Seed string used for pseudo-random generations. |
| [probability] | `number` | `0.5`   | Probability to get `true`.                      |

#### Properties

##### .`value` <a id="boolean-controller-value"></a>

Pseudo-random boolean value generated by the controller.

```ts
BooleanController.value: boolean;
```

##### .`probability` <a id="boolean-controller-probability"></a>

Probability to get `true`.

```ts
BooleanController.probability: number;
```

### SignController <a id="sign-controller"></a>

Utility class extending [PRNGController](#prng-controller) for generating pseudo-random sign values (-1 or 1).

- [new SignController(seed, probability?)](#sign-controller-constructor)
  - [.value](#sign-controller-value): `number`
  - [.probability](#sign-controller-probability): `number`

#### Constructor <a id="sign-controller-constructor"></a>

| Parameter     | Type     | Default | Description                                     |
| ------------- | ---------| ------- | ----------------------------------------------- |
| seed          | `Seed`   |         | Seed string used for pseudo-random generations. |
| [probability] | `number` | `0.5`   | Probability to get `1`.                      |

#### Properties

##### .`value` <a id="sign-controller-value"></a>

Pseudo-random sign value generated by the controller.

```ts
SignController.value: number;
```

##### .`probability` <a id="sign-controller-probability"></a>

Probability to get `1`.

```ts
SignController.probability: number;
```

### FloatController <a id="float-controller"></a>

Utility class extending [PRNGController](#prng-controller) for generating pseudo-random floating-point numbers within a specified range.

- [new FloatController(seed, min?, max?)](#float-controller-constructor)
  - [.value](#float-controller-value): `number`
  - [.min](#float-controller-min): `number`
  - [.max](#float-controller-max): `number`

#### Constructor <a id="float-controller-constructor"></a>

| Parameter | Type               | Default | Description                                     |
| --------- | ------------------ | ------- | ----------------------------------------------- |
| seed      | `Seed`             |         | Seed string used for pseudo-random generations. |
| [min]     | `number`           | `0`     | Minimum boundary.                               |
| [max]     | `number`           | `1`     | Maximum boundary.                               |

#### Properties

##### .`value` <a id="float-controller-value"></a>

Pseudo-random floating-point number generated by the controller.

```ts
FloatController.value: number;
```

##### .`min` <a id="float-controller-min"></a>

Minimum boundary.

```ts
FloatController.min: number;
```

##### .`max` <a id="float-controller-max"></a>

Maximum boundary.

```ts
FloatController.max: number;
```

### IntController <a id="int-controller"></a>

Utility class extending [PRNGController](#prng-controller) for generating pseudo-random integer numbers within a specified range.

- [new IntController(seed, min, max)](#int-controller-constructor)
  - [.value](#int-controller-value): `number`
  - [.min](#int-controller-min): `number`
  - [.max](#int-controller-max): `number`

#### Constructor <a id="int-controller-constructor"></a>

| Parameter | Type               | Default | Description                                     |
| --------- | ------------------ | ------- | ----------------------------------------------- |
| seed      | `Seed`             |         | Seed string used for pseudo-random generations. |
| min       | `number`           |         | Minimum boundary.                               |
| max       | `number`           |         | Maximum boundary.                               |

#### Properties

##### .`value` <a id="int-controller-value"></a>

Pseudo-random integer number generated by the controller.

```ts
IntController.value: number;
```

##### .`min` <a id="int-controller-min"></a>

Minimum boundary.

```ts
IntController.min: number;
```

##### .`max` <a id="int-controller-max"></a>

Maximum boundary.

```ts
IntController.max: number;
```

### HexColorController <a id="hex-color-controller"></a>

Utility class extending [PRNGController](#prng-controller) for generating pseudo-random hexadecimal color strings.

- [new HexColorController(seed)](#hex-color-controller-constructor)
  - [.value](#hex-color-controller-value): `string`

#### Constructor <a id="hex-color-controller-constructor"></a>

| Parameter | Type     | Default | Description                                     |
| --------- | -------- | ------- | ----------------------------------------------- |
| seed      | `Seed`   |         | Seed string used for pseudo-random generations. |

#### Properties

##### .`value` <a id="hex-color-controller-value"></a>

Pseudo-random hexadecimal color string generated by the controller.

```ts
HexColorController.value: string;
```

### ItemController <a id="item-controller"></a>

Utility class extending [PRNGController](#prng-controller) for pseudo-randomly picking an item from an array.

- [new ItemController(seed, items)](#item-controller-constructor)
  - [.value](#item-controller-value): `T`
  - [.items](#item-controller-items): `T[]`

#### Constructor <a id="item-controller-constructor"></a>

| Parameter | Type   | Default | Description                                     |
| --------- | ------ | ------- | ----------------------------------------------- |
| seed      | `Seed` |         | Seed string used for pseudo-random generations. |
| items     | `T[]`  |         | Array of items to pseudo-randomly pick from.    |

#### Properties

##### .`value` <a id="item-controller-value"></a>

Item pseudo-randomly picked from the items array.

```ts
ItemController<T>.value: T;
```

##### .`items` <a id="item-controller-items"></a>

Array of items to pseudo-randomly pick from.

```ts
ItemController<T>.items: T[];
```

### ObjectPropertyController <a id="object-property-controller"></a>

Utility class extending [PRNGController](#prng-controller) for pseudo-randomly picking a property value from an object.

- [new ObjectPropertyController(seed, object)](#object-property-controller-constructor)
  - [.value](#object-property-controller-value): `T|undefined`
  - [.object](#object-property-controller-object): `Record<string, T>`

#### Constructor <a id="object-property-controller-constructor"></a>

| Parameter | Type                | Default | Description                                             |
| --------- | ------------------- | ------- | ------------------------------------------------------- |
| seed      | `Seed`              |         | Seed string used for pseudo-random generations.         |
| object    | `Record<string, T>` |         | Object to pseudo-randomly pick the property value from. |

#### Properties

##### .`value` <a id="object-property-controller-value"></a>

Property value pseudo-randomly picked from the object.

```ts
ObjectPropertyController<T>.value: T | undefined;
```

##### .`object` <a id="object-property-controller-object"></a>

Object to pseudo-randomly pick the property value from.

```ts
ObjectPropertyController<T>.object: Record<string, T>;
```

### WeightsController <a id="weights-controller"></a>

Utility class extending [PRNGController](#prng-controller) for pseudo-randomly picking an item from an array of weighted items.

- [new WeightsController(seed, items)](#weights-controller-constructor)
  - [.value](#weights-controller-value): `T`
  - [.items](#weights-controller-items): `Array<{ weight: number; value: T }>`
  - [.weights](#weights-controller-weights): `readonly number[]`

#### Types

```ts
type WeightedItem<T = unknown> = { weight: number; value: T };

type WeightedItems<T = unknown> = Array<WeightedItem<T>>;
```

#### Constructor <a id="weights-controller-constructor"></a>

| Parameter | Type               | Default | Description                                               |
| --------- | ------------------ | ------- | --------------------------------------------------------- |
| seed      | `Seed`             |         | Seed string or number used for pseudo-random generations. |
| items     | `WeightedItems<T>` |         | Array of weighted items to pseudo-randomly pick from.     |

#### Properties

##### .`value` <a id="weights-controller-value"></a>

Item pseudo-randomly picked from the weighted items array.

```ts
WeightsController<T>.value: T;
```

##### .`items` <a id="weights-controller-items"></a>

Array of weighted items to pseudo-randomly pick from.

```ts
WeightsController<T>.items: WeightedItems<T>;
```

##### .`weights` <a id="weights-controller-weights"></a>

Array of weights.

```ts
WeightsController.weights: readonly number[];
```

### GaussianController <a id="gaussian-controller"></a>

Utility class extending [PRNGController](#prng-controller) for generating pseudo-random numbers fitting a Gaussian (normal) distribution.

- [new GaussianController(seed, mean?, spread?)](#gaussian-controller-constructor)
  - [.value](#gaussian-controller-value): `number`
  - [.mean](#gaussian-controller-mean): `number`
  - [.spread](#gaussian-controller-spread): `number`

#### Constructor

| Parameter | Type      | Default | Description                                               |
|-----------|-----------|---------|---------------------------------------------------------- |
| seed      | `Seed`    |         | Seed string or number used for pseudo-random generations. |
| [mean]    | `number`  | `0`     | Mean (central) value of the distribution.                 |
| [spread]  | `number`  | `1`     | Spread (standard deviation) of the distribution.          |

#### Properties

##### .`value` <a id="gaussian-controller-value"></a>

Pseudo-random number value generated by the controller.

```ts
GaussianController.value: number;
```

##### .`mean` <a id="gaussian-controller-mean"></a>

Mean (central) value for the distribution.

```ts
GaussianController.mean: number;
```

##### .`spread` <a id="gaussian-controller-spread"></a>

Spread (standard deviation) for the distribution.

```ts
GaussianController.spread: number;
```

## Group Controllers

### PRNGGroupController <a id="prng-group-controller"></a>

Utility abstract class for managing multiple instances of controllers.

- new PRNGGroupController\<T, C\>(seed)
  - [.seed](#prng-group-controller-seed): `string`
  - [.controllers](#prng-group-controller-controllers): `C[]`
  - [.createController(index)](#prng-group-controller-create-controller-method): `C`
  - [.getValueAt(index)](#prng-group-controller-get-value-at-method): `T`
  - [.dispose()](#prng-group-controller-dispose-method): `void`

#### Properties

##### .`seed` <a id="prng-group-controller-seed"></a>

Seed string used for pseudo-random generations.

```ts
PRNGGroupController.seed: string;
```

##### .`controllers` <a id="prng-group-controller-controllers"></a>

Controllers managed by the group.

```ts
PRNGGroupController<T, C>.controllers: C[];
```

#### Methods

##### .`createController(index)` <a id="prng-group-controller-create-controller-method"></a>

Create a new controller.

- `index`: Index of the controller to create.

```ts
PRNGGroupController<T, C>.createController(index: number): C;
```

##### .`getValueAt(index)` <a id="prng-group-controller-get-value-at-method"></a>

Generate a pseudo-random value.

- `index`: Index of the controller to use.

```ts
PRNGGroupController<T>.getValueAt(index: number): T;
```

##### .`dispose()` <a id="prng-group-controller-dispose-method"></a>

Dispose the group controllers.

```ts
PRNGGroupController.dispose(): void;
```

### BooleanGroupController <a id="boolean-group-controller"></a>

Utility class extending [PRNGGroupController](#prng-group-controller) for managing multiple [BooleanController](#boolean-controller).

- [new BooleanGroupController(seed, probability?)](#boolean-group-controller-constructor)
  - [.probability](#boolean-group-controller-probability): `number`

#### Constructor <a id="boolean-group-controller-constructor"></a>

| Parameter     | Type     | Default | Description                                     |
| ------------- | ---------| ------- | ----------------------------------------------- |
| seed          | `Seed`   |         | Seed string used for pseudo-random generations. |
| [probability] | `number` | `0.5`   | Probability to get `true`.                      |

#### Properties

##### .`probability` <a id="boolean-group-controller-probability"></a>

Probability to get `true`.

```ts
BooleanGroupController.probability: number;
```

### SignGroupController <a id="sign-group-controller"></a>

Utility class extending [PRNGGroupController](#prng-group-controller) for managing multiple [SignController](#sign-controller).

- [new SignGroupController(seed, probability?)](#sign-group-controller-constructor)
  - [.probability](#sign-group-controller-probability): `number`

#### Constructor <a id="sign-group-controller-constructor"></a>

| Parameter     | Type     | Default | Description                                     |
| ------------- | ---------| ------- | ----------------------------------------------- |
| seed          | `Seed`   |         | Seed string used for pseudo-random generations. |
| [probability] | `number` | `0.5`   | Probability to get `1`.                         |

#### Properties

##### .`probability` <a id="sign-group-controller-probability"></a>

Probability to get `1`.

```ts
SignGroupController.probability: number;
```

### FloatGroupController <a id="float-group-controller"></a>

Utility class extending [PRNGGroupController](#prng-group-controller) for managing multiple [FloatController](#float-controller).

- [new FloatGroupController(seed, min?, max?)](#float-group-controller-constructor)
  - [.min](#float-group-controller-min): `number`
  - [.max](#float-group-controller-max): `number`

#### Constructor <a id="float-group-controller-constructor"></a>

| Parameter | Type               | Default | Description                                     |
| --------- | ------------------ | ------- | ----------------------------------------------- |
| seed      | `Seed`             |         | Seed string used for pseudo-random generations. |
| [min]     | `number`           | `0`     | Minimum boundary.                               |
| [max]     | `number`           | `1`     | Maximum boundary.                               |

#### Properties

##### .`min` <a id="float-group-controller-min"></a>

Minimum boundary.

```ts
FloatGroupController.min: number;
```

##### .`max` <a id="float-group-controller-max"></a>

Maximum boundary.

```ts
FloatGroupController.max: number;
```

### IntGroupController <a id="int-group-controller"></a>

Utility class extending [PRNGGroupController](#prng-group-controller) for managing multiple [IntController](#int-controller).

- [new IntGroupController(seed, min, max)](#int-group-controller-constructor)
  - [.min](#int-group-controller-min): `number`
  - [.max](#int-group-controller-max): `number`

#### Constructor <a id="int-group-controller-constructor"></a>

| Parameter | Type               | Default | Description                                     |
| --------- | ------------------ | ------- | ----------------------------------------------- |
| seed      | `Seed`             |         | Seed string used for pseudo-random generations. |
| min       | `number`           |         | Minimum boundary.                               |
| max       | `number`           |         | Maximum boundary.                               |

#### Properties

##### .`min` <a id="int-group-controller-min"></a>

Minimum boundary.

```ts
IntGroupController.min: number;
```

##### .`max` <a id="int-group-controller-max"></a>

Maximum boundary.

```ts
IntGroupController.max: number;
```

### HexColorGroupController <a id="hex-color-group-controller"></a>

Utility class extending [PRNGGroupController](#prng-group-controller) for managing multiple [HexColorController](#hex-color-controller).

- [new HexColorGroupController(seed)](#hex-color-group-controller-constructor)

#### Constructor <a id="hex-color-group-controller-constructor"></a>

| Parameter | Type     | Default | Description                                     |
| --------- | -------- | ------- | ----------------------------------------------- |
| seed      | `Seed`   |         | Seed string used for pseudo-random generations. |

### ItemGroupController <a id="item-group-controller"></a>

Utility class extending [PRNGGroupController](#prng-group-controller) for managing multiple [ItemController](#item-controller).

- [new ItemGroupController(seed, items)](#item-group-controller-constructor)
  - [.items](#item-group-controller-items): `T[]`

#### Constructor <a id="item-group-controller-constructor"></a>

| Parameter | Type   | Default | Description                                     |
| --------- | ------ | ------- | ----------------------------------------------- |
| seed      | `Seed` |         | Seed string used for pseudo-random generations. |
| items     | `T[]`  |         | Array of items to pseudo-randomly pick from.    |

#### Properties

##### .`items` <a id="item-group-controller-items"></a>

Array of items to pseudo-randomly pick from.

```ts
ItemGroupController<T>.items: T[];
```

### ObjectPropertyGroupController <a id="object-property-group-controller"></a>

Utility class extending [PRNGGroupController](#prng-group-controller) for managing multiple [ObjectPropertyController](#object-property-controller).

- [new ObjectPropertyGroupController(seed, object)](#object-property-group-controller-constructor)
  - [.object](#object-property-group-controller-object): `Record<string, T>`

#### Constructor <a id="object-property-group-controller-constructor"></a>

| Parameter | Type                | Default | Description                                             |
| --------- | ------------------- | ------- | ------------------------------------------------------- |
| seed      | `Seed`              |         | Seed string used for pseudo-random generations.         |
| object    | `Record<string, T>` |         | Object to pseudo-randomly pick the property value from. |

#### Properties

##### .`object` <a id="object-property-group-controller-object"></a>

Object to pseudo-randomly pick the property value from.

```ts
ObjectPropertyGroupController<T>.object: Record<string, T>;
```

### WeightsGroupController <a id="weights-group-controller"></a>

Utility class extending [PRNGGroupController](#prng-group-controller) for managing multiple [WeightsController](#weights-controller).

- [new WeightsGroupController(seed, items)](#weights-group-controller-constructor)
  - [.items](#weights-group-controller-items): `Array<{ weight: number; value: T }>`
  - [.weights](#weights-group-controller-weights): `readonly number[]`

#### Constructor <a id="weights-group-controller-constructor"></a>

| Parameter | Type               | Default | Description                                               |
| --------- | ------------------ | ------- | --------------------------------------------------------- |
| seed      | `Seed`             |         | Seed string or number used for pseudo-random generations. |
| items     | `WeightedItems<T>` |         | Array of weighted items to pseudo-randomly pick from.     |

#### Properties

##### .`items` <a id="weights-group-controller-items"></a>

Array of weighted items to pseudo-randomly pick from.

```ts
WeightsGroupController<T>.items: WeightedItems<T>;
```

##### .`weights` <a id="weights-group-controller-weights"></a>

Array of weights.

```ts
WeightsGroupController.weights: readonly number[];
```

### GaussianGroupController <a id="gaussian-group-controller"></a>

Utility class extending [PRNGGroupController](#prng-group-controller) for managing multiple [GaussianController](#gaussian-controller).

- [new GaussianGroupController(seed, mean?, spread?)](#gaussian-group-controller-constructor)
  - [.mean](#gaussian-group-controller-mean): `number`
  - [.spread](#gaussian-group-controller-spread): `number`

#### Constructor <a id="gaussian-group-controller-constructor"></a>

| Parameter | Type      | Default | Description                                               |
|-----------|-----------|---------|---------------------------------------------------------- |
| seed      | `Seed`    |         | Seed string or number used for pseudo-random generations. |
| [mean]    | `number`  | `0`     | Mean (central) value of the distribution.                 |
| [spread]  | `number`  | `1`     | Spread (standard deviation) of the distribution.          |

#### Properties

##### .`mean` <a id="gaussian-group-controller-mean"></a>

Mean (central) value for the distribution.

```ts
GaussianGroupController.mean: number;
```

##### .`spread` <a id="gaussian-group-controller-spread"></a>

Spread (standard deviation) for the distribution.

```ts
GaussianGroupController.spread: number;
```

## License

MIT License, see [LICENSE](https://github.com/toosoon-dev/toosoon-prng/tree/master/LICENSE) for details.