spikard 0.13.0 → 0.15.2

data/vendor/crates/spikard-bindings-shared/src/json_conversion.rs

@@ -1,829 +0,0 @@
-//! Optimized JSON conversion utilities for language bindings
-//!
-//! This module provides a high-performance JSON conversion abstraction that eliminates
-//! duplicate code across Python, Node.js, Ruby, PHP, and WASM bindings.
-//!
-//! # Design Goals
-//!
-//! - **Zero-copy conversions** for primitives (fast path handles 60% of conversions)
-//! - **Language-agnostic trait** allowing each binding to implement native conversions
-//! - **Performance focused** with fast-path optimizations for common JSON types
-//! - **No allocations** for primitives when using fast-path helper
-//!
-//! # Architecture
-//!
-//! The module provides:
-//!
-//! 1. **`JsonConverter` trait**: Language bindings implement this to convert between
-//!    `serde_json::Value` and their native types (`PyObject`, `JsValue`, etc.)
-//!
-//! 2. **`JsonConversionHelper`**: Static utility for fast-path optimizations that detect
-//!    primitive types and return early, avoiding recursive descent.
-//!
-//! 3. **Error types**: Structured error reporting using `thiserror`
-//!
-//! # Example: Python Binding
-//!
-//! ```ignore
-//! use spikard_bindings_shared::JsonConverter;
-//! use pyo3::Python;
-//!
-//! struct PyJsonConverter;
-//!
-//! impl JsonConverter for PyJsonConverter {
-//!     type LanguageValue = pyo3::PyObject;
-//!     type Error = pyo3::PyErr;
-//!
-//!     fn json_to_language(py: Python, value: &serde_json::Value)
-//!         -> Result<Self::LanguageValue, Self::Error>
-//!     {
-//!         // Fast path handles null, bool, number, string
-//!         if let Some(result) = JsonConversionHelper::try_fast_path_from_json(py, value) {
-//!             return result;
-//!         }
-//!
-//!         // Slow path for arrays and objects
-//!         match value {
-//!             Value::Array(arr) => { /* ... */ }
-//!             Value::Object(obj) => { /* ... */ }
-//!             _ => unreachable!()
-//!         }
-//!     }
-//! }
-//! ```
-
-use serde_json::Value;
-use thiserror::Error;
-
-/// Error type for JSON conversion operations
-///
-/// Provides detailed error information about conversion failures,
-/// distinguishing between type mismatches, missing fields, and serialization errors.
-#[derive(Debug, Error)]
-pub enum JsonConversionError {
-    /// Type mismatch: expected one JSON type but received another
-    #[error("Type mismatch: expected {expected}, got {got}")]
-    TypeMismatch { expected: String, got: String },
-
-    /// Invalid value for the target type
-    #[error("Invalid value: {reason}")]
-    InvalidValue { reason: String },
-
-    /// Missing required field in JSON object
-    #[error("Missing required field: {field}")]
-    MissingField { field: String },
-
-    /// Serialization or deserialization failed
-    #[error("Serialization error: {reason}")]
-    SerializationError { reason: String },
-
-    /// Language-specific conversion error (for binding-specific errors)
-    #[error("Conversion error: {reason}")]
-    ConversionError { reason: String },
-}
-
-impl JsonConversionError {
-    /// Create a type mismatch error
-    pub fn type_mismatch(expected: impl Into<String>, got: impl Into<String>) -> Self {
-        Self::TypeMismatch {
-            expected: expected.into(),
-            got: got.into(),
-        }
-    }
-
-    /// Create an invalid value error
-    pub fn invalid_value(reason: impl Into<String>) -> Self {
-        Self::InvalidValue { reason: reason.into() }
-    }
-
-    /// Create a missing field error
-    pub fn missing_field(field: impl Into<String>) -> Self {
-        Self::MissingField { field: field.into() }
-    }
-
-    /// Create a serialization error
-    pub fn serialization_error(reason: impl Into<String>) -> Self {
-        Self::SerializationError { reason: reason.into() }
-    }
-
-    /// Create a conversion error
-    pub fn conversion_error(reason: impl Into<String>) -> Self {
-        Self::ConversionError { reason: reason.into() }
-    }
-}
-
-/// Trait for converting between JSON values and language-native types
-///
-/// Each language binding (Python, Node.js, Ruby, PHP, WASM) implements this trait
-/// to provide bidirectional conversion between `serde_json::Value` and their
-/// native representation (`PyObject`, `JsValue`, `RValue`, etc.).
-///
-/// # Type Parameters
-///
-/// - `LanguageValue`: The native type of the target language
-/// - `Error`: The error type used by the binding (commonly a language-specific exception)
-///
-/// # Implementation Notes
-///
-/// Implementations should use `JsonConversionHelper::try_fast_path_to_json()` and
-/// `JsonConversionHelper::try_fast_path_from_json()` to handle primitive types efficiently.
-/// These fast paths avoid recursion for the ~60% of conversions that are primitives,
-/// strings, or small arrays.
-///
-/// # Example
-///
-/// See the module-level documentation for a Python binding example.
-pub trait JsonConverter {
-    /// The native type of the target language
-    type LanguageValue;
-
-    /// The error type for conversion failures
-    type Error;
-
-    /// Convert from a JSON value to the language's native type
-    ///
-    /// # Arguments
-    ///
-    /// * `value` - The JSON value to convert
-    ///
-    /// # Returns
-    ///
-    /// The converted language value, or an error if conversion fails
-    ///
-    /// # Errors
-    ///
-    /// Returns an error if the JSON value cannot be converted to a valid language value.
-    fn json_to_language(value: &Value) -> Result<Self::LanguageValue, Self::Error>;
-
-    /// Convert from the language's native type to a JSON value
-    ///
-    /// # Arguments
-    ///
-    /// * `value` - The language value to convert
-    ///
-    /// # Returns
-    ///
-    /// The converted JSON value, or an error if conversion fails
-    ///
-    /// # Errors
-    ///
-    /// Returns an error if the language value cannot be converted to a valid JSON value.
-    fn language_to_json(value: &Self::LanguageValue) -> Result<Value, Self::Error>;
-}
-
-/// Fast-path optimization helper for JSON conversions
-///
-/// This helper detects primitive JSON types (null, bool, number, string) and returns
-/// early without recursive processing. This eliminates ~60% of the conversion code
-/// in each binding by handling common cases with minimal overhead.
-///
-/// # Performance Benefits
-///
-/// - **Null**: Single branch check + early return
-/// - **Boolean**: Single branch check + early return
-/// - **Number (small integers)**: Direct conversion without float parsing
-/// - **String**: Direct reference, no copying needed
-/// - **Complex types (arrays, objects)**: Return None, caller handles recursion
-///
-/// By detecting these cases early, bindings can optimize their implementations:
-/// instead of checking every possible type, the fast path handles common cases,
-/// and the slow path only needs to handle arrays and objects.
-///
-/// # Example: Using in Python Binding
-///
-/// ```ignore
-/// use serde_json::Value;
-/// use spikard_bindings_shared::JsonConversionHelper;
-/// use pyo3::Python;
-///
-/// fn json_to_python(py: Python, value: &Value) -> PyResult<PyObject> {
-///     // Fast path: null, bool, int, float, string
-///     if let Some(result) = JsonConversionHelper::try_fast_path_from_json(value) {
-///         return convert_primitive_to_python(py, result);
-///     }
-///
-///     // Slow path: array, object (requires recursion)
-///     match value {
-///         Value::Array(arr) => {
-///             let list = PyList::empty(py);
-///             for item in arr {
-///                 let py_item = json_to_python(py, item)?;
-///                 list.append(py_item)?;
-///             }
-///             Ok(list.into())
-///         }
-///         Value::Object(obj) => {
-///             let dict = PyDict::new(py);
-///             for (k, v) in obj {
-///                 let py_val = json_to_python(py, v)?;
-///                 dict.set_item(k, py_val)?;
-///             }
-///             Ok(dict.into())
-///         }
-///         _ => unreachable!() // Fast path covered all primitives
-///     }
-/// }
-/// ```
-#[derive(Debug, Clone, Copy)]
-pub struct JsonConversionHelper;
-
-/// Represents a primitive JSON value suitable for fast-path conversion
-///
-/// This enum captures the primitive types that can be converted without
-/// recursive descent: null, booleans, numbers (as owned strings to preserve precision),
-/// and string references.
-#[derive(Debug, Clone)]
-pub enum JsonPrimitive<'a> {
-    /// JSON null value
-    Null,
-
-    /// JSON boolean value
-    Bool(bool),
-
-    /// JSON number - stored as string to preserve precision
-    /// (`serde_json::Number` stores the original text, so String clone is acceptable)
-    Number(String),
-
-    /// JSON string value
-    String(&'a str),
-}
-
-impl JsonConversionHelper {
-    /// Attempt fast-path conversion for primitive JSON types
-    ///
-    /// Returns `Some(primitive)` if the value is a primitive (null, bool, number, or string),
-    /// allowing the caller to convert without recursion. Returns `None` for complex types
-    /// (arrays and objects) that require recursive processing.
-    ///
-    /// This function is the key to the performance optimization: ~60% of JSON conversions
-    /// are primitives, so detecting them here avoids the overhead of recursive matching
-    /// in the binding layer.
-    ///
-    /// # Arguments
-    ///
-    /// * `value` - The JSON value to check
-    ///
-    /// # Returns
-    ///
-    /// - `Some(JsonPrimitive)` if value is a primitive type
-    /// - `None` if value is an array or object (requires recursion)
-    ///
-    /// # Example
-    ///
-    /// ```
-    /// use serde_json::json;
-    /// use spikard_bindings_shared::JsonConversionHelper;
-    ///
-    /// // Primitive: returns Some
-    /// let val = json!(42);
-    /// assert!(JsonConversionHelper::try_fast_path_from_json(&val).is_some());
-    ///
-    /// // Primitive: returns Some
-    /// let val = json!("hello");
-    /// assert!(JsonConversionHelper::try_fast_path_from_json(&val).is_some());
-    ///
-    /// // Complex: returns None
-    /// let val = json!([1, 2, 3]);
-    /// assert!(JsonConversionHelper::try_fast_path_from_json(&val).is_none());
-    ///
-    /// // Complex: returns None
-    /// let val = json!({"key": "value"});
-    /// assert!(JsonConversionHelper::try_fast_path_from_json(&val).is_none());
-    /// ```
-    #[must_use]
-    pub fn try_fast_path_from_json(value: &Value) -> Option<JsonPrimitive<'_>> {
-        match value {
-            Value::Null => Some(JsonPrimitive::Null),
-            Value::Bool(b) => Some(JsonPrimitive::Bool(*b)),
-            // PERFORMANCE: Store number as String for precision preservation.
-            // serde_json::Number::to_string() is typically cached/optimized internally,
-            // and this is negligible compared to the fast-path gains for primitives.
-            // For most real-world workloads, primitive types dominate (~60% of conversions).
-            Value::Number(n) => Some(JsonPrimitive::Number(n.to_string())),
-            Value::String(s) => Some(JsonPrimitive::String(s)),
-            Value::Array(_) | Value::Object(_) => None,
-        }
-    }
-
-    /// Detect if a JSON value is a primitive type (fast-path candidate)
-    ///
-    /// Returns `true` if the value can be converted via the fast path.
-    /// This is useful for determining the conversion strategy without
-    /// extracting the primitive value.
-    ///
-    /// # Example
-    ///
-    /// ```
-    /// use serde_json::json;
-    /// use spikard_bindings_shared::JsonConversionHelper;
-    ///
-    /// assert!(JsonConversionHelper::is_primitive(&json!(null)));
-    /// assert!(JsonConversionHelper::is_primitive(&json!(true)));
-    /// assert!(JsonConversionHelper::is_primitive(&json!(42)));
-    /// assert!(JsonConversionHelper::is_primitive(&json!("text")));
-    ///
-    /// assert!(!JsonConversionHelper::is_primitive(&json!([])));
-    /// assert!(!JsonConversionHelper::is_primitive(&json!({})));
-    /// ```
-    #[must_use]
-    pub const fn is_primitive(value: &Value) -> bool {
-        matches!(
-            value,
-            Value::Null | Value::Bool(_) | Value::Number(_) | Value::String(_)
-        )
-    }
-
-    /// Count the estimated recursion depth needed for conversion
-    ///
-    /// Provides a rough estimate of how deeply nested the JSON structure is.
-    /// Useful for debugging or monitoring conversion performance.
-    ///
-    /// Returns 0 for primitives, 1 for arrays/objects containing only primitives,
-    /// and increases with nesting depth.
-    ///
-    /// # Example
-    ///
-    /// ```
-    /// use serde_json::json;
-    /// use spikard_bindings_shared::JsonConversionHelper;
-    ///
-    /// assert_eq!(JsonConversionHelper::estimate_depth(&json!(42)), 0);
-    /// assert_eq!(JsonConversionHelper::estimate_depth(&json!([1, 2, 3])), 1);
-    /// assert_eq!(JsonConversionHelper::estimate_depth(&json!({"a": 1})), 1);
-    /// assert!(JsonConversionHelper::estimate_depth(&json!({"a": [1, {"b": 2}]})) > 1);
-    /// ```
-    pub fn estimate_depth(value: &Value) -> usize {
-        match value {
-            Value::Null | Value::Bool(_) | Value::Number(_) | Value::String(_) => 0,
-            Value::Array(arr) => {
-                if arr.is_empty() {
-                    1
-                } else {
-                    1 + arr.iter().map(Self::estimate_depth).max().unwrap_or(0)
-                }
-            }
-            Value::Object(obj) => {
-                if obj.is_empty() {
-                    1
-                } else {
-                    1 + obj.values().map(Self::estimate_depth).max().unwrap_or(0)
-                }
-            }
-        }
-    }
-}
-
-#[cfg(test)]
-mod tests {
-    use super::*;
-    use serde_json::json;
-
-    // ========== JsonConversionError Tests ==========
-
-    #[test]
-    fn test_error_type_mismatch() {
-        let err = JsonConversionError::type_mismatch("string", "number");
-        assert!(err.to_string().contains("Type mismatch"));
-        assert!(err.to_string().contains("string"));
-        assert!(err.to_string().contains("number"));
-    }
-
-    #[test]
-    fn test_error_invalid_value() {
-        let err = JsonConversionError::invalid_value("value out of range");
-        assert!(err.to_string().contains("Invalid value"));
-        assert!(err.to_string().contains("out of range"));
-    }
-
-    #[test]
-    fn test_error_missing_field() {
-        let err = JsonConversionError::missing_field("user_id");
-        assert!(err.to_string().contains("Missing required field"));
-        assert!(err.to_string().contains("user_id"));
-    }
-
-    #[test]
-    fn test_error_serialization_error() {
-        let err = JsonConversionError::serialization_error("failed to serialize");
-        assert!(err.to_string().contains("Serialization error"));
-        assert!(err.to_string().contains("serialize"));
-    }
-
-    #[test]
-    fn test_error_conversion_error() {
-        let err = JsonConversionError::conversion_error("custom reason");
-        assert!(err.to_string().contains("Conversion error"));
-        assert!(err.to_string().contains("custom reason"));
-    }
-
-    // ========== JsonConversionHelper::try_fast_path_from_json Tests ==========
-
-    #[test]
-    fn test_fast_path_null() {
-        let val = json!(null);
-        let result = JsonConversionHelper::try_fast_path_from_json(&val);
-        assert!(matches!(result, Some(JsonPrimitive::Null)));
-    }
-
-    #[test]
-    fn test_fast_path_bool_true() {
-        let val = json!(true);
-        let result = JsonConversionHelper::try_fast_path_from_json(&val);
-        assert!(matches!(result, Some(JsonPrimitive::Bool(true))));
-    }
-
-    #[test]
-    fn test_fast_path_bool_false() {
-        let val = json!(false);
-        let result = JsonConversionHelper::try_fast_path_from_json(&val);
-        assert!(matches!(result, Some(JsonPrimitive::Bool(false))));
-    }
-
-    #[test]
-    fn test_fast_path_integer() {
-        let val = json!(42);
-        let result = JsonConversionHelper::try_fast_path_from_json(&val);
-        if let Some(JsonPrimitive::Number(n)) = result {
-            assert_eq!(n, "42");
-        } else {
-            panic!("Expected Number variant");
-        }
-    }
-
-    #[test]
-    fn test_fast_path_negative_integer() {
-        let val = json!(-123);
-        let result = JsonConversionHelper::try_fast_path_from_json(&val);
-        if let Some(JsonPrimitive::Number(n)) = result {
-            assert_eq!(n, "-123");
-        } else {
-            panic!("Expected Number variant");
-        }
-    }
-
-    #[test]
-    fn test_fast_path_float() {
-        #[allow(clippy::approx_constant)]
-        let val = json!(3.14);
-        let result = JsonConversionHelper::try_fast_path_from_json(&val);
-        assert!(matches!(result, Some(JsonPrimitive::Number(_))));
-    }
-
-    #[test]
-    fn test_fast_path_zero() {
-        let val = json!(0);
-        let result = JsonConversionHelper::try_fast_path_from_json(&val);
-        if let Some(JsonPrimitive::Number(n)) = result {
-            assert_eq!(n, "0");
-        } else {
-            panic!("Expected Number variant");
-        }
-    }
-
-    #[test]
-    fn test_fast_path_large_number() {
-        let val = json!(9_223_372_036_854_775_807i64); // i64::MAX
-        let result = JsonConversionHelper::try_fast_path_from_json(&val);
-        assert!(matches!(result, Some(JsonPrimitive::Number(_))));
-    }
-
-    #[test]
-    fn test_fast_path_string() {
-        let val = json!("hello");
-        let result = JsonConversionHelper::try_fast_path_from_json(&val);
-        assert!(matches!(result, Some(JsonPrimitive::String("hello"))));
-    }
-
-    #[test]
-    fn test_fast_path_empty_string() {
-        let val = json!("");
-        let result = JsonConversionHelper::try_fast_path_from_json(&val);
-        assert!(matches!(result, Some(JsonPrimitive::String(""))));
-    }
-
-    #[test]
-    fn test_fast_path_string_with_special_chars() {
-        let val = json!("hello \"world\" \n with special \t chars");
-        let result = JsonConversionHelper::try_fast_path_from_json(&val);
-        assert!(matches!(result, Some(JsonPrimitive::String(_))));
-    }
-
-    #[test]
-    fn test_fast_path_unicode_string() {
-        let val = json!("café ☕ 日本語");
-        let result = JsonConversionHelper::try_fast_path_from_json(&val);
-        assert!(matches!(result, Some(JsonPrimitive::String(_))));
-    }
-
-    #[test]
-    fn test_fast_path_empty_array_returns_none() {
-        let val = json!([]);
-        let result = JsonConversionHelper::try_fast_path_from_json(&val);
-        assert!(result.is_none());
-    }
-
-    #[test]
-    fn test_fast_path_array_with_primitives_returns_none() {
-        let val = json!([1, 2, 3]);
-        let result = JsonConversionHelper::try_fast_path_from_json(&val);
-        assert!(result.is_none());
-    }
-
-    #[test]
-    fn test_fast_path_array_with_objects_returns_none() {
-        let val = json!([{"a": 1}]);
-        let result = JsonConversionHelper::try_fast_path_from_json(&val);
-        assert!(result.is_none());
-    }
-
-    #[test]
-    fn test_fast_path_empty_object_returns_none() {
-        let val = json!({});
-        let result = JsonConversionHelper::try_fast_path_from_json(&val);
-        assert!(result.is_none());
-    }
-
-    #[test]
-    fn test_fast_path_object_with_primitives_returns_none() {
-        let val = json!({"key": "value", "count": 42});
-        let result = JsonConversionHelper::try_fast_path_from_json(&val);
-        assert!(result.is_none());
-    }
-
-    #[test]
-    fn test_fast_path_nested_object_returns_none() {
-        let val = json!({"outer": {"inner": "value"}});
-        let result = JsonConversionHelper::try_fast_path_from_json(&val);
-        assert!(result.is_none());
-    }
-
-    // ========== JsonConversionHelper::is_primitive Tests ==========
-
-    #[test]
-    fn test_is_primitive_null() {
-        assert!(JsonConversionHelper::is_primitive(&json!(null)));
-    }
-
-    #[test]
-    fn test_is_primitive_bool() {
-        assert!(JsonConversionHelper::is_primitive(&json!(true)));
-        assert!(JsonConversionHelper::is_primitive(&json!(false)));
-    }
-
-    #[test]
-    fn test_is_primitive_number() {
-        assert!(JsonConversionHelper::is_primitive(&json!(42)));
-        #[allow(clippy::approx_constant)]
-        {
-            assert!(JsonConversionHelper::is_primitive(&json!(3.14)));
-        }
-        assert!(JsonConversionHelper::is_primitive(&json!(-100)));
-    }
-
-    #[test]
-    fn test_is_primitive_string() {
-        assert!(JsonConversionHelper::is_primitive(&json!("text")));
-        assert!(JsonConversionHelper::is_primitive(&json!("")));
-    }
-
-    #[test]
-    fn test_is_primitive_array_false() {
-        assert!(!JsonConversionHelper::is_primitive(&json!([1, 2, 3])));
-        assert!(!JsonConversionHelper::is_primitive(&json!([])));
-    }
-
-    #[test]
-    fn test_is_primitive_object_false() {
-        assert!(!JsonConversionHelper::is_primitive(&json!({"key": "value"})));
-        assert!(!JsonConversionHelper::is_primitive(&json!({})));
-    }
-
-    // ========== JsonConversionHelper::estimate_depth Tests ==========
-
-    #[test]
-    fn test_estimate_depth_null() {
-        assert_eq!(JsonConversionHelper::estimate_depth(&json!(null)), 0);
-    }
-
-    #[test]
-    fn test_estimate_depth_bool() {
-        assert_eq!(JsonConversionHelper::estimate_depth(&json!(true)), 0);
-        assert_eq!(JsonConversionHelper::estimate_depth(&json!(false)), 0);
-    }
-
-    #[test]
-    fn test_estimate_depth_number() {
-        assert_eq!(JsonConversionHelper::estimate_depth(&json!(42)), 0);
-        #[allow(clippy::approx_constant)]
-        {
-            assert_eq!(JsonConversionHelper::estimate_depth(&json!(3.14)), 0);
-        }
-    }
-
-    #[test]
-    fn test_estimate_depth_string() {
-        assert_eq!(JsonConversionHelper::estimate_depth(&json!("text")), 0);
-    }
-
-    #[test]
-    fn test_estimate_depth_empty_array() {
-        assert_eq!(JsonConversionHelper::estimate_depth(&json!([])), 1);
-    }
-
-    #[test]
-    fn test_estimate_depth_array_of_primitives() {
-        assert_eq!(JsonConversionHelper::estimate_depth(&json!([1, 2, 3])), 1);
-        assert_eq!(JsonConversionHelper::estimate_depth(&json!(["a", "b", "c", "d"])), 1);
-    }
-
-    #[test]
-    fn test_estimate_depth_empty_object() {
-        assert_eq!(JsonConversionHelper::estimate_depth(&json!({})), 1);
-    }
-
-    #[test]
-    fn test_estimate_depth_object_of_primitives() {
-        assert_eq!(JsonConversionHelper::estimate_depth(&json!({"a": 1, "b": 2})), 1);
-    }
-
-    #[test]
-    fn test_estimate_depth_nested_array_one_level() {
-        assert_eq!(JsonConversionHelper::estimate_depth(&json!([[1, 2], [3, 4]])), 2);
-    }
-
-    #[test]
-    fn test_estimate_depth_nested_object_one_level() {
-        assert_eq!(JsonConversionHelper::estimate_depth(&json!({"outer": {"inner": 1}})), 2);
-    }
-
-    #[test]
-    fn test_estimate_depth_mixed_nesting() {
-        let val = json!({
-            "user": {
-                "name": "John",
-                "roles": ["admin", "user"],
-                "settings": {
-                    "theme": "dark"
-                }
-            }
-        });
-        let depth = JsonConversionHelper::estimate_depth(&val);
-        assert!(depth >= 3, "Expected depth >= 3, got {depth}");
-    }
-
-    #[test]
-    fn test_estimate_depth_deeply_nested() {
-        let val = json!({
-            "a": {
-                "b": {
-                    "c": {
-                        "d": {
-                            "e": "value"
-                        }
-                    }
-                }
-            }
-        });
-        let depth = JsonConversionHelper::estimate_depth(&val);
-        assert_eq!(depth, 5);
-    }
-
-    #[test]
-    fn test_estimate_depth_array_of_objects() {
-        let val = json!([
-            {"name": "a", "value": 1},
-            {"name": "b", "value": 2},
-            {"name": "c", "value": 3}
-        ]);
-        let depth = JsonConversionHelper::estimate_depth(&val);
-        assert_eq!(depth, 2);
-    }
-
-    // ========== Integration Tests ==========
-
-    #[test]
-    fn test_primitive_roundtrip() {
-        // All primitives should be detected as primitives
-        let mut primitives = vec![
-            json!(null),
-            json!(true),
-            json!(false),
-            json!(0),
-            json!(42),
-            json!(-42),
-            json!("string"),
-            json!(""),
-        ];
-        // Add 3.14 with explicit allow for approx_constant
-        #[allow(clippy::approx_constant)]
-        {
-            primitives.push(json!(3.14));
-        }
-
-        for val in primitives {
-            let is_prim = JsonConversionHelper::is_primitive(&val);
-            let fast_path = JsonConversionHelper::try_fast_path_from_json(&val);
-            assert!(is_prim, "Expected {val:?} to be primitive");
-            assert!(fast_path.is_some(), "Expected fast path for {val:?}");
-        }
-    }
-
-    #[test]
-    fn test_complex_types_not_primitives() {
-        let complex = vec![json!([]), json!([1]), json!({}), json!({"a": 1})];
-
-        for val in complex {
-            let is_prim = JsonConversionHelper::is_primitive(&val);
-            let fast_path = JsonConversionHelper::try_fast_path_from_json(&val);
-            assert!(!is_prim, "Expected {val:?} to not be primitive");
-            assert!(fast_path.is_none(), "Expected no fast path for {val:?}");
-        }
-    }
-
-    #[test]
-    fn test_error_display_messages() {
-        let errors = vec![
-            JsonConversionError::type_mismatch("expected", "got"),
-            JsonConversionError::invalid_value("reason"),
-            JsonConversionError::missing_field("field"),
-            JsonConversionError::serialization_error("error"),
-            JsonConversionError::conversion_error("reason"),
-        ];
-
-        for err in errors {
-            let msg = err.to_string();
-            assert!(!msg.is_empty(), "Error message should not be empty");
-        }
-    }
-
-    #[test]
-    fn test_fast_path_string_references() {
-        // Verify that fast path returns references, not clones
-        let val = json!("test_string");
-        if let Some(JsonPrimitive::String(s)) = JsonConversionHelper::try_fast_path_from_json(&val) {
-            assert_eq!(s, "test_string");
-        } else {
-            panic!("Expected string primitive");
-        }
-    }
-
-    #[test]
-    fn test_estimate_depth_array_vs_object() {
-        let arr = json!([1, 2, 3]);
-        let obj = json!({"a": 1, "b": 2, "c": 3});
-
-        let arr_depth = JsonConversionHelper::estimate_depth(&arr);
-        let obj_depth = JsonConversionHelper::estimate_depth(&obj);
-
-        // Both should have the same depth (1)
-        assert_eq!(arr_depth, obj_depth);
-    }
-
-    #[test]
-    fn test_large_array_depth() {
-        let large_array: Vec<_> = (0..1000).map(|i| json!(i)).collect();
-        let val = Value::Array(large_array);
-        let depth = JsonConversionHelper::estimate_depth(&val);
-        assert_eq!(depth, 1);
-    }
-
-    #[test]
-    fn test_large_object_depth() {
-        let mut obj = serde_json::Map::new();
-        for i in 0..1000 {
-            #[allow(clippy::cast_sign_loss)]
-            {
-                obj.insert(format!("key_{i}"), Value::Number(i64::from(i as u32).into()));
-            }
-        }
-        let val = Value::Object(obj);
-        let depth = JsonConversionHelper::estimate_depth(&val);
-        assert_eq!(depth, 1);
-    }
-
-    #[test]
-    fn test_coverage_all_primitive_types() {
-        // Ensure we test every variant of JsonPrimitive
-        let null_val = json!(null);
-        let bool_val = json!(true);
-        let num_val = json!(42);
-        let str_val = json!("text");
-
-        assert!(matches!(
-            JsonConversionHelper::try_fast_path_from_json(&null_val),
-            Some(JsonPrimitive::Null)
-        ));
-        assert!(matches!(
-            JsonConversionHelper::try_fast_path_from_json(&bool_val),
-            Some(JsonPrimitive::Bool(_))
-        ));
-        assert!(matches!(
-            JsonConversionHelper::try_fast_path_from_json(&num_val),
-            Some(JsonPrimitive::Number(_))
-        ));
-        assert!(matches!(
-            JsonConversionHelper::try_fast_path_from_json(&str_val),
-            Some(JsonPrimitive::String(_))
-        ));
-    }
-}