@xtia/alea-rc 0.0.10 → 0.0.12

package/README.md

@@ -6,11 +6,10 @@ 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
+* Expressive: code with intent
 * No dependencies
-* ~2.6kb minified core
-* Ranged int, array shuffling, dice roll, weighted sampling, recursive template phrase generation, UUID, bytes and many more
-
-## Brief:
+* ~2.4kb minified core
+* Array shuffling, weighted sampling, recursive template phrase generation, UUID, bytes and many more
 
 `npm i @xtia/alea` (pending release; use `@xtia/alea-rc` to preview)
 
@@ -18,14 +17,13 @@ Alea is a utility wrapper for turning random numbers into useful values. Give it
 import { alea, cryptoAlea } from "@xtia/alea";
 
 // generate values (driven by Math.random())
-const damage = alea.roll(2, 6); // 2d6
-const duration = alea.between(1000, 1500);
+const damage = alea.between(50, 150);
 const loot = alea.chance(0.125) ? "epic" : "common";
 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);
+// same API, secure source (driven by environment's crypto)
+const id = cryptoAlea.string(16, alphanumeric);
 ```
 # Custom sources
 
@@ -64,5 +62,5 @@ const fast = mulberry32("my-seed");
 const varied = sfc32(1, 2, 3, 4);
 const strong = xoshiro128pp(5, 6, 7, 8);
 
-const reproducibleRoll = varied.roll(3, 6);
+const reproducibleId = varied.string(12, hexadecimal);
 ```

package/entry/other.js

@@ -4,5 +4,5 @@ export * from "./common.js";
  * An Alea instance that uses the runtime environment's `crypto` provider as a source
  */
 export const cryptoAlea = new Alea(() => {
-    throw new Error("cryptoAlea is not available in this environment. Consider using createAleaFromByteSource() with your environment's crypto API.");
+    throw new Error("cryptoAlea is not available in this environment. Consider using aleaFromByteSource() with your environment's crypto API.");
 });

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
@@ -62,7 +56,7 @@ export declare class Alea {
      *   greeting: ["hello", "hi", "{int} blessings"],
      *   addressee: ["world", "planet", "{adjective} @xtia user"],
      *   adjective: ["beautiful", "wonderful"],
-     *   int: () => alea.int(0, 9).toString(),
+     *   int: () => Math.floor(alea.between(3, 9)).toString(),
      * }, "{greeting}, {addressee}!")
      * ```
      * @param table
@@ -109,20 +103,6 @@ export declare class Alea {
      * @returns Gaussian normal pair
      */
     normal(mean?: number, deviation?: number): [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
-     */
-    roll(count?: number, sides?: 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)
@@ -90,7 +79,7 @@ export class Alea {
      *   greeting: ["hello", "hi", "{int} blessings"],
      *   addressee: ["world", "planet", "{adjective} @xtia user"],
      *   adjective: ["beautiful", "wonderful"],
-     *   int: () => alea.int(0, 9).toString(),
+     *   int: () => Math.floor(alea.between(3, 9)).toString(),
      * }, "{greeting}, {addressee}!")
      * ```
      * @param table
@@ -157,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;
     }
@@ -199,28 +188,6 @@ export class Alea {
             mean + z1 * 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;
-    }
     /**
      * Generate a random UUID (version 4)
      *

package/internal/factories.d.ts

@@ -4,8 +4,8 @@ import { Alea } from "./alea.js";
  * as a RNG source
  * @example
  * ```ts
- * const cryptoAlea = createAleaFromByteSource(crypto.getRandomValues);
- * const hwAlea = createAleaFromByteSource(hardwareRng.fillBytes);
+ * const cryptoAlea = aleaFromByteSource(crypto.getRandomValues);
+ * const hwAlea = aleaFromByteSource(hardwareRng.fillBytes);
  * ```
  * @param applyBytes A callback that fills a Uint8Array with random bytes
  * @returns A byte generator-sourced Alea instance
@@ -25,8 +25,8 @@ export declare function aleaFromSeed(seed: number | string): Alea;
  * Create an Alea instance using a custom function as an RNG source
  * @example
  * ```ts
- * const basicAlea = createAleaFromFunc(Math.random);
- * const lcgAlea = createAleaFromFunc(customRng.next);
+ * const basicAlea = aleaFromFunc(Math.random);
+ * const lcgAlea = aleaFromFunc(customRng.next);
  * ```
  * @param fn Source RNG; a function that returns a value >= 0 and < 1
  * @returns Custom function-sourced Alea instance

package/internal/factories.js

@@ -5,8 +5,8 @@ import { Alea } from "./alea.js";
  * as a RNG source
  * @example
  * ```ts
- * const cryptoAlea = createAleaFromByteSource(crypto.getRandomValues);
- * const hwAlea = createAleaFromByteSource(hardwareRng.fillBytes);
+ * const cryptoAlea = aleaFromByteSource(crypto.getRandomValues);
+ * const hwAlea = aleaFromByteSource(hardwareRng.fillBytes);
  * ```
  * @param applyBytes A callback that fills a Uint8Array with random bytes
  * @returns A byte generator-sourced Alea instance
@@ -36,8 +36,8 @@ export function aleaFromSeed(seed) {
  * Create an Alea instance using a custom function as an RNG source
  * @example
  * ```ts
- * const basicAlea = createAleaFromFunc(Math.random);
- * const lcgAlea = createAleaFromFunc(customRng.next);
+ * const basicAlea = aleaFromFunc(Math.random);
+ * const lcgAlea = aleaFromFunc(customRng.next);
  * ```
  * @param fn Source RNG; a function that returns a value >= 0 and < 1
  * @returns Custom function-sourced Alea instance
@@ -45,4 +45,4 @@ export function aleaFromSeed(seed) {
 export function aleaFromFunc(fn) {
     return new Alea(fn);
 }
-// const xkcdAlea = createAleaFromFunc(() => 4/6); // decided by die roll
+// const xkcdAlea = aleaFromFunc(() => 4/6); // decided by die roll

package/package.json

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