Error Classes

Custom error types thrown by library functions.

CardsError

Base error class for all library errors.

class CardsError extends Error {
  name: 'CardsError'
}

All library errors extend this class, so you can catch them uniformly:

import { CardsError } from '@motioneffector/cards'

try {
  const card = readCard(bytes)
} catch (error) {
  if (error instanceof CardsError) {
    console.error('Cards library error:', error.message)
  }
}

ParseError

Thrown when parsing fails (invalid format, corrupted data, etc.).

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

When thrown:

• readCard() - Invalid format, corrupted data, no card data found
• readCardFromPng() - Invalid PNG, no card chunks
• readCardFromJson() - Invalid JSON, unrecognized card format
• readCardFromCharx() - Invalid ZIP, missing card.json
• readLorebook() - Invalid format, no lorebook data found

Example:

import { readCard, ParseError } from '@motioneffector/cards'

try {
  const card = readCard(bytes)
} catch (error) {
  if (error instanceof ParseError) {
    console.error('Parse failed:', error.message)

    if (error.position !== undefined) {
      console.error('At position:', error.position)
    }
  }
}

ValidationError

Thrown when validation fails in strict contexts.

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

When thrown:

• validateCard() and validateLorebook() do not throw - they return ValidationResult
• This error is available for use in your own validation logic

Example:

import { ValidationError } from '@motioneffector/cards'

function requireValidName(card: CharacterCard) {
  if (!card.data.name || card.data.name.trim() === '') {
    throw new ValidationError('Name is required', 'data.name')
  }
}

try {
  requireValidName(card)
} catch (error) {
  if (error instanceof ValidationError) {
    console.error(`Validation failed for ${error.field}: ${error.message}`)
  }
}

Error Handling Patterns

Catch All Library Errors

import { readCard, CardsError } from '@motioneffector/cards'

try {
  const card = readCard(bytes)
} catch (error) {
  if (error instanceof CardsError) {
    // Any library error
    console.error('Library error:', error.message)
  } else {
    // Something else (system error, etc.)
    throw error
  }
}

Catch Specific Errors

import { readCard, ParseError, ValidationError } from '@motioneffector/cards'

try {
  const card = readCard(bytes, { strict: true })
} catch (error) {
  if (error instanceof ParseError) {
    console.error('Failed to parse:', error.message)
  } else if (error instanceof ValidationError) {
    console.error('Invalid data:', error.message)
  } else {
    throw error
  }
}

Graceful Fallback

import { readCard, repairCard, ParseError } from '@motioneffector/cards'

function loadCardSafely(bytes: Uint8Array) {
  try {
    return readCard(bytes)
  } catch (error) {
    if (error instanceof ParseError) {
      console.warn('Attempting repair...')
      const result = repairCard(bytes)
      return result.card
    }
    throw error
  }
}