Skip to content
RANDSUM — TypeScript Dice Rolling Library for Tabletop RPGs

@randsum/notation

Parse, validate, and transform dice notation strings without a roll engine. @randsum/notation is the type foundation of the RANDSUM ecosystem — zero runtime dependencies.

When to use notation vs roller

Section titled “When to use notation vs roller”

Use @randsum/notation when you need notation utilities but not roll():

  • Validating user-provided dice strings in a form or chat command
  • Building a notation editor or input component
  • Converting between notation strings and structured options
  • Tokenizing notation for syntax highlighting

If you also need to roll dice, use @randsum/roller instead — it re-exports validateNotation, isDiceNotation, and notation for convenience. Functions like notationToOptions, suggestNotationFix, and tokenize require @randsum/notation directly.

What it does

Section titled “What it does”

Validation — check if a string is valid dice notation, with type narrowing or structured error details.

import { isDiceNotation, validateNotation } from '@randsum/notation'


// Type guard — narrows to DiceNotation
if (isDiceNotation(userInput)) {
// userInput is typed as DiceNotation
}


// Full validation with error info
const result = validateNotation(userInput)
if (!result.valid) {
console.error(result.error.message)
}

Parsing — convert notation strings into structured ParsedNotationOptions arrays.

import { notationToOptions } from '@randsum/notation'


const options = notationToOptions('4d6L')
// [{ sides: 6, quantity: 4, modifiers: { drop: { lowest: 1 } } }]

Transformation — convert structured options back to notation strings or human-readable descriptions.

import { optionsToNotation, optionsToDescription } from '@randsum/notation'


const options = {
sides: 6,
quantity: 4,
modifiers: { drop: { lowest: 1 } }
}


optionsToNotation(options)     // '4d6L'
optionsToDescription(options)  // ['Roll 4 6-sided dice', 'Drop lowest']

Suggestion — offer corrected notation for invalid input.

import { suggestNotationFix } from '@randsum/notation'


suggestNotationFix('d20')  // '1d20' — adds missing quantity

Tokenization — break notation into typed tokens for syntax highlighting or UI display.

import { tokenize } from '@randsum/notation'


const tokens = tokenize('4d6L+5')
// Each token has: text, type, start, end, description

Learn more

Section titled “Learn more”
Section titled “Links”