Error Handling

JMESPathError (base)
├─ LexerError (invalid character)
├─ ParseError (syntax error)
│  ├─ IncompleteExpressionError
│  └─ EmptyExpressionError
└─ ArityError (wrong argument count)
   ├─ VariadicArityError
   ├─ JMESPathTypeError (wrong argument type)
   └─ UnknownFunctionError (function not found)

class JMESPathError extends Error {
  expression?: string;                    // Set by parser
  setExpression(expression: string): void;
}

import { search, JMESPathError } from '@aws-lambda-powertools/jmespath';

try {
  search('invalid..expression', { foo: 'bar' });
} catch (error) {
  if (error instanceof JMESPathError) {
    console.error('Expression:', error.expression);
  }
}

class LexerError extends JMESPathError {
  lexerPosition: number;  // Position of unknown token
  lexerValue: string;     // Value of unknown token
}

import { search, LexerError } from '@aws-lambda-powertools/jmespath';

try {
  search('foo$bar', { foo: 'value' });  // $ is invalid
} catch (error) {
  if (error instanceof LexerError) {
    console.error(`Unknown token "${error.lexerValue}" at position ${error.lexerPosition}`);
  }
}

class ParseError extends JMESPathError {
  lexPosition: number;    // Error position
  tokenType: string;      // Token type that caused error
  tokenValue: unknown;    // Token value that caused error
  reason?: string;        // Additional context
}

import { search, ParseError } from '@aws-lambda-powertools/jmespath';

try {
  search('foo[0', { foo: [1, 2, 3] });  // Missing closing bracket
} catch (error) {
  if (error instanceof ParseError) {
    console.error(`Syntax error at position ${error.lexPosition}: ${error.reason}`);
  }
}

class IncompleteExpressionError extends ParseError {}

try {
  search('foo.bar.', data);  // Ends with dot
} catch (error) {
  if (error instanceof IncompleteExpressionError) {
    console.error('Incomplete expression');
  }
}

class EmptyExpressionError extends JMESPathError {}

try {
  search('', { foo: 'bar' });
} catch (error) {
  if (error instanceof EmptyExpressionError) {
    console.error('Empty expression');
  }
}

class ArityError extends JMESPathError {
  actualArity: number;    // Number of args provided
  expectedArity: number;  // Number of args expected
}

import { search, ArityError } from '@aws-lambda-powertools/jmespath';

try {
  search('abs(`5`, `10`)', {});  // abs() expects 1 arg, got 2
} catch (error) {
  if (error instanceof ArityError) {
    console.error(`Expected ${error.expectedArity} args, got ${error.actualArity}`);
  }
}

class VariadicArityError extends ArityError {}

try {
  search('merge()', {});  // merge() requires at least 1 arg
} catch (error) {
  if (error instanceof VariadicArityError) {
    console.error(`Minimum ${error.expectedArity} args required`);
  }
}

class JMESPathTypeError extends JMESPathError {
  actualType: string;           // Actual type received
  expectedTypes: string[];      // Expected types
  currentValue: unknown;        // Value that caused error
}

import { search, JMESPathTypeError } from '@aws-lambda-powertools/jmespath';

try {
  search('abs(`hello`)', {});  // abs() expects number, got string
} catch (error) {
  if (error instanceof JMESPathTypeError) {
    console.error(`Expected ${error.expectedTypes.join('|')}, got ${error.actualType}`);
    console.error('Value:', error.currentValue);
  }
}

class UnknownFunctionError extends JMESPathError {
  constructor(funcName: string);
}

import { search, UnknownFunctionError } from '@aws-lambda-powertools/jmespath';

try {
  search('nonexistent_func(foo)', { foo: 'bar' });
} catch (error) {
  if (error instanceof UnknownFunctionError) {
    console.error('Unknown function. Check function name or provide customFunctions');
  }
}

// Common case: forgetting to provide PowertoolsFunctions
try {
  search('powertools_json(body)', { body: '{"foo":"bar"}' });
} catch (error) {
  if (error instanceof UnknownFunctionError) {
    // Need: { customFunctions: new PowertoolsFunctions() }
  }
}

import {
  search,
  JMESPathError,
  LexerError,
  ParseError,
  JMESPathTypeError,
  UnknownFunctionError,
} from '@aws-lambda-powertools/jmespath';

function safeSearch(expression: string, data: unknown): unknown {
  try {
    return search(expression, data);
  } catch (error) {
    if (error instanceof LexerError) {
      console.error(`Invalid character "${error.lexerValue}" at position ${error.lexerPosition}`);
    } else if (error instanceof ParseError) {
      console.error(`Syntax error at position ${error.lexPosition}`);
    } else if (error instanceof JMESPathTypeError) {
      console.error(`Type error: expected ${error.expectedTypes}, got ${error.actualType}`);
    } else if (error instanceof UnknownFunctionError) {
      console.error(`Unknown function. Check customFunctions option.`);
    } else if (error instanceof JMESPathError) {
      console.error(`JMESPath error: ${error.message}`);
    } else {
      throw error;  // Re-throw non-JMESPath errors
    }
    return null;  // or throw based on use case
  }
}

type Token = {
  type: 'eof' | 'unquoted_identifier' | 'quoted_identifier' | 'literal' |
        'rbracket' | 'rparen' | 'comma' | 'rbrace' | 'number' | 'current' |
        'expref' | 'colon' | 'pipe' | 'or' | 'and' | 'eq' | 'gt' | 'lt' |
        'gte' | 'lte' | 'ne' | 'flatten' | 'star' | 'filter' | 'dot' |
        'not' | 'lbrace' | 'lbracket' | 'lparen';
  value: JSONValue;
  start: number;
  end: number;
};