jpx_engine/
error.rs

1//! Error types for the jpx engine.
2//!
3//! This module defines the error types used throughout the engine.
4//! All public methods that can fail return [`Result<T>`](Result).
5//!
6//! # Error Handling
7//!
8//! ```rust
9//! use jpx_engine::{JpxEngine, EngineError};
10//!
11//! let engine = JpxEngine::new();
12//!
13//! // Handle specific error types
14//! match engine.evaluate("invalid[", &serde_json::json!({})) {
15//!     Ok(result) => println!("Result: {}", result),
16//!     Err(EngineError::InvalidExpression(msg)) => {
17//!         eprintln!("Syntax error: {}", msg);
18//!     }
19//!     Err(e) => eprintln!("Other error: {}", e),
20//! }
21//! ```
22
23use thiserror::Error;
24
25/// Errors that can occur during engine operations.
26///
27/// Each variant represents a specific failure mode, making it easy to
28/// handle different error types appropriately.
29#[derive(Debug, Error)]
30pub enum EngineError {
31    /// JMESPath expression has invalid syntax.
32    ///
33    /// Returned when [`JpxEngine::evaluate`](crate::JpxEngine::evaluate) or
34    /// [`JpxEngine::validate`](crate::JpxEngine::validate) encounters a
35    /// malformed expression.
36    #[error("Invalid expression: {0}")]
37    InvalidExpression(String),
38
39    /// JSON input could not be parsed.
40    ///
41    /// Returned when [`JpxEngine::evaluate_str`](crate::JpxEngine::evaluate_str)
42    /// or similar methods receive invalid JSON.
43    #[error("Invalid JSON: {0}")]
44    InvalidJson(String),
45
46    /// Expression evaluation failed at runtime.
47    ///
48    /// This can happen when calling undefined functions (in strict mode),
49    /// type mismatches, or other runtime errors.
50    #[error("Evaluation failed: {0}")]
51    EvaluationFailed(String),
52
53    /// Requested function does not exist.
54    ///
55    /// Returned by introspection methods when a function name is not found.
56    #[error("Unknown function: {0}")]
57    UnknownFunction(String),
58
59    /// Requested stored query does not exist.
60    ///
61    /// Returned by [`JpxEngine::run_query`](crate::JpxEngine::run_query)
62    /// when the named query hasn't been defined.
63    #[error("Query not found: {0}")]
64    QueryNotFound(String),
65
66    /// Discovery registration failed.
67    ///
68    /// Returned when registering a discovery spec fails validation
69    /// or conflicts with an existing registration.
70    #[error("Registration failed: {0}")]
71    RegistrationFailed(String),
72
73    /// Internal error (lock poisoning, serialization failure, etc.).
74    ///
75    /// These errors indicate bugs or unexpected conditions and should
76    /// generally be reported.
77    #[error("Internal error: {0}")]
78    Internal(String),
79
80    /// Arrow conversion error (only available with `arrow` feature).
81    ///
82    /// Returned when converting between Arrow RecordBatches and JSON fails.
83    #[cfg(feature = "arrow")]
84    #[error("Arrow error: {0}")]
85    ArrowError(String),
86}
87
88/// A specialized Result type for engine operations.
89///
90/// This is defined as `std::result::Result<T, EngineError>` for convenience.
91pub type Result<T> = std::result::Result<T, EngineError>;
jpx_engine/error.rs

jpx_engine/
error.rs
