Errors API

Error classes that may be thrown by the parser.

ParserError

Base error class for all parser errors.

class ParserError extends Error {
  name: 'ParserError'
}

Usage:

import { ParserError } from '@motioneffector/parser'

try {
  parser.parse(input)
} catch (error) {
  if (error instanceof ParserError) {
    // Handle parser-specific error
  }
}

ValidationError

Thrown when input validation fails.

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

When Thrown:

Example:

import { createParser, ValidationError } from '@motioneffector/parser'

try {
  // Missing resolver
  createParser({} as any)
} catch (error) {
  if (error instanceof ValidationError) {
    console.log(error.message)  // "Resolver must be a function"
    console.log(error.field)    // "resolver"
  }
}

try {
  // Input too long
  parser.parse('x'.repeat(2_000_000))
} catch (error) {
  if (error instanceof ValidationError) {
    console.log(error.message)  // "Input exceeds maximum length..."
    console.log(error.field)    // "input"
  }
}

ParseError

Thrown when parsing fails critically.

class ParseError extends ParserError {
  name: 'ParseError'
  position?: number
  input?: string
}

Notes:

This error class exists for internal use and future extension. Currently, parsing failures are returned as ParseErrorResult values rather than thrown exceptions.

// Parsing issues return results, not exceptions
const result = parser.parse('get')
if (result.type === 'parse_error') {
  console.log(result.message)  // "Expected object after GET"
}

Error Handling Pattern

import { createParser, ValidationError, ParserError } from '@motioneffector/parser'

function safeCreate(resolver: Resolver): Parser | null {
  try {
    return createParser({ resolver })
  } catch (error) {
    if (error instanceof ValidationError) {
      console.error(`Configuration error: ${error.message}`)
      return null
    }
    throw error  // Re-throw unexpected errors
  }
}

function safeParse(parser: Parser, input: string): ParseResult | null {
  try {
    return parser.parse(input)
  } catch (error) {
    if (error instanceof ValidationError) {
      // Input too long
      console.error('Input rejected:', error.message)
      return null
    }
    if (error instanceof ParserError) {
      console.error('Parser error:', error.message)
      return null
    }
    throw error
  }
}

Error vs Result

The parser distinguishes between:

Errors (thrown): Configuration problems, security limits

• Invalid resolver → ValidationError
• Input too long → ValidationError

Results (returned): Normal parsing outcomes

• Empty input → ParseErrorResult
• Unknown word → UnknownVerbResult / UnknownNounResult
• Missing argument → ParseErrorResult
• Multiple matches → AmbiguousResult
• Success → CommandResult