@xtia/alea-rc 0.0.8 → 0.0.10

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.6kb 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

@@ -103,12 +103,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
+     * @returns Gaussian normal pair
      */
-    normal(mean: number, deviation: number): number;
+    normal(mean?: number, deviation?: number): [number, number];
     /**
      * Get a random integer value between `min` and `max`, inclusive.
      * @param min Minimum value, **inclusive**

package/internal/alea.js

@@ -77,10 +77,10 @@ export class Alea {
     string(length, charset) {
         if (!Number.isInteger(length) || length < 0)
             throw new RangeError("length must be a non-negative integer");
-        if (!charset || charset.length === 0)
+        const pool = [...charset];
+        if (pool.length === 0)
             throw new RangeError("charset must not be empty");
-        const chars = Array.from({ length }, () => charset[Math.floor(this.next() * charset.length)]);
-        return chars.join("");
+        return Array.from({ length }, () => this.sample(pool)).join("");
     }
     /**
      * Generate a phrase from a table and a root string
@@ -180,20 +180,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;
+        const z0 = mag * Math.cos(angle);
+        const z1 = mag * Math.sin(angle);
+        return [
+            mean + z0 * deviation,
+            mean + z1 * deviation
+        ];
     }
     /**
      * Get a random integer value between `min` and `max`, inclusive.

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/internal/util.js

@@ -1,4 +1,3 @@
-const encoder = new TextEncoder();
 export function hashSeed(seed) {
     let hash = 0;
     for (let i = 0; i < seed.length; i++) {

package/package.json

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