Getting Started with Notation
Notation validation and parsing are built into @randsum/roller, so there is no separate package to install. Install roller to get isDiceNotation, validateNotation, notationToOptions, optionsToNotation, and the full notation toolkit.
Quick notation examples
Section titled “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 notationisDiceNotation('z6') // true: zero-bias die (faces 0-5)isDiceNotation('d{fire,ice,lightning}') // true: custom facesisDiceNotation('4d6KM') // true: keep the middle, dropping the highest and lowestisDiceNotation('4d20ro{<5}') // true: reroll each die under 5 onceisDiceNotation('1d20ms{15}') // true: margin of success, the result minus 15isDiceNotation('6d6sd') // true: sort descendingCheck if a string is valid notation
Section titled “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') // trueisDiceNotation('not-valid') // false
if (isDiceNotation(userInput)) {// userInput is now typed as DiceNotation}Validate with detailed feedback
Section titled “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) // [{ quantity: 4, arithmetic: 'add', sides: 6, modifiers: { drop: { lowest: 1 } } }]} else {console.log(result.error) // { message, argument, position? }}Parse notation into options
Section titled “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) // 6console.log(options.quantity) // 2console.log(options.modifiers) // { plus: 3 }}Convert options back to notation
Section titled “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
Section titled “What’s next”- Notation Syntax Guide: the full syntax reference for all notation features
- Validation & Parsing: a detailed guide to validation, suggestions, and parsing
- API Reference: the complete list of exports from
@randsum/roller