toosoon-prng 1.4.0 → 2.0.0

package/README.md

@@ -1,6 +1,6 @@
 # TOOSOON Pseudo-Random Number Generator (PRNG)
 
-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.
+This project provides PRNG functions for generating pseudo-random values using a seed-based approach and various algorithms. These are particularly useful for applications requiring deterministic randomization, such as procedural generation or simulations.
 
 ## Installation
 
@@ -18,8 +18,6 @@ $ npm install toosoon-prng
 
 ## Usage
 
-##### PRNG
-
 ```ts
 import prng from 'toosoon-prng';
 
@@ -27,34 +25,14 @@ prng.setSeed('seed');
 console.log(prng.randomFloat('angle', 0, Math.PI)); // Pseudo-random number in the interval [0, PI]
 ```
 
-##### PRNG Controllers
-
-```ts
-import { IntController, IntGroupController } from 'toosoon-prng';
-
-const config = {
-  count: new IntController('count', 0, Math.PI),
-  counts: new IntGroupController('counts', 0, Math.PI)
-};
-
-config.count.addGUI(gui, 0, 10);
-config.counts.addGUI(gui, 5, 10);
-
-console.log(config.count.getValue()); // Pseudo-random integer in the interval [0, 10]
-
-for (let i = 0; i < 5; i++) {
-  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.
+All PRNG functions have a `seed` parameter wich allows you to add a sub-seed string to the `PRNG` instance global `seed` in order to get different pseudo-random values 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
+console.log(prng.randomBoolean('one')); // Could be true or false
+console.log(prng.randomBoolean('two')); // Could be different from the first pseudo-random value
 ```
 
 ##### setSeed(seed)
@@ -67,14 +45,14 @@ Set the `PRNG` instance seed.
 prng.setSeed(seed: string): void;
 ```
 
-##### setAlgorithm(algorithm)
+##### setAlgorithm(algorithmName)
 
 Set the `PRNG` algorithm for generating pseudo-random values.
 
-- `algorithm`: Algorithm name.
+- `algorithmName`: Algorithm name.
 
 ```ts
-prng.setAlgorithm(algorithm: Algorithm): void;
+prng.setAlgorithm(algorithmName: AlgorithmName): void;
 ```
 
 ##### random(seed)
@@ -163,7 +141,7 @@ Pick a pseudo-random property value from a given object.
 - `object`: Object to pick the property from.
 
 ```ts
-prng.randomObjectProperty<T>(seed: string, object: object): T | undefined;
+prng.randomObjectProperty<T>(seed: string, object: Record<string, T>): T | undefined;
 ```
 
 ##### randomIndex(seed, weights)
@@ -177,138 +155,6 @@ Select a pseudo-random index from an array of weighted items.
 prng.randomIndex(seed: string, weights: number[]): number;
 ```
 
-## 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:
@@ -322,10 +168,10 @@ By default, the library is using _SplitMix32_ algorithm for generating the pseud
 ```ts
 import prng, { Algorithm } from 'toosoon-prng';
 
-// Set 'Simple Fast Counter' as PRNG instance algorithm
+// Set 'Simple Fast Counter' as the PRNG instance algorithm
 prng.setAlgorithm(Algorithm.sfc32);
 ```
 
 ## License
 
-MIT License, see [LICENSE](https://github.com/toosoon-dev/toosoon-prng/tree/master/LICENSE) for details
+MIT License, see [LICENSE](https://github.com/toosoon-dev/toosoon-prng/tree/master/LICENSE) for details.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "toosoon-prng",
-  "version": "1.4.0",
-  "description": "This project provides a `PRNG` instance and a set of `Controllers` for generating pseudo-random values using a seed-based approach and various algorithms",
+  "version": "2.0.0",
+  "description": "This project provides PRNG functions for generating pseudo-random values using a seed-based approach and various algorithms",
   "main": "./lib/index.js",
   "types": "./lib/index.d.ts",
   "scripts": {
@@ -27,10 +27,6 @@
     "url": "https://github.com/toosoon-dev/toosoon-prng/issues"
   },
   "homepage": "https://github.com/toosoon-dev/toosoon-prng#readme",
-  "dependencies": {
-    "toosoon-gui": "^1.3.0",
-    "toosoon-utils": "^1.3.0"
-  },
   "devDependencies": {
     "typescript": "^5.3.3"
   }

package/src/index.ts

@@ -1,22 +1,3 @@
-export {
-  BooleanController,
-  SignController,
-  IntController,
-  FloatController,
-  HexColorController,
-  ItemController,
-  ObjectPropertyController,
-  WeightsController,
-  BooleanGroupController,
-  SignGroupController,
-  IntGroupController,
-  FloatGroupController,
-  HexColorGroupController,
-  ItemGroupController,
-  ObjectPropertyGroupController,
-  WeightsGroupController
-} from './controllers';
-
-export { default } from './prng';
+export { default, PRNG } from './prng';
 
 export type * from './types';

package/src/prng.ts

@@ -1,36 +1,15 @@
-import { cyrb128, jsf32, mulberry32, sfc32, splitmix32, xoshiro128ss } from 'toosoon-utils/prng';
-
-import { PRNGController } from './controllers';
-import { Algorithm } from './types';
+import { cyrb128, jsf32, mulberry32, sfc32, splitmix32, xoshiro128ss } from './utils';
+import { AlgorithmName } from './types';
 
 /**
- * PRNG class
+ * Utility class for generating pseudo-random values
  *
  * @class PRNG
+ * @exports
  */
-class PRNG {
+export class PRNG {
   public seed: string = '';
-  public algorithm: Algorithm = Algorithm.splitmix32;
-  public controllers: PRNGController[] = [];
-
-  /**
-   * Add a controller to this PRNG
-   *
-   * @param {PRNGController} controller
-   */
-  public addController(controller: PRNGController): void {
-    this.controllers.push(controller);
-  }
-
-  /**
-   * Remove a controller from this PRNG
-   *
-   * @param {PRNGController} controller
-   */
-  public removeController(controller: PRNGController): void {
-    const index = this.controllers.indexOf(controller);
-    this.controllers.splice(index, 1);
-  }
+  public algorithm: (...args: number[]) => number = splitmix32;
 
   /**
    * Set this PRNG seed
@@ -38,19 +17,16 @@ class PRNG {
    * @param {string} seed
    */
   public setSeed(seed: string): void {
-    if (this.seed === seed) return;
     this.seed = seed;
-    this.controllers.forEach((controller) => controller.getValue());
   }
 
   /**
-   * Set this PRNG algorithm for generating pseudo-random values
+   * Set this PRNG algorithm
    *
-   * @param {Algorithm} algorithm Algorithm name
+   * @param {AlgorithmName} algorithmName Algorithm name
    */
-  public setAlgorithm(algorithm: Algorithm): void {
-    this.algorithm = algorithm;
-    this.controllers.forEach((controller) => controller.getValue());
+  public setAlgorithm(algorithmName: AlgorithmName): void {
+    this.algorithm = this.getAlgorithmByName(algorithmName);
   }
 
   /**
@@ -62,18 +38,7 @@ class PRNG {
    */
   public random(seed: string): number {
     const hashes = cyrb128(this.seed + seed);
-    switch (this.algorithm) {
-      case Algorithm.splitmix32:
-        return splitmix32(hashes[0]);
-      case Algorithm.jsf32:
-        return jsf32(hashes[0], hashes[1], hashes[2], hashes[3]);
-      case Algorithm.mulberry32:
-        return mulberry32(hashes[0]);
-      case Algorithm.sfc32:
-        return sfc32(hashes[0], hashes[1], hashes[2], hashes[3]);
-      case Algorithm.xoshiro128ss:
-        return xoshiro128ss(hashes[0], hashes[1], hashes[2], hashes[3]);
-    }
+    return this.algorithm(...hashes);
   }
 
   /**
@@ -152,7 +117,7 @@ class PRNG {
    * @param {object} object Object to pick the property from
    * @returns {T|undefined} Random item picked
    */
-  public randomObjectProperty<T = unknown>(seed: string, object: { [key: string]: T }): T | undefined {
+  public randomObjectProperty<T = unknown>(seed: string, object: Record<string, T>): T | undefined {
     const keys = Object.keys(object);
     const key = this.randomItem(seed, keys);
     if (key && object.hasOwnProperty(key)) {
@@ -177,14 +142,37 @@ class PRNG {
 
     if (totalWeight <= 0) console.warn('PRNG.randomIndex()', 'Weights must sum to > 0', totalWeight);
 
-    let random = this.random(seed) * totalWeight;
+    let weight = this.random(seed) * totalWeight;
     for (let i = 0; i < weights.length; i++) {
-      if (random < weights[i]) return i;
-      random -= weights[i];
+      if (weight < weights[i]) return i;
+      weight -= weights[i];
     }
 
     return 0;
   }
+
+  /**
+   * Get the PRNG algorithm function by its name
+   *
+   * @param {AlgorithmName} algorithmName Algorithm name
+   * @returns {Function} PRNG algorithm function
+   */
+  protected getAlgorithmByName(algorithmName: AlgorithmName): (...args: number[]) => number {
+    switch (algorithmName) {
+      case AlgorithmName.jsf32:
+        return jsf32;
+      case AlgorithmName.mulberry32:
+        return mulberry32;
+      case AlgorithmName.sfc32:
+        return sfc32;
+      case AlgorithmName.splitmix32:
+        return splitmix32;
+      case AlgorithmName.xoshiro128ss:
+        return xoshiro128ss;
+      default:
+        return splitmix32;
+    }
+  }
 }
 
 const prng = new PRNG();

package/src/types.ts

@@ -1,6 +1,4 @@
-export type { PRNGController, PRNGGroupController } from './controllers';
-
-export enum Algorithm {
+export enum AlgorithmName {
   jsf32 = 'jsf32',
   mulberry32 = 'mulberry32',
   sfc32 = 'sfc32',

package/src/utils.ts

@@ -0,0 +1,119 @@
+/**
+ * Produce a 128-bit hash value from a seed
+ *
+ * @param {string} seed Initial seed state
+ * @returns {[number, number, number, number]} Hash numbers
+ */
+export function cyrb128(seed: string): [number, number, number, number] {
+  let h1 = 1779033703;
+  let h2 = 3144134277;
+  let h3 = 1013904242;
+  let h4 = 2773480762;
+  for (let i = 0, k; i < seed.length; i++) {
+    k = seed.charCodeAt(i);
+    h1 = h2 ^ Math.imul(h1 ^ k, 597399067);
+    h2 = h3 ^ Math.imul(h2 ^ k, 2869860233);
+    h3 = h4 ^ Math.imul(h3 ^ k, 951274213);
+    h4 = h1 ^ Math.imul(h4 ^ k, 2716044179);
+  }
+  h1 = Math.imul(h3 ^ (h1 >>> 18), 597399067);
+  h2 = Math.imul(h4 ^ (h2 >>> 22), 2869860233);
+  h3 = Math.imul(h1 ^ (h3 >>> 17), 951274213);
+  h4 = Math.imul(h2 ^ (h4 >>> 19), 2716044179);
+  return [(h1 ^ h2 ^ h3 ^ h4) >>> 0, (h2 ^ h1) >>> 0, (h3 ^ h1) >>> 0, (h4 ^ h1) >>> 0];
+}
+
+// *********************
+// PRNG Algorithms
+// *********************
+
+/**
+ * Simple Fast Counter, Generator with a 128-bit state
+ *
+ * @param {number} a
+ * @param {number} b
+ * @param {number} c
+ * @param {number} d
+ * @returns {number} Pseudo-random number
+ */
+export function sfc32(a: number, b: number, c: number, d: number): number {
+  a >>>= 0;
+  b >>>= 0;
+  c >>>= 0;
+  d >>>= 0;
+  let t = (a + b) | 0;
+  a = b ^ (b >>> 9);
+  b = (c + (c << 3)) | 0;
+  c = (c << 21) | (c >>> 11);
+  d = (d + 1) | 0;
+  t = (t + d) | 0;
+  c = (c + t) | 0;
+  return (t >>> 0) / 4294967296;
+}
+
+/**
+ * SplitMix32, Generator with a 32-bit state
+ *
+ * @param {number} a
+ * @returns {number} Pseudo-random number
+ */
+export function splitmix32(a: number): number {
+  a |= 0;
+  a = (a + 0x9e3779b9) | 0;
+  var t = a ^ (a >>> 16);
+  t = Math.imul(t, 0x21f0aaad);
+  t = t ^ (t >>> 15);
+  t = Math.imul(t, 0x735a2d97);
+  return ((t = t ^ (t >>> 15)) >>> 0) / 4294967296;
+}
+
+/**
+ * Mulberry32, Generator with a 32-bit state
+ *
+ * @param {number} a
+ * @returns {number} Pseudo-random number
+ */
+export function mulberry32(a: number): number {
+  let t = (a += 0x6d2b79f5);
+  t = Math.imul(t ^ (t >>> 15), t | 1);
+  t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+  return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+}
+
+/**
+ * Jenkins' Small Fast, Generator with a 32-bit state
+ *
+ * @param {number} a
+ * @returns {number} Pseudo-random number
+ */
+export function jsf32(a: number, b: number, c: number, d: number): number {
+  a |= 0;
+  b |= 0;
+  c |= 0;
+  d |= 0;
+  let t = (a - ((b << 27) | (b >>> 5))) | 0;
+  a = b ^ ((c << 17) | (c >>> 15));
+  b = (c + d) | 0;
+  c = (d + t) | 0;
+  d = (a + t) | 0;
+  return (d >>> 0) / 4294967296;
+}
+
+/**
+ * xoshiro128**, Generator with a 128-bit state
+ *
+ * @param {number} a
+ * @returns {number} Pseudo-random number
+ */
+export function xoshiro128ss(a: number, b: number, c: number, d: number): number {
+  let t = b << 9;
+  let r = a * 5;
+  r = ((r << 7) | (r >>> 25)) * 9;
+  c ^= a;
+  d ^= b;
+  b ^= c;
+  a ^= d;
+  c ^= t;
+  d = (d << 11) | (d >>> 21);
+  return (r >>> 0) / 4294967296;
+}

package/.prettierrc

@@ -1,7 +0,0 @@
-{
-  "semi": true,
-  "singleQuote": true,
-  "printWidth": 120,
-  "trailingComma": "none",
-  "endOfLine": "auto"
-}

package/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2024 TOOSOON
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.