Getting Started with Notation

Notation validation and parsing are built into @randsum/roller — no separate package required. Install roller to get isDiceNotation, validateNotation, notationToOptions, optionsToNotation, and the full notation toolkit.

Quick notation examples

Standard dice, special dice types, and modifiers all work with every notation function:

import { isDiceNotation } from '@randsum/roller'

isDiceNotation('4d6L')                // true — standard notation
isDiceNotation('z6')                  // true — zero-bias die (faces 0-5)
isDiceNotation('d{fire,ice,lightning}') // true — custom faces
isDiceNotation('4d6KM')               // true — keep middle dice, discard highest and lowest
isDiceNotation('4d20ro{<5}')          // true — reroll once any die showing less than 5
isDiceNotation('1d20ms{15}')          // true — margin of success: result minus target (15)
isDiceNotation('6d6sd')               // true — sort descending

Check if a string is valid notation

Use isDiceNotation() as a type guard to check user input before processing it:

import { isDiceNotation } from '@randsum/roller'

isDiceNotation('4d6L')       // true
isDiceNotation('not-valid')  // false

if (isDiceNotation(userInput)) {
// userInput is now typed as DiceNotation
}

Validate with detailed feedback

validateNotation() returns a result object with either the parsed structure or error details:

import { validateNotation } from '@randsum/roller'

const result = validateNotation('4d6L')

if (result.valid) {
console.log(result.notation)  // ['4d6L']
console.log(result.options)   // [{ sides: 6, quantity: 4, modifiers: { drop: { lowest: 1 } } }]
} else {
console.log(result.error)     // { message: '...', argument: '...' }
}

Parse notation into options

Convert a notation string into structured ParsedNotationOptions. Returns an array (one entry per roll group):

import { isDiceNotation, notationToOptions } from '@randsum/roller'

const notation = '2d6+3'

if (isDiceNotation(notation)) {
const [options] = notationToOptions(notation)
console.log(options.sides)       // 6
console.log(options.quantity)    // 2
console.log(options.modifiers)   // { plus: 3 }
}

Convert options back to notation

import { optionsToNotation } from '@randsum/roller'

const notation = optionsToNotation({
sides: 6,
quantity: 4,
modifiers: { drop: { lowest: 1 } }
})
console.log(notation) // '4d6L'

What’s next

Randsum Dice Notation Spec — full syntax reference for all notation features
Validation & Parsing — detailed guide to validation, suggestions, and parsing
API Reference — complete list of exports from @randsum/roller