# 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.

<CodeExample code={`isDiceNotation('4d6L')   // true — value is typed as DiceNotation
isDiceNotation('hello')  // false`} />

**Signature:**

```typescript
function isDiceNotation(value: string): value is DiceNotation
```

### `notation(value)`

Assert a string is valid notation or throw `NotationParseError`.

```typescript
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).

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

**Signature:**

```typescript
function notationToOptions(notation: string): RollOptions[]
```

### `validateNotation(notation)`

Validate with a detailed result. Returns a `ValidationResult`.

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

**Signature:**

```typescript
function validateNotation(notation: string): ValidationResult
```

### `suggestNotationFix(notation)`

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

<CodeExample code={`suggestNotationFix('d6')    // '1d6'
suggestNotationFix('46')    // '4d6'
suggestNotationFix('xyz')   // undefined`} />

**Signature:**

```typescript
function suggestNotationFix(notation: string): string | undefined
```

## Transform functions

### `optionsToNotation(options)`

Convert a `RollOptions` object to a notation string.

<CodeExample code={`optionsToNotation({ sides: 6, quantity: 4, modifiers: { drop: { lowest: 1 } } })
// '4d6L'`} />

```typescript
function optionsToNotation(options: RollOptions): DiceNotation
```

### `optionsToDescription(options)`

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

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

### `modifiersToNotation(modifiers)`

Convert modifier options to their notation suffix.

```typescript
function modifiersToNotation(modifiers: ModifierOptions | undefined): string
```

### `modifiersToDescription(modifiers)`

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

```typescript
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`.

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

### `Token`

```typescript
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.

```typescript
type TokenCategory = ModifierCategory | 'unknown'
```

### `ModifierCategory`

The facet a modifier belongs to, per the [notation taxonomy](https://notation.randsum.dev).

```typescript
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 }`            |