@xtia/alea-rc 0.0.1

package/README.md

@@ -0,0 +1,61 @@
+# Alea
+
+### Tame the Chaos
+
+Alea is a utility wrapper for turning random numbers into useful values. Give it any source of randomness, get a toolkit for dice, samples, strings, and more.
+
+* Fully typed
+* Crypto-safe and seeded algorithms out-of-the-box
+* No dependencies
+* ~2.7kb minified
+* Ranged int, array shuffling, dice roll, weighted sampling, phrase generation, uuid, bytes and many more
+
+## Brief:
+
+`npm i @xtia/alea` (pending release; use `@xtia/alea-rc` to preview)
+
+```ts
+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 loot = alea.chance(0.125) ? "epic" : "common";
+const id = alea.string(5);
+const npcName = alea.sample(["Alice", "Bob", "Charlie"]);
+
+// secure source (driven by environment's crypto)
+const key = cryptoAlea.string(16);
+```
+
+## Custom sources
+
+Use any provider as RNG source:
+
+```ts
+import {
+    createAleaFromFunc,
+    createAleaFromSeed,
+    createAleaFromByteSource,
+} from "@xtia/alea";
+
+const deterministic = createAleaFromSeed("abc123");
+const xkcdRng = createAleaFromFunc(() => 4/6); // https://xkcd.com/221/
+const secure = createAleaFromByteSource(
+    buf => hardwareRNG.fillRandomBytes(buf)
+);
+
+// or use provided PRNG algorithms:
+import {
+    mulberry32,
+    sfc32,
+    xoshiro128pp,
+} from "@xtia/alea/prng";
+
+// each returns an Alea instance:
+const fast = mulberry32("my-seed");
+const varied = sfc32(1, 2, 3, 4);
+const strong = xoshiro128pp(5, 6, 7, 8);
+
+const reproducibleId = varied.string(5);
+```

package/browser.d.ts

@@ -0,0 +1,2 @@
+export * from "./common";
+export declare const cryptoAlea: import("./common").Alea;

package/browser.js

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

package/common.d.ts

@@ -0,0 +1,5 @@
+import { Alea } from "./internal/alea";
+export type { Alea };
+export { createAleaFromByteSource, createAleaFromSeed, createAleaFromFunc, } from "./internal/factories";
+export { charsets } from "./internal/util";
+export declare const alea: Alea;

package/common.js

@@ -0,0 +1,4 @@
+import { Alea } from "./internal/alea";
+export { createAleaFromByteSource, createAleaFromSeed, createAleaFromFunc, } from "./internal/factories";
+export { charsets } from "./internal/util";
+export const alea = new Alea(Math.random);

package/internal/alea.d.ts

@@ -0,0 +1,130 @@
+type RandomFunction = () => number;
+type PhraseFunc = (parse: (template: string) => string) => string;
+export declare class Alea {
+    /**
+     * Generate a float between 0 and 1 (exclusive)
+     */
+    readonly next: RandomFunction;
+    /**
+     * @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
+     * @returns Random item from an array
+     */
+    sample<T>(items: ArrayLike<T>): T;
+    /**
+     * Pick a number of unique random items from an array
+     * @param items
+     * @param count
+     * @returns Random items from an array
+     */
+    sample<T>(items: ArrayLike<T>, count: number): T[];
+    /**
+     * Get a boolean value with a (`probability` in 1) chance of being `true`
+     * @param probability
+     * @returns Random boolean
+     */
+    chance(probability: number): boolean;
+    /**
+     * Get a shuffled copy of an array
+     * @param items
+     * @returns Shuffled copy of an array
+     */
+    shuffle<T>(items: ArrayLike<T>): T[];
+    /**
+     * Get a value between `min` and `max`
+     * @param min Minimum value, *inclusive*
+     * @param max Maximum value, *exclusive*
+     * @returns Random value in range
+     */
+    between(min: number, max: number): number;
+    /**
+     * Generate a random string, drawing a given character set
+     * @param length
+     * @param charset
+     * @returns Generated string
+     */
+    string(length: number, charset?: string): string;
+    /**
+     * Generates a phrase from a table and a root string
+     * @example
+     * ```ts
+     * const message = alea.phrase({
+     *   greeting: ["hello", "hi", "{int} blessings"],
+     *   addressee: ["world", "planet", "{adjective} @xtia user"],
+     *   adjective: ["beautiful", "wonderful"],
+     *   int: () => alea.int(0, 9).toString(),
+     * }, "{greeting}, {addressee}!")
+     * ```
+     * @param table
+     * @param root
+     * @returns Generated phrase
+     */
+    phrase(table: Record<string, ArrayLike<string> | string | PhraseFunc>, root: string): string;
+    /**
+     * Create a factory to pick random items from a biased list
+     * @param table Candidate table, as an array of `[value, weight]` tuples
+     * @returns Random item factory
+     */
+    createWeightedSampler<T>(table: [value: T, weight: number][]): {
+        sample: () => T;
+    };
+    /**
+     * Generate a sequence of bytes
+     * @param count
+     * @returns Random byte array
+     */
+    bytes(count: number): Uint8Array<ArrayBuffer>;
+    /**
+     * Round a value up or down, according to probability defined by its non-integral part
+     * @example
+     * ```ts
+     * const rawDamage = weapon.damage / armour.protection;
+     * hp -= alea.round(rawDamage);
+     * // HP remains integer while law of averages applies fractional damage
+     * ```
+     * @param n
+     * @returns Randomly rounded value
+     */
+    round(n: number): number;
+    /**
+     * Get a random gaussian normal value
+     * @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
+     */
+    roll(count?: number, sides?: number): number;
+    /**
+     * Generate a random UUID (version 4)
+     *
+     * **Security note**: output is only as cryptographically secure as
+     * an instance's PRNG source, which, by default, is not.
+     * @see {@link Alea.crypto}
+     * @returns Random UUID string
+     */
+    uuid(): string;
+}
+export {};

package/internal/alea.js

@@ -0,0 +1,232 @@
+import { charsets } from "./util";
+export class Alea {
+    /**
+     * @param next Source RNG - a function that returns a value >= 0 and < 1
+     */
+    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)
+                throw new RangeError("Empty sample source");
+            return items[Math.floor(this.next() * items.length)];
+        }
+        if (!Number.isInteger(count) || count < 0) {
+            throw new RangeError("count must be a non-negative integer");
+        }
+        if (count > items.length) {
+            throw new RangeError(`Cannot sample ${count} items from array of length ${items.length}`);
+        }
+        const result = Array.from({ length: count }, (_, index) => items[index]);
+        for (let i = count; i < items.length; i++) {
+            const replaceIndex = Math.floor(this.next() * (i + 1));
+            if (replaceIndex < count) {
+                result[replaceIndex] = items[i];
+            }
+        }
+        return result;
+    }
+    /**
+     * Get a boolean value with a (`probability` in 1) chance of being `true`
+     * @param probability
+     * @returns Random boolean
+     */
+    chance(probability) {
+        return this.next() < probability;
+    }
+    /**
+     * Get a shuffled copy of an array
+     * @param items
+     * @returns Shuffled copy of an array
+     */
+    shuffle(items) {
+        const shuffled = Array.from(items);
+        for (let i = shuffled.length - 1; i > 0; i--) {
+            const j = Math.floor(this.next() * (i + 1));
+            [shuffled[i], shuffled[j]] = [shuffled[j], shuffled[i]];
+        }
+        return shuffled;
+    }
+    /**
+     * Get a value between `min` and `max`
+     * @param min Minimum value, *inclusive*
+     * @param max Maximum value, *exclusive*
+     * @returns Random value in range
+     */
+    between(min, max) {
+        const range = max - min;
+        return min + range * this.next();
+    }
+    /**
+     * Generate a random string, drawing a given character set
+     * @param length
+     * @param charset
+     * @returns Generated string
+     */
+    string(length, charset = charsets.alphanumericMixedCase) {
+        if (!Number.isInteger(length) || length < 0)
+            throw new RangeError("length must be a non-negative integer");
+        if (!charset || charset.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('');
+    }
+    /**
+     * Generates a phrase from a table and a root string
+     * @example
+     * ```ts
+     * const message = alea.phrase({
+     *   greeting: ["hello", "hi", "{int} blessings"],
+     *   addressee: ["world", "planet", "{adjective} @xtia user"],
+     *   adjective: ["beautiful", "wonderful"],
+     *   int: () => alea.int(0, 9).toString(),
+     * }, "{greeting}, {addressee}!")
+     * ```
+     * @param table
+     * @param root
+     * @returns Generated phrase
+     */
+    phrase(table, root) {
+        return root.replace(/\{([^}]+)\}/g, ((_, key) => {
+            if (table[key] === undefined)
+                return `{${key}}`;
+            if (typeof table[key] == "function") {
+                return table[key](template => this.phrase(table, template));
+            }
+            const source = table[key];
+            if (typeof source == "string")
+                return this.phrase(table, source);
+            return this.phrase(table, this.sample(source));
+        }));
+    }
+    /**
+     * Create a factory to pick random items from a biased list
+     * @param table Candidate table, as an array of `[value, weight]` tuples
+     * @returns Random item factory
+     */
+    createWeightedSampler(table) {
+        const filtered = table.filter(v => Number.isFinite(v[1]) && v[1] > 0);
+        if (filtered.length === 0) {
+            throw new Error("Weighted source has no viable candidates");
+        }
+        const cumulative = new Array(filtered.length);
+        let total = 0;
+        for (let i = 0; i < filtered.length; i++) {
+            total += filtered[i][1];
+            cumulative[i] = total;
+        }
+        return {
+            sample: () => {
+                const r = this.between(0, total);
+                let lo = 0;
+                let hi = cumulative.length - 1;
+                while (lo < hi) {
+                    const mid = (lo + hi) >>> 1;
+                    if (r < cumulative[mid])
+                        hi = mid;
+                    else
+                        lo = mid + 1;
+                }
+                return filtered[lo][0];
+            },
+        };
+    }
+    /**
+     * Generate a sequence of bytes
+     * @param count
+     * @returns Random byte array
+     */
+    bytes(count) {
+        const arr = new Uint8Array(count);
+        for (let i = 0; i < count; i++)
+            arr[i] = this.int(0, 255);
+        return arr;
+    }
+    /**
+     * Round a value up or down, according to probability defined by its non-integral part
+     * @example
+     * ```ts
+     * const rawDamage = weapon.damage / armour.protection;
+     * hp -= alea.round(rawDamage);
+     * // HP remains integer while law of averages applies fractional damage
+     * ```
+     * @param n
+     * @returns Randomly rounded value
+     */
+    round(n) {
+        const floor = Math.floor(n);
+        return this.chance(n - floor) ? floor + 1 : floor;
+    }
+    /**
+     * Get a random gaussian normal value
+     * @param mean
+     * @param deviation
+     * @returns Random gaussian normal
+     */
+    normal(mean, deviation) {
+        let u1 = this.next();
+        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;
+    }
+    /**
+     * Generate a random UUID (version 4)
+     *
+     * **Security note**: output is only as cryptographically secure as
+     * an instance's PRNG source, which, by default, is not.
+     * @see {@link Alea.crypto}
+     * @returns Random UUID string
+     */
+    uuid() {
+        // xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx
+        const bytes = this.bytes(16);
+        bytes[6] = (bytes[6] & 0x0f) | 0x40;
+        bytes[8] = (bytes[8] & 0x3f) | 0x80;
+        const hex = Array.from(bytes, byte => byte.toString(16).padStart(2, '0')).join('');
+        return [
+            hex.slice(0, 8),
+            hex.slice(8, 12),
+            hex.slice(12, 16),
+            hex.slice(16, 20),
+            hex.slice(20, 32)
+        ].join('-');
+    }
+}

package/internal/factories.d.ts

@@ -0,0 +1,34 @@
+import { Alea } from "./alea";
+/**
+ * Create an Alea instance using a byte generator, such as `crypto`,
+ * as a RNG source
+ * @example
+ * ```ts
+ * const cryptoAlea = createAleaFromByteSource(crypto.getRandomValues);
+ * const hwAlea = createAleaFromByteSource(hardwareRng.fillBytes);
+ * ```
+ * @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;
+/**
+ * Create an Alea instance using a Mulberry32 source
+ *
+ * Fast, with decent statistical quality
+ *
+ * For applications requiring higher statistical quality or different characteristics, see the specialized PRNGs in @xtia/Alea/prng
+ * @param seed
+ * @returns Alea instance using Mulberry32
+ */
+export declare function createAleaFromSeed(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);
+ * ```
+ * @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;

package/internal/factories.js

@@ -0,0 +1,48 @@
+import { mulberry32 } from "../prng";
+import { Alea } from "./alea";
+/**
+ * Create an Alea instance using a byte generator, such as `crypto`,
+ * as a RNG source
+ * @example
+ * ```ts
+ * const cryptoAlea = createAleaFromByteSource(crypto.getRandomValues);
+ * const hwAlea = createAleaFromByteSource(hardwareRng.fillBytes);
+ * ```
+ * @param applyBytes A callback that fills a Uint8Array with random bytes
+ * @returns A byte generator-sourced Alea instance
+ */
+export function createAleaFromByteSource(applyBytes) {
+    const buffer = new ArrayBuffer(4);
+    const view = new Uint8Array(buffer);
+    const uint32View = new Uint32Array(buffer);
+    return new Alea(() => {
+        applyBytes(view);
+        return uint32View[0] / 4294967296;
+    });
+}
+/**
+ * Create an Alea instance using a Mulberry32 source
+ *
+ * Fast, with decent statistical quality
+ *
+ * For applications requiring higher statistical quality or different characteristics, see the specialized PRNGs in @xtia/Alea/prng
+ * @param seed
+ * @returns Alea instance using Mulberry32
+ */
+export function createAleaFromSeed(seed) {
+    return mulberry32(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);
+ * ```
+ * @param fn Source RNG; a function that returns a value >= 0 and < 1
+ * @returns Custom function-sourced Alea instance
+ */
+export function createAleaFromFunc(fn) {
+    return new Alea(fn);
+}
+// const xkcdAlea = createAleaFromFunc(() => 4/6); // decided by die roll

package/internal/util.d.ts

@@ -0,0 +1,15 @@
+export declare function murmur3_32(key: string, seed?: number): number;
+export declare const charsets: {
+    lowercase: string;
+    uppercase: string;
+    numbers: string;
+    hexadecimalUppercase: string;
+    hexadecimalLowercase: string;
+    alphanumericUppercase: string;
+    alphanumericLowercase: string;
+    alphanumericMixedCase: string;
+    urlSafe: string;
+    wide: string;
+    exclude: (charset: string, excluded: string) => string;
+    unique: (charset: string) => string;
+};

package/internal/util.js

@@ -0,0 +1,63 @@
+export function murmur3_32(key, seed = 0) {
+    let remainder = key.length & 3;
+    let bytes = key.length - remainder;
+    let h1 = seed >>> 0;
+    const c1 = 0xcc9e2d51;
+    const c2 = 0x1b873593;
+    let i = 0;
+    while (i < bytes) {
+        let k1 = (key.charCodeAt(i) & 0xff)
+            | ((key.charCodeAt(i + 1) & 0xff) << 8)
+            | ((key.charCodeAt(i + 2) & 0xff) << 16)
+            | ((key.charCodeAt(i + 3) & 0xff) << 24);
+        i += 4;
+        k1 = Math.imul(k1, c1);
+        k1 = (k1 << 15) | (k1 >>> 17);
+        k1 = Math.imul(k1, c2);
+        h1 ^= k1;
+        h1 = (h1 << 13) | (h1 >>> 19);
+        h1 = (Math.imul(h1, 5) + 0xe6546b64) | 0;
+    }
+    let k1 = 0;
+    switch (remainder) {
+        case 3:
+            k1 ^= (key.charCodeAt(i + 2) & 0xff) << 16;
+        case 2:
+            k1 ^= (key.charCodeAt(i + 1) & 0xff) << 8;
+        case 1:
+            k1 ^= (key.charCodeAt(i) & 0xff);
+            k1 = Math.imul(k1, c1);
+            k1 = (k1 << 15) | (k1 >>> 17);
+            k1 = Math.imul(k1, c2);
+            h1 ^= k1;
+    }
+    h1 ^= key.length;
+    h1 ^= h1 >>> 16;
+    h1 = Math.imul(h1, 0x85ebca6b);
+    h1 ^= h1 >>> 13;
+    h1 = Math.imul(h1, 0xc2b2ae35);
+    h1 ^= h1 >>> 16;
+    return h1 >>> 0;
+}
+const lowercase = "abcdefghijklmnopqrstuvwxyz";
+const uppercase = lowercase.toUpperCase();
+const numbers = "0123456789";
+export const charsets = {
+    lowercase,
+    uppercase,
+    numbers,
+    hexadecimalUppercase: numbers + "ABCDEF",
+    hexadecimalLowercase: numbers + "abcdef",
+    alphanumericUppercase: uppercase + numbers,
+    alphanumericLowercase: lowercase + numbers,
+    alphanumericMixedCase: lowercase + uppercase + numbers,
+    urlSafe: uppercase + lowercase + numbers + "_-.~",
+    wide: uppercase + lowercase + numbers + "_-+=[]{};#:@~,./<>?!$%^&*()",
+    exclude: (charset, excluded) => {
+        const excludedSet = new Set([...excluded]);
+        return [...charset].filter(c => !excludedSet.has(c)).join("");
+    },
+    unique: (charset) => {
+        return [...new Set([...charset])].join("");
+    },
+};

package/node.d.ts

@@ -0,0 +1,2 @@
+export * from "./common";
+export declare const cryptoAlea: import("./common").Alea;

package/node.js

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

package/other.d.ts

@@ -0,0 +1,6 @@
+import { Alea } from "./internal/alea";
+export * from "./common";
+/**
+ * An Alea instance that uses the local environment's `crypto` provider
+ */
+export declare const cryptoAlea: Alea;

package/other.js

@@ -0,0 +1,8 @@
+import { Alea } from "./internal/alea";
+export * from "./common";
+/**
+ * An Alea instance that uses the local environment's `crypto` provider
+ */
+export const cryptoAlea = new Alea(() => {
+    throw new Error("cryptoAlea is not available in this environment. Consider using createAleaFromByteSource() with your environment's crypto API.");
+});

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@xtia/alea-rc",
+  "version": "0.0.1",
+  "description": "RNG utilities",
+  "repository": {
+    "url": "https://github.com/tiadrop/alea",
+    "type": "github"
+  },
+  "sideEffects": false,
+  "types": "./index.d.ts",
+  "main": "./index.js",
+  "exports": {
+    ".": {
+      "types": "./other.d.ts",
+      "browser": "./browser.js",
+      "workerd": "./browser.js",
+      "deno": "./browser.js",
+      "node": "./node.js",
+      "bun": "./node.js",
+      "default": "./other.js"
+    },
+    "./prng": {
+      "types": "./prng/index.d.ts",
+      "default": "./prng/index.js"
+    },
+    "./internal/*": null
+  },
+  "scripts": {
+    "prepublishOnly": "cp ../README.md .",
+    "postpublish": "rm README.md"
+  },
+  "keywords": [
+    "random",
+    "rng"
+  ],
+  "author": "Aleta Lovelace",
+  "license": "MIT"
+}

package/prng/index.d.ts

@@ -0,0 +1,3 @@
+export { mulberry32 } from "./mulberry32";
+export { sfc32 } from "./sfc32";
+export { xoshiro128pp } from "./xoshiro128pp";

package/prng/index.js

@@ -0,0 +1,3 @@
+export { mulberry32 } from "./mulberry32";
+export { sfc32 } from "./sfc32";
+export { xoshiro128pp } from "./xoshiro128pp";

package/prng/mulberry32.d.ts

@@ -0,0 +1,9 @@
+import { Alea } from "../internal/alea";
+/**
+ * Create an Alea instance using a Mulberry32 source
+ *
+ * Fast, with decent statistical quality
+ * @param seed
+ * @returns Alea instance using Mulberry32
+ */
+export declare const mulberry32: (seed: number | string) => Alea;

package/prng/mulberry32.js

@@ -0,0 +1,19 @@
+import { Alea } from "../internal/alea";
+import { murmur3_32 } from "../internal/util";
+/**
+ * Create an Alea instance using a Mulberry32 source
+ *
+ * Fast, with decent statistical quality
+ * @param seed
+ * @returns Alea instance using Mulberry32
+ */
+export const mulberry32 = (seed) => {
+    let nseed = typeof seed == "string" ? murmur3_32(seed) : (seed >>> 0);
+    return new Alea(() => {
+        nseed |= 0;
+        nseed = nseed + 0x6D2B79F5 | 0;
+        let t = Math.imul(nseed ^ nseed >>> 15, 1 | nseed);
+        t = t + Math.imul(t ^ t >>> 7, 61 | t) ^ t;
+        return ((t ^ t >>> 14) >>> 0) / 4294967296;
+    });
+};

package/prng/sfc32.d.ts

@@ -0,0 +1,12 @@
+import { Alea } from "../internal/alea";
+/**
+ * Create an Alea instance using a Small Fast Counter (SFC32) source
+ *
+ * Fairly fast, with high statistical quality
+ * @param a Seed A
+ * @param b Seed B
+ * @param c Seed C
+ * @param d Seed D
+ * @returns Alea isntance using SFC32
+ */
+export declare function sfc32(a: number | string, b: number | string, c: number | string, d: number | string): Alea;

package/prng/sfc32.js

@@ -0,0 +1,31 @@
+import { Alea } from "../internal/alea";
+import { murmur3_32 } from "../internal/util";
+/**
+ * Create an Alea instance using a Small Fast Counter (SFC32) source
+ *
+ * Fairly fast, with high statistical quality
+ * @param a Seed A
+ * @param b Seed B
+ * @param c Seed C
+ * @param d Seed D
+ * @returns Alea isntance using SFC32
+ */
+export function sfc32(a, b, c, d) {
+    const toWord = (v) => typeof v === "number" ? (v >>> 0) : murmur3_32(String(v));
+    let s0 = toWord(a) | 0;
+    let s1 = toWord(b) | 0;
+    let s2 = toWord(c) | 0;
+    let s3 = toWord(d) | 0;
+    return new Alea(() => {
+        s0 |= 0;
+        s1 |= 0;
+        s2 |= 0;
+        s3 |= 0;
+        const t = (s0 + s1 | 0) + s3 | 0;
+        s3 = s3 + 1 | 0;
+        s0 = s1 ^ s1 >>> 9;
+        s1 = s2 + (s2 << 3) | 0;
+        s2 = (s2 << 21 | s2 >>> 11) + t | 0;
+        return (t >>> 0) / 4294967296;
+    });
+}

package/prng/xoshiro128pp.d.ts

@@ -0,0 +1,12 @@
+import { Alea } from "../internal/alea";
+/**
+ * Create an Alea instance using a Xoshiro128++ source
+ *
+ * Very high statistical quality
+ * @param a Seed A
+ * @param b Seed B
+ * @param c Seed C
+ * @param d Seed D
+ * @returns Alea instance using Xoshiro128++
+ */
+export declare function xoshiro128pp(a: number | string, b: number | string, c: number | string, d: number | string): Alea;

package/prng/xoshiro128pp.js

@@ -0,0 +1,41 @@
+import { Alea } from "../internal/alea";
+import { murmur3_32 } from "../internal/util";
+function rotl(x, k) {
+    return (x << k) | (x >>> (32 - k));
+}
+/**
+ * Create an Alea instance using a Xoshiro128++ source
+ *
+ * Very high statistical quality
+ * @param a Seed A
+ * @param b Seed B
+ * @param c Seed C
+ * @param d Seed D
+ * @returns Alea instance using Xoshiro128++
+ */
+export function xoshiro128pp(a, b, c, d) {
+    const toWord = (v) => typeof v === "number" ? v >>> 0 : murmur3_32(String(v));
+    let s0 = toWord(a) | 0;
+    let s1 = toWord(b) | 0;
+    let s2 = toWord(c) | 0;
+    let s3 = toWord(d) | 0;
+    // requires at least one non-zero value
+    if (s0 === 0 && s1 === 0 && s2 === 0 && s3 === 0) {
+        s0 = 1;
+    }
+    return new Alea(() => {
+        s0 |= 0;
+        s1 |= 0;
+        s2 |= 0;
+        s3 |= 0;
+        const result = (rotl(s0 + s3, 7) + s0) >>> 0;
+        const t = s1 << 9;
+        s2 ^= s0;
+        s3 ^= s1;
+        s1 ^= s2;
+        s0 ^= s3;
+        s2 ^= t;
+        s3 = rotl(s3, 11);
+        return result / 4294967296;
+    });
+}