v1.1.0

What's Changed

• Adds custom dice support with presets by @risadams in #4

Full Changelog: v1.0.0...v1.1.0

V1.1.2

What's Changed

• Enhances CLI with Verbose Output and New Commands by @risadams in #5

Full Changelog: V1.1.1...V1.1.2

V1.1.1

Patch:
added scrum and fib to CLI roller
Full Changelog: v1.1.0...V1.1.1

v1.0.0

Release Notes - v1.0.0 🎲

Release Date: August 26, 2025

We're excited to announce the first stable release of the Dice Roller TypeScript Library - an elegant, sophisticated dice rolling solution for tabletop RPGs, games, and any application requiring advanced dice mechanics.

🎯 What's New

Core Library Features

• Complete TypeScript Implementation: Converted from C# with full type safety and strict mode compliance
• Four Main Classes: Roller, Die, DiceExpression, and DiceExpressionPart providing comprehensive dice functionality
• Zero Dependencies: Lightweight library with no external runtime dependencies
• Full Type Definitions: Complete TypeScript support with exported type definitions

Dice Rolling Capabilities

• Standard Dice Support: d4, d6, d8, d10, d12, d20, d100
• Complex Expressions: Parse and evaluate expressions like "3d6+5", "2d8-1d4+3"
• Mathematical Operations: Addition, subtraction, multiplication, and division in dice expressions
• Statistical Analysis: Generate comprehensive statistics for any dice expression

Advanced Mechanics

• Advantage/Disadvantage: D&D 5e style rolling (roll twice, take higher/lower)
• Keep Highest/Lowest: Roll multiple dice and keep only the best/worst results
• Exploding Dice: Reroll dice on maximum values with configurable explosion limits
• Custom Random Functions: Use your own random number generator for deterministic or seeded results

Command Line Interface

• npx Support: Try the library instantly without installation using npx @risadams/dice-roller
• Interactive Demo: Built-in demo mode showcasing all features
• Flexible Commands: Support for expressions, specific dice types, and advanced mechanics
• Statistical Analysis: Command-line statistics generation with distribution visualization

🛡️ Security & Reliability

ReDoS Protection

• Expression Length Limits: Maximum 1000 character expressions to prevent ReDoS attacks
• Optimized Regex Patterns: Carefully crafted patterns that avoid exponential backtracking
• Input Validation: Comprehensive validation with descriptive error messages

Robust Error Handling

• Zero Dice Validation: ✨ NEW - Prevents rolling 0 dice with clear error: "At least one die is required"
• Invalid Expression Detection: Catches malformed dice expressions with helpful error messages
• Type Safety: TypeScript strict mode prevents common runtime errors

Comprehensive Testing

• 100% Test Coverage: Every function and edge case thoroughly tested with Jest
• 42 Test Cases: Covering normal usage, edge cases, and error conditions
• Performance Testing: Ensures ReDoS protection doesn't impact performance

📚 Developer Experience

Rich API Design

import { Roller, DiceExpression, Die } from '@risadams/dice-roller';

const roller = new Roller();

// Simple rolling
const attack = roller.rollExpression('1d20+5');

// Advanced mechanics  
const advantage = roller.rollWithAdvantage(20);
const abilityScore = roller.rollKeepHighest(4, 6, 3);

// Statistical analysis
const stats = roller.getStatistics('3d6', 1000);

Detailed Results

const detailed = roller.rollExpressionDetailed('2d8+1d4-2');
// Returns: result, expression, minValue, maxValue, and breakdown of each part

Flexible Configuration

// Use custom random function for deterministic results
const seededRoller = new Roller(() => 0.5);

🎮 Usage Examples

Tabletop RPG Integration

# Character creation
npx @risadams/dice-roller "4d6" # Ability scores

# Combat mechanics  
npx @risadams/dice-roller advantage d20 # Attack with advantage
npx @risadams/dice-roller "1d8+3" # Weapon damage

Game Development

// Procedural generation
const treasureValue = roller.rollExpression('3d6*10');
const encounterDifficulty = roller.rollWithAdvantage(10);

// Balanced randomness
const damage = roller.rollKeepHighest(3, 6, 2); // Roll 3d6, keep best 2

📊 Performance & Quality

• Fast Execution: Sub-millisecond performance for complex expressions
• Memory Efficient: Minimal memory footprint with no memory leaks
• Browser Compatible: Works in Node.js and modern browsers
• ES2020 Target: Modern JavaScript features with broad compatibility

🚀 Installation & Usage

Quick Try (No Installation)

npx @risadams/dice-roller "3d6+5"
npx @risadams/dice-roller demo

Install for Projects

npm install @risadams/dice-roller

Import and Use

import { Roller } from '@risadams/dice-roller';
const roller = new Roller();
console.log(roller.rollExpression('3d6+5'));

🔧 Development & Contribution

• MIT Licensed: Open source with permissive licensing
• TypeScript First: Built with TypeScript for TypeScript developers
• Jest Testing: Comprehensive test suite using industry standard tools
• GitHub Actions: Automated testing and quality checks
• Contribution Guidelines: Clear guidelines for community contributions

📋 What's Included

• ✅ Core dice rolling engine (Roller class)
• ✅ Individual die mechanics (Die class)
• ✅ Complex expression parsing (DiceExpression class)
• ✅ Expression component system (DiceExpressionPart class)
• ✅ Command-line interface with npx support
• ✅ Statistical analysis tools
• ✅ Advanced rolling mechanics
• ✅ Comprehensive documentation
• ✅ 100% test coverage
• ✅ Security hardening against ReDoS attacks
• ✅ Zero dice validation and error handling

🎯 Target Audience

• Game Developers: Building games with dice mechanics
• RPG Applications: Digital character sheets, VTTs, dice bots
• Educational Tools: Probability and statistics demonstrations
• Simulation Software: Monte Carlo simulations using dice
• CLI Users: Quick dice rolling from the command line

🔮 Looking Forward

This v1.0.0 release represents a stable, production-ready foundation. The API is considered stable and suitable for production use. Future releases will focus on additional mechanics, performance optimizations, and community-requested features while maintaining backward compatibility.

---

Get Started: npx @risadams/dice-roller demo

Documentation: GitHub Repository

Support: Open an issue on GitHub for questions or bug reports

License: MIT - free for commercial and personal use