typescript

nicerand (TypeScript)

A "nice" random library for games - random selection with memory to prevent frustrating repeats.

Features

• Weighted random selection - Perfect for loot tables
• Cooldown system - Prevent items from repeating too soon
• Shuffle bag mode - Guarantee all items appear before repeats
• Seeding support - Deterministic output for testing/replays
• TypeScript native - Full type safety
• Zero dependencies - Lightweight and fast
• Works everywhere - Node.js and browsers

Installation

npm install nicerand

Quick Start

import { NiceRandom } from 'nicerand';

// Default cooldown is 1 (no immediate repeats)
const picker = new NiceRandom(['a', 'b', 'c', 'd']);
const item = picker.pick();  // Won't get the same item twice in a row

// Weighted loot table
const loot = new NiceRandom({
  'Gold Coins': 10,    // Very common
  'Magic Sword': 2,    // Rare
  'Legendary Armor': 1 // Very rare
});
const drop = loot.pick();

// Shuffle bag (all items before any repeat)
const pieces = new NiceRandom(['I', 'O', 'T', 'S', 'Z', 'J', 'L'], {
  cooldown: 7  // Set to array length for full rotation
});

API

Constructor

new NiceRandom<T>(items: T[] | Record<string, number>, options?: {
  cooldown?: number;  // Default: 1 (no immediate repeats). Set to items.length for shuffle bag.
  seed?: number;      // Optional seed for deterministic output
})

Methods

• pick(): T - Pick a random item
• pickN(n: number): T[] - Pick n items sequentially
• reset(): void - Clear history
• getItems(): T[] - Get all items
• getHistory(): T[] - Get recent picks
• get cooldown(): number - Get cooldown setting
• get size(): number - Get pool size

Examples

See examples/basic_usage.ts for comprehensive examples including:

• Music playlist rotation
• Weighted loot drops
• Shuffle bag (full rotation)
• Enemy attack patterns
• Comparison with true random

Run examples:

npm run example

Development

# Install dependencies
npm install

# Run tests
npm test

# Build
npm run build

# Type check
npm run typecheck

License

MIT