Notation API Reference

All functions on this page are exported from @randsum/roller. The tokenize function is also available from @randsum/roller/tokenize for lightweight use.

Parse functions

isDiceNotation(value)

Type guard that returns true if the string is valid dice notation.

import { isDiceNotation } from '@randsum/roller'

isDiceNotation('4d6L')   // true — value is typed as DiceNotation
isDiceNotation('hello')  // false

Open in StackBlitz ↗

Signature:

function isDiceNotation(value: string): value is DiceNotation

notation(value)

Assert a string is valid notation or throw NotationParseError.

function notation(value: string): DiceNotation

notationToOptions(notation)

Parse a notation string into structured options. Accepts any string (validate first with isDiceNotation for safety). Returns an array (one entry per roll group).

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

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

Open in StackBlitz ↗

Signature:

function notationToOptions(notation: string): RollOptions[]

validateNotation(notation)

Validate with a detailed result. Returns a ValidationResult.

import { validateNotation } from '@randsum/roller'

const result = validateNotation('4d6L')
if (result.valid) {
result.notation   // DiceNotation[]
result.options    // RollOptions[]
} else {
result.error      // ValidationErrorInfo
}

Open in StackBlitz ↗

Signature:

function validateNotation(notation: string): ValidationResult

suggestNotationFix(notation)

Suggest a corrected version of invalid notation. Returns undefined if no fix is available.

import { suggestNotationFix } from '@randsum/roller'

suggestNotationFix('d6')    // '1d6'
suggestNotationFix('46')    // '4d6'
suggestNotationFix('xyz')   // undefined

Open in StackBlitz ↗

Signature:

function suggestNotationFix(notation: string): string | undefined

Transform functions

optionsToNotation(options)

Convert a RollOptions object to a notation string.

import { optionsToNotation } from '@randsum/roller'

optionsToNotation({ sides: 6, quantity: 4, modifiers: { drop: { lowest: 1 } } })
// '4d6L'

Open in StackBlitz ↗

function optionsToNotation(options: RollOptions): DiceNotation

optionsToDescription(options)

Generate a human-readable description. Returns an array of description strings.

function optionsToDescription<T = string>(options: RollOptions<T>): string[]

modifiersToNotation(modifiers)

Convert modifier options to their notation suffix.

function modifiersToNotation(modifiers: ModifierOptions | undefined): string

modifiersToDescription(modifiers)

Convert modifier options to an array of human-readable description strings.

function modifiersToDescription(modifiers: ModifierOptions | undefined): string[]

Tokenization

tokenize(notation)

Parse notation into typed tokens for syntax highlighting or UI display. Also available from @randsum/roller/tokenize.

function tokenize(notation: string): readonly Token[]

Token

interface Token {
  readonly text: string
  readonly key: string
  readonly category: TokenCategory
  readonly start: number
  readonly end: number
  readonly description: string
}

TokenCategory

The faceted classification of a token. A ModifierCategory, or 'unknown' for unrecognized fragments.

type TokenCategory = ModifierCategory | 'unknown'

ModifierCategory

The facet a modifier belongs to, per the notation taxonomy.

type ModifierCategory =
  | 'Core' | 'Special' | 'Order' | 'Clamp' | 'Map' | 'Filter'
  | 'Substitute' | 'Generate' | 'Accumulate' | 'Scale'
  | 'Reinterpret' | 'Dispatch'

Error classes

NotationParseError

Thrown by notation() when a string is not valid dice notation. Extends RandsumError.

Property	Type	Description
suggestion	string | undefined	A corrected notation string, when one can be inferred
message	string	Human-readable error message including the invalid input

Types

Core types

Type	Description
DiceNotation	Branded template literal type for valid notation strings
RollOptions<T>	Configuration object for a roll (sides, quantity, modifiers, key, arithmetic)
RollArgument<T>	Any accepted roll() argument — a number, notation string, or RollOptions
ModifierOptions	Top-level modifier configuration with all modifier keys
RollRecord<T>	Full record of a single roll: parameters, raw rolls, modifier logs, and total
RollerRollResult<T>	Result of roll() — rolls, values, and total

Modifier option types

Type	Description
ComparisonOptions	{ greaterThan?, greaterThanOrEqual?, lessThan?, lessThanOrEqual?, exact? }
DropOptions	Extends ComparisonOptions with { highest?, lowest? }
KeepOptions	{ highest?, lowest? }
RerollOptions	Extends ComparisonOptions with { max? }
ReplaceOptions	{ from: number | ComparisonOptions, to: number }
UniqueOptions	{ notUnique: number[] }
CountOptions	Success / failure counting threshold configuration

Validation types

Type	Description
ValidationResult	Discriminated union of the valid and invalid results
ValidationErrorInfo	{ message: string, argument: string }