@xtia/alea-rc 0.0.9 → 0.0.11

package/README.md

@@ -7,8 +7,8 @@ Alea is a utility wrapper for turning random numbers into useful values. Give it
 * Fully typed
 * Crypto-safe and seeded algorithms out-of-the-box
 * No dependencies
-* ~2.3kb minified core (1.04kb gzipped)
-* Ranged int, array shuffling, dice roll, weighted sampling, phrase generation, UUID, bytes and many more
+* ~2.4kb minified core
+* Ranged int, array shuffling, dice roll, weighted sampling, recursive template phrase generation, UUID, bytes and many more
 
 ## Brief:
 
@@ -21,31 +21,38 @@ import { alea, cryptoAlea } from "@xtia/alea";
 const damage = alea.roll(2, 6); // 2d6
 const duration = alea.between(1000, 1500);
 const loot = alea.chance(0.125) ? "epic" : "common";
-const id = alea.string(5);
+const id = alea.string(5, "abcdef0123456789");
 const npcName = alea.sample(["Alice", "Bob", "Charlie"]);
 
 // secure source (driven by environment's crypto)
 const key = cryptoAlea.string(16);
 ```
-
-## Custom sources
+# Custom sources
 
 Use any provider as RNG source:
 
 ```ts
 import {
-    createAleaFromFunc,
-    createAleaFromSeed,
-    createAleaFromByteSource,
+    aleaFromFunc,
+    aleaFromSeed,
+    aleaFromByteSource,
 } from "@xtia/alea";
 
-const deterministic = createAleaFromSeed("abc123");
-const xkcdRng = createAleaFromFunc(() => 4/6); // https://xkcd.com/221/
-const secure = createAleaFromByteSource(
+// deterministic, with seed (uses Mulberry32 PRNG):
+const seededRng = aleaFromSeed("abc123");
+
+// custom source of randomness:
+const xkcdRng = aleaFromFunc(() => 4/6); // https://xkcd.com/221/
+
+// from random byte providers:
+const secureRng = aleaFromByteSource(
     buf => hardwareRNG.fillRandomBytes(buf)
 );
+```
+
+Or use a provided PRNG algorithm:
 
-// or use provided PRNG algorithms:
+```ts
 import {
     mulberry32,
     sfc32,
@@ -57,5 +64,5 @@ const fast = mulberry32("my-seed");
 const varied = sfc32(1, 2, 3, 4);
 const strong = xoshiro128pp(5, 6, 7, 8);
 
-const reproducibleId = varied.string(5);
+const reproducibleRoll = varied.roll(3, 6);
 ```

package/entry/browser.js

@@ -1,3 +1,3 @@
-import { createAleaFromByteSource } from "../internal/factories.js";
+import { aleaFromByteSource } from "../internal/factories.js";
 export * from "./common.js";
-export const cryptoAlea = createAleaFromByteSource((arr) => globalThis.crypto.getRandomValues(arr));
+export const cryptoAlea = aleaFromByteSource((arr) => globalThis.crypto.getRandomValues(arr));

package/entry/common.d.ts

@@ -1,5 +1,5 @@
 import { Alea } from "../internal/alea.js";
 export type { Alea };
-export { createAleaFromByteSource, createAleaFromSeed, createAleaFromFunc, } from "../internal/factories.js";
+export { aleaFromByteSource, aleaFromSeed, aleaFromFunc, } from "../internal/factories.js";
 export { charsets } from "../internal/charsets.js";
 export { alea } from "../internal/mathalea.js";

package/entry/common.js

@@ -1,3 +1,3 @@
-export { createAleaFromByteSource, createAleaFromSeed, createAleaFromFunc, } from "../internal/factories.js";
+export { aleaFromByteSource, aleaFromSeed, aleaFromFunc, } from "../internal/factories.js";
 export { charsets } from "../internal/charsets.js";
 export { alea } from "../internal/mathalea.js";

package/entry/node.js

@@ -1,6 +1,6 @@
-import { createAleaFromByteSource } from "../internal/factories.js";
+import { aleaFromByteSource } from "../internal/factories.js";
 import { randomBytes } from 'node:crypto';
 export * from "./common.js";
-export const cryptoAlea = createAleaFromByteSource(arr => {
+export const cryptoAlea = aleaFromByteSource(arr => {
     randomBytes(arr.length).copy(arr);
 });

package/internal/alea.d.ts

@@ -9,12 +9,6 @@ export declare class Alea {
      * @param next Source RNG - a function that returns a value >= 0 and < 1
      */
     constructor(next: RandomFunction);
-    /**
-     * Generate a series of normalised random values
-     * @param count
-     * @returns Random values
-     */
-    batch(count: number): number[];
     /**
      * Pick a random item from an array
      * @param items
@@ -103,26 +97,12 @@ export declare class Alea {
      */
     round(n: number): number;
     /**
-     * Get a random gaussian normal value
+     * Get a random normal pair using Box-Muller transform
      * @param mean
      * @param deviation
-     * @returns Random gaussian normal
-     */
-    normal(mean: number, deviation: number): number;
-    /**
-     * Get a random integer value between `min` and `max`, inclusive.
-     * @param min Minimum value, **inclusive**
-     * @param max Maximum value, **inclusive**
-     * @returns Random int value
-     */
-    int(min: number, max: number): number;
-    /**
-     * Roll dice
-     * @param count Number of dice to roll (default 1)
-     * @param sides Number of sides per die (default 6)
-     * @returns Dice result
+     * @returns Gaussian normal pair
      */
-    roll(count?: number, sides?: number): number;
+    normal(mean?: number, deviation?: number): [number, number];
     /**
      * Generate a random UUID (version 4)
      *

package/internal/alea.js

@@ -5,17 +5,6 @@ export class Alea {
     constructor(next) {
         this.next = next;
     }
-    /**
-     * Generate a series of normalised random values
-     * @param count
-     * @returns Random values
-     */
-    batch(count) {
-        if (!Number.isInteger(count) || count < 0) {
-            throw new RangeError("count must be a non-negative integer");
-        }
-        return Array.from({ length: count }, () => this.next());
-    }
     sample(items, count) {
         if (count === undefined) {
             if (items.length === 0)
@@ -80,8 +69,7 @@ export class Alea {
         const pool = [...charset];
         if (pool.length === 0)
             throw new RangeError("charset must not be empty");
-        const chars = Array.from({ length }, () => this.sample(pool));
-        return chars.join("");
+        return Array.from({ length }, () => this.sample(pool)).join("");
     }
     /**
      * Generate a phrase from a table and a root string
@@ -158,10 +146,10 @@ export class Alea {
         const words = Math.floor(len / 4);
         const view = new DataView(byteArray.buffer, byteArray.byteOffset, byteArray.byteLength);
         for (let i = 0; i < words; i++) {
-            view.setUint32(i * 4, this.int(0, 0xffffffff));
+            view.setUint32(i * 4, this.between(0, 0x100000000) >>> 0);
         }
         for (let i = words * 4; i < len; i++) {
-            byteArray[i] = this.int(0, 255);
+            byteArray[i] = this.between(0, 256) | 0;
         }
         return result;
     }
@@ -181,42 +169,24 @@ export class Alea {
         return this.chance(n - floor) ? floor + 1 : floor;
     }
     /**
-     * Get a random gaussian normal value
+     * Get a random normal pair using Box-Muller transform
      * @param mean
      * @param deviation
-     * @returns Random gaussian normal
+     * @returns Gaussian normal pair
      */
-    normal(mean, deviation) {
+    normal(mean = 0, deviation = 1) {
         let u1 = this.next();
-        while (u1 <= Number.EPSILON) {
+        while (u1 <= Number.EPSILON)
             u1 = this.next();
-        }
         const u2 = this.next();
         const mag = Math.sqrt(-2 * Math.log(u1));
         const angle = 2 * Math.PI * u2;
-        return mean + mag * Math.cos(angle) * deviation;
-    }
-    /**
-     * Get a random integer value between `min` and `max`, inclusive.
-     * @param min Minimum value, **inclusive**
-     * @param max Maximum value, **inclusive**
-     * @returns Random int value
-     */
-    int(min, max) {
-        return Math.floor(this.between(min, max + 1));
-    }
-    /**
-     * Roll dice
-     * @param count Number of dice to roll (default 1)
-     * @param sides Number of sides per die (default 6)
-     * @returns Dice result
-     */
-    roll(count = 1, sides = 6) {
-        let total = 0;
-        for (let i = 0; i < count; i++) {
-            total += this.int(1, sides);
-        }
-        return total;
+        const z0 = mag * Math.cos(angle);
+        const z1 = mag * Math.sin(angle);
+        return [
+            mean + z0 * deviation,
+            mean + z1 * deviation
+        ];
     }
     /**
      * Generate a random UUID (version 4)

package/internal/factories.d.ts

@@ -10,7 +10,7 @@ import { Alea } from "./alea.js";
  * @param applyBytes A callback that fills a Uint8Array with random bytes
  * @returns A byte generator-sourced Alea instance
  */
-export declare function createAleaFromByteSource(applyBytes: (buffer: Uint8Array) => void): Alea;
+export declare function aleaFromByteSource(applyBytes: (buffer: Uint8Array) => void): Alea;
 /**
  * Create an Alea instance using a Mulberry32 source
  *
@@ -20,7 +20,7 @@ export declare function createAleaFromByteSource(applyBytes: (buffer: Uint8Array
  * @param seed
  * @returns Alea instance using Mulberry32
  */
-export declare function createAleaFromSeed(seed: number | string): Alea;
+export declare function aleaFromSeed(seed: number | string): Alea;
 /**
  * Create an Alea instance using a custom function as an RNG source
  * @example
@@ -31,4 +31,4 @@ export declare function createAleaFromSeed(seed: number | string): Alea;
  * @param fn Source RNG; a function that returns a value >= 0 and < 1
  * @returns Custom function-sourced Alea instance
  */
-export declare function createAleaFromFunc(fn: () => number): Alea;
+export declare function aleaFromFunc(fn: () => number): Alea;

package/internal/factories.js

@@ -11,7 +11,7 @@ import { Alea } from "./alea.js";
  * @param applyBytes A callback that fills a Uint8Array with random bytes
  * @returns A byte generator-sourced Alea instance
  */
-export function createAleaFromByteSource(applyBytes) {
+export function aleaFromByteSource(applyBytes) {
     const buffer = new ArrayBuffer(4);
     const view = new Uint8Array(buffer);
     const uint32View = new Uint32Array(buffer);
@@ -29,7 +29,7 @@ export function createAleaFromByteSource(applyBytes) {
  * @param seed
  * @returns Alea instance using Mulberry32
  */
-export function createAleaFromSeed(seed) {
+export function aleaFromSeed(seed) {
     return mulberry32(seed);
 }
 /**
@@ -42,7 +42,7 @@ export function createAleaFromSeed(seed) {
  * @param fn Source RNG; a function that returns a value >= 0 and < 1
  * @returns Custom function-sourced Alea instance
  */
-export function createAleaFromFunc(fn) {
+export function aleaFromFunc(fn) {
     return new Alea(fn);
 }
 // const xkcdAlea = createAleaFromFunc(() => 4/6); // decided by die roll

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xtia/alea-rc",
-  "version": "0.0.9",
+  "version": "0.0.11",
   "description": "RNG utilities",
   "repository": {
     "url": "https://github.com/tiadrop/alea",