toosoon-prng 1.1.0 → 1.2.1

package/src/prng.ts

@@ -1,80 +1,163 @@
 import { PRNGController } from './controllers';
-import { cyrb128, jsf32, mulberry32, sfc32, xoshiro128ss } from './utils';
+import { cyrb128, jsf32, mulberry32, sfc32, splitmix32, xoshiro128ss } from './utils';
 
-export enum PRNGMethod {
+export enum Algorithm {
   jsf32 = 'jsf32',
   mulberry32 = 'mulberry32',
   sfc32 = 'sfc32',
+  splitmix32 = 'splitmix32', // Default
   xoshiro128ss = 'xoshiro128**'
 }
 
+/**
+ * PRNG class
+ *
+ * @class PRNG
+ */
 class PRNG {
   public seed: string = '';
-  public method: PRNGMethod = PRNGMethod.sfc32;
+  public algorithm: Algorithm = Algorithm.splitmix32;
   public controllers: PRNGController[] = [];
 
-  constructor(seed: string = '') {
-    this.setSeed(seed);
-  }
-
-  public addController(controller: PRNGController) {
+  /**
+   * Add a controller to this PRNG
+   *
+   * @param {PRNGController} controller
+   */
+  public addController(controller: PRNGController): void {
     this.controllers.push(controller);
   }
 
-  public removeController(controller: PRNGController) {
+  /**
+   * 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 setSeed(seed: string) {
+  /**
+   * Set this PRNG seed
+   *
+   * @param {string} seed
+   */
+  public setSeed(seed: string): void {
     if (this.seed === seed) return;
     this.seed = seed;
     this.controllers.forEach((controller) => controller.getValue());
   }
 
-  public setMethod(method: PRNGMethod) {
-    this.method = method;
+  /**
+   * Set this PRNG algorithm for generating pseudo-random values
+   *
+   * @param {Algorithm} algorithm Algorithm name
+   */
+  public setAlgorithm(algorithm: Algorithm): void {
+    this.algorithm = algorithm;
+    this.controllers.forEach((controller) => controller.getValue());
   }
 
+  /**
+   * Generate a pseudo-random number in the interval [0, 1]
+   * PRNG equivalent of `Math.random()`
+   *
+   * @param {string} seed
+   * @returns {number}
+   */
   public random(seed: string): number {
     const hashes = cyrb128(this.seed + seed);
-    switch (this.method) {
-      case PRNGMethod.jsf32:
+    switch (this.algorithm) {
+      case Algorithm.splitmix32:
+        return splitmix32(hashes[0]);
+      case Algorithm.jsf32:
         return jsf32(hashes[0], hashes[1], hashes[2], hashes[3]);
-      case PRNGMethod.mulberry32:
+      case Algorithm.mulberry32:
         return mulberry32(hashes[0]);
-      case PRNGMethod.sfc32:
+      case Algorithm.sfc32:
         return sfc32(hashes[0], hashes[1], hashes[2], hashes[3]);
-      case PRNGMethod.xoshiro128ss:
+      case Algorithm.xoshiro128ss:
         return xoshiro128ss(hashes[0], hashes[1], hashes[2], hashes[3]);
     }
   }
 
+  /**
+   * Generate a pseudo-random boolean (true or false)
+   *
+   * @param {string} seed
+   * @param {number} [probability=0.5] Probability to get `true`
+   * @returns {boolean} Either `true` or `false`
+   */
   public randomBoolean(seed: string, probability: number = 0.5): boolean {
     return this.random(seed) < probability;
   }
 
+  /**
+   * Generate a pseudo-random sign (1 or -1)
+   *
+   * @param {string} seed
+   * @param {number} [probability=0.5] Probability to get 1
+   * @returns {number} Either 1 or -1
+   */
   public randomSign(seed: string, probability: number = 0.5): number {
     return this.randomBoolean(seed, probability) ? 1 : -1;
   }
 
+  /**
+   * Generate a pseudo-random floating-point number within a specified range
+   *
+   * @param {string} seed
+   * @param {number} [min=0]       Minimum boundary
+   * @param {number} [max=1]       Maximum boundary
+   * @param {number} [precision=2] Number of digits after the decimal point
+   * @returns {number} Generated float
+   */
   public randomFloat(seed: string, min: number = 0, max: number = 1, precision: number = 2): number {
     return parseFloat(Math.min(min + this.random(seed) * (max - min), max).toFixed(precision));
   }
 
-  public randomInt(seed: string, min: number, max: number) {
+  /**
+   * Generate a pseudo-random integer number within a specified range
+   *
+   * @param {string} seed
+   * @param {number} min Minimum boundary
+   * @param {number} max Maximum boundary
+   * @returns {number} Generated integer
+   */
+  public randomInt(seed: string, min: number, max: number): number {
     return Math.floor(this.random(seed) * (max - min + 1) + min);
   }
 
+  /**
+   * Generate a pseudo-random hexadecimal color
+   *
+   * @param {string} seed
+   * @returns {string} Generated hexadecimal color
+   */
   public randomHexColor(seed: string): string {
     return '#' + ('00000' + ((this.random(seed) * (1 << 24)) | 0).toString(16)).slice(-6);
   }
 
-  public randomItem<T = unknown>(seed: string, array: T[] = []): T | undefined {
+  /**
+   * Pick a pseudo-random item from a given array
+   *
+   * @param {string} seed
+   * @param {T[]} array Array to pick the item from
+   * @returns {T|undefined} Random item picked
+   */
+  public randomItem<T = unknown>(seed: string, array: T[]): T | undefined {
     if (array.length === 0) return undefined;
     return array[this.randomInt(seed, 0, array.length - 1)];
   }
 
+  /**
+   * Pick a pseudo-random property value from a given object
+   *
+   * @param {string} seed
+   * @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 {
     const keys = Object.keys(object);
     const key = this.randomItem(seed, keys);
@@ -83,7 +166,14 @@ class PRNG {
     }
   }
 
-  public randomIndex(seed: string, weights: number[] = []): number {
+  /**
+   * Select a pseudo-random index from an array of weighted items
+   *
+   * @param {string} seed
+   * @param {number[]} weights Array of weights
+   * @returns {number} Random index based on weights
+   */
+  public randomIndex(seed: string, weights: number[]): number {
     if (weights.length === 0) return -1;
 
     let totalWeight = 0;

package/src/utils.ts

@@ -26,9 +26,9 @@ export function cyrb128(seed: string): number[] {
   return [(h1 ^ h2 ^ h3 ^ h4) >>> 0, (h2 ^ h1) >>> 0, (h3 ^ h1) >>> 0, (h4 ^ h1) >>> 0];
 }
 
-// ******************************************
-// Pseudo-random Number Generator
-// ******************************************
+// *********************
+// Algorithms
+// *********************
 
 /**
  * Simple Fast Counter, Generator with a 128-bit state
@@ -37,7 +37,7 @@ export function cyrb128(seed: string): number[] {
  * @param {number} b
  * @param {number} c
  * @param {number} d
- * @return {Function}
+ * @return {number}
  */
 export function sfc32(a: number, b: number, c: number, d: number): number {
   a >>>= 0;
@@ -54,11 +54,27 @@ export function sfc32(a: number, b: number, c: number, d: number): number {
   return (t >>> 0) / 4294967296;
 }
 
+/**
+ * SplitMix32, Generator with a 32-bit state
+ *
+ * @param {number} a
+ * @returns {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
- * @return {Function}
+ * @return {number}
  */
 export function mulberry32(a: number): number {
   let t = (a += 0x6d2b79f5);
@@ -71,7 +87,7 @@ export function mulberry32(a: number): number {
  * Jenkins' Small Fast, Generator with a 32-bit state
  *
  * @param {number} a
- * @return {Function}
+ * @returns {number}
  */
 export function jsf32(a: number, b: number, c: number, d: number): number {
   a |= 0;
@@ -90,7 +106,7 @@ export function jsf32(a: number, b: number, c: number, d: number): number {
  * xoshiro128**, Generator with a 128-bit state
  *
  * @param {number} a
- * @return {Function}
+ * @returns {number}
  */
 export function xoshiro128ss(a: number, b: number, c: number, d: number): number {
   let t = b << 9;

package/tsconfig.json

@@ -5,7 +5,8 @@
     "baseUrl": ".",
     "outDir": "lib",
     "target": "ES5",
-    "module": "NodeNext",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
     "lib": ["DOM", "ESNext"],
     "allowJs": true,
     "allowSyntheticDefaultImports": true,