@esportsplus/random 0.0.32 → 0.0.33

package/README.md

@@ -2,7 +2,7 @@
 
 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.
+All functions accept an optional `seed` string as the last argument for reproducible results.
 
 ---
 
@@ -108,6 +108,22 @@ range(1, 10, true, 'seed'); // Reproducible integer
 
 ---
 
+### `rng(seed?)`
+Core random number generator. Returns a number in `[0, 1)`. Without a seed, uses `crypto.getRandomValues`. With a seed, uses a deterministic PRNG (cyrb128 + sfc32).
+
+```ts
+rng();            // 0.7234... (crypto random)
+rng('my-seed');   // Deterministic result
+```
+
+`rng.seed()` generates a cryptographically secure 64-character hex string.
+
+```ts
+rng.seed();  // 'a1b2c3d4e5f6...' (64 chars)
+```
+
+---
+
 ### `roll(numerator, denominator, seed?)`
 Roll "N in D" chance.
 
@@ -137,251 +153,21 @@ shuffle([1, 2, 3, 4, 5]);  // [3, 1, 5, 2, 4]
 
 ---
 
-### `uuid(seed?)`
-Generate UUID v4.
-
-```ts
-uuid();  // "550e8400-e29b-41d4-a716-446655440000"
-```
-
----
+## Seeded Mode
 
-## 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)
-```
+All functions accept an optional `seed` string as the last argument. Same seed = same result, enabling reproducible and provably fair outcomes.
 
 ```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
+range(1, 100, true, 'my-seed');  // Always the same integer
+shuffle([1, 2, 3, 4, 5], 'my-seed');  // Always the same order
 ```
 
 ---
 
-### 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
+## Testing
 
-**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 };
+```bash
+pnpm test
 ```
 
-**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
-```
+90 tests across 14 files covering all 13 modules — determinism, error paths, edge cases, and statistical validation.

package/build/index.d.ts

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

package/build/index.js

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

package/package.json

@@ -1,7 +1,8 @@
 {
   "author": "ICJR",
   "devDependencies": {
-    "@esportsplus/typescript": "^0.9.2"
+    "@esportsplus/typescript": "^0.9.2",
+    "vitest": "^4.1.1"
   },
   "main": "build/index.js",
   "name": "@esportsplus/random",
@@ -12,9 +13,10 @@
   },
   "type": "module",
   "types": "build/index.d.ts",
-  "version": "0.0.32",
+  "version": "0.0.33",
   "scripts": {
     "build": "tsc && tsc-alias",
+    "test": "vitest run",
     "-": "-"
   }
 }

package/src/index.ts

@@ -1,3 +1,5 @@
+import { rng } from './rng';
+
 import alphanumeric from './alphanumeric';
 import between from './between';
 import coinflip from './coinflip';
@@ -13,4 +15,4 @@ import sample from './sample';
 import shuffle from './shuffle';
 
 
-export { alphanumeric, between, coinflip, exponential, gaussian, groups, hex, item, pick, range, roll, sample, shuffle };
+export { alphanumeric, between, coinflip, exponential, gaussian, groups, hex, item, pick, range, rng, roll, sample, shuffle };

package/tests/alphanumeric.ts

@@ -0,0 +1,45 @@
+import { describe, expect, it } from 'vitest';
+
+import alphanumeric from '~/alphanumeric';
+
+
+describe('alphanumeric', () => {
+    describe('validation', () => {
+        it('throws when length is 0', () => {
+            expect(() => alphanumeric(0)).toThrow('@esportsplus/random: length must be positive');
+        });
+
+        it('throws when length is negative', () => {
+            expect(() => alphanumeric(-1)).toThrow('@esportsplus/random: length must be positive');
+        });
+    });
+
+    describe('output', () => {
+        it('returns string of correct length', () => {
+            expect(alphanumeric(10)).toHaveLength(10);
+        });
+
+        it('contains only alphanumeric characters', () => {
+            let result = alphanumeric(200);
+
+            expect(result).toMatch(/^[0-9A-Za-z]+$/);
+        });
+
+        it('handles length of 1', () => {
+            expect(alphanumeric(1)).toHaveLength(1);
+        });
+
+        it('handles length of 100', () => {
+            expect(alphanumeric(100)).toHaveLength(100);
+        });
+    });
+
+    describe('determinism', () => {
+        it('same seed produces same string', () => {
+            let a = alphanumeric(20, 'test-seed'),
+                b = alphanumeric(20, 'test-seed');
+
+            expect(a).toBe(b);
+        });
+    });
+});

package/tests/between.ts

@@ -0,0 +1,57 @@
+import { describe, expect, it } from 'vitest';
+
+import between from '~/between';
+
+
+describe('between', () => {
+    it('throws with less than 2 items', () => {
+        expect(() => between([])).toThrow('@esportsplus/random: need at least 2 items');
+        expect(() => between([1])).toThrow('@esportsplus/random: need at least 2 items');
+    });
+
+    it('returns both items when exactly 2', () => {
+        let result = between([1, 2], 'seed');
+
+        expect(result).toHaveLength(2);
+        expect(result.slice().sort((a, b) => a - b)).toEqual([1, 2]);
+    });
+
+    it('returns two different items', () => {
+        let items = [10, 20, 30, 40, 50],
+            result = between(items, 'seed');
+
+        expect(result[0]).not.toBe(result[1]);
+    });
+
+    it('is deterministic with same seed', () => {
+        let a = between([10, 20, 30, 40, 50], 'seed'),
+            b = between([10, 20, 30, 40, 50], 'seed');
+
+        expect(a).toEqual(b);
+        expect(a).toEqual([10, 20]);
+    });
+
+    it('seeded rng is stateless so same seed same rng value', () => {
+        // rng(seed) returns the same value for the same seed (no state progression)
+        // first = (r * n) >>> 0, second = (r * (n-1)) >>> 0
+        // These may differ due to different multipliers, but are deterministic
+        let items = ['a', 'b', 'c', 'd', 'e'];
+
+        for (let i = 0; i < 20; i++) {
+            let seed = `test-${i}`,
+                a = between(items, seed),
+                b = between(items, seed);
+
+            expect(a).toEqual(b);
+            expect(a[0]).not.toBe(a[1]);
+        }
+    });
+
+    it('returns items from the input array', () => {
+        let items = [10, 20, 30, 40, 50],
+            result = between(items, 'check');
+
+        expect(items).toContain(result[0]);
+        expect(items).toContain(result[1]);
+    });
+});

package/tests/coinflip.ts

@@ -0,0 +1,36 @@
+import { describe, expect, it } from 'vitest';
+
+import coinflip from '~/coinflip';
+
+
+describe('coinflip', () => {
+    describe('output', () => {
+        it('returns a boolean', () => {
+            expect(typeof coinflip()).toBe('boolean');
+        });
+    });
+
+    describe('determinism', () => {
+        it('same seed produces same result', () => {
+            let a = coinflip('test-seed'),
+                b = coinflip('test-seed');
+
+            expect(a).toBe(b);
+        });
+    });
+
+    describe('distribution', () => {
+        it('roughly 50% true over 1000 trials', () => {
+            let trueCount = 0;
+
+            for (let i = 0; i < 1000; i++) {
+                if (coinflip()) {
+                    trueCount++;
+                }
+            }
+
+            expect(trueCount).toBeGreaterThan(350);
+            expect(trueCount).toBeLessThan(650);
+        });
+    });
+});

package/tests/exponential.ts

@@ -0,0 +1,52 @@
+import { describe, expect, it } from 'vitest';
+
+import exponential from '~/exponential';
+
+
+describe('exponential', () => {
+    describe('lambda <= 0 throws', () => {
+        it('throws when lambda is zero', () => {
+            expect(() => exponential(0)).toThrow('@esportsplus/random: lambda must be positive');
+        });
+
+        it('throws when lambda is negative', () => {
+            expect(() => exponential(-1)).toThrow('@esportsplus/random: lambda must be positive');
+        });
+    });
+
+    describe('returns positive number', () => {
+        it('output is always > 0', () => {
+            for (let i = 0; i < 100; i++) {
+                expect(exponential(1)).toBeGreaterThan(0);
+            }
+        });
+    });
+
+    describe('deterministic with seed', () => {
+        it('same seed produces same output', () => {
+            let a = exponential(1, 'fixed'),
+                b = exponential(1, 'fixed'),
+                c = exponential(1, 'fixed');
+
+            expect(a).toBe(b);
+            expect(b).toBe(c);
+        });
+    });
+
+    describe('statistical validation', () => {
+        it('sample mean approximates 1/lambda', () => {
+            let lambda = 1,
+                n = 10000,
+                sum = 0;
+
+            for (let i = 0; i < n; i++) {
+                sum += exponential(lambda);
+            }
+
+            let sampleMean = sum / n;
+
+            expect(sampleMean).toBeGreaterThan(0.9);
+            expect(sampleMean).toBeLessThan(1.1);
+        });
+    });
+});

package/tests/gaussian.ts

@@ -0,0 +1,73 @@
+import { describe, expect, it } from 'vitest';
+
+import gaussian from '~/gaussian';
+
+
+describe('gaussian', () => {
+    describe('negative stddev throws', () => {
+        it('throws when stddev is negative', () => {
+            expect(() => gaussian(0, -1)).toThrow('@esportsplus/random: stddev cannot be negative');
+        });
+    });
+
+    describe('zero stddev', () => {
+        it('always returns mean exactly', () => {
+            expect(gaussian(5, 0, 'seed-a')).toBe(5);
+            expect(gaussian(100, 0, 'seed-b')).toBe(100);
+            expect(gaussian(-3, 0, 'seed-c')).toBe(-3);
+        });
+    });
+
+    describe('deterministic with seed', () => {
+        it('same seed produces same output', () => {
+            let a = gaussian(10, 5, 'fixed'),
+                b = gaussian(10, 5, 'fixed'),
+                c = gaussian(10, 5, 'fixed');
+
+            expect(a).toBe(b);
+            expect(b).toBe(c);
+        });
+    });
+
+    describe('returns a number', () => {
+        it('output is of type number', () => {
+            expect(typeof gaussian(0, 1)).toBe('number');
+            expect(typeof gaussian(50, 10, 'seed')).toBe('number');
+        });
+    });
+
+    describe('statistical validation', () => {
+        it('sample mean and stddev approximate parameters', () => {
+            let mean = 100,
+                n = 10000,
+                stddev = 10,
+                values: number[] = [];
+
+            for (let i = 0; i < n; i++) {
+                values.push(gaussian(mean, stddev));
+            }
+
+            let sum = 0;
+
+            for (let i = 0; i < n; i++) {
+                sum += values[i];
+            }
+
+            let sampleMean = sum / n,
+                sumSq = 0;
+
+            for (let i = 0; i < n; i++) {
+                let diff = values[i] - sampleMean;
+
+                sumSq += diff * diff;
+            }
+
+            let sampleStddev = Math.sqrt(sumSq / (n - 1));
+
+            expect(sampleMean).toBeGreaterThan(mean - 2);
+            expect(sampleMean).toBeLessThan(mean + 2);
+            expect(sampleStddev).toBeGreaterThan(stddev - 3);
+            expect(sampleStddev).toBeLessThan(stddev + 3);
+        });
+    });
+});

package/tests/groups.ts

@@ -0,0 +1,67 @@
+import { describe, expect, it } from 'vitest';
+
+import groups from '~/groups';
+
+
+describe('groups', () => {
+    it('throws when total is 0 or negative', () => {
+        expect(() => groups([1, 2, 3], 0)).toThrow('@esportsplus/random: total must be positive');
+        expect(() => groups([1, 2, 3], -1)).toThrow('@esportsplus/random: total must be positive');
+    });
+
+    it('divides evenly', () => {
+        let result = groups([1, 2, 3, 4, 5, 6], 3, 'seed');
+
+        expect(result).toHaveLength(3);
+
+        for (let i = 0, n = result.length; i < n; i++) {
+            expect(result[i]).toHaveLength(2);
+        }
+    });
+
+    it('handles uneven division with all items present', () => {
+        let result = groups([1, 2, 3, 4, 5, 6, 7], 3, 'seed');
+
+        expect(result).toHaveLength(3);
+
+        let flat = result.flat().sort((a, b) => a - b);
+
+        expect(flat).toEqual([1, 2, 3, 4, 5, 6, 7]);
+    });
+
+    it('preserves all items across groups', () => {
+        let input = [1, 2, 3, 4, 5, 6];
+        let result = groups(input, 3, 'seed');
+        let flat = result.flat().sort((a, b) => a - b);
+
+        expect(flat).toEqual([1, 2, 3, 4, 5, 6]);
+    });
+
+    it('is deterministic with same seed', () => {
+        let a = groups([1, 2, 3, 4, 5, 6], 3, 'seed'),
+            b = groups([1, 2, 3, 4, 5, 6], 3, 'seed');
+
+        expect(a).toEqual(b);
+        expect(a).toEqual([[2, 3], [4, 5], [6, 1]]);
+    });
+
+    it('produces empty groups when more groups than items', () => {
+        let result = groups([1, 2], 5, 'seed');
+
+        expect(result).toHaveLength(5);
+
+        let flat = result.flat().sort((a, b) => a - b);
+
+        expect(flat).toEqual([1, 2]);
+
+        let emptyCount = 0;
+
+        for (let i = 0, n = result.length; i < n; i++) {
+            if (result[i].length === 0) {
+                emptyCount++;
+            }
+        }
+
+        expect(emptyCount).toBeGreaterThan(0);
+    });
+});

package/tests/hex.ts

@@ -0,0 +1,45 @@
+import { describe, expect, it } from 'vitest';
+
+import hex from '~/hex';
+
+
+describe('hex', () => {
+    describe('validation', () => {
+        it('throws when length is 0', () => {
+            expect(() => hex(0)).toThrow('@esportsplus/random: length must be positive');
+        });
+
+        it('throws when length is negative', () => {
+            expect(() => hex(-1)).toThrow('@esportsplus/random: length must be positive');
+        });
+    });
+
+    describe('output', () => {
+        it('returns string of correct length', () => {
+            expect(hex(10)).toHaveLength(10);
+        });
+
+        it('contains only lowercase hex characters', () => {
+            let result = hex(200);
+
+            expect(result).toMatch(/^[0-9a-f]+$/);
+        });
+
+        it('handles length of 1', () => {
+            expect(hex(1)).toHaveLength(1);
+        });
+
+        it('handles length of 64', () => {
+            expect(hex(64)).toHaveLength(64);
+        });
+    });
+
+    describe('determinism', () => {
+        it('same seed produces same string', () => {
+            let a = hex(32, 'test-seed'),
+                b = hex(32, 'test-seed');
+
+            expect(a).toBe(b);
+        });
+    });
+});

package/tests/item.ts

@@ -0,0 +1,86 @@
+import { describe, expect, it } from 'vitest';
+
+import item from '~/item';
+
+
+describe('item', () => {
+    describe('empty map throws', () => {
+        it('throws when map has no entries', () => {
+            expect(() => item(new Map())).toThrow('@esportsplus/random: map cannot be empty');
+        });
+    });
+
+    describe('single item map', () => {
+        it('always returns the only item', () => {
+            let map = new Map([['only', 1]]);
+
+            for (let i = 0; i < 50; i++) {
+                expect(item(map)).toBe('only');
+            }
+        });
+    });
+
+    describe('weighted selection with seed', () => {
+        it('same seed produces same result', () => {
+            let map = new Map([['a', 1], ['b', 2], ['c', 3]]),
+                a = item(map, 'deterministic'),
+                b = item(map, 'deterministic'),
+                c = item(map, 'deterministic');
+
+            expect(a).toBe(b);
+            expect(b).toBe(c);
+        });
+    });
+
+    describe('multiple items', () => {
+        it('result is always one of the map keys', () => {
+            let keys = ['x', 'y', 'z'],
+                map = new Map([['x', 1], ['y', 1], ['z', 1]]);
+
+            for (let i = 0; i < 100; i++) {
+                expect(keys).toContain(item(map));
+            }
+        });
+    });
+
+    describe('zero weight item', () => {
+        it('item with weight 0 is almost never selected', () => {
+            let map = new Map([['zero', 0], ['heavy', 100]]),
+                zeroCount = 0;
+
+            for (let i = 0; i < 1000; i++) {
+                if (item(map) === 'zero') {
+                    zeroCount++;
+                }
+            }
+
+            expect(zeroCount).toBeLessThan(5);
+        });
+    });
+
+    describe('fallback throw with negative weights', () => {
+        it('throws when weighted pick fails due to negative weights', () => {
+            let map = new Map([['a', -10], ['b', 1]]);
+
+            expect(() => item(map, 'any-seed')).toThrow('@esportsplus/random: weighted item pick failed');
+        });
+    });
+
+    describe('equal weights', () => {
+        it('all items are roughly equally likely', () => {
+            let counts: Record<string, number> = { a: 0, b: 0, c: 0 },
+                map = new Map([['a', 1], ['b', 1], ['c', 1]]),
+                n = 3000;
+
+            for (let i = 0; i < n; i++) {
+                let result = item(map);
+
+                counts[result]++;
+            }
+
+            for (let key of Object.keys(counts)) {
+                expect(counts[key] / n).toBeGreaterThan(0.15);
+            }
+        });
+    });
+});

package/tests/pick.ts

@@ -0,0 +1,57 @@
+import { describe, expect, it } from 'vitest';
+
+import pick from '~/pick';
+
+
+describe('pick', () => {
+    describe('validation', () => {
+        it('throws when items array is empty', () => {
+            expect(() => pick([], 1)).toThrow('@esportsplus/random: items cannot be empty');
+        });
+
+        it('throws when count is 0', () => {
+            expect(() => pick([1], 0)).toThrow('@esportsplus/random: count must be positive');
+        });
+
+        it('throws when count is negative', () => {
+            expect(() => pick([1], -1)).toThrow('@esportsplus/random: count must be positive');
+        });
+    });
+
+    describe('output', () => {
+        it('returns correct count of items', () => {
+            let result = pick([1, 2, 3], 5);
+
+            expect(result).toHaveLength(5);
+        });
+
+        it('all returned items exist in source array', () => {
+            let items = ['a', 'b', 'c', 'd'],
+                result = pick(items, 20);
+
+            for (let i = 0, n = result.length; i < n; i++) {
+                expect(items).toContain(result[i]);
+            }
+        });
+
+        it('allows duplicates when count exceeds items length', () => {
+            let items = [1, 2],
+                result = pick(items, 100);
+
+            expect(result).toHaveLength(100);
+
+            for (let i = 0, n = result.length; i < n; i++) {
+                expect(items).toContain(result[i]);
+            }
+        });
+    });
+
+    describe('determinism', () => {
+        it('same seed produces same result', () => {
+            let a = pick([1, 2, 3, 4, 5], 3, 'test-seed'),
+                b = pick([1, 2, 3, 4, 5], 3, 'test-seed');
+
+            expect(a).toEqual(b);
+        });
+    });
+});

package/tests/range.ts

@@ -0,0 +1,75 @@
+import { describe, expect, it } from 'vitest';
+
+import range from '~/range';
+
+
+describe('range', () => {
+    it('throws when min is greater than max', () => {
+        expect(() => range(5, 3)).toThrow('@esportsplus/random: min cannot be greater than max');
+    });
+
+    it('returns float in [min, max] by default', () => {
+        for (let i = 0; i < 100; i++) {
+            let result = range(1, 10);
+
+            expect(result).toBeGreaterThanOrEqual(1);
+            expect(result).toBeLessThanOrEqual(10);
+        }
+    });
+
+    it('returns integer in integer mode', () => {
+        for (let i = 0; i < 100; i++) {
+            let result = range(1, 10, true);
+
+            expect(Number.isInteger(result)).toBe(true);
+            expect(result).toBeGreaterThanOrEqual(1);
+            expect(result).toBeLessThanOrEqual(10);
+        }
+    });
+
+    it('returns min when min equals max in float mode', () => {
+        let result = range(5, 5, false, 'seed');
+
+        expect(result).toBe(5);
+    });
+
+    it('returns min when min equals max in integer mode', () => {
+        let result = range(5, 5, true, 'seed');
+
+        expect(result).toBe(5);
+    });
+
+    it('is deterministic with same seed', () => {
+        let a = range(1, 10, false, 'seed'),
+            b = range(1, 10, false, 'seed');
+
+        expect(a).toBe(b);
+        expect(a).toBeCloseTo(2.2514521240376526);
+
+        let c = range(1, 10, true, 'seed'),
+            d = range(1, 10, true, 'seed');
+
+        expect(c).toBe(d);
+        expect(c).toBe(2);
+    });
+
+    it('handles fractional min/max in integer mode', () => {
+        // range(1.5, 2.5, true) → ceil(1.5)=2, floor(2.5)+1=3, so only 2 is possible
+        for (let i = 0; i < 50; i++) {
+            expect(range(1.5, 2.5, true)).toBe(2);
+        }
+    });
+
+    it('returns 0 or 1 for range(0, 1, true)', () => {
+        let seen = new Set<number>();
+
+        for (let i = 0; i < 100; i++) {
+            let result = range(0, 1, true);
+
+            expect(result === 0 || result === 1).toBe(true);
+            seen.add(result);
+        }
+
+        expect(seen.size).toBe(2);
+    });
+});

package/tests/rng.ts

@@ -0,0 +1,78 @@
+import { describe, expect, it } from 'vitest';
+import { rng } from '~/rng';
+
+
+describe('rng', () => {
+    describe('determinism', () => {
+        it('same seed always returns same value', () => {
+            let a = rng('test-seed'),
+                b = rng('test-seed'),
+                c = rng('test-seed');
+
+            expect(a).toBe(b);
+            expect(b).toBe(c);
+        });
+    });
+
+    describe('different seeds produce different values', () => {
+        it('distinct seeds yield distinct outputs', () => {
+            let a = rng('seed-a'),
+                b = rng('seed-b');
+
+            expect(a).not.toBe(b);
+        });
+    });
+
+    describe('output range', () => {
+        it('seeded output is in [0, 1)', () => {
+            let seeds = ['alpha', 'beta', 'gamma', 'delta', 'epsilon', 'zeta', 'eta', 'theta'];
+
+            for (let i = 0, n = seeds.length; i < n; i++) {
+                let value = rng(seeds[i]);
+
+                expect(value).toBeGreaterThanOrEqual(0);
+                expect(value).toBeLessThan(1);
+            }
+        });
+    });
+
+    describe('unseeded path', () => {
+        it('returns a number in [0, 1)', () => {
+            for (let i = 0; i < 100; i++) {
+                let value = rng();
+
+                expect(value).toBeGreaterThanOrEqual(0);
+                expect(value).toBeLessThan(1);
+            }
+        });
+    });
+
+    describe('empty string seed', () => {
+        it('treats empty string as unseeded (falsy)', () => {
+            let results = new Set<number>();
+
+            for (let i = 0; i < 10; i++) {
+                results.add(rng(''));
+            }
+
+            // If seeded, all 10 would be identical. Unseeded → likely all different.
+            expect(results.size).toBeGreaterThan(1);
+        });
+    });
+
+    describe('rng.seed', () => {
+        it('returns a 64-character hex string', () => {
+            let seed = rng.seed();
+
+            expect(seed).toHaveLength(64);
+            expect(seed).toMatch(/^[0-9a-f]{64}$/);
+        });
+
+        it('two calls produce different seeds', () => {
+            let a = rng.seed(),
+                b = rng.seed();
+
+            expect(a).not.toBe(b);
+        });
+    });
+});

package/tests/roll.ts

@@ -0,0 +1,60 @@
+import { describe, expect, it } from 'vitest';
+
+import roll from '~/roll';
+
+
+describe('roll', () => {
+    describe('validation', () => {
+        it('throws when numerator is 0', () => {
+            expect(() => roll(0, 6)).toThrow('@esportsplus/random: numerator and denominator must be positive');
+        });
+
+        it('throws when numerator is negative', () => {
+            expect(() => roll(-1, 6)).toThrow('@esportsplus/random: numerator and denominator must be positive');
+        });
+
+        it('throws when denominator is 0', () => {
+            expect(() => roll(1, 0)).toThrow('@esportsplus/random: numerator and denominator must be positive');
+        });
+
+        it('throws when denominator is negative', () => {
+            expect(() => roll(1, -1)).toThrow('@esportsplus/random: numerator and denominator must be positive');
+        });
+    });
+
+    describe('output', () => {
+        it('returns a boolean', () => {
+            expect(typeof roll(1, 2)).toBe('boolean');
+        });
+
+        it('1/1 always returns true', () => {
+            for (let i = 0; i < 100; i++) {
+                expect(roll(1, 1)).toBe(true);
+            }
+        });
+    });
+
+    describe('determinism', () => {
+        it('same seed produces same result', () => {
+            let a = roll(1, 2, 'test-seed'),
+                b = roll(1, 2, 'test-seed');
+
+            expect(a).toBe(b);
+        });
+    });
+
+    describe('distribution', () => {
+        it('roll(1, 2) is roughly 50% true over 1000 trials', () => {
+            let trueCount = 0;
+
+            for (let i = 0; i < 1000; i++) {
+                if (roll(1, 2)) {
+                    trueCount++;
+                }
+            }
+
+            expect(trueCount).toBeGreaterThan(400);
+            expect(trueCount).toBeLessThan(600);
+        });
+    });
+});

package/tests/sample.ts

@@ -0,0 +1,57 @@
+import { describe, expect, it } from 'vitest';
+
+import sample from '~/sample';
+
+
+describe('sample', () => {
+    it('throws when items is empty', () => {
+        expect(() => sample([], 1)).toThrow('@esportsplus/random: items cannot be empty');
+    });
+
+    it('throws when count is 0 or negative', () => {
+        expect(() => sample([1], 0)).toThrow('@esportsplus/random: count must be positive');
+        expect(() => sample([1], -1)).toThrow('@esportsplus/random: count must be positive');
+    });
+
+    it('throws when count exceeds items length', () => {
+        expect(() => sample([1, 2], 3)).toThrow('@esportsplus/random: count cannot exceed items length');
+    });
+
+    it('returns correct count', () => {
+        let result = sample([1, 2, 3, 4, 5], 3, 'seed');
+
+        expect(result).toHaveLength(3);
+    });
+
+    it('returns no duplicates', () => {
+        let result = sample([1, 2, 3, 4, 5, 6, 7, 8, 9, 10], 5, 'no-dup'),
+            unique = new Set(result);
+
+        expect(unique.size).toBe(result.length);
+    });
+
+    it('returns only items from source', () => {
+        let input = [10, 20, 30, 40, 50],
+            result = sample(input, 3, 'source-check');
+
+        for (let i = 0, n = result.length; i < n; i++) {
+            expect(input).toContain(result[i]);
+        }
+    });
+
+    it('is deterministic with same seed', () => {
+        let a = sample([1, 2, 3, 4, 5], 3, 'seed'),
+            b = sample([1, 2, 3, 4, 5], 3, 'seed');
+
+        expect(a).toEqual(b);
+        expect(a).toEqual([2, 3, 4]);
+    });
+
+    it('returns all items when count equals length', () => {
+        let input = [1, 2, 3, 4, 5],
+            result = sample(input, 5, 'seed');
+
+        expect(result).toHaveLength(5);
+        expect(result.slice().sort((a, b) => a - b)).toEqual([1, 2, 3, 4, 5]);
+    });
+});

package/tests/shuffle.ts

@@ -0,0 +1,67 @@
+import { describe, expect, it } from 'vitest';
+
+import shuffle from '~/shuffle';
+
+
+describe('shuffle', () => {
+    it('returns same empty array', () => {
+        let arr: number[] = [],
+            result = shuffle(arr);
+
+        expect(result).toBe(arr);
+        expect(result).toEqual([]);
+    });
+
+    it('returns array with single element', () => {
+        let arr = [42],
+            result = shuffle(arr);
+
+        expect(result).toEqual([42]);
+    });
+
+    it('preserves all elements', () => {
+        let arr = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10],
+            result = shuffle([...arr], 'preserve-test');
+
+        expect(result.slice().sort((a, b) => a - b)).toEqual(arr);
+    });
+
+    it('mutates in place and returns same reference', () => {
+        let arr = [1, 2, 3, 4, 5],
+            result = shuffle(arr, 'ref-test');
+
+        expect(result).toBe(arr);
+    });
+
+    it('is deterministic with same seed', () => {
+        let a = shuffle([1, 2, 3, 4, 5], 'seed'),
+            b = shuffle([1, 2, 3, 4, 5], 'seed');
+
+        expect(a).toEqual(b);
+        expect(a).toEqual([2, 3, 4, 5, 1]);
+    });
+
+    it('actually shuffles with many elements', () => {
+        let original = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10],
+            differed = false;
+
+        for (let i = 0; i < 10; i++) {
+            let result = shuffle([...original]);
+            let same = true;
+
+            for (let j = 0, n = original.length; j < n; j++) {
+                if (result[j] !== original[j]) {
+                    same = false;
+                    break;
+                }
+            }
+
+            if (!same) {
+                differed = true;
+                break;
+            }
+        }
+
+        expect(differed).toBe(true);
+    });
+});

package/vitest.config.ts

@@ -0,0 +1,14 @@
+import { defineConfig } from 'vitest/config';
+import { resolve } from 'path';
+
+
+export default defineConfig({
+    resolve: {
+        alias: {
+            '~': resolve(import.meta.dirname, 'src')
+        }
+    },
+    test: {
+        include: ['tests/**/*.ts']
+    }
+});