Skip to content
RANDSUMspec

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.

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 the middle, dropping the highest and lowest
isDiceNotation('4d20ro{<5}') // true: reroll each die under 5 once
isDiceNotation('1d20ms{15}') // true: margin of success, the result minus 15
isDiceNotation('6d6sd') // true: sort descending

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
}

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? }
}

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 }
}
import { optionsToNotation } from '@randsum/roller'
const notation = optionsToNotation({
sides: 6,
quantity: 4,
modifiers: { drop: { lowest: 1 } }
})
console.log(notation) // '4d6L'