toosoon-prng 1.0.5 → 1.2.0

package/README.md

@@ -1,7 +1,9 @@
-# TOOSOON PRNG
+# TOOSOON PRNG (Pseudo-Random Number Generator)
 
 TOOSOON pseudo-random number generator utility functions & controllers.
 
+This project provides a `prng` instance and a set of `Controllers` for generating pseudo-random values using a seed-based approach and various algorithms. These controllers are particularly useful for applications requiring deterministic randomization, such as procedural generation or simulations.
+
 ## Installation
 
 Yarn:
@@ -18,158 +20,317 @@ $ npm install toosoon-prng
 
 ## Usage
 
-PRNG:
+##### PRNG
+
+##### setSeed
 
 ```ts
 import prng from 'toosoon-prng';
 
-prng.setSeed('010101');
+prng.setSeed('seed');
 console.log(prng.randomFloat('angle', 0, Math.PI)); // Pseudo-random number in the interval [0, PI]
 ```
 
-PRNG Controllers:
+##### PRNG Controllers
 
 ```ts
-import { FloatController, FloatGroupController } from 'toosoon-prng';
+import { IntController, IntGroupController } from 'toosoon-prng';
 
 const config = {
-  angle: new FloatController('angle', 0, Math.PI),
-  angles: new FloatGroupController('angle', 0, Math.PI)
+  count: new IntController('count', 0, Math.PI),
+  counts: new IntGroupController('counts', 0, Math.PI)
 };
 
-config.angle.addGui(gui, 0, Math.PI, 0.01);
-config.angles.addGui(gui, 0, Math.PI, 0.01);
+config.count.addGUI(gui, 0, 10);
+config.counts.addGUI(gui, 5, 10);
 
-console.log(config.angle.getValue()); // Pseudo-random number in the interval [0, PI]
+console.log(config.count.getValue()); // Pseudo-random integer in the interval [0, 10]
 
 for (let i = 0; i < 5; i++) {
-  console.log(config.angles.getValueAt(i)); // 5 Pseudo-random numbers in the interval [0, PI]
+  console.log(config.counts.getValueAt(i)); // Pseudo-random integers in the interval [5, 10]
 }
 ```
 
 ## PRNG Functions
 
+All PRNG functions have a `seed` argument wich allows you to add a sub-seed string to the `PRNG` instance global `seed` in order to get different pseudo-random outputs while using a PRNG function multiple times.
+
+```ts
+prng.setSeed('global-seed');
+console.log(prng.randomBoolean('1')); // Could be true or false
+console.log(prng.randomBoolean('2')); // Could be different from the first pseudo-random value
+```
+
+##### setSeed(seed)
+
+Set the `PRNG` instance seed.
+
+- `seed`
+
 ```ts
-// Set PRNG instance seed
 prng.setSeed(seed: string) => void;
 ```
 
+##### setAlgorithm(algorithm)
+
+Set the `PRNG` algorithm for generating pseudo-random values.
+
+- `algorithm`: Algorithm name.
+
 ```ts
-// Set PRNG instance method
-prng.setMethod(method: PRNGMethod) => void;
+prng.setAlgorithm(algorithm: Algorithm) => void;
 ```
 
+##### random(seed)
+
+Generate a pseudo-random number in the interval [0, 1]. PRNG equivalent of `Math.random()`.
+
+- `seed`
+
 ```ts
-// Generate a pseudo-random number in the interval [0, 1] (PRNG equivalent of Math.random)
 prng.random(seed: string) => number;
 ```
 
+##### randomBoolean(seed)
+
+Generate a pseudo-random boolean (true or false).
+
+- `seed`
+- `[probability=0.5]`: Probability to get `true`.
+
 ```ts
-// Generate a pseudo-random boolean (true or false)
 prng.randomBoolean(seed: string, probability?: number) => boolean;
 ```
 
+##### randomSign(seed)
+
+Generate a pseudo-random sign (1 or -1).
+
+- `seed`
+- `[probability=0.5]`: Probability to get 1.
+
 ```ts
-// Generate a pseudo-random sign (1 or -1)
 prng.randomSign(seed: string, probability?: number) => number;
 ```
 
+##### randomFloat(seed, min, max)
+
+Generate pseudo-random a floating-point number within a specified range.
+
+- `seed`
+- `[min=0]`: Minimum boundary.
+- `[max=1]`: Maximum boundary.
+- `[precison=2]`: Number of digits after the decimal point.
+
 ```ts
-// Generate a pseudo-random float number
 prng.randomFloat(seed: string, min?: number, max?: number1, precision?: number) => number;
 ```
 
+##### randomInt(seed, min, max)
+
+Generate pseudo-random integer number within a specified range.
+
+- `seed`
+- `min`: Minimum boundary.
+- `max`: Maximum boundary.
+
 ```ts
-// Generate a pseudo-random integer number
 prng.randomInt(seed: string, min: number, max: number) => void;
 ```
 
+##### randomHexColor(seed)
+
+Generate a pseudo-random hexadecimal color.
+
+- `seed`
+
 ```ts
-// Generate a pseudo-random hexadecimal color
 prng.randomHexColor(seed: string) => string;
 ```
 
+##### randomItem(seed0 array)
+
+Pick a pseudo-random item from a given array.
+
+- `seed`
+- `array`: Array to pick the item from.
+
 ```ts
-// Pick a pseudo-random item from an array
 prng.randomItem<T>(seed: string, array: T[]) => T | undefined;
 ```
 
+##### randomObjectProperty(seed, object)
+
+Pick a pseudo-random property value from a given object.
+
+- `seed`
+- `object`: Object to pick the property from.
+
 ```ts
-// Pick a pseudo-random property from an object
-prng.randomObjectProperty(seed: string, object: object) => unknown | undefined
+prng.randomObjectProperty<T>(seed: string, object: object) => T | undefined;
 ```
 
+##### randomIndex(seed, weights)
+
+Select a pseudo-random index from an array of weighted items.
+
+- `seed`
+- `weights`: Array of weights
+
 ```ts
-// Return a pseudo-random index from an array of weights
-prng.randomIndex(seed: string, weights?: number[]) => number;
+prng.randomIndex(seed: string, weights: number[]) => number;
 ```
 
-## PRNG Controllers
+## Controllers
+
+### BooleanController
+
+Generate pseudo-random boolean values.
 
 ```ts
 class BooleanController(seed: string, probability?: number);
 ```
 
+### SignController
+
+Generate pseudo-random sign values (-1 or 1).
+
 ```ts
 class SignController(seed: string, probability?: number);
 ```
 
+### FloatController
+
+Generate pseudo-random floating-point numbers within a specified range.
+
 ```ts
 class FloatController(seed: string, min?: number, max?: number);
 ```
 
+### IntController
+
 ```ts
 class IntController(seed: string, min: number, max: number);
 ```
 
+### HexColorController
+
+Generates pseudo-random hexadecimal color.
+
 ```ts
 class HexColorController(seed: string);
 ```
 
+### ItemController
+
+Pick a pseudo-random item from a given array.
+
 ```ts
 class ItemController<T>(seed: string, items: T[]);
 ```
 
+### ObjectPropertyController
+
+Pick a pseudo-random property value from a given object.
+
 ```ts
 class ObjectPropertyController<T>(seed: string, object: object);
 ```
 
+### WeightsController
+
+Select a pseudo-random index from an array of weighted items.
+
 ```ts
 class WeightsController<T>(seed: string, items: Array<{ weight: number; value: T }>);
 ```
 
+## Group Controllers
+
+Group Controllers manage multiple instances of individual controllers.
+
+### BooleanGroupController
+
+Manage multiple [`BooleanController`](###booleancontroller).
+
 ```ts
 class BooleanGroupController(seed: string, probability: number);
 ```
 
+### SignGroupController
+
+Manage multiple [`SignController`](###signcontroller).
+
 ```ts
 class SignGroupController(seed: string, probability: number);
 ```
 
+### FloatGroupController
+
+Manage multiple [`FloatController`](###floatcontroller).
+
 ```ts
 class FloatGroupController(seed: string, min: number, max: number);
 ```
 
+### IntGroupController
+
+Manage multiple [`IntController`](#intcontroller).
+
 ```ts
 class IntGroupController(seed: string, min: number, max: number);
 ```
 
+### HexColorGroupController
+
+Manage multiple [`HexColorController`](#hexcolorcontroller).
+
 ```ts
 class HexColorGroupController(seed: string);
 ```
 
+### ItemGroupController
+
+Manage multiple [`ItemController`](#itemcontroller).
+
 ```ts
 class ItemGroupController<T>(seed: string, items: T[]);
 ```
 
+### ObjectPropertyGroupController
+
+Manage multiple [`ObjectPropertyController`](#objectpropertycontroller).
+
 ```ts
 class ObjectPropertyGroupController<T>(seed: string, object: object);
 ```
 
+### WeightsGroupController
+
+Manage multiple [`WeightsController`](#weightscontroller).
+
 ```ts
 class WeightsGroupController<T>(seed: string, items: Array<{ weight: number; value: T }>);
 ```
 
+## Algorithms
+
+By default, the library is using `SplitMix32` algorithm for generating the pseudo-random values but it is possible to change the algorithm used by one of the following:
+
+- `jsf32`: Jenkins' Small Fast, Generator with a 32-bit state.
+- `mulberry32`: Mulberry32, Generator with a 32-bit state.
+- `sfc32`: Simple Fast Counter, Generator with a 128-bit state.
+- `splitmix32`: SplitMix32, Generator with a 32-bit state.
+- `xoshiro128ss`: xoshiro128\*\*, Generator with a 128-bit state.
+
+**Credits**: [Seeding random number generator in Javascript](https://stackoverflow.com/questions/521295/seeding-the-random-number-generator-in-javascript)
+
+```ts
+import prng, { Algorithm } from 'toosoon-prng';
+
+prng.setAlgorithm(Algorithm.sfc32);
+```
+
 ## License
 
 MIT License, see [LICENSE](https://github.com/toosoon-dev/toosoon-prng/tree/master/LICENSE) for details

package/lib/controllers.d.ts

@@ -1,14 +1,14 @@
-import type { Gui, GuiController } from 'toosoon-gui';
+import { Gui, GuiController } from 'toosoon-gui';
 export interface PRNGController<T = unknown> {
     seed: string;
     value: T;
-    addGui(gui: Gui, min?: number, max?: number, step?: number): GuiController;
+    addGUI(gui: Gui, min?: number, max?: number, step?: number): GuiController;
     getValue(): T;
     dispose(): void;
 }
 export interface PRNGGroupController<T = unknown> {
     seed: string;
-    addGui(gui: Gui, min?: number, max?: number, step?: number): Gui;
+    addGUI(gui: Gui, min?: number, max?: number, step?: number): Gui;
     createController(index: number): PRNGController<T>;
     getValueAt(index: number): T;
     dispose(): void;
@@ -18,7 +18,7 @@ declare abstract class BasePRNGController<T> implements PRNGController<T> {
     abstract value: T;
     gui: GuiController;
     constructor(seed: string);
-    abstract addGui(gui: Gui, min?: number, max?: number, step?: number): GuiController;
+    abstract addGUI(gui: Gui, min?: number, max?: number, step?: number): GuiController;
     abstract getValue(): T;
     dispose(): void;
 }
@@ -32,7 +32,7 @@ declare abstract class BasePRNGGroupController<T> implements PRNGGroupController
         step?: number;
     };
     constructor(seed: string);
-    addGui(gui: Gui, min?: number, max?: number, step?: number): Gui;
+    addGUI(gui: Gui, min?: number, max?: number, step?: number): Gui;
     abstract createController(index: number): PRNGController<T>;
     getValueAt(index: number): T;
     dispose(): void;
@@ -41,14 +41,14 @@ export declare class BooleanController extends BasePRNGController<boolean> {
     value: boolean;
     probability: number;
     constructor(seed: string, probability?: number);
-    addGui(gui: Gui): GuiController;
+    addGUI(gui: Gui): GuiController;
     getValue(): boolean;
 }
 export declare class SignController extends BasePRNGController<number> {
     value: number;
     probability: number;
     constructor(seed: string, probability?: number);
-    addGui(gui: Gui): GuiController;
+    addGUI(gui: Gui): GuiController;
     getValue(): number;
 }
 export declare class FloatController extends BasePRNGController<number> {
@@ -56,7 +56,7 @@ export declare class FloatController extends BasePRNGController<number> {
     min: number;
     max: number;
     constructor(seed: string, min?: number, max?: number);
-    addGui(gui: Gui, min: number, max: number, step?: number): GuiController;
+    addGUI(gui: Gui, min: number, max: number, step?: number): GuiController;
     getValue(): number;
 }
 export declare class IntController extends BasePRNGController<number> {
@@ -64,20 +64,20 @@ export declare class IntController extends BasePRNGController<number> {
     min: number;
     max: number;
     constructor(seed: string, min: number, max: number);
-    addGui(gui: Gui, min: number, max: number, step?: number): GuiController;
+    addGUI(gui: Gui, min: number, max: number, step?: number): GuiController;
     getValue(): number;
 }
 export declare class HexColorController extends BasePRNGController<string> {
     value: string;
     constructor(seed: string);
-    addGui(gui: Gui): GuiController;
+    addGUI(gui: Gui): GuiController;
     getValue(): string;
 }
 export declare class ItemController<T = unknown> extends BasePRNGController<T> {
     value: T;
     items: T[];
     constructor(seed: string, items: T[]);
-    addGui(gui: Gui): GuiController;
+    addGUI(gui: Gui): GuiController;
     getValue(): T;
 }
 export declare class ObjectPropertyController<T = unknown> extends BasePRNGController<T> {
@@ -88,7 +88,7 @@ export declare class ObjectPropertyController<T = unknown> extends BasePRNGContr
     constructor(seed: string, object: {
         [key: string]: T;
     });
-    addGui(gui: Gui): GuiController;
+    addGUI(gui: Gui): GuiController;
     getValue(): T;
 }
 type WeightsItems<T> = Array<{
@@ -100,7 +100,7 @@ export declare class WeightsController<T = unknown> extends BasePRNGController<T
     items: WeightsItems<T>;
     weights: number[];
     constructor(seed: string, items: WeightsItems<T>);
-    addGui(gui: Gui): GuiController;
+    addGUI(gui: Gui): GuiController;
     getValue(): T;
 }
 export declare class BooleanGroupController extends BasePRNGGroupController<boolean> {