@randsum/notation
Dice Notation Parser and Types
The type and parsing foundation of the @randsum ecosystem.
[](https://www.npmjs.com/package/@randsum/notation)
[](https://bundlephobia.com/package/@randsum/notation)
[](https://www.npmjs.com/package/@randsum/notation)
[](https://github.com/RANDSUM/randsum/blob/main/LICENSE)
Zero-dependency dice notation parser, validator, and type system for JavaScript and TypeScript.
> **Note:** Most users should install `@randsum/roller`, which re-exports everything from this package along with the `roll()` function. Install `@randsum/notation` directly only if you need parsing and validation without the rolling engine.
## Installation
```bash
npm install @randsum/notation
# or
bun add @randsum/notation
```
## Usage
### Parsing Notation
```typescript
import { isDiceNotation, notationToOptions } from "@randsum/notation"
isDiceNotation("4d6L") // true
isDiceNotation("banana") // false
const options = notationToOptions("4d6L")
// { sides: 6, quantity: 4, modifiers: { drop: { lowest: 1 } } }
```
### Validation
```typescript
import { validateNotation } from "@randsum/notation"
const result = validateNotation("4d6L")
if (result.valid) {
result.notation // '4d6L'
result.options // parsed RollOptions
} else {
result.errors // array of validation errors
}
```
### Converting Between Formats
```typescript
import { optionsToNotation, optionsToDescription } from "@randsum/notation"
const notation = optionsToNotation({
sides: 6,
quantity: 4,
modifiers: { drop: { lowest: 1 } }
})
// '4d6L'
const description = optionsToDescription({
sides: 20,
quantity: 1,
modifiers: { plus: 5 }
})
// '1d20 + 5'
```
### Listing Notation Strings
```typescript
import { listOfNotations } from "@randsum/notation"
const notations = listOfNotations("4d6L + 2d8")
// ['4d6L', '2d8']
```
## API
### Parsing
- `isDiceNotation(value)` - Type guard for valid dice notation strings
- `notationToOptions(notation)` - Parse a notation string into a `RollOptions` object
- `listOfNotations(input)` - Extract individual notation strings from a combined expression
- `validateNotation(notation)` - Validate notation and return parsed result or errors
- `suggestNotationFix(notation)` - Suggest corrections for invalid notation
### Transformers
- `optionsToNotation(options)` - Convert a `RollOptions` object to a notation string
- `optionsToDescription(options)` - Convert a `RollOptions` object to a human-readable description
- `modifiersToNotation(modifiers)` - Convert modifier options to their notation suffix
- `modifiersToDescription(modifiers)` - Convert modifier options to a readable description
### Comparison Utilities
- `parseComparisonNotation(notation)` - Parse comparison syntax like `{<3,>18}`
- `hasConditions(options)` - Check if comparison options have any conditions
- `formatComparisonNotation(options)` - Format comparison options as notation
- `formatComparisonDescription(options)` - Format comparison options as text
### Types
```typescript
import type {
DiceNotation,
RollOptions,
ModifierOptions,
ComparisonOptions,
DropOptions,
KeepOptions,
RerollOptions,
ReplaceOptions,
UniqueOptions,
SuccessCountOptions,
ValidationResult,
NotationSchema
} from "@randsum/notation"
```
### Modifier Schemas
All 14 modifier notation schemas are exported for use by the roller's modifier registry:
`capSchema`, `dropSchema`, `keepSchema`, `replaceSchema`, `rerollSchema`, `explodeSchema`, `compoundSchema`, `penetrateSchema`, `uniqueSchema`, `countSuccessesSchema`, `multiplySchema`, `plusSchema`, `minusSchema`, `multiplyTotalSchema`
## Related Packages
- [@randsum/roller](../roller) - Core dice rolling engine (depends on this package)
- [randsum.dev](https://randsum.dev) - Documentation site