@esportsplus/random 0.0.28 → 0.0.30

package/.github/dependabot.yml

@@ -4,11 +4,13 @@
 # https://docs.github.com/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file
 
 version: 2
+
 registries:
   npm-npmjs:
     token: ${{secrets.NPM_TOKEN}}
     type: npm-registry
     url: https://registry.npmjs.org
+
 updates:
   - package-ecosystem: "npm"
     directory: "/"

package/.github/workflows/bump.yml

@@ -1,7 +1,9 @@
 name: bump
+
 on:
   push:
     branches: '**' # only trigger on branches, not on tags
+
 jobs:
   bump:
     uses: esportsplus/workflows/.github/workflows/bump.yml@main

package/.github/workflows/dependabot.yml

@@ -0,0 +1,12 @@
+name: dependabot automerge
+
+on:
+  pull_request:
+    types: [opened, synchronize, labeled]
+  workflow_dispatch:
+
+jobs:
+  automerge:
+    secrets:
+      NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
+    uses: esportsplus/workflows/.github/workflows/dependabot.yml@main

package/.github/workflows/publish.yml

@@ -1,4 +1,5 @@
 name: publish to npm
+
 on:
   release:
     types: [published]
@@ -7,8 +8,9 @@ on:
     workflows: [bump]
     types:
       - completed
+
 jobs:
   publish:
     secrets:
-        NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN_PUBLISHING }}
-    uses: esportsplus/workflows/.github/workflows/publish.yml@main
+        NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
+    uses: esportsplus/workflows/.github/workflows/publish.yml@main

package/README.md

@@ -0,0 +1,387 @@
+# @esportsplus/random
+
+Cryptographically secure random utilities with optional seeded/provably fair mode.
+
+All functions accept an optional `seed` parameter (number or string) as the last argument for reproducible results.
+
+---
+
+## Functions
+
+### `alphanumeric(length, seed?)`
+Generate random alphanumeric string.
+
+```ts
+alphanumeric(8);           // "Kj3mX9pL"
+alphanumeric(8, 'seed');   // Reproducible result
+```
+
+---
+
+### `between(items, seed?)`
+Pick 2 unique items from array. Useful for matchmaking/pairings.
+
+```ts
+between(['a', 'b', 'c', 'd']);  // ['b', 'd']
+```
+
+---
+
+### `coinflip(seed?)`
+50/50 true/false.
+
+```ts
+coinflip();        // true or false
+coinflip('seed');  // Reproducible result
+```
+
+---
+
+### `exponential(lambda, seed?)`
+Exponential distribution. Useful for time-between-events simulation.
+
+```ts
+exponential(1.5);  // 0.234...
+```
+
+---
+
+### `gaussian(mean, stddev, seed?)`
+Normal/Gaussian distribution. Useful for realistic simulations.
+
+```ts
+gaussian(100, 15);  // ~100 with stddev 15
+```
+
+---
+
+### `groups(items, total, seed?)`
+Randomly split array into N groups.
+
+```ts
+groups([1, 2, 3, 4, 5, 6], 2);  // [[3, 1, 5], [6, 2, 4]]
+```
+
+---
+
+### `hex(length, seed?)`
+Generate random hex string.
+
+```ts
+hex(16);  // "a3f2b1c9e4d8f0a2"
+```
+
+---
+
+### `item(map, seed?)`
+Weighted random selection from Map.
+
+```ts
+let rewards = new Map([
+    ['common', 70],
+    ['rare', 25],
+    ['legendary', 5]
+]);
+
+item(rewards);  // 'common' (70% chance)
+```
+
+---
+
+### `pick(items, count, seed?)`
+Pick N items with replacement (duplicates allowed).
+
+```ts
+pick([1, 2, 3, 4, 5], 3);  // [2, 2, 5] (same item can repeat)
+```
+
+---
+
+### `range(min, max, integer?, seed?)`
+Random number in range. Set `integer=true` for whole numbers.
+
+```ts
+range(0, 100);              // 42.7381...
+range(1, 10, true);         // 7
+range(1, 10, true, 'seed'); // Reproducible integer
+```
+
+---
+
+### `roll(numerator, denominator, seed?)`
+Roll "N in D" chance.
+
+```ts
+roll(1, 100);   // 1% chance (1 in 100)
+roll(25, 100);  // 25% chance
+roll(1, 6);     // ~16.7% chance (1 in 6)
+```
+
+---
+
+### `sample(items, count, seed?)`
+Pick N unique items (no duplicates).
+
+```ts
+sample([1, 2, 3, 4, 5], 3);  // [4, 1, 5] (each item appears once max)
+```
+
+---
+
+### `shuffle(values, seed?)`
+Fisher-Yates shuffle. Mutates original array.
+
+```ts
+shuffle([1, 2, 3, 4, 5]);  // [3, 1, 5, 2, 4]
+```
+
+---
+
+### `uuid(seed?)`
+Generate UUID v4.
+
+```ts
+uuid();  // "550e8400-e29b-41d4-a716-446655440000"
+```
+
+---
+
+## Provably Fair / Seeded Mode
+
+---
+
+### rng
+
+Cryptographically secure random number generator with optional seeded/provably fair mode.
+
+```ts
+rng(): number                  // Crypto RNG (0-1)
+rng(seed: string): number      // Seeded RNG (deterministic)
+```
+
+```ts
+import { rng } from '@esportsplus/crypto';
+
+// Cryptographic random
+let random = rng();  // 0.7234...
+
+// Seeded/provably fair (same seed = same result)
+let seeded = rng('server-seed:client-seed:nonce');  // Deterministic
+```
+
+#### Provably Fair Item Drop Example
+
+```ts
+import { hash, rng } from '@esportsplus/crypto';
+
+// 1. Server generates secret seed (hidden until round ends)
+let serverSeed = rng.seed();
+let serverSeedHash = await hash(serverSeed);  // Reveal this to client before roll
+
+// 2. Client provides their seed
+let clientSeed = 'my-lucky-seed-123';
+
+// 3. Combine seeds with nonce for deterministic result
+let nonce = 0;  // Increment per roll
+let combinedSeed = `${serverSeed}:${clientSeed}:${nonce}`;
+
+// 4. Generate roll and determine drop
+let items = [
+    { name: 'Common Sword', weight: 0.70 },
+    { name: 'Rare Armor', weight: 0.25 },
+    { name: 'Legendary Helm', weight: 0.05 }
+];
+
+let roll = rng(combinedSeed);  // 0.0 - 1.0
+let cumulative = 0;
+let drop = items[0];
+
+for (let i = 0, n = items.length; i < n; i++) {
+    cumulative += items[i].weight;
+    if (roll < cumulative) {
+        drop = items[i];
+        break;
+    }
+}
+
+// 5. After round: reveal serverSeed so client can verify
+//    Client checks: hash(serverSeed) === serverSeedHash
+//    Client recalculates: rng(`${serverSeed}:${clientSeed}:${nonce}`) === roll
+```
+
+---
+
+### rng.seed
+
+Generate a cryptographically secure 32-byte hex seed.
+
+```ts
+rng.seed(): string
+```
+
+**Returns:** 64-character hex string
+
+```ts
+import { rng } from '@esportsplus/crypto';
+
+let serverSeed = rng.seed();  // 'a1b2c3d4...' (64 chars)
+let clientSeed = rng.seed();
+
+// Combine for provably fair result
+let result = rng(`${serverSeed}:${clientSeed}:0`);
+```
+
+#### Provably Fair System - Complete Flow
+
+**Database Schema (per user):**
+```ts
+interface UserSeeds {
+    id: string;
+    serverSeed: string;       // Current secret (never exposed until rotation)
+    serverSeedHash: string;   // SHA-256 of serverSeed (shown to user)
+    clientSeed: string;       // User-provided or auto-generated
+    nonce: number;            // Roll counter, increments each roll
+}
+```
+
+**1. Initial Setup (User Registration/First Visit)**
+```ts
+import { hash, rng } from '@esportsplus/crypto';
+
+// Server generates seeds
+let serverSeed = rng.seed();
+let serverSeedHash = await hash(serverSeed);
+let clientSeed = rng.seed();  // Or user provides custom value
+
+// Store in database
+await db.user.create({
+    id: odx(),
+    serverSeed,               // Hidden from user
+    serverSeedHash,           // Visible to user
+    clientSeed,               // Visible to user
+    nonce: 0
+});
+
+// Send to client (NEVER send serverSeed)
+return { serverSeedHash, clientSeed, nonce: 0 };
+```
+
+**2. Rolling (Each Game Action)**
+```ts
+// Server-side roll
+async function roll(userId: string) {
+    let user = await db.user.get(userId);
+    let { serverSeed, clientSeed, nonce } = user;
+
+    // Generate deterministic result
+    let combinedSeed = `${serverSeed}:${clientSeed}:${nonce}`;
+    let result = rng(combinedSeed);
+
+    // Increment nonce for next roll
+    await db.user.update(userId, { nonce: nonce + 1 });
+
+    // Return result (NOT the serverSeed)
+    return {
+        result,
+        nonce,              // So user can verify later
+        clientSeed,         // Confirm which seed was used
+        serverSeedHash      // Confirm commitment
+    };
+}
+```
+
+**3. User Changes Client Seed (Anytime)**
+```ts
+async function updateClientSeed(userId: string, newClientSeed: string) {
+    // User can change client seed freely
+    // Does NOT reveal server seed
+    // Does NOT reset nonce (same server seed epoch)
+    await db.user.update(userId, { clientSeed: newClientSeed });
+}
+```
+
+**4. Seed Rotation (User-Initiated)**
+```ts
+async function rotateServerSeed(userId: string) {
+    let user = await db.user.get(userId);
+
+    // Generate new server seed
+    let newServerSeed = rng.seed();
+    let newServerSeedHash = await hash(newServerSeed);
+
+    // Update database
+    await db.user.update(userId, {
+        serverSeed: newServerSeed,
+        serverSeedHash: newServerSeedHash,
+        nonce: 0  // Reset nonce for new seed epoch
+    });
+
+    // NOW reveal the old serverSeed for verification
+    return {
+        previousServerSeed: user.serverSeed,    // User can now verify all past rolls
+        previousServerSeedHash: user.serverSeedHash,
+        previousNonce: user.nonce,              // Total rolls under old seed
+        newServerSeedHash,                      // New commitment
+        nonce: 0
+    };
+}
+```
+
+**5. Client-Side Verification (After Rotation)**
+```ts
+import { hash, rng } from '@esportsplus/crypto';
+
+async function verifyRolls(
+    previousServerSeed: string,
+    previousServerSeedHash: string,
+    clientSeed: string,
+    rolls: { nonce: number; result: number }[]
+) {
+    // Step 1: Verify server didn't change the seed
+    let computedHash = await hash(previousServerSeed);
+    if (computedHash !== previousServerSeedHash) {
+        throw new Error('Server seed does not match committed hash!');
+    }
+
+    // Step 2: Verify each roll result
+    for (let i = 0, n = rolls.length; i < n; i++) {
+        let { nonce, result } = rolls[i];
+        let combinedSeed = `${previousServerSeed}:${clientSeed}:${nonce}`;
+        let expectedResult = rng(combinedSeed);
+
+        if (expectedResult !== result) {
+            throw new Error(`Roll ${nonce} was manipulated!`);
+        }
+    }
+
+    return true;  // All rolls verified
+}
+```
+
+**Security Properties:**
+| Property | Guarantee |
+|----------|-----------|
+| Server can't predict | Client seed unknown when server commits |
+| Server can't manipulate | Hash commitment locks server seed |
+| Client can't predict | Server seed hidden until rotation |
+| Deterministic | Same seeds + nonce = same result always |
+| Verifiable | User can audit all rolls after rotation |
+
+**Timeline Example:**
+```
+Day 1: User signs up
+       → serverSeed=ABC, hash(ABC)=XYZ shown, clientSeed=123, nonce=0
+
+Day 1: User rolls 50 times
+       → nonce increments 0→49, serverSeed stays ABC (hidden)
+
+Day 3: User changes clientSeed to "lucky-charm"
+       → nonce continues at 50, serverSeed stays ABC (hidden)
+
+Day 5: User rolls 100 more times
+       → nonce increments 50→149
+
+Day 7: User clicks "Rotate Seed"
+       → ABC revealed, user verifies all 150 rolls
+       → New serverSeed=DEF, hash(DEF)=UVW shown, nonce=0
+```

package/build/alphanumeric.d.ts

@@ -0,0 +1,2 @@
+declare const _default: (length: number, seed?: string) => string;
+export default _default;

package/build/alphanumeric.js

@@ -0,0 +1,12 @@
+import { rng } from './rng.js';
+const CHARS = '0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz';
+export default (length, seed) => {
+    if (length <= 0) {
+        throw new Error('@esportsplus/random: length must be positive');
+    }
+    let n = CHARS.length, result = '';
+    for (let i = 0; i < length; i++) {
+        result += CHARS[(rng(seed) * n) >>> 0];
+    }
+    return result;
+};

package/build/between.d.ts

@@ -0,0 +1,2 @@
+declare const _default: <T>(items: T[], seed?: string) => [T, T];
+export default _default;

package/build/between.js

@@ -0,0 +1,12 @@
+import { rng } from './rng.js';
+export default (items, seed) => {
+    let n = items.length;
+    if (n < 2) {
+        throw new Error('@esportsplus/random: need at least 2 items');
+    }
+    let first = (rng(seed) * n) >>> 0, second = (rng(seed) * (n - 1)) >>> 0;
+    if (second >= first) {
+        second++;
+    }
+    return [items[first], items[second]];
+};

package/build/coinflip.d.ts

@@ -1,2 +1,2 @@
-declare const _default: () => boolean;
+declare const _default: (seed?: string) => boolean;
 export default _default;

package/build/coinflip.js

@@ -1,4 +1,4 @@
-import { rng } from '@esportsplus/crypto';
-export default () => {
-    return rng() < 0.5;
+import { rng } from './rng.js';
+export default (seed) => {
+    return rng(seed) < 0.5;
 };

package/build/exponential.d.ts

@@ -0,0 +1,2 @@
+declare const _default: (lambda: number, seed?: string) => number;
+export default _default;

package/build/exponential.js

@@ -0,0 +1,11 @@
+import { rng } from './rng.js';
+export default (lambda, seed) => {
+    if (lambda <= 0) {
+        throw new Error('@esportsplus/random: lambda must be positive');
+    }
+    let u = rng(seed);
+    while (u === 0) {
+        u = rng(seed);
+    }
+    return -Math.log(u) / lambda;
+};

package/build/gaussian.d.ts

@@ -0,0 +1,2 @@
+declare const _default: (mean: number, stddev: number, seed?: string) => number;
+export default _default;

package/build/gaussian.js

@@ -0,0 +1,12 @@
+import { rng } from './rng.js';
+export default (mean, stddev, seed) => {
+    if (stddev < 0) {
+        throw new Error('@esportsplus/random: stddev cannot be negative');
+    }
+    let u1 = rng(seed), u2 = rng(seed);
+    while (u1 === 0) {
+        u1 = rng(seed);
+    }
+    let z = Math.sqrt(-2 * Math.log(u1)) * Math.cos(2 * Math.PI * u2);
+    return mean + stddev * z;
+};

package/build/groups.d.ts

@@ -0,0 +1,2 @@
+declare const _default: <T>(items: T[], total: number, seed?: string) => T[][];
+export default _default;

package/build/groups.js

@@ -0,0 +1,11 @@
+import shuffle from './shuffle.js';
+export default (items, total, seed) => {
+    if (total <= 0) {
+        throw new Error('@esportsplus/random: total must be positive');
+    }
+    let copy = shuffle([...items], seed), groups = [], n = copy.length, size = Math.ceil(n / total);
+    for (let i = 0; i < total; i++) {
+        groups.push(copy.slice(i * size, (i + 1) * size));
+    }
+    return groups;
+};

package/build/hex.d.ts

@@ -0,0 +1,2 @@
+declare const _default: (length: number, seed?: string) => string;
+export default _default;

package/build/hex.js

@@ -0,0 +1,12 @@
+import { rng } from './rng.js';
+const CHARS = '0123456789abcdef';
+export default (length, seed) => {
+    if (length <= 0) {
+        throw new Error('@esportsplus/random: length must be positive');
+    }
+    let result = '';
+    for (let i = 0; i < length; i++) {
+        result += CHARS[(rng(seed) * 16) >>> 0];
+    }
+    return result;
+};

package/build/index.d.ts

@@ -1,6 +1,14 @@
+import alphanumeric from './alphanumeric.js';
+import between from './between.js';
 import coinflip from './coinflip.js';
+import exponential from './exponential.js';
+import gaussian from './gaussian.js';
+import groups from './groups.js';
+import hex from './hex.js';
 import item from './item.js';
+import pick from './pick.js';
 import range from './range.js';
 import roll from './roll.js';
+import sample from './sample.js';
 import shuffle from './shuffle.js';
-export { coinflip, item, range, roll, shuffle };
+export { alphanumeric, between, coinflip, exponential, gaussian, groups, hex, item, pick, range, roll, sample, shuffle };

package/build/index.js

@@ -1,6 +1,14 @@
+import alphanumeric from './alphanumeric.js';
+import between from './between.js';
 import coinflip from './coinflip.js';
+import exponential from './exponential.js';
+import gaussian from './gaussian.js';
+import groups from './groups.js';
+import hex from './hex.js';
 import item from './item.js';
+import pick from './pick.js';
 import range from './range.js';
 import roll from './roll.js';
+import sample from './sample.js';
 import shuffle from './shuffle.js';
-export { coinflip, item, range, roll, shuffle };
+export { alphanumeric, between, coinflip, exponential, gaussian, groups, hex, item, pick, range, roll, sample, shuffle };

package/build/item.d.ts

@@ -1,2 +1,2 @@
-declare const _default: <T>(items: T[], weights?: number[]) => T;
+declare const _default: <T>(map: Map<T, number>, seed?: string) => T;
 export default _default;

package/build/item.js

@@ -1,22 +1,18 @@
-import { rng } from '@esportsplus/crypto';
-export default (items, weights) => {
-    if (weights === undefined) {
-        return items[Math.floor(rng() * items.length)];
+import { rng } from './rng.js';
+export default (map, seed) => {
+    if (map.size === 0) {
+        throw new Error('@esportsplus/random: map cannot be empty');
     }
-    let n = items.length, random = 0;
-    if (n !== weights.length) {
-        throw new Error('Random: each item requires a weight');
+    let current = 0, total = 0;
+    for (let weight of map.values()) {
+        total += weight;
     }
-    for (let i = 0; i < n; i++) {
-        random += weights[i];
-    }
-    let current = 0;
-    random *= rng();
-    for (let i = 0; i < n; i++) {
-        current += weights[i];
+    let random = rng(seed) * total;
+    for (let [item, weight] of map) {
+        current += weight;
         if (random <= current) {
-            return items[i];
+            return item;
         }
     }
-    throw new Error('Random: weighted item pick failed');
+    throw new Error('@esportsplus/random: weighted item pick failed');
 };

package/build/pick.d.ts

@@ -0,0 +1,2 @@
+declare const _default: <T>(items: T[], count: number, seed?: string) => T[];
+export default _default;

package/build/pick.js

@@ -0,0 +1,14 @@
+import { rng } from './rng.js';
+export default (items, count, seed) => {
+    if (items.length === 0) {
+        throw new Error('@esportsplus/random: items cannot be empty');
+    }
+    if (count <= 0) {
+        throw new Error('@esportsplus/random: count must be positive');
+    }
+    let n = items.length, result = [];
+    for (let i = 0; i < count; i++) {
+        result.push(items[(rng(seed) * n) >>> 0]);
+    }
+    return result;
+};

package/build/range.d.ts

@@ -1,2 +1,2 @@
-declare const _default: (min: number, max: number, integer?: boolean) => number;
+declare const _default: (min: number, max: number, integer?: boolean, seed?: string) => number;
 export default _default;

package/build/range.js

@@ -1,9 +1,12 @@
-import { rng } from '@esportsplus/crypto';
-export default (min, max, integer = false) => {
+import { rng } from './rng.js';
+export default (min, max, integer = false, seed) => {
+    if (min > max) {
+        throw new Error('@esportsplus/random: min cannot be greater than max');
+    }
     if (!integer) {
-        return rng() * (max - min) + min;
+        return rng(seed) * (max - min) + min;
     }
     min = Math.ceil(min);
     max = Math.floor(max) + 1;
-    return Math.floor(rng() * (max - min) + min);
+    return Math.floor(rng(seed) * (max - min) + min);
 };

package/build/rng.d.ts

@@ -0,0 +1,5 @@
+declare function rng(seed?: string): number;
+declare namespace rng {
+    var seed: () => string;
+}
+export { rng };

package/build/rng.js

@@ -0,0 +1,53 @@
+const MAX = 0xFFFFFFFF;
+const RNG_BUFFER = new Uint32Array(1);
+const SEED_BUFFER = new Uint8Array(32);
+function cyrb128(str) {
+    let h1 = 1779033703, h2 = 3144134277, h3 = 1013904242, h4 = 2773480762;
+    for (let i = 0, n = str.length; i < n; i++) {
+        let k = str.charCodeAt(i);
+        h1 = h2 ^ Math.imul(h1 ^ k, 597399067);
+        h2 = h3 ^ Math.imul(h2 ^ k, 2869860233);
+        h3 = h4 ^ Math.imul(h3 ^ k, 951274213);
+        h4 = h1 ^ Math.imul(h4 ^ k, 2716044179);
+    }
+    h1 = Math.imul(h3 ^ (h1 >>> 18), 597399067);
+    h2 = Math.imul(h4 ^ (h2 >>> 22), 2869860233);
+    h3 = Math.imul(h1 ^ (h3 >>> 17), 951274213);
+    h4 = Math.imul(h2 ^ (h4 >>> 19), 2716044179);
+    h1 ^= (h2 ^ h3 ^ h4);
+    h2 ^= h1;
+    h3 ^= h1;
+    h4 ^= h1;
+    return [h1 >>> 0, h2 >>> 0, h3 >>> 0, h4 >>> 0];
+}
+function sfc32(a, b, c, d) {
+    return () => {
+        a >>>= 0;
+        b >>>= 0;
+        c >>>= 0;
+        d >>>= 0;
+        let t = (a + b) | 0;
+        a = b ^ b >>> 9;
+        b = c + (c << 3) | 0;
+        c = (c << 21 | c >>> 11);
+        d = d + 1 | 0;
+        t = t + d | 0;
+        c = c + t | 0;
+        return (t >>> 0) / MAX;
+    };
+}
+function rng(seed) {
+    if (seed) {
+        let [a, b, c, d] = cyrb128(seed);
+        return sfc32(a, b, c, d)();
+    }
+    return crypto.getRandomValues(RNG_BUFFER)[0] / MAX;
+}
+rng.seed = () => {
+    let bytes = crypto.getRandomValues(SEED_BUFFER), hex = '';
+    for (let i = 0, n = bytes.length; i < n; i++) {
+        hex += bytes[i].toString(16).padStart(2, '0');
+    }
+    return hex;
+};
+export { rng };

package/build/roll.d.ts

@@ -1,2 +1,2 @@
-declare const _default: (percentage: number) => boolean;
+declare const _default: (numerator: number, denominator: number, seed?: string) => boolean;
 export default _default;

package/build/roll.js

@@ -1,4 +1,7 @@
-import { rng } from '@esportsplus/crypto';
-export default (percentage) => {
-    return rng() <= percentage;
+import { rng } from './rng.js';
+export default (numerator, denominator, seed) => {
+    if (numerator <= 0 || denominator <= 0) {
+        throw new Error('@esportsplus/random: numerator and denominator must be positive');
+    }
+    return rng(seed) <= (numerator / denominator);
 };

package/build/sample.d.ts

@@ -0,0 +1,2 @@
+declare const _default: <T>(items: T[], count: number, seed?: string) => T[];
+export default _default;

package/build/sample.js

@@ -0,0 +1,14 @@
+import shuffle from './shuffle.js';
+export default (items, count, seed) => {
+    let n = items.length;
+    if (n === 0) {
+        throw new Error('@esportsplus/random: items cannot be empty');
+    }
+    if (count <= 0) {
+        throw new Error('@esportsplus/random: count must be positive');
+    }
+    if (count > n) {
+        throw new Error('@esportsplus/random: count cannot exceed items length');
+    }
+    return shuffle([...items], seed).slice(0, count);
+};

package/build/shuffle.d.ts

@@ -1,2 +1,2 @@
-declare const _default: (values: any[]) => any[];
+declare const _default: <T>(values: T[], seed?: string) => T[];
 export default _default;

package/build/shuffle.js

@@ -1,8 +1,11 @@
-import { rng } from '@esportsplus/crypto';
-export default (values) => {
+import { rng } from './rng.js';
+export default (values, seed) => {
+    if (values.length === 0) {
+        return values;
+    }
     let n = values.length, random, value;
     while (--n > 0) {
-        random = Math.floor(rng() * (n + 1));
+        random = (rng(seed) * (n + 1)) >>> 0;
         value = values[random];
         values[random] = values[n];
         values[n] = value;

package/package.json

@@ -1,17 +1,18 @@
 {
   "author": "ICJR",
-  "dependencies": {
-    "@esportsplus/crypto": "^0.1.0"
-  },
   "devDependencies": {
-    "@esportsplus/typescript": "^0.9.1"
+    "@esportsplus/typescript": "^0.9.2"
   },
   "main": "build/index.js",
   "name": "@esportsplus/random",
   "private": false,
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/esportsplus/random"
+  },
   "type": "module",
   "types": "build/index.d.ts",
-  "version": "0.0.28",
+  "version": "0.0.30",
   "scripts": {
     "build": "tsc && tsc-alias",
     "-": "-"

package/src/alphanumeric.ts

@@ -0,0 +1,20 @@
+import { rng } from './rng';
+
+
+const CHARS = '0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz';
+
+
+export default (length: number, seed?: string) => {
+    if (length <= 0) {
+        throw new Error('@esportsplus/random: length must be positive');
+    }
+
+    let n = CHARS.length,
+        result = '';
+
+    for (let i = 0; i < length; i++) {
+        result += CHARS[(rng(seed) * n) >>> 0];
+    }
+
+    return result;
+};

package/src/between.ts

@@ -0,0 +1,19 @@
+import { rng } from './rng';
+
+
+export default <T>(items: T[], seed?: string): [T, T] => {
+    let n = items.length;
+
+    if (n < 2) {
+        throw new Error('@esportsplus/random: need at least 2 items');
+    }
+
+    let first = (rng(seed) * n) >>> 0,
+        second = (rng(seed) * (n - 1)) >>> 0;
+
+    if (second >= first) {
+        second++;
+    }
+
+    return [items[first], items[second]];
+};

package/src/coinflip.ts

@@ -1,6 +1,6 @@
-import { rng } from '@esportsplus/crypto';
+import { rng } from './rng';
 
 
-export default () => {
-    return rng() < 0.5;
+export default (seed?: string) => {
+    return rng(seed) < 0.5;
 };

package/src/exponential.ts

@@ -0,0 +1,19 @@
+import { rng } from './rng';
+
+
+// Box-Muller transform for normal distribution
+// - https://en.wikipedia.org/wiki/Box-Muller_transform
+export default (lambda: number, seed?: string) => {
+    if (lambda <= 0) {
+        throw new Error('@esportsplus/random: lambda must be positive');
+    }
+
+    let u = rng(seed);
+
+    // Avoid log(0)
+    while (u === 0) {
+        u = rng(seed);
+    }
+
+    return -Math.log(u) / lambda;
+};

package/src/gaussian.ts

@@ -0,0 +1,22 @@
+import { rng } from './rng';
+
+
+// Box-Muller transform for normal distribution
+// - https://en.wikipedia.org/wiki/Box-Muller_transform
+export default (mean: number, stddev: number, seed?: string) => {
+    if (stddev < 0) {
+        throw new Error('@esportsplus/random: stddev cannot be negative');
+    }
+
+    let u1 = rng(seed),
+        u2 = rng(seed);
+
+    // Avoid log(0)
+    while (u1 === 0) {
+        u1 = rng(seed);
+    }
+
+    let z = Math.sqrt(-2 * Math.log(u1)) * Math.cos(2 * Math.PI * u2);
+
+    return mean + stddev * z;
+};

package/src/groups.ts

@@ -0,0 +1,19 @@
+import shuffle from './shuffle';
+
+
+export default <T>(items: T[], total: number, seed?: string): T[][] => {
+    if (total <= 0) {
+        throw new Error('@esportsplus/random: total must be positive');
+    }
+
+    let copy = shuffle([...items], seed),
+        groups: T[][] = [],
+        n = copy.length,
+        size = Math.ceil(n / total);
+
+    for (let i = 0; i < total; i++) {
+        groups.push(copy.slice(i * size, (i + 1) * size));
+    }
+
+    return groups;
+};

package/src/hex.ts

@@ -0,0 +1,19 @@
+import { rng } from './rng';
+
+
+const CHARS = '0123456789abcdef';
+
+
+export default (length: number, seed?: string) => {
+    if (length <= 0) {
+        throw new Error('@esportsplus/random: length must be positive');
+    }
+
+    let result = '';
+
+    for (let i = 0; i < length; i++) {
+        result += CHARS[(rng(seed) * 16) >>> 0];
+    }
+
+    return result;
+};

package/src/index.ts

@@ -1,8 +1,16 @@
+import alphanumeric from './alphanumeric';
+import between from './between';
 import coinflip from './coinflip';
+import exponential from './exponential';
+import gaussian from './gaussian';
+import groups from './groups';
+import hex from './hex';
 import item from './item';
+import pick from './pick';
 import range from './range';
 import roll from './roll';
+import sample from './sample';
 import shuffle from './shuffle';
 
 
-export { coinflip, item, range, roll, shuffle };
+export { alphanumeric, between, coinflip, exponential, gaussian, groups, hex, item, pick, range, roll, sample, shuffle };

package/src/item.ts

@@ -1,33 +1,27 @@
-import { rng } from '@esportsplus/crypto';
+import { rng } from './rng';
 
 
-export default <T>(items: T[], weights?: number[]): T => {
-    if (weights === undefined) {
-        return items[ Math.floor(rng() * items.length) ];
+export default <T>(map: Map<T, number>, seed?: string): T => {
+    if (map.size === 0) {
+        throw new Error('@esportsplus/random: map cannot be empty');
     }
 
-    let n = items.length,
-        random = 0;
+    let current = 0,
+        total = 0;
 
-    if (n !== weights.length) {
-        throw new Error('Random: each item requires a weight');
+    for (let weight of map.values()) {
+        total += weight;
     }
 
-    for (let i = 0; i < n; i++) {
-        random += weights[i];
-    }
-
-    let current = 0;
-
-    random *= rng();
+    let random = rng(seed) * total;
 
-    for (let i = 0; i < n; i++) {
-        current += weights[i];
+    for (let [item, weight] of map) {
+        current += weight;
 
         if (random <= current) {
-            return items[i];
+            return item;
         }
     }
 
-    throw new Error('Random: weighted item pick failed');
+    throw new Error('@esportsplus/random: weighted item pick failed');
 };

package/src/pick.ts

@@ -0,0 +1,21 @@
+import { rng } from './rng';
+
+
+export default <T>(items: T[], count: number, seed?: string): T[] => {
+    if (items.length === 0) {
+        throw new Error('@esportsplus/random: items cannot be empty');
+    }
+
+    if (count <= 0) {
+        throw new Error('@esportsplus/random: count must be positive');
+    }
+
+    let n = items.length,
+        result: T[] = [];
+
+    for (let i = 0; i < count; i++) {
+        result.push(items[(rng(seed) * n) >>> 0]);
+    }
+
+    return result;
+};

package/src/range.ts

@@ -1,13 +1,17 @@
-import { rng } from '@esportsplus/crypto';
+import { rng } from './rng';
 
 
-export default (min: number, max: number, integer = false) => {
+export default (min: number, max: number, integer = false, seed?: string) => {
+    if (min > max) {
+        throw new Error('@esportsplus/random: min cannot be greater than max');
+    }
+
     if (!integer) {
-        return rng() * (max - min) + min;
+        return rng(seed) * (max - min) + min;
     }
 
     min = Math.ceil(min);
     max = Math.floor(max) + 1;
 
-    return Math.floor(rng() * (max - min) + min);
+    return Math.floor(rng(seed) * (max - min) + min);
 };

package/src/rng.ts

@@ -0,0 +1,79 @@
+const MAX = 0xFFFFFFFF;
+
+const RNG_BUFFER = new Uint32Array(1);
+
+const SEED_BUFFER = new Uint8Array(32);
+
+
+function cyrb128(str: string): [number, number, number, number] {
+    let h1 = 1779033703,
+        h2 = 3144134277,
+        h3 = 1013904242,
+        h4 = 2773480762;
+
+    for (let i = 0, n = str.length; i < n; i++) {
+        let k = str.charCodeAt(i);
+
+        h1 = h2 ^ Math.imul(h1 ^ k, 597399067);
+        h2 = h3 ^ Math.imul(h2 ^ k, 2869860233);
+        h3 = h4 ^ Math.imul(h3 ^ k, 951274213);
+        h4 = h1 ^ Math.imul(h4 ^ k, 2716044179);
+    }
+
+    h1 = Math.imul(h3 ^ (h1 >>> 18), 597399067);
+    h2 = Math.imul(h4 ^ (h2 >>> 22), 2869860233);
+    h3 = Math.imul(h1 ^ (h3 >>> 17), 951274213);
+    h4 = Math.imul(h2 ^ (h4 >>> 19), 2716044179);
+
+    h1 ^= (h2 ^ h3 ^ h4);
+    h2 ^= h1;
+    h3 ^= h1;
+    h4 ^= h1;
+
+    return [h1 >>> 0, h2 >>> 0, h3 >>> 0, h4 >>> 0];
+}
+
+function sfc32(a: number, b: number, c: number, d: number): () => number {
+    return () => {
+        a >>>= 0;
+        b >>>= 0;
+        c >>>= 0;
+        d >>>= 0;
+
+        let t = (a + b) | 0;
+
+        a = b ^ b >>> 9;
+        b = c + (c << 3) | 0;
+        c = (c << 21 | c >>> 11);
+        d = d + 1 | 0;
+        t = t + d | 0;
+        c = c + t | 0;
+
+        return (t >>> 0) / MAX;
+    };
+}
+
+
+function rng(seed?: string): number {
+    if (seed) {
+        let [a, b, c, d] = cyrb128(seed);
+
+        return sfc32(a, b, c, d)();
+    }
+
+    return crypto.getRandomValues(RNG_BUFFER)[0] / MAX;
+}
+
+rng.seed = () => {
+    let bytes = crypto.getRandomValues(SEED_BUFFER),
+        hex = '';
+
+    for (let i = 0, n = bytes.length; i < n; i++) {
+        hex += bytes[i].toString(16).padStart(2, '0');
+    }
+
+    return hex;
+};
+
+
+export { rng };

package/src/roll.ts

@@ -1,6 +1,10 @@
-import { rng } from '@esportsplus/crypto';
+import { rng } from './rng';
 
 
-export default (percentage: number) => {
-    return rng() <= percentage;
+export default (numerator: number, denominator: number, seed?: string) => {
+    if (numerator <= 0 || denominator <= 0) {
+        throw new Error('@esportsplus/random: numerator and denominator must be positive');
+    }
+
+    return rng(seed) <= (numerator / denominator);
 };

package/src/sample.ts

@@ -0,0 +1,20 @@
+import shuffle from './shuffle';
+
+
+export default <T>(items: T[], count: number, seed?: string): T[] => {
+    let n = items.length;
+
+    if (n === 0) {
+        throw new Error('@esportsplus/random: items cannot be empty');
+    }
+
+    if (count <= 0) {
+        throw new Error('@esportsplus/random: count must be positive');
+    }
+
+    if (count > n) {
+        throw new Error('@esportsplus/random: count cannot exceed items length');
+    }
+
+    return shuffle([...items], seed).slice(0, count);
+};

package/src/shuffle.ts

@@ -1,15 +1,19 @@
-import { rng } from '@esportsplus/crypto';
+import { rng } from './rng';
 
 
 // Fisher-Yates shuffle
 // - https://wikipedia.org/wiki/Fisher-Yates_shuffle
-export default (values: any[]) => {
+export default <T>(values: T[], seed?: string): T[] => {
+    if (values.length === 0) {
+        return values;
+    }
+
     let n = values.length,
         random: number,
-        value;
+        value: T;
 
     while (--n > 0) {
-        random = Math.floor(rng() * (n + 1));
+        random = (rng(seed) * (n + 1)) >>> 0;
         value = values[random];
 
         values[random] = values[n];