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
Section titled “Parse functions”isDiceNotation(value)
Section titled “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 DiceNotationisDiceNotation('hello') // falseSignature:
function isDiceNotation(value: string): value is DiceNotationnotation(value)
Section titled “notation(value)”Assert a string is valid notation or throw NotationParseError, whose suggestion holds a fix when one can be inferred.
function notation(value: string): DiceNotationnotationToOptions(notation)
Section titled “notationToOptions(notation)”Parse a notation string into structured options. Throws NotationParseError (with context.position) on invalid notation, so check with isDiceNotation first to branch instead. Returns an array (one entry per roll group).
import { notationToOptions, isDiceNotation } from '@randsum/roller'
if (isDiceNotation('4d6L+2')) {const [options] = notationToOptions('4d6L+2')// { quantity: 4, arithmetic: 'add', sides: 6, modifiers: { drop: { lowest: 1 }, plus: 2 } }}Signature:
function notationToOptions(notation: string): ParsedNotationOptions[]validateNotation(notation)
Section titled “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 // ParsedNotationOptions[]} else {result.error // ValidationErrorInfo}Signature:
function validateNotation(notation: string): ValidationResultsuggestNotationFix(notation)
Section titled “suggestNotationFix(notation)”Suggest a corrected version of invalid notation. Returns undefined if no fix is available.
import { suggestNotationFix } from '@randsum/roller'
suggestNotationFix('4d6 L') // '4d6L'suggestNotationFix('46') // '4d6'suggestNotationFix('xyz') // undefinedSignature:
function suggestNotationFix(notation: string): string | undefinedTransform functions
Section titled “Transform functions”optionsToNotation(options)
Section titled “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'function optionsToNotation<T = string>(options: RollOptions<T>): DiceNotationThrows NotationParseError if the options cannot be written as valid notation.
optionsToDescription(options)
Section titled “optionsToDescription(options)”Generate a human-readable description. Returns an array of description strings.
function optionsToDescription<T = string>(options: RollOptions<T>): string[]modifiersToNotation(modifiers)
Section titled “modifiersToNotation(modifiers)”Convert modifier options to their notation suffix.
function modifiersToNotation(modifiers: ModifierOptions | undefined): stringmodifiersToDescription(modifiers)
Section titled “modifiersToDescription(modifiers)”Convert modifier options to an array of human-readable description strings.
function modifiersToDescription(modifiers: ModifierOptions | undefined): string[]Tokenization
Section titled “Tokenization”tokenize(notation)
Section titled “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[]interface Token { readonly text: string readonly key: string readonly category: TokenCategory readonly start: number readonly end: number readonly description: string}TokenCategory
Section titled “TokenCategory”The faceted classification of a token. A ModifierCategory, or 'unknown' for
unrecognized fragments.
type TokenCategory = ModifierCategory | 'unknown'ModifierCategory
Section titled “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
Section titled “Error classes”NotationParseError
Section titled “NotationParseError”Thrown by notation() and notationToOptions() when a string is not valid dice notation, and by optionsToNotation() when options cannot be written as notation. Extends RandsumError; its code is INVALID_NOTATION.
| 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 |
Core types
Section titled “Core types”| Type | Description |
|---|---|
DiceNotation |
Template literal type for notation strings |
RollOptions<T> |
Configuration object for a roll (sides, quantity, modifiers, key, label, 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
Section titled “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?, once? } |
ReplaceOptions |
{ from: number | ComparisonOptions, to: number } |
UniqueOptions |
{ notUnique: number[] } |
CountOptions |
Extends ComparisonOptions with { deduct? } for counting successes and failures |
Validation types
Section titled “Validation types”| Type | Description |
|---|---|
ValidationResult |
Discriminated union of the valid and invalid results |
ValidationErrorInfo |
{ message: string, argument: string, position?: number, code?: ErrorCode } |