@randsum/roller

Roll dice with a single function call — numbers, notation strings, or options objects. @randsum/roller is the core engine that powers the entire RANDSUM ecosystem: full TypeScript types, strict input validation, and a single dependency (@randsum/notation).

Features

Three input modes — pass a number, a notation string, or a typed options object
Advanced notation — drop/keep, reroll, exploding, compounding, penetrating, cap, replace, unique, count successes
Modifier pipeline — modifiers execute in a defined priority order, composable and predictable
Multiple arguments — combine rolls into a single total: roll('1d20+5', '2d6')
Strict validation — throws on invalid input; validate user strings with isDiceNotation() or validateNotation()
Custom RNG — pass a randomFn for seeded, deterministic, or cryptographic randomness
Universal runtime — works in Node.js, Bun, Deno, browsers, and edge functions

Argument types

Number

Pass a number to roll one die with that many sides.

import { roll } from '@randsum/roller'

const result = roll(20)
console.log(result.total) // 1-20

Notation string

Pass a Randsum Dice Notation string for complex rolls.

import { roll } from '@randsum/roller'

// 4d6, drop the lowest
const abilityScore = roll('4d6L')

// 2d20, keep highest (advantage), add 5
const attack = roll('2d20K+5')

// Exploding d6s with rerolls below 3
const wild = roll('4d6!R{<3}')

Options object

Pass a typed object for full control over the roll without notation parsing.

import { roll } from '@randsum/roller'

const result = roll({
sides: 6,
quantity: 4,
modifiers: {
  drop: { lowest: 1 },
  plus: 2
}
})

console.log(result.total)  // Sum of best 3d6 + 2

All three input types produce the same RollerRollResult — you can mix them in a single call:

import { roll } from '@randsum/roller'

// Combine multiple arguments into one total
const result = roll('1d20+5', '2d6')
console.log(result.total) // d20 + 5 + 2d6

Notation quick reference

Pattern	Description	Example
`NdS`	Roll N dice with S sides	`4d6`
`+X` / `-X`	Add/subtract from total	`1d20+5`
`L` / `H`	Drop lowest/highest	`4d6L`
`K` / `kl`	Keep highest/lowest	`4d6K3`
`!`	Exploding dice	`3d6!`
`!!`	Compounding exploding	`3d6!!`
`!p`	Penetrating exploding	`3d6!p`
`U`	Unique results	`4d20U`

See the full Randsum Dice Notation Spec for reroll conditions, caps, replacements, success counting, and multipliers.

Learn more

Getting Started — install, first roll, result types
Roll Options — every option the roll() function accepts
Modifiers — how the modifier pipeline works, priority order, and examples
Error Handling — validation patterns for user-provided input
API Reference — all exported functions and types