Errors

Error classes thrown by the library.

StatsError

Base class for all library errors.

class StatsError extends Error {
  name: 'StatsError'
}

All other errors extend this class.

ParseError

Thrown when dice notation cannot be parsed.

class ParseError extends StatsError {
  name: 'ParseError'
  notation?: string
}

Thrown by:

• roll() — When notation is invalid

Common causes:

• Invalid syntax: "2d", "d", "abc"
• Negative dice: "-2d6", "2d-6"
• Zero dice: "0d6"
• Incomplete modifier: "2d6+"

Example:

import { roll, ParseError } from '@motioneffector/stats'

try {
  roll('invalid')
} catch (error) {
  if (error instanceof ParseError) {
    console.log(`Invalid notation: ${error.notation}`)
  }
}

ValidationError

Thrown when input validation fails.

class ValidationError extends StatsError {
  name: 'ValidationError'
  field?: string
}

Thrown by:

• createStatBlock() — When min > max
• rollTable() — When table is empty or has invalid weights

Common causes:

• Stat definition has min greater than max
• Roll table is empty
• Roll table has negative weights
• Roll table has all zero weights

Example:

import { createStatBlock, ValidationError } from '@motioneffector/stats'

try {
  createStatBlock({
    health: { base: 50, min: 100, max: 10 } // min > max
  })
} catch (error) {
  if (error instanceof ValidationError) {
    console.log(`Validation failed for: ${error.field}`)
  }
}

CircularDependencyError

Thrown when derived stats create a circular dependency.

class CircularDependencyError extends StatsError {
  name: 'CircularDependencyError'
  cycle?: string[]
}

Thrown by:

• createDerivedStat() — When formula creates a cycle

Common causes:

• Derived stat references itself
• Two derived stats reference each other
• Chain of derived stats forms a loop

Example:

import { createStatBlock, createDerivedStat, CircularDependencyError } from '@motioneffector/stats'

const stats = createStatBlock({ a: { base: 10 } })

try {
  // This creates a circular dependency
  createDerivedStat(stats, 'b', (s) => s.get('b')! + 1)
} catch (error) {
  if (error instanceof CircularDependencyError) {
    console.log(`Cycle detected: ${error.cycle?.join(' → ')}`)
  }
}

VersionError

Thrown when loading serialized data with an unsupported version.

class VersionError extends StatsError {
  name: 'VersionError'
  version?: number
}

Thrown by:

• createStatBlock() with fromJSON — When version is unsupported

Common causes:

• Loading data from a future library version
• Corrupted save data

Example:

import { createStatBlock, VersionError } from '@motioneffector/stats'

try {
  createStatBlock(
    { health: { base: 100 } },
    { fromJSON: { version: 999, stats: {}, modifiers: {} } }
  )
} catch (error) {
  if (error instanceof VersionError) {
    console.log(`Unsupported version: ${error.version}`)
  }
}

Error Handling Pattern

import {
  roll,
  createStatBlock,
  createDerivedStat,
  ParseError,
  ValidationError,
  CircularDependencyError,
  VersionError,
  StatsError
} from '@motioneffector/stats'

try {
  // Your code here
} catch (error) {
  if (error instanceof ParseError) {
    // Handle invalid dice notation
  } else if (error instanceof ValidationError) {
    // Handle validation failures
  } else if (error instanceof CircularDependencyError) {
    // Handle circular dependencies
  } else if (error instanceof VersionError) {
    // Handle version mismatch
  } else if (error instanceof StatsError) {
    // Handle any other library error
  } else {
    // Re-throw unknown errors
    throw error
  }
}

Related

• Dice API — Functions that throw ParseError
• Stat Block API — Functions that throw ValidationError
• Checks API — Functions that throw CircularDependencyError