Getting Started with Notation

Install @randsum/notation to validate and parse dice notation strings without the roll engine.

Install

bun add @randsum/notation

npm install @randsum/notation

yarn add @randsum/notation

Check if a string is valid notation

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

import { isDiceNotation } from '@randsum/notation'

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/notation'

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/notation'

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/notation'

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/notation