Skip to main content

qubit_json/value/traverse/
json_tree_process_error.rs

1// =============================================================================
2//    Copyright (c) 2026 Haixing Hu.
3//
4//    SPDX-License-Identifier: Apache-2.0
5//
6//    Licensed under the Apache License, Version 2.0.
7// =============================================================================
8//! Defines failures produced while processing JSON trees.
9
10use std::fmt::Debug;
11
12use qubit_budget::MeasuredBudgetError;
13use thiserror::Error;
14
15/// Identifies whether JSON tree processing failed in infrastructure or domain
16/// code.
17///
18/// This enum intentionally remains exhaustive so callers can distinguish the
19/// complete set of processing failure domains at compile time. Adding a domain
20/// requires a breaking release rather than a `#[non_exhaustive]` change.
21///
22/// # Type Parameters
23///
24/// * `R` - Resource identity attached to budget failures.
25/// * `Q` - Quantity representation attached to budget failures.
26/// * `E` - Error type returned by the visitor.
27///
28/// # Examples
29///
30/// ```
31/// use qubit_json::value::traverse::JsonTreeProcessError;
32///
33/// let error: JsonTreeProcessError<(), usize, &str> =
34///     JsonTreeProcessError::Visitor("visitor rejected the node");
35/// assert!(matches!(error, JsonTreeProcessError::Visitor(_)));
36/// ```
37#[must_use]
38#[derive(Debug, Error)]
39pub enum JsonTreeProcessError<R, Q, E>
40where
41    Q: Copy + Debug,
42{
43    /// A JSON resource measurement or budget rejected a tree node.
44    #[error(transparent)]
45    Budget(
46        /// Resource measurement that exceeded the configured limit.
47        #[from]
48        MeasuredBudgetError<R, Q>,
49    ),
50    /// The caller-defined visitor rejected a budget-admitted node.
51    #[error("JSON tree visitor failed")]
52    Visitor(
53        /// Domain error returned by the visitor callback.
54        E,
55    ),
56}