nautilus_core/

serialization.rs

// -------------------------------------------------------------------------------------------------
//  Copyright (C) 2015-2026 Nautech Systems Pty Ltd. All rights reserved.
//  https://nautechsystems.io
//
//  Licensed under the GNU Lesser General Public License Version 3.0 (the "License");
//  You may not use this file except in compliance with the License.
//  You may obtain a copy of the License at https://www.gnu.org/licenses/lgpl-3.0.en.html
//
//  Unless required by applicable law or agreed to in writing, software
//  distributed under the License is distributed on an "AS IS" BASIS,
//  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
//  See the License for the specific language governing permissions and
//  limitations under the License.
// -------------------------------------------------------------------------------------------------

//! Common serialization traits and functions.
//!
//! This module provides custom serde deserializers and serializers for common
//! patterns encountered when parsing exchange API responses, particularly:
//!
//! - Empty strings that should be interpreted as `None` or zero.
//! - Type conversions from strings to primitives.
//! - Decimal values represented as strings.

use std::{borrow::Cow, str::FromStr};

use bytes::Bytes;
use rust_decimal::Decimal;
use serde::{
    Deserialize, Deserializer, Serialize, Serializer,
    de::{Error, MapAccess, Unexpected, Visitor, value::MapAccessDeserializer},
    ser::SerializeSeq,
};
use serde_json::value::RawValue;
use ustr::Ustr;

pub mod decimal;

/// Sorted serialization for `AHashSet<T>` where element order must be deterministic.
///
/// Use with `#[serde(with = "nautilus_core::serialization::sorted_hashset")]`.
pub mod sorted_hashset {
    use ahash::AHashSet;
    use serde::{Deserialize, Deserializer, Serialize, Serializer};

    /// Serializes an `AHashSet<T>` as a sorted array for deterministic output.
    ///
    /// # Errors
    ///
    /// Returns an error if the underlying [`Serializer`] fails when writing the sorted vector.
    pub fn serialize<T, S>(set: &AHashSet<T>, s: S) -> Result<S::Ok, S::Error>
    where
        T: Serialize + Ord,
        S: Serializer,
    {
        let mut sorted: Vec<&T> = set.iter().collect();
        sorted.sort_unstable();
        sorted.serialize(s)
    }

    /// Deserializes an array into an `AHashSet<T>`.
    ///
    /// # Errors
    ///
    /// Returns an error if the underlying [`Deserializer`] fails when reading the source array.
    pub fn deserialize<'de, T, D>(d: D) -> Result<AHashSet<T>, D::Error>
    where
        T: Deserialize<'de> + Eq + std::hash::Hash,
        D: Deserializer<'de>,
    {
        let vec = Vec::<T>::deserialize(d)?;
        Ok(vec.into_iter().collect())
    }
}

/// Decimal visitor for direct JSON token conversion.
///
/// Directly visits JSON tokens without intermediate `serde_json::Value` allocation.
/// Handles all JSON numeric representations: strings, integers, floats, and null.
struct DecimalVisitor;

impl<'de> Visitor<'de> for DecimalVisitor {
    type Value = Decimal;

    fn expecting(&self, formatter: &mut std::fmt::Formatter) -> std::fmt::Result {
        formatter.write_str("a decimal number as string, integer, or float")
    }

    // Fast path: borrowed string (zero-copy)
    fn visit_str<E: Error>(self, v: &str) -> Result<Self::Value, E> {
        if v.is_empty() {
            return Ok(Decimal::ZERO);
        }
        parse_decimal_str(v).map_err(E::custom)
    }

    // Owned string (rare case, delegates to visit_str)
    fn visit_string<E: Error>(self, v: String) -> Result<Self::Value, E> {
        self.visit_str(&v)
    }

    // Direct integer handling - no string conversion needed
    fn visit_i64<E: Error>(self, v: i64) -> Result<Self::Value, E> {
        Ok(Decimal::from(v))
    }

    fn visit_u64<E: Error>(self, v: u64) -> Result<Self::Value, E> {
        Ok(Decimal::from(v))
    }

    fn visit_i128<E: Error>(self, v: i128) -> Result<Self::Value, E> {
        Decimal::try_from_i128_with_scale(v, 0).map_err(E::custom)
    }

    fn visit_u128<E: Error>(self, v: u128) -> Result<Self::Value, E> {
        let v = i128::try_from(v).map_err(E::custom)?;
        Decimal::try_from_i128_with_scale(v, 0).map_err(E::custom)
    }

    // Float handling - direct conversion
    fn visit_f64<E: Error>(self, v: f64) -> Result<Self::Value, E> {
        if !v.is_finite() {
            return Err(E::invalid_value(Unexpected::Float(v), &self));
        }
        Decimal::try_from(v).map_err(E::custom)
    }

    fn visit_map<A: MapAccess<'de>>(self, map: A) -> Result<Self::Value, A::Error> {
        let number = serde_json::Number::deserialize(MapAccessDeserializer::new(map))?;
        self.visit_str(&number.to_string())
    }

    // Null → zero (matches existing behavior)
    fn visit_unit<E: Error>(self) -> Result<Self::Value, E> {
        Ok(Decimal::ZERO)
    }

    fn visit_none<E: Error>(self) -> Result<Self::Value, E> {
        Ok(Decimal::ZERO)
    }
}

/// Optional decimal visitor for direct JSON token conversion.
///
/// Handles null values as `None` and empty strings as `None`.
/// Uses `deserialize_any` approach to handle all JSON value types uniformly.
struct OptionalDecimalVisitor;

impl<'de> Visitor<'de> for OptionalDecimalVisitor {
    type Value = Option<Decimal>;

    fn expecting(&self, formatter: &mut std::fmt::Formatter) -> std::fmt::Result {
        formatter.write_str("null or a decimal number as string, integer, or float")
    }

    // Fast path: borrowed string (zero-copy)
    // Empty string → None (different from DecimalVisitor which returns ZERO)
    fn visit_str<E: Error>(self, v: &str) -> Result<Self::Value, E> {
        if v.is_empty() {
            return Ok(None);
        }
        DecimalVisitor.visit_str(v).map(Some)
    }

    fn visit_string<E: Error>(self, v: String) -> Result<Self::Value, E> {
        self.visit_str(&v)
    }

    fn visit_i64<E: Error>(self, v: i64) -> Result<Self::Value, E> {
        DecimalVisitor.visit_i64(v).map(Some)
    }

    fn visit_u64<E: Error>(self, v: u64) -> Result<Self::Value, E> {
        DecimalVisitor.visit_u64(v).map(Some)
    }

    fn visit_i128<E: Error>(self, v: i128) -> Result<Self::Value, E> {
        DecimalVisitor.visit_i128(v).map(Some)
    }

    fn visit_u128<E: Error>(self, v: u128) -> Result<Self::Value, E> {
        DecimalVisitor.visit_u128(v).map(Some)
    }

    fn visit_f64<E: Error>(self, v: f64) -> Result<Self::Value, E> {
        DecimalVisitor.visit_f64(v).map(Some)
    }

    fn visit_map<A: MapAccess<'de>>(self, map: A) -> Result<Self::Value, A::Error> {
        DecimalVisitor.visit_map(map).map(Some)
    }

    // Null → None
    fn visit_unit<E: Error>(self) -> Result<Self::Value, E> {
        Ok(None)
    }

    fn visit_none<E: Error>(self) -> Result<Self::Value, E> {
        Ok(None)
    }
}

fn json_token_text(raw: &RawValue) -> serde_json::Result<Cow<'_, str>> {
    let text = raw.get();
    if text.starts_with('"') {
        // Generic deserializers can supply RawValue text without lexical validation.
        if let Some(contents) = text
            .strip_prefix('"')
            .and_then(|text| text.strip_suffix('"'))
            && !contents
                .bytes()
                .any(|byte| byte < 0x20 || byte == b'"' || byte == b'\\')
        {
            return Ok(Cow::Borrowed(contents));
        }
        serde_json::from_str::<String>(text).map(Cow::Owned)
    } else {
        Ok(Cow::Borrowed(text))
    }
}

fn parse_decimal_str(value: &str) -> Result<Decimal, String> {
    let parsed = if value.contains('e') || value.contains('E') {
        if value.len() <= Decimal::MAX_SCALE as usize {
            Decimal::from_scientific(value)
        } else {
            decimal::parse(value).or_else(|_| Decimal::from_scientific(value))
        }
    } else {
        Decimal::from_str(value)
    };

    match parsed {
        Ok(decimal) => Ok(decimal),
        Err(e) => decimal_str_rounded(value).ok_or_else(|| e.to_string()),
    }
}

// Fractional digits beyond Decimal's maximum scale are sub-representable; round to the highest
// scale that fits (venues quoting 18-decimal on-chain units emit such values)
fn decimal_str_rounded(value: &str) -> Option<Decimal> {
    for scale in (0..=Decimal::MAX_SCALE as usize).rev() {
        let clamped = decimal_string_clamped_to_scale(value, scale)?;

        if let Ok(decimal) = Decimal::from_str(&clamped) {
            return Some(decimal);
        }
    }

    None
}

fn decimal_string_clamped_to_scale(value: &str, max_scale: usize) -> Option<String> {
    let (coefficient, exponent) = match value.find(['e', 'E']) {
        Some(index) => {
            let exponent = value[index + 1..].parse::<i32>().ok()?;
            (&value[..index], exponent)
        }
        None => (value, 0),
    };

    let (sign, unsigned) = match coefficient.as_bytes().first()? {
        b'+' => ("", &coefficient[1..]),
        b'-' => ("-", &coefficient[1..]),
        _ => ("", coefficient),
    };
    let (integer, fractional) = decimal_components(unsigned)?;
    let digits = format!("{integer}{fractional}");
    if decimal_digits_are_zero(&digits, "") {
        return Some("0".to_string());
    }

    let point = i32::try_from(integer.len()).ok()?.checked_add(exponent)?;

    // Decimal can hold at most 29 significant integer digits, and
    // `Decimal::from_str` below still rejects values above Decimal::MAX.
    // Check significant digits before expansion so absurd exponents keep the
    // original parse error without allocating an absurd string.
    if decimal_integer_digits_exceed_max(&digits, point) {
        return None;
    }

    let (integer, fractional) = if point <= 0 {
        // Digits past the rounding position are leading zeros, so the cap
        // cannot change the result; bounds allocation for absurd exponents.
        let zero_count = usize::try_from(point.checked_neg()?)
            .ok()?
            .min(max_scale + 1);
        (
            "0".to_string(),
            format!("{}{digits}", "0".repeat(zero_count)),
        )
    } else {
        let point = usize::try_from(point).ok()?;
        if point >= digits.len() {
            (
                format!("{}{}", digits, "0".repeat(point - digits.len())),
                String::new(),
            )
        } else {
            (digits[..point].to_string(), digits[point..].to_string())
        }
    };

    let (integer, fractional) = round_decimal_components(integer, fractional, max_scale);
    let sign = if sign == "-" && decimal_digits_are_zero(&integer, &fractional) {
        ""
    } else {
        sign
    };

    if fractional.is_empty() {
        Some(format!("{sign}{integer}"))
    } else {
        Some(format!("{sign}{integer}.{fractional}"))
    }
}

fn decimal_components(value: &str) -> Option<(&str, &str)> {
    let mut split = value.split('.');
    let integer = split.next()?;
    let fractional = split.next().unwrap_or("");
    if split.next().is_some()
        || (integer.is_empty() && fractional.is_empty())
        || !integer.chars().all(|c| c.is_ascii_digit())
        || !fractional.chars().all(|c| c.is_ascii_digit())
    {
        return None;
    }
    Some((integer, fractional))
}

fn decimal_integer_digits_exceed_max(digits: &str, point: i32) -> bool {
    const DECIMAL_MAX_INTEGER_DIGITS: i32 = 29;

    if point <= 0 {
        return false;
    }

    let Some(first_non_zero) = digits.bytes().position(|digit| digit != b'0') else {
        return false;
    };
    let Ok(first_non_zero) = i32::try_from(first_non_zero) else {
        return true;
    };

    point.saturating_sub(first_non_zero) > DECIMAL_MAX_INTEGER_DIGITS
}

fn round_decimal_components(
    mut integer: String,
    fractional: String,
    max_scale: usize,
) -> (String, String) {
    if fractional.len() <= max_scale {
        return (integer, fractional);
    }

    let mut rounded = fractional.as_bytes()[..max_scale].to_vec();
    if fractional.as_bytes()[max_scale] >= b'5' {
        increment_decimal_digits(&mut integer, &mut rounded);
    }

    (
        integer,
        String::from_utf8(rounded).expect("decimal digits are ASCII"),
    )
}

fn increment_decimal_digits(integer: &mut String, fractional: &mut [u8]) {
    for digit in fractional.iter_mut().rev() {
        if *digit < b'9' {
            *digit += 1;
            return;
        }
        *digit = b'0';
    }

    let mut integer_digits = integer.as_bytes().to_vec();
    for digit in integer_digits.iter_mut().rev() {
        if *digit < b'9' {
            *digit += 1;
            *integer = String::from_utf8(integer_digits).expect("decimal digits are ASCII");
            return;
        }
        *digit = b'0';
    }
    integer_digits.insert(0, b'1');
    *integer = String::from_utf8(integer_digits).expect("decimal digits are ASCII");
}

fn decimal_digits_are_zero(integer: &str, fractional: &str) -> bool {
    integer
        .bytes()
        .chain(fractional.bytes())
        .all(|digit| digit == b'0')
}

/// Represents types which are serializable for JSON specifications.
pub trait Serializable: Serialize + for<'de> Deserialize<'de> {
    /// Deserialize an object from JSON encoded bytes.
    ///
    /// # Errors
    ///
    /// Returns an error if JSON deserialization fails.
    fn from_json_bytes(data: &[u8]) -> Result<Self, serde_json::Error> {
        serde_json::from_slice(data)
    }

    /// Serialize an object to JSON encoded bytes.
    ///
    /// # Errors
    ///
    /// Returns an error if JSON serialization fails.
    fn to_json_bytes(&self) -> Result<Bytes, serde_json::Error> {
        serde_json::to_vec(self).map(Bytes::from)
    }
}

pub use self::msgpack::{FromMsgPack, MsgPackSerializable, ToMsgPack};

/// Provides `MsgPack` serialization support for types implementing [`Serializable`].
///
/// This module contains traits for `MsgPack` serialization and deserialization,
/// separated from the core [`Serializable`] trait to allow independent opt-in.
pub mod msgpack {
    use bytes::Bytes;
    use serde::{Deserialize, Serialize};

    use super::Serializable;

    /// Provides deserialization from `MsgPack` encoded bytes.
    pub trait FromMsgPack: for<'de> Deserialize<'de> + Sized {
        /// Deserialize an object from `MsgPack` encoded bytes.
        ///
        /// # Errors
        ///
        /// Returns an error if MessagePack deserialization fails.
        fn from_msgpack_bytes(data: &[u8]) -> Result<Self, rmp_serde::decode::Error> {
            rmp_serde::from_slice(data)
        }
    }

    /// Provides serialization to `MsgPack` encoded bytes.
    pub trait ToMsgPack: Serialize {
        /// Serialize an object to `MsgPack` encoded bytes.
        ///
        /// # Errors
        ///
        /// Returns an error if MessagePack serialization fails.
        fn to_msgpack_bytes(&self) -> Result<Bytes, rmp_serde::encode::Error> {
            rmp_serde::to_vec_named(self).map(Bytes::from)
        }
    }

    /// Marker trait combining [`Serializable`], [`FromMsgPack`], and [`ToMsgPack`].
    ///
    /// This trait is automatically implemented for all types that implement [`Serializable`].
    pub trait MsgPackSerializable: Serializable + FromMsgPack + ToMsgPack {}

    impl<T> FromMsgPack for T where T: Serializable {}

    impl<T> ToMsgPack for T where T: Serializable {}

    impl<T> MsgPackSerializable for T where T: Serializable {}
}

/// Serde default value function that returns `true`.
///
/// Use with `#[serde(default = "default_true")]` on boolean fields.
#[must_use]
pub const fn default_true() -> bool {
    true
}

/// Serde default value function that returns `false`.
///
/// Use with `#[serde(default = "default_false")]` on boolean fields.
#[must_use]
pub const fn default_false() -> bool {
    false
}

/// Deserializes a `Decimal` from either a JSON string or number.
///
/// High-performance implementation using a custom visitor that avoids intermediate
/// `serde_json::Value` allocations. Handles all JSON numeric representations:
///
/// - JSON string: `"123.456"` → Decimal (zero-copy for borrowed strings)
/// - JSON integer: `123` → Decimal (direct conversion, no string allocation)
/// - JSON float: `123.456` → Decimal
/// - JSON null: → `Decimal::ZERO`
/// - Scientific notation: `"1.5e-8"` → Decimal
/// - Fractional digits beyond `Decimal`'s maximum scale (28) are rounded
/// - Scientific strings preserve exactly representable values after exponent normalization
///
/// # Performance
///
/// This implementation is optimized for high-frequency trading scenarios:
/// - Zero allocations for exactly representable plain borrowed strings
/// - Scientific normalization and high-scale rounding may allocate
/// - Direct integer conversion without string intermediary
/// - No intermediate `serde_json::Value` heap allocation
///
/// # Errors
///
/// Returns an error if the value cannot be parsed as a valid decimal.
pub fn deserialize_decimal<'de, D>(deserializer: D) -> Result<Decimal, D::Error>
where
    D: Deserializer<'de>,
{
    deserializer.deserialize_any(DecimalVisitor)
}

/// Deserializes a `Decimal` through `rust_decimal`'s own `Deserialize` implementation, keeping
/// its rounding and scale.
///
/// When `rust_decimal`'s arbitrary-precision integration is disabled, `serde_json`
/// arbitrary-precision numbers parse from their text as `rust_decimal` parses a string, which
/// matches the result with that integration enabled. Unlike [`deserialize_decimal`], null and
/// empty strings are errors.
///
/// # Errors
///
/// Returns an error if:
/// - The value is null or an empty string.
/// - The value is a non-numeric type.
/// - `rust_decimal` rejects the value.
pub fn deserialize_decimal_native<'de, D>(deserializer: D) -> Result<Decimal, D::Error>
where
    D: Deserializer<'de>,
{
    #[derive(Deserialize)]
    #[serde(untagged)]
    enum Value {
        Decimal(Decimal),
        Number(serde_json::Number),
    }

    match Value::deserialize(deserializer)? {
        Value::Decimal(value) => Ok(value),

        // Handle serde_json's numeric map when rust_decimal's AP integration is disabled
        Value::Number(value) => <Decimal as Deserialize>::deserialize(
            serde::de::value::StringDeserializer::<D::Error>::new(value.to_string()),
        ),
    }
}

/// Deserializes an `Option<Decimal>` from a JSON string, number, or null.
///
/// High-performance implementation using a custom visitor that avoids intermediate
/// `serde_json::Value` allocations. Handles all JSON numeric representations:
///
/// - JSON string: `"123.456"` → Some(Decimal) (zero-copy for borrowed strings)
/// - JSON integer: `123` → Some(Decimal) (direct conversion)
/// - JSON float: `123.456` → Some(Decimal)
/// - JSON null: → `None`
/// - Empty string: `""` → `None`
/// - Scientific notation: `"1.5e-8"` → Some(Decimal)
/// - Fractional digits beyond `Decimal`'s maximum scale (28) are rounded
/// - Scientific strings preserve exactly representable values after exponent normalization
///
/// # Performance
///
/// This implementation is optimized for high-frequency trading scenarios:
/// - Zero allocations for exactly representable plain borrowed strings
/// - Scientific normalization and high-scale rounding may allocate
/// - Direct integer conversion without string intermediary
/// - No intermediate `serde_json::Value` heap allocation
///
/// # Errors
///
/// Returns an error if the value cannot be parsed as a valid decimal.
pub fn deserialize_optional_decimal<'de, D>(deserializer: D) -> Result<Option<Decimal>, D::Error>
where
    D: Deserializer<'de>,
{
    // Use deserialize_any to handle all JSON value types uniformly
    // (deserialize_option would route non-null through visit_some, losing empty string handling)
    deserializer.deserialize_any(OptionalDecimalVisitor)
}

/// Deserializes a `Decimal` from the source text of a JSON number or numeric string.
///
/// Numeric tokens keep their source digits instead of passing through `f64`. Representable
/// values, including scientific notation, parse exactly. Values with fractional digits beyond
/// `Decimal`'s maximum scale (28) round as strings do in [`deserialize_decimal`]. Unlike
/// [`deserialize_decimal`], null and empty strings are errors.
///
/// The raw token is only available from direct JSON input: serde's internally tagged and
/// untagged enum buffers cannot carry it. A buffered `serde_json::Value` renders its number,
/// which keeps the source digits only with `serde_json/arbitrary_precision`. For borrowed JSON
/// text, [`deserialize_decimal_token_borrowed`] reads the same tokens without copying them.
///
/// # Errors
///
/// Returns an error if the token is null, an empty string, not a decimal, or outside `Decimal`'s
/// range.
pub fn deserialize_decimal_token<'de, D>(deserializer: D) -> Result<Decimal, D::Error>
where
    D: Deserializer<'de>,
{
    deserialize_optional_decimal_token(deserializer)?
        .ok_or_else(|| D::Error::custom(DECIMAL_TOKEN_MISSING))
}

/// Deserializes an `Option<Decimal>` from the source text of a JSON number, numeric string, or
/// null.
///
/// Null and empty strings read as `None`; other tokens parse as in
/// [`deserialize_decimal_token`]. Add `#[serde(default)]` to accept a missing field.
///
/// # Errors
///
/// Returns an error if a token other than null or an empty string is not a decimal or is outside
/// `Decimal`'s range.
pub fn deserialize_optional_decimal_token<'de, D>(
    deserializer: D,
) -> Result<Option<Decimal>, D::Error>
where
    D: Deserializer<'de>,
{
    Option::<Box<RawValue>>::deserialize(deserializer)?
        .map_or(Ok(None), |raw| parse_decimal_token(&raw))
}

/// Deserializes a `Decimal` as [`deserialize_decimal_token`] does, borrowing the token from the
/// input instead of copying it.
///
/// Requires a deserializer that borrows from its input, such as `serde_json::from_str` or
/// `serde_json::from_slice`. Use [`deserialize_decimal_token`] for `serde_json::from_reader` and
/// `serde_json::Value` input.
///
/// # Errors
///
/// Returns an error if the deserializer cannot lend the token, or for any token that
/// [`deserialize_decimal_token`] rejects.
pub fn deserialize_decimal_token_borrowed<'de, D>(deserializer: D) -> Result<Decimal, D::Error>
where
    D: Deserializer<'de>,
{
    deserialize_optional_decimal_token_borrowed(deserializer)?
        .ok_or_else(|| D::Error::custom(DECIMAL_TOKEN_MISSING))
}

/// Deserializes an `Option<Decimal>` as [`deserialize_optional_decimal_token`] does, borrowing
/// the token from the input instead of copying it.
///
/// Requires borrowed input, as described for [`deserialize_decimal_token_borrowed`].
///
/// # Errors
///
/// Returns an error if the deserializer cannot lend the token, or for any token that
/// [`deserialize_optional_decimal_token`] rejects.
pub fn deserialize_optional_decimal_token_borrowed<'de, D>(
    deserializer: D,
) -> Result<Option<Decimal>, D::Error>
where
    D: Deserializer<'de>,
{
    Option::<&'de RawValue>::deserialize(deserializer)?.map_or(Ok(None), parse_decimal_token)
}

const DECIMAL_TOKEN_MISSING: &str = "expected a decimal, was null or an empty string";

fn parse_decimal_token<E: Error>(raw: &RawValue) -> Result<Option<Decimal>, E> {
    let text = json_token_text(raw).map_err(E::custom)?;

    if let Ok(value) = decimal::parse(&text) {
        return Ok(Some(value));
    }

    // `Decimal::from_scientific` rounds the significand before applying the exponent
    if text.contains(['e', 'E'])
        && let Some(value) = decimal_str_rounded(&text)
    {
        return Ok(Some(value));
    }

    OptionalDecimalVisitor.visit_str(&text)
}

/// Deserializes a `Decimal` from a JSON string.
///
/// This is the strict form that requires the value to be a string, rejecting
/// numeric JSON values to avoid precision loss.
///
/// # Errors
///
/// Returns an error if the string cannot be parsed as a valid decimal.
pub fn deserialize_decimal_from_str<'de, D>(deserializer: D) -> Result<Decimal, D::Error>
where
    D: Deserializer<'de>,
{
    let s: std::borrow::Cow<'de, str> = Deserialize::deserialize(deserializer)?;
    Decimal::from_str(s.as_ref()).map_err(D::Error::custom)
}

/// Deserializes a `Decimal` from a string field that might be empty.
///
/// Handles edge cases where empty string "" or "0" becomes `Decimal::ZERO`.
///
/// # Errors
///
/// Returns an error if the string cannot be parsed as a valid decimal.
pub fn deserialize_decimal_or_zero<'de, D>(deserializer: D) -> Result<Decimal, D::Error>
where
    D: Deserializer<'de>,
{
    let s: std::borrow::Cow<'de, str> = Deserialize::deserialize(deserializer)?;
    if s.is_empty() || s == "0" {
        Ok(Decimal::ZERO)
    } else {
        Decimal::from_str(s.as_ref()).map_err(D::Error::custom)
    }
}

/// Deserializes an optional `Decimal` from a string field.
///
/// Returns `None` if the string is empty or "0", otherwise parses to `Decimal`.
/// This is a strict string-only deserializer; for flexible handling of strings,
/// numbers, and null, use [`deserialize_optional_decimal`].
///
/// # Errors
///
/// Returns an error if the string cannot be parsed as a valid decimal.
pub fn deserialize_optional_decimal_str<'de, D>(
    deserializer: D,
) -> Result<Option<Decimal>, D::Error>
where
    D: Deserializer<'de>,
{
    let s: std::borrow::Cow<'de, str> = Deserialize::deserialize(deserializer)?;
    if s.is_empty() || s == "0" {
        Ok(None)
    } else {
        Decimal::from_str(s.as_ref())
            .map(Some)
            .map_err(D::Error::custom)
    }
}

/// Deserializes an optional `Decimal` from a string-only field.
///
/// Returns `None` if the value is null or the string is empty, otherwise
/// parses to `Decimal`.
///
/// # Errors
///
/// Returns an error if the string cannot be parsed as a valid decimal.
pub fn deserialize_optional_decimal_from_str<'de, D>(
    deserializer: D,
) -> Result<Option<Decimal>, D::Error>
where
    D: Deserializer<'de>,
{
    let opt = Option::<String>::deserialize(deserializer)?;
    match opt {
        Some(s) if !s.is_empty() => Decimal::from_str(&s).map(Some).map_err(D::Error::custom),
        _ => Ok(None),
    }
}

/// Deserializes a `Decimal` from an optional string field, defaulting to zero.
///
/// Handles edge cases: `None`, empty string "", or "0" all become `Decimal::ZERO`.
///
/// # Errors
///
/// Returns an error if the string cannot be parsed as a valid decimal.
pub fn deserialize_optional_decimal_or_zero<'de, D>(deserializer: D) -> Result<Decimal, D::Error>
where
    D: Deserializer<'de>,
{
    let opt: Option<String> = Deserialize::deserialize(deserializer)?;
    match opt {
        None => Ok(Decimal::ZERO),
        Some(s) if s.is_empty() || s == "0" => Ok(Decimal::ZERO),
        Some(s) => Decimal::from_str(&s).map_err(D::Error::custom),
    }
}

/// Deserializes a `Vec<Decimal>` from a JSON array of strings.
///
/// # Errors
///
/// Returns an error if any string cannot be parsed as a valid decimal.
pub fn deserialize_vec_decimal_from_str<'de, D>(deserializer: D) -> Result<Vec<Decimal>, D::Error>
where
    D: Deserializer<'de>,
{
    let strings = Vec::<String>::deserialize(deserializer)?;
    strings
        .into_iter()
        .map(|s| Decimal::from_str(&s).map_err(D::Error::custom))
        .collect()
}

/// Serializes a `Decimal` as a string (lossless, no scientific notation).
///
/// # Errors
///
/// Returns an error if serialization fails.
pub fn serialize_decimal_as_str<S>(decimal: &Decimal, serializer: S) -> Result<S::Ok, S::Error>
where
    S: Serializer,
{
    serializer.serialize_str(&decimal.to_string())
}

/// Serializes an optional `Decimal` as a string.
///
/// # Errors
///
/// Returns an error if serialization fails.
pub fn serialize_optional_decimal_as_str<S>(
    decimal: &Option<Decimal>,
    serializer: S,
) -> Result<S::Ok, S::Error>
where
    S: Serializer,
{
    match decimal {
        Some(d) => serializer.serialize_str(&d.to_string()),
        None => serializer.serialize_none(),
    }
}

/// Serializes a `Vec<Decimal>` as an array of strings.
///
/// # Errors
///
/// Returns an error if serialization fails.
pub fn serialize_vec_decimal_as_str<S>(
    decimals: &Vec<Decimal>,
    serializer: S,
) -> Result<S::Ok, S::Error>
where
    S: Serializer,
{
    let mut seq = serializer.serialize_seq(Some(decimals.len()))?;
    for decimal in decimals {
        seq.serialize_element(&decimal.to_string())?;
    }
    seq.end()
}

/// Parses a string to `Decimal`, returning an error if parsing fails.
///
/// # Errors
///
/// Returns an error if the string cannot be parsed as a Decimal.
pub fn parse_decimal(s: &str) -> anyhow::Result<Decimal> {
    Decimal::from_str(s).map_err(|e| anyhow::anyhow!("Failed to parse decimal from '{s}': {e}"))
}

/// Parses an optional string to `Decimal`, returning `None` if the string is `None` or empty.
///
/// # Errors
///
/// Returns an error if the string cannot be parsed as a Decimal.
pub fn parse_optional_decimal(s: &Option<String>) -> anyhow::Result<Option<Decimal>> {
    match s {
        None => Ok(None),
        Some(s) if s.is_empty() => Ok(None),
        Some(s) => parse_decimal(s).map(Some),
    }
}

/// Deserializes an empty string into `None`.
///
/// Many exchange APIs represent null string fields as an empty string (`""`).
/// When such a payload is mapped onto `Option<String>` the default behavior
/// would yield `Some("")`, which is semantically different from the intended
/// absence of a value. This deserializer normalizes empty strings
/// to `None` during deserialization.
///
/// # Errors
///
/// Returns an error if the JSON value cannot be deserialized into a string.
pub fn deserialize_empty_string_as_none<'de, D>(deserializer: D) -> Result<Option<String>, D::Error>
where
    D: Deserializer<'de>,
{
    let opt = Option::<String>::deserialize(deserializer)?;
    Ok(opt.filter(|s| !s.is_empty()))
}

/// Deserializes an empty [`Ustr`] into `None`.
///
/// # Errors
///
/// Returns an error if the JSON value cannot be deserialized into a string.
pub fn deserialize_empty_ustr_as_none<'de, D>(deserializer: D) -> Result<Option<Ustr>, D::Error>
where
    D: Deserializer<'de>,
{
    let opt = Option::<Ustr>::deserialize(deserializer)?;
    Ok(opt.filter(|s| !s.is_empty()))
}

/// Deserializes a `u8` from a string field.
///
/// Returns 0 if the string is empty.
///
/// # Errors
///
/// Returns an error if the string cannot be parsed as a u8.
pub fn deserialize_string_to_u8<'de, D>(deserializer: D) -> Result<u8, D::Error>
where
    D: Deserializer<'de>,
{
    let s: std::borrow::Cow<'de, str> = Deserialize::deserialize(deserializer)?;
    if s.is_empty() {
        return Ok(0);
    }
    s.as_ref().parse::<u8>().map_err(D::Error::custom)
}

/// Deserializes a `u64` from a string field.
///
/// Returns 0 if the string is empty.
///
/// # Errors
///
/// Returns an error if the string cannot be parsed as a u64.
pub fn deserialize_string_to_u64<'de, D>(deserializer: D) -> Result<u64, D::Error>
where
    D: Deserializer<'de>,
{
    let s: std::borrow::Cow<'de, str> = Deserialize::deserialize(deserializer)?;
    if s.is_empty() {
        Ok(0)
    } else {
        s.as_ref().parse::<u64>().map_err(D::Error::custom)
    }
}

/// Deserializes an optional `u64` from a string field.
///
/// Returns `None` if the value is null or the string is empty.
///
/// # Errors
///
/// Returns an error if the string cannot be parsed as a u64.
pub fn deserialize_optional_string_to_u64<'de, D>(deserializer: D) -> Result<Option<u64>, D::Error>
where
    D: Deserializer<'de>,
{
    let s: Option<String> = Option::deserialize(deserializer)?;
    match s {
        Some(s) if s.is_empty() => Ok(None),
        Some(s) => s.parse().map(Some).map_err(D::Error::custom),
        None => Ok(None),
    }
}

#[cfg(test)]
mod tests {
    use ahash::AHashSet;
    use rstest::*;
    use rust_decimal::Decimal;
    use rust_decimal_macros::dec;
    use serde::{
        Deserialize, Serialize,
        de::{Visitor, value::Error as ValueError},
    };
    use serde_json::json;
    use ustr::Ustr;

    use super::{
        DecimalVisitor, OptionalDecimalVisitor, Serializable, decimal, default_false, default_true,
        deserialize_decimal, deserialize_decimal_from_str, deserialize_decimal_native,
        deserialize_decimal_or_zero, deserialize_decimal_token, deserialize_decimal_token_borrowed,
        deserialize_empty_string_as_none, deserialize_empty_ustr_as_none,
        deserialize_optional_decimal, deserialize_optional_decimal_or_zero,
        deserialize_optional_decimal_str, deserialize_optional_decimal_token,
        deserialize_optional_decimal_token_borrowed, deserialize_optional_string_to_u64,
        deserialize_string_to_u8, deserialize_string_to_u64, deserialize_vec_decimal_from_str,
        msgpack::{FromMsgPack, ToMsgPack},
        parse_decimal, parse_optional_decimal, serialize_decimal_as_str,
        serialize_optional_decimal_as_str, serialize_vec_decimal_as_str, sorted_hashset,
    };

    #[derive(Debug, PartialEq, Serialize, Deserialize)]
    struct SortedSetPayload {
        #[serde(with = "sorted_hashset")]
        values: AHashSet<i32>,
    }

    #[derive(Serialize, Deserialize, PartialEq, Debug)]
    struct SerializableTestStruct {
        id: u32,
        name: String,
        value: f64,
    }

    impl Serializable for SerializableTestStruct {}

    #[rstest]
    #[case("\"")]
    #[case("\"1x")]
    #[case("\"1\u{e9}")]
    #[case("\"1\0")]
    #[case("\"1\n")]
    #[case("\"1\"\"")]
    #[case("\"1\0\"")]
    #[case("\"1\n\"")]
    fn test_json_decimal_rejects_malformed_raw_strings(#[case] raw: &str) {
        // A generic deserializer can supply RawValue text without serde_json's lexical validation.
        let expected = serde_json::from_str::<String>(raw).unwrap_err().to_string();
        let deserializer = serde::de::value::MapDeserializer::<_, ValueError>::new(
            [("$serde_json::private::RawValue", raw)].into_iter(),
        );
        let error = decimal::deserialize_json(deserializer).unwrap_err();
        assert_eq!(error.to_string(), expected);
    }

    #[rstest]
    #[case("0.125", "0.125", 3)]
    #[case("9007199254740993", "9007199254740993", 0)]
    #[case("\"1.2500\"", "1.2500", 4)]
    #[case(
        "\"0.12345678901234567890123456789\"",
        "0.1234567890123456789012345679",
        28
    )]
    fn test_native_decimal_preserves_rounding_and_scale(
        #[case] token: &str,
        #[case] expected: &str,
        #[case] scale: u32,
    ) {
        let direct =
            deserialize_decimal_native(&mut serde_json::Deserializer::from_str(token)).unwrap();
        let buffered =
            deserialize_decimal_native(serde_json::from_str::<serde_json::Value>(token).unwrap())
                .unwrap();
        let expected = Decimal::from_str_exact(expected).unwrap();

        assert_eq!(direct, expected);
        assert_eq!(direct.scale(), scale);
        assert_eq!(buffered, expected);
        assert_eq!(buffered.scale(), scale);
    }

    #[rstest]
    #[case("null")]
    #[case("true")]
    #[case("\"\"")]
    #[case("\"NaN\"")]
    #[case("\"79228162514264337593543950336\"")]
    fn test_native_decimal_rejects_invalid_values(#[case] token: &str) {
        let direct = deserialize_decimal_native(&mut serde_json::Deserializer::from_str(token));
        let buffered =
            deserialize_decimal_native(serde_json::from_str::<serde_json::Value>(token).unwrap());

        assert!(direct.is_err());
        assert!(buffered.is_err());
    }

    #[rstest]
    #[case("1.25")]
    #[case("2.0")]
    #[case("1.2500")]
    #[case("-0.0")]
    #[case("1e-7")]
    #[case("1.5E3")]
    #[case("1e-30")]
    #[case("1e30")]
    #[case("13.223699999999997")]
    #[case("9007199254740993")]
    #[case("18446744073709551615")]
    #[case("-9223372036854775808")]
    #[case("\"1.2500\"")]
    #[case("\"1e5\"")]
    #[case("\"0.12345678901234567890123456789\"")]
    #[case("\"79228162514264337593543950336\"")]
    #[case("\"not-a-number\"")]
    fn test_native_decimal_matches_rust_decimal(#[case] token: &str) {
        let value = serde_json::from_str::<serde_json::Value>(token).unwrap();

        // Where rust_decimal rejects an arbitrary-precision number map, the token digits must
        // parse as rust_decimal parses them when its own AP integration is enabled.
        let fallback = (is_arbitrary_precision() && value.is_number())
            .then(|| serde_json::from_value::<Decimal>(serde_json::json!(token)).ok())
            .flatten();
        let routes = [
            (
                serde_json::from_str::<Decimal>(token).ok(),
                deserialize_decimal_native(&mut serde_json::Deserializer::from_str(token)).ok(),
            ),
            (
                serde_json::from_value::<Decimal>(value.clone()).ok(),
                deserialize_decimal_native(value).ok(),
            ),
        ];

        for (native, consolidated) in routes {
            let expected = native.or(fallback);
            assert_eq!(
                consolidated.map(|value| (value, value.scale())),
                expected.map(|value| (value, value.scale()))
            );
        }
    }

    #[rstest]
    #[case("10.0", Decimal::from(10), 0, 1, 0)]
    #[case("1.2500", Decimal::new(125, 2), 2, 4, 4)]
    #[case("1.25e1", Decimal::new(125, 1), 1, 1, 1)]
    fn test_numeric_decimal_preserves_route_scale(
        #[case] token: &str,
        #[case] expected: Decimal,
        #[case] float_scale: u32,
        #[case] token_scale: u32,
        #[case] buffered_token_scale: u32,
    ) {
        let arbitrary_precision = is_arbitrary_precision();

        let scale = if arbitrary_precision {
            token_scale
        } else {
            float_scale
        };

        let buffered_scale = if arbitrary_precision {
            buffered_token_scale
        } else {
            float_scale
        };

        let direct = deserialize_decimal(&mut serde_json::Deserializer::from_str(token)).unwrap();
        let buffered =
            deserialize_decimal(serde_json::from_str::<serde_json::Value>(token).unwrap()).unwrap();
        let quoted = deserialize_decimal(serde_json::Value::String("1.2500".to_string())).unwrap();
        assert_eq!(direct, expected);
        assert_eq!(direct.scale(), scale);
        assert_eq!(buffered, expected);
        assert_eq!(buffered.scale(), buffered_scale);
        assert_eq!(quoted, Decimal::new(12500, 4));
        assert_eq!(quoted.scale(), 4);
    }

    fn is_arbitrary_precision() -> bool {
        serde_json::from_str::<serde_json::Number>("1.2500")
            .unwrap()
            .to_string()
            == "1.2500"
    }

    #[rstest]
    fn test_sorted_hashset_serialization_is_deterministic() {
        let payload = SortedSetPayload {
            values: [29, 3, 17, 5, 23, 11].into_iter().collect(),
        };

        let encoded = serde_json::to_string(&payload).unwrap();
        let expected = serde_json::to_string(&json!({ "values": [3, 5, 11, 17, 23, 29] })).unwrap();
        let restored: SortedSetPayload = serde_json::from_str(&encoded).unwrap();

        assert_eq!(encoded, expected);
        assert_eq!(restored, payload);
    }

    #[rstest]
    fn test_serializable_json_roundtrip() {
        let original = SerializableTestStruct {
            id: 42,
            name: "test".to_string(),
            value: std::f64::consts::PI,
        };

        let json_bytes = original.to_json_bytes().unwrap();
        let deserialized = SerializableTestStruct::from_json_bytes(&json_bytes).unwrap();

        assert_eq!(original, deserialized);
    }

    #[rstest]
    fn test_serializable_msgpack_roundtrip() {
        let original = SerializableTestStruct {
            id: 123,
            name: "msgpack_test".to_string(),
            value: std::f64::consts::E,
        };

        let msgpack_bytes = original.to_msgpack_bytes().unwrap();
        let deserialized = SerializableTestStruct::from_msgpack_bytes(&msgpack_bytes).unwrap();

        assert_eq!(original, deserialized);
    }

    #[rstest]
    fn test_serializable_json_invalid_data() {
        let invalid_json = b"invalid json data";
        let result = SerializableTestStruct::from_json_bytes(invalid_json);
        assert!(result.is_err());
    }

    #[rstest]
    fn test_serializable_msgpack_invalid_data() {
        let invalid_msgpack = b"invalid msgpack data";
        let result = SerializableTestStruct::from_msgpack_bytes(invalid_msgpack);
        assert!(result.is_err());
    }

    #[rstest]
    fn test_serializable_json_empty_values() {
        let test_struct = SerializableTestStruct {
            id: 0,
            name: String::new(),
            value: 0.0,
        };

        let json_bytes = test_struct.to_json_bytes().unwrap();
        let deserialized = SerializableTestStruct::from_json_bytes(&json_bytes).unwrap();

        assert_eq!(test_struct, deserialized);
    }

    #[rstest]
    fn test_serializable_msgpack_empty_values() {
        let test_struct = SerializableTestStruct {
            id: 0,
            name: String::new(),
            value: 0.0,
        };

        let msgpack_bytes = test_struct.to_msgpack_bytes().unwrap();
        let deserialized = SerializableTestStruct::from_msgpack_bytes(&msgpack_bytes).unwrap();

        assert_eq!(test_struct, deserialized);
    }

    #[derive(Deserialize)]
    struct TestOptionalDecimalStr {
        #[serde(deserialize_with = "deserialize_optional_decimal_str")]
        value: Option<Decimal>,
    }

    #[derive(Deserialize)]
    struct TestDecimalOrZero {
        #[serde(deserialize_with = "deserialize_decimal_or_zero")]
        value: Decimal,
    }

    #[derive(Deserialize)]
    struct TestOptionalDecimalOrZero {
        #[serde(deserialize_with = "deserialize_optional_decimal_or_zero")]
        value: Decimal,
    }

    #[derive(Serialize, Deserialize, PartialEq, Debug)]
    struct TestDecimalRoundtrip {
        #[serde(
            serialize_with = "serialize_decimal_as_str",
            deserialize_with = "deserialize_decimal_from_str"
        )]
        value: Decimal,
        #[serde(
            serialize_with = "serialize_optional_decimal_as_str",
            deserialize_with = "super::deserialize_optional_decimal_from_str"
        )]
        optional_value: Option<Decimal>,
    }

    #[rstest]
    #[case(r#"{"value":"123.45"}"#, Some(dec!(123.45)))]
    #[case(r#"{"value":"0"}"#, None)]
    #[case(r#"{"value":""}"#, None)]
    fn test_deserialize_optional_decimal_str(
        #[case] json: &str,
        #[case] expected: Option<Decimal>,
    ) {
        let result: TestOptionalDecimalStr = serde_json::from_str(json).unwrap();
        assert_eq!(result.value, expected);
    }

    #[rstest]
    fn test_deserialize_optional_decimal_from_str_empty_is_none() {
        let json = r#"{"value": "1.5", "optional_value": ""}"#;
        let result: TestDecimalRoundtrip = serde_json::from_str(json).unwrap();
        assert_eq!(result.optional_value, None);
    }

    #[rstest]
    #[case(r#"{"value":"123.45"}"#, dec!(123.45))]
    #[case(r#"{"value":"0"}"#, Decimal::ZERO)]
    #[case(r#"{"value":""}"#, Decimal::ZERO)]
    fn test_deserialize_decimal_or_zero(#[case] json: &str, #[case] expected: Decimal) {
        let result: TestDecimalOrZero = serde_json::from_str(json).unwrap();
        assert_eq!(result.value, expected);
    }

    #[rstest]
    #[case(r#"{"value":"123.45"}"#, dec!(123.45))]
    #[case(r#"{"value":"0"}"#, Decimal::ZERO)]
    #[case(r#"{"value":null}"#, Decimal::ZERO)]
    #[case(r#"{"value":""}"#, Decimal::ZERO)]
    fn test_deserialize_optional_decimal_or_zero(#[case] json: &str, #[case] expected: Decimal) {
        let result: TestOptionalDecimalOrZero = serde_json::from_str(json).unwrap();
        assert_eq!(result.value, expected);
    }

    #[rstest]
    fn test_decimal_serialization_roundtrip() {
        let original = TestDecimalRoundtrip {
            value: dec!(123.456789012345678),
            optional_value: Some(dec!(0.000000001)),
        };

        let json = serde_json::to_string(&original).unwrap();

        // Check that it's serialized as strings
        assert!(json.contains("\"123.456789012345678\""));
        assert!(json.contains("\"0.000000001\""));

        let deserialized: TestDecimalRoundtrip = serde_json::from_str(&json).unwrap();
        assert_eq!(original.value, deserialized.value);
        assert_eq!(original.optional_value, deserialized.optional_value);
    }

    #[rstest]
    fn test_decimal_optional_none_handling() {
        let test_struct = TestDecimalRoundtrip {
            value: dec!(42.0),
            optional_value: None,
        };

        let json = serde_json::to_string(&test_struct).unwrap();
        assert!(json.contains("null"));

        let parsed: TestDecimalRoundtrip = serde_json::from_str(&json).unwrap();
        assert_eq!(test_struct.value, parsed.value);
        assert_eq!(None, parsed.optional_value);
    }

    #[derive(Deserialize)]
    struct TestEmptyStringAsNone {
        #[serde(deserialize_with = "deserialize_empty_string_as_none")]
        value: Option<String>,
    }

    #[rstest]
    #[case(r#"{"value":"hello"}"#, Some("hello".to_string()))]
    #[case(r#"{"value":""}"#, None)]
    #[case(r#"{"value":null}"#, None)]
    fn test_deserialize_empty_string_as_none(#[case] json: &str, #[case] expected: Option<String>) {
        let result: TestEmptyStringAsNone = serde_json::from_str(json).unwrap();
        assert_eq!(result.value, expected);
    }

    #[derive(Deserialize)]
    struct TestEmptyUstrAsNone {
        #[serde(deserialize_with = "deserialize_empty_ustr_as_none")]
        value: Option<Ustr>,
    }

    #[rstest]
    #[case(r#"{"value":"hello"}"#, Some(Ustr::from("hello")))]
    #[case(r#"{"value":""}"#, None)]
    #[case(r#"{"value":null}"#, None)]
    fn test_deserialize_empty_ustr_as_none(#[case] json: &str, #[case] expected: Option<Ustr>) {
        let result: TestEmptyUstrAsNone = serde_json::from_str(json).unwrap();
        assert_eq!(result.value, expected);
    }

    #[derive(Serialize, Deserialize, PartialEq, Debug)]
    struct TestVecDecimal {
        #[serde(
            serialize_with = "serialize_vec_decimal_as_str",
            deserialize_with = "deserialize_vec_decimal_from_str"
        )]
        values: Vec<Decimal>,
    }

    #[rstest]
    fn test_vec_decimal_roundtrip() {
        let original = TestVecDecimal {
            values: vec![dec!(1.5), dec!(2.25), dec!(100.001)],
        };

        let json = serde_json::to_string(&original).unwrap();
        assert!(json.contains("[\"1.5\",\"2.25\",\"100.001\"]"));

        let parsed: TestVecDecimal = serde_json::from_str(&json).unwrap();
        assert_eq!(original.values, parsed.values);
    }

    #[rstest]
    fn test_vec_decimal_empty() {
        let original = TestVecDecimal { values: vec![] };

        let json = serde_json::to_string(&original).unwrap();
        let parsed: TestVecDecimal = serde_json::from_str(&json).unwrap();
        assert_eq!(original.values, parsed.values);
    }

    #[derive(Deserialize)]
    struct TestStringToU8 {
        #[serde(deserialize_with = "deserialize_string_to_u8")]
        value: u8,
    }

    #[rstest]
    #[case(r#"{"value":"42"}"#, 42)]
    #[case(r#"{"value":"0"}"#, 0)]
    #[case(r#"{"value":"255"}"#, 255)]
    #[case(r#"{"value":""}"#, 0)]
    fn test_deserialize_string_to_u8(#[case] json: &str, #[case] expected: u8) {
        let result: TestStringToU8 = serde_json::from_str(json).unwrap();
        assert_eq!(result.value, expected);
    }

    #[rstest]
    #[case(r#"{"value":"256"}"#)]
    #[case(r#"{"value":"999"}"#)]
    #[case(r#"{"value":"abc"}"#)]
    fn test_deserialize_string_to_u8_invalid(#[case] json: &str) {
        let result: Result<TestStringToU8, _> = serde_json::from_str(json);
        assert!(result.is_err());
    }

    #[derive(Deserialize)]
    struct TestStringToU64 {
        #[serde(deserialize_with = "deserialize_string_to_u64")]
        value: u64,
    }

    #[rstest]
    #[case(r#"{"value":"12345678901234"}"#, 12_345_678_901_234)]
    #[case(r#"{"value":"0"}"#, 0)]
    #[case(r#"{"value":"18446744073709551615"}"#, u64::MAX)]
    #[case(r#"{"value":""}"#, 0)]
    fn test_deserialize_string_to_u64(#[case] json: &str, #[case] expected: u64) {
        let result: TestStringToU64 = serde_json::from_str(json).unwrap();
        assert_eq!(result.value, expected);
    }

    #[rstest]
    #[case(r#"{"value":"18446744073709551616"}"#)]
    #[case(r#"{"value":"abc"}"#)]
    #[case(r#"{"value":"-1"}"#)]
    fn test_deserialize_string_to_u64_invalid(#[case] json: &str) {
        let result: Result<TestStringToU64, _> = serde_json::from_str(json);
        assert!(result.is_err());
    }

    #[derive(Deserialize)]
    struct TestOptionalStringToU64 {
        #[serde(deserialize_with = "deserialize_optional_string_to_u64")]
        value: Option<u64>,
    }

    #[rstest]
    #[case(r#"{"value":"12345678901234"}"#, Some(12_345_678_901_234))]
    #[case(r#"{"value":"0"}"#, Some(0))]
    #[case(r#"{"value":""}"#, None)]
    #[case(r#"{"value":null}"#, None)]
    fn test_deserialize_optional_string_to_u64(#[case] json: &str, #[case] expected: Option<u64>) {
        let result: TestOptionalStringToU64 = serde_json::from_str(json).unwrap();
        assert_eq!(result.value, expected);
    }

    #[rstest]
    #[case("123.45", dec!(123.45))]
    #[case("0", Decimal::ZERO)]
    #[case("0.0", Decimal::ZERO)]
    fn test_parse_decimal(#[case] input: &str, #[case] expected: Decimal) {
        let result = parse_decimal(input).unwrap();
        assert_eq!(result, expected);
    }

    #[rstest]
    fn test_parse_decimal_invalid() {
        assert!(parse_decimal("invalid").is_err());
        assert!(parse_decimal("").is_err());
    }

    #[rstest]
    #[case(&Some("123.45".to_string()), Some(dec!(123.45)))]
    #[case(&Some("0".to_string()), Some(Decimal::ZERO))]
    #[case(&Some(String::new()), None)]
    #[case(&None, None)]
    fn test_parse_optional_decimal(
        #[case] input: &Option<String>,
        #[case] expected: Option<Decimal>,
    ) {
        let result = parse_optional_decimal(input).unwrap();
        assert_eq!(result, expected);
    }

    // Tests for flexible decimal deserializers (handles both string and number JSON values)

    #[derive(Debug, Serialize, Deserialize, PartialEq)]
    struct TestFlexibleDecimal {
        #[serde(
            serialize_with = "decimal::serialize",
            deserialize_with = "deserialize_decimal"
        )]
        value: Decimal,
        #[serde(
            serialize_with = "decimal::serialize_optional",
            deserialize_with = "deserialize_optional_decimal"
        )]
        optional_value: Option<Decimal>,
    }

    #[rstest]
    #[case(r#"{"value": 123.456, "optional_value": 789.012}"#, dec!(123.456), Some(dec!(789.012)))]
    #[case(r#"{"value": "123.456", "optional_value": "789.012"}"#, dec!(123.456), Some(dec!(789.012)))]
    #[case(r#"{"value": 1.25e-3, "optional_value": 2.5e2}"#, dec!(0.00125), Some(dec!(250)))]
    #[case(r#"{"value": 100, "optional_value": null}"#, dec!(100), None)]
    #[case(r#"{"value": null, "optional_value": null}"#, Decimal::ZERO, None)]
    fn test_deserialize_flexible_decimal(
        #[case] json: &str,
        #[case] expected_value: Decimal,
        #[case] expected_optional: Option<Decimal>,
    ) {
        let result: TestFlexibleDecimal = serde_json::from_str(json).unwrap();
        assert_eq!(result.value, expected_value);
        assert_eq!(result.optional_value, expected_optional);
    }

    #[rstest]
    fn test_flexible_decimal_roundtrip() {
        let original = TestFlexibleDecimal {
            value: dec!(123.456),
            optional_value: Some(dec!(789.012)),
        };

        let json = serde_json::to_string(&original).unwrap();
        let deserialized: TestFlexibleDecimal = serde_json::from_str(&json).unwrap();

        assert_eq!(original.value, deserialized.value);
        assert_eq!(original.optional_value, deserialized.optional_value);
    }

    #[rstest]
    fn test_flexible_decimal_scientific_notation() {
        // Test that scientific notation from serde_json is handled correctly.
        // serde_json outputs very small numbers like 0.00000001 as "1e-8".
        // Note: JSON numbers are parsed as f64, so values are limited to ~15 significant digits.
        let json = r#"{"value": 0.00000001, "optional_value": 12345678.12345}"#;
        let parsed: TestFlexibleDecimal = serde_json::from_str(json).unwrap();
        assert_eq!(parsed.value, dec!(0.00000001));
        assert_eq!(parsed.optional_value, Some(dec!(12345678.12345)));
    }

    #[rstest]
    fn test_flexible_decimal_empty_string_optional() {
        let json = r#"{"value": 100, "optional_value": ""}"#;
        let parsed: TestFlexibleDecimal = serde_json::from_str(json).unwrap();
        assert_eq!(parsed.value, dec!(100));
        assert_eq!(parsed.optional_value, None);
    }

    #[derive(Debug, Deserialize)]
    struct TestDecimalToken {
        #[serde(deserialize_with = "deserialize_decimal_token")]
        value: Decimal,
        #[serde(default, deserialize_with = "deserialize_optional_decimal_token")]
        optional_value: Option<Decimal>,
    }

    #[derive(Debug, Deserialize)]
    struct TestDecimalTokenBorrowed {
        #[serde(deserialize_with = "deserialize_decimal_token_borrowed")]
        value: Decimal,
        #[serde(
            default,
            deserialize_with = "deserialize_optional_decimal_token_borrowed"
        )]
        optional_value: Option<Decimal>,
    }

    #[rstest]
    #[case(r#"{"value": 100000000.123456789}"#, "100000000.123456789", None)]
    #[case(
        r#"{"value": 100000000.123456788, "optional_value": null}"#,
        "100000000.123456788",
        None
    )]
    #[case(r#"{"value": "0.10", "optional_value": ""}"#, "0.10", None)]
    #[case(
        r#"{"value": 18446744073709551617, "optional_value": 0.30000000000000004}"#,
        "18446744073709551617",
        Some("0.30000000000000004")
    )]
    #[case(
        r#"{"value": 1.1403e-4, "optional_value": "2.5e2"}"#,
        "0.00011403",
        Some("250")
    )]
    #[case(
        r#"{"value": 5.551115123125783e-17}"#,
        "0.0000000000000000555111512313",
        None
    )]
    #[case(r#"{"value": 0.00000000000000000000000000001e28}"#, "0.1", None)]
    #[case(
        r#"{"value": 0.000000000000000000000000000012345678901234567890123456789e28}"#,
        "0.1234567890123456789012345679",
        None
    )]
    #[case(
        r#"{"value": 0.12345678901234567890123456789}"#,
        "0.1234567890123456789012345679",
        None
    )]
    #[case(
        r#"{"value": "-7.50", "optional_value": -0.001}"#,
        "-7.50",
        Some("-0.001")
    )]
    fn test_deserialize_decimal_token(
        #[case] json: &str,
        #[case] expected_value: &str,
        #[case] expected_optional: Option<&str>,
    ) {
        let result: TestDecimalToken = serde_json::from_str(json).unwrap();
        let borrowed: TestDecimalTokenBorrowed = serde_json::from_str(json).unwrap();

        assert_eq!(result.value.to_string(), expected_value);
        assert_eq!(
            result
                .optional_value
                .map(|value| value.to_string())
                .as_deref(),
            expected_optional
        );
        assert_eq!(borrowed.value.to_string(), expected_value);
        assert_eq!(
            borrowed
                .optional_value
                .map(|value| value.to_string())
                .as_deref(),
            expected_optional
        );
    }

    #[rstest]
    fn test_deserialize_decimal_token_keeps_decimals_that_collapse_in_f64() {
        let first: TestDecimalToken =
            serde_json::from_str(r#"{"value": 100000000.123456789}"#).unwrap();
        let second: TestDecimalToken =
            serde_json::from_str(r#"{"value": 100000000.123456788}"#).unwrap();
        let first_f64 = "100000000.123456789".parse::<f64>().unwrap();
        let second_f64 = "100000000.123456788".parse::<f64>().unwrap();

        assert_eq!(first_f64.to_bits(), second_f64.to_bits());
        assert_eq!(first.value, dec!(100000000.123456789));
        assert_eq!(second.value, dec!(100000000.123456788));
    }

    #[rstest]
    #[case(r#"{"value": null}"#)]
    #[case(r#"{"value": ""}"#)]
    #[case(r#"{"value": "abc"}"#)]
    #[case(r#"{"value": true}"#)]
    #[case(r#"{"value": {}}"#)]
    #[case(r#"{"value": [1]}"#)]
    #[case(r#"{"value": 1e400}"#)]
    #[case(r#"{"value": 79228162514264337593543950336}"#)]
    #[case(r#"{"value": 1, "optional_value": "abc"}"#)]
    #[case(r#"{"optional_value": 1}"#)]
    fn test_deserialize_decimal_token_rejects_invalid(#[case] json: &str) {
        assert!(serde_json::from_str::<TestDecimalToken>(json).is_err());
        assert!(serde_json::from_str::<TestDecimalTokenBorrowed>(json).is_err());
    }

    #[rstest]
    fn test_deserialize_decimal_token_borrowed_requires_borrowed_input() {
        let json = r#"{"value": 1.25}"#;
        let value: serde_json::Value = serde_json::from_str(json).unwrap();

        let from_slice: TestDecimalTokenBorrowed = serde_json::from_slice(json.as_bytes()).unwrap();
        let from_reader =
            serde_json::from_reader::<_, TestDecimalTokenBorrowed>(json.as_bytes()).unwrap_err();
        let from_value = serde_json::from_value::<TestDecimalTokenBorrowed>(value).unwrap_err();

        assert_eq!(from_slice.value, dec!(1.25));
        assert_eq!(
            from_reader.to_string(),
            "invalid type: string \"1.25\", expected raw value at line 1 column 15"
        );
        assert_eq!(
            from_value.to_string(),
            "invalid type: string \"1.25\", expected raw value"
        );
    }

    #[rstest]
    fn test_deserialize_decimal_token_buffered_value_renders_number() {
        let value = json!({"value": 65000.5, "optional_value": "0.10"});

        let result: TestDecimalToken = serde_json::from_value(value).unwrap();

        assert_eq!(result.value.to_string(), "65000.5");
        assert_eq!(
            result
                .optional_value
                .map(|value| value.to_string())
                .as_deref(),
            Some("0.10")
        );
    }

    #[rstest]
    fn test_deserialize_decimal_token_rejects_tagged_enum_buffer() {
        #[derive(Debug, Deserialize)]
        #[serde(tag = "type")]
        #[allow(dead_code, reason = "the test only checks that decoding fails")]
        enum Tagged {
            Token(TestDecimalToken),
        }

        let result = serde_json::from_str::<Tagged>(r#"{"type": "Token", "value": 1.5}"#);

        assert!(result.is_err());
    }

    // Additional tests for DecimalVisitor edge cases

    #[derive(Debug, Deserialize)]
    struct TestDecimalOnly {
        #[serde(deserialize_with = "deserialize_decimal")]
        value: Decimal,
    }

    #[rstest]
    #[case("0.12345678901234567890123456789e1", dec!(1.2345678901234567890123456789))]
    #[case("-0.12345678901234567890123456789E1", dec!(-1.2345678901234567890123456789))]
    #[case("0.00000000000000000000000000001e1", dec!(0.0000000000000000000000000001))]
    fn test_deserialize_decimal_scientific_representable(
        #[case] value: &str,
        #[case] expected: Decimal,
        #[values(false, true)] optional: bool,
    ) {
        let json = serde_json::to_string(&json!({"value": value})).unwrap();

        let actual = if optional {
            serde_json::from_str::<TestOptionalDecimalOnly>(&json)
                .unwrap()
                .value
        } else {
            Some(
                serde_json::from_str::<TestDecimalOnly>(&json)
                    .unwrap()
                    .value,
            )
        };

        assert_eq!(actual, Some(expected));
    }

    #[rstest]
    #[case(23, 28, 23)]
    #[case(24, 29, 0)]
    fn test_deserialize_decimal_scientific_length_boundary(
        #[case] zeros: usize,
        #[case] length: usize,
        #[case] scale: u32,
    ) {
        let value = format!("1.5{}e1", "0".repeat(zeros));
        let json = serde_json::to_string(&json!({"value": value})).unwrap();
        let required: TestDecimalOnly = serde_json::from_str(&json).unwrap();
        let optional: TestOptionalDecimalOnly = serde_json::from_str(&json).unwrap();

        assert_eq!(value.len(), length);
        assert_eq!(required.value, dec!(15));
        assert_eq!(required.value.scale(), scale);
        assert_eq!(optional.value, Some(dec!(15)));
        assert_eq!(optional.value.unwrap().scale(), scale);
    }

    #[rstest]
    #[case(".1e-2147483648")]
    #[case("-.1E-2147483648")]
    #[case("+.1e-2147483648")]
    fn test_deserialize_decimal_rejects_min_exponent(
        #[case] value: &str,
        #[values("visitor", "token", "token_borrowed")] route: &str,
        #[values(false, true)] optional: bool,
    ) {
        let json = serde_json::to_string(value).unwrap();
        let mut deserializer = serde_json::Deserializer::from_str(&json);
        let result = match (route, optional) {
            ("visitor", false) => deserialize_decimal(&mut deserializer).map(Some),
            ("visitor", true) => deserialize_optional_decimal(&mut deserializer),
            ("token", false) => deserialize_decimal_token(&mut deserializer).map(Some),
            ("token", true) => deserialize_optional_decimal_token(&mut deserializer),
            ("token_borrowed", false) => {
                deserialize_decimal_token_borrowed(&mut deserializer).map(Some)
            }
            ("token_borrowed", true) => {
                deserialize_optional_decimal_token_borrowed(&mut deserializer)
            }
            _ => unreachable!(),
        };

        let error = result.unwrap_err();
        let expected = "Scale exceeds the maximum precision allowed: 2147483648 > 28";

        assert_eq!(error.classify(), serde_json::error::Category::Data);
        assert_eq!(error.to_string().split(" at line ").next(), Some(expected));
    }

    #[rstest]
    #[case(r#"{"value": "1.5e-8"}"#, dec!(0.000000015))]
    #[case(r#"{"value": "1E10"}"#, dec!(10000000000))]
    #[case(r#"{"value": "-1.23e5"}"#, dec!(-123000))]
    fn test_deserialize_decimal_scientific_string(#[case] json: &str, #[case] expected: Decimal) {
        let result: TestDecimalOnly = serde_json::from_str(json).unwrap();
        assert_eq!(result.value, expected);
    }

    #[rstest]
    #[case(r#"{"value": 9223372036854775807}"#, dec!(9223372036854775807))] // i64::MAX
    #[case(r#"{"value": -9223372036854775808}"#, dec!(-9223372036854775808))] // i64::MIN
    #[case(r#"{"value": 0}"#, Decimal::ZERO)]
    fn test_deserialize_decimal_large_integers(#[case] json: &str, #[case] expected: Decimal) {
        let result: TestDecimalOnly = serde_json::from_str(json).unwrap();
        assert_eq!(result.value, expected);
    }

    #[rstest]
    #[case(r#"{"value": "-123.456789"}"#, dec!(-123.456789))]
    #[case(r#"{"value": -999.99}"#, dec!(-999.99))]
    fn test_deserialize_decimal_negative(#[case] json: &str, #[case] expected: Decimal) {
        let result: TestDecimalOnly = serde_json::from_str(json).unwrap();
        assert_eq!(result.value, expected);
    }

    #[rstest]
    #[case(r#"{"value": "123456789.123456789012345678"}"#)] // High precision string
    fn test_deserialize_decimal_high_precision(#[case] json: &str) {
        let result: TestDecimalOnly = serde_json::from_str(json).unwrap();
        assert_eq!(result.value, dec!(123456789.123456789012345678));
    }

    #[rstest]
    #[case(
        r#"{"value": "1.234567890123456789012345678912345e-1"}"#,
        "0.1234567890123456789012345679"
    )]
    #[case(
        r#"{"value": "0.1234567890123456789012345678912345"}"#,
        "0.1234567890123456789012345679"
    )]
    #[case(
        r#"{"value": "999999999999999999999999999995e-29"}"#,
        "10.000000000000000000000000000"
    )]
    #[case(r#"{"value": "0.5e29"}"#, "50000000000000000000000000000")]
    #[case(r#"{"value": "-4e-29"}"#, "0.0000000000000000000000000000")]
    #[case(r#"{"value": "1.5e-999999"}"#, "0.0000000000000000000000000000")]
    #[case(r#"{"value": "9e-999999"}"#, "0.0000000000000000000000000000")]
    #[case(r#"{"value": "0e2000000000"}"#, "0")]
    fn test_deserialize_decimal_rounds_high_scale_values(
        #[case] json: &str,
        #[case] expected: &str,
    ) {
        // Carries propagate and a rounded-away negative loses its sign.
        let result: TestDecimalOnly = serde_json::from_str(json).unwrap();
        assert_eq!(result.value.to_string(), expected);
    }

    #[rstest]
    #[rstest]
    fn test_deserialize_decimal_negative_rounding_to_zero_loses_sign() {
        let json = r#"{"value": "-1.5e-999999"}"#;
        let result: TestDecimalOnly = serde_json::from_str(json).unwrap();
        assert_eq!(result.value.to_string(), "0.0000000000000000000000000000");
    }

    #[rstest]
    #[case(r#"{"value": "899999999999999999999999999995e-29"}"#)]
    #[case(r#"{"value": "+899999999999999999999999999995e-29"}"#)]
    fn test_deserialize_decimal_rounding_carries_into_integer(#[case] json: &str) {
        // Thirty-digit mantissas fail scientific parsing and round up into a non-nine digit
        let result: TestDecimalOnly = serde_json::from_str(json).unwrap();
        assert_eq!(result.value.to_string(), "9.000000000000000000000000000");
    }

    #[rstest]
    #[case(r#"{"value": "8e28"}"#)] // above Decimal::MAX
    #[case(r#"{"value": "1e1000000000"}"#)] // absurd exponent must fail without expansion
    #[case(r#"{"value": {"number": "1.5"}}"#)]
    #[case(r#"{"value": "not-a-number"}"#)]
    #[case(r#"{"value": "1.2.3e1"}"#)] // multiple decimal points
    #[case(r#"{"value": ".e1"}"#)] // empty coefficient
    fn test_deserialize_decimal_rejects_unrepresentable_values(#[case] json: &str) {
        // The fallback rounds fractional digits only; oversized magnitudes
        // keep their original parse error.
        let result: Result<TestDecimalOnly, _> = serde_json::from_str(json);
        assert!(result.is_err());
    }

    #[rstest]
    fn test_deserialize_optional_decimal_rounds_high_scale_values() {
        let json = r#"{"value": "51.234567890123456789012345678912345e-1"}"#;
        let result: TestOptionalDecimalOnly = serde_json::from_str(json).unwrap();
        assert_eq!(
            result.value.map(|v| v.to_string()),
            Some("5.1234567890123456789012345679".into()),
        );
    }

    #[derive(Debug, Deserialize)]
    struct TestOptionalDecimalOnly {
        #[serde(deserialize_with = "deserialize_optional_decimal")]
        value: Option<Decimal>,
    }

    #[rstest]
    #[case(r#"{"value": "1.5e-8"}"#, Some(dec!(0.000000015)))]
    #[case(r#"{"value": null}"#, None)]
    #[case(r#"{"value": ""}"#, None)]
    #[case(r#"{"value": 42}"#, Some(dec!(42)))]
    #[case(r#"{"value": -100.5}"#, Some(dec!(-100.5)))]
    fn test_deserialize_optional_decimal_various(
        #[case] json: &str,
        #[case] expected: Option<Decimal>,
    ) {
        let result: TestOptionalDecimalOnly = serde_json::from_str(json).unwrap();
        assert_eq!(result.value, expected);
    }

    #[rstest]
    fn test_decimal_visitor_direct_owned_and_wide_integer_paths() {
        assert_eq!(
            DecimalVisitor
                .visit_string::<ValueError>("1.5".to_string())
                .unwrap(),
            dec!(1.5)
        );
        assert_eq!(
            DecimalVisitor.visit_i128::<ValueError>(5).unwrap(),
            Decimal::from(5i128)
        );
        assert_eq!(
            DecimalVisitor.visit_u128::<ValueError>(5).unwrap(),
            Decimal::from(5u128)
        );
        assert_eq!(
            DecimalVisitor.visit_none::<ValueError>().unwrap(),
            Decimal::ZERO
        );
    }

    #[rstest]
    fn test_decimal_visitor_rejects_non_finite_float() {
        assert!(
            DecimalVisitor
                .visit_f64::<ValueError>(f64::INFINITY)
                .is_err()
        );
        assert!(
            DecimalVisitor
                .visit_f64::<ValueError>(f64::NEG_INFINITY)
                .is_err()
        );
        assert!(DecimalVisitor.visit_f64::<ValueError>(f64::NAN).is_err());
    }

    #[rstest]
    fn test_optional_decimal_visitor_direct_paths() {
        assert_eq!(
            OptionalDecimalVisitor
                .visit_string::<ValueError>("1.5".to_string())
                .unwrap(),
            Some(dec!(1.5))
        );
        assert_eq!(
            OptionalDecimalVisitor.visit_i64::<ValueError>(42).unwrap(),
            Some(dec!(42))
        );
        assert_eq!(
            OptionalDecimalVisitor.visit_i128::<ValueError>(5).unwrap(),
            Some(Decimal::from(5i128))
        );
        assert_eq!(
            OptionalDecimalVisitor.visit_u128::<ValueError>(5).unwrap(),
            Some(Decimal::from(5u128))
        );
        assert_eq!(
            OptionalDecimalVisitor.visit_none::<ValueError>().unwrap(),
            None
        );
    }

    #[rstest]
    fn test_serialize_optional_decimal_none_serializes_null() {
        let original = TestFlexibleDecimal {
            value: dec!(1),
            optional_value: None,
        };

        let json = serde_json::to_string(&original).unwrap();
        let parsed: serde_json::Value = serde_json::from_str(&json).unwrap();
        assert_eq!(parsed["optional_value"], json!(null));
    }

    #[rstest]
    fn test_serde_bool_defaults() {
        assert!(default_true());
        assert!(!default_false());
    }

    use proptest::prelude::*;
    use rust_decimal::prelude::ToPrimitive;

    fn representable_decimal_strategy() -> impl Strategy<Value = Decimal> {
        // Mantissa spans Decimal's full 96-bit range; every generated value is
        // exactly representable.
        (
            -79_228_162_514_264_337_593_543_950_335i128
                ..=79_228_162_514_264_337_593_543_950_335i128,
            0u32..=28u32,
        )
            .prop_map(|(mantissa, scale)| Decimal::from_i128_with_scale(mantissa, scale))
    }

    fn numeric_string_strategy() -> impl Strategy<Value = String> {
        // Signed digit strings with long fractions and exponents, covering
        // both natively-parsed shapes and the high-scale clamp fallback.
        (
            proptest::bool::ANY,
            "[0-9]{1,30}",
            proptest::option::of("[0-9]{1,40}"),
            proptest::option::of(-40i32..=40),
        )
            .prop_map(|(negative, integer, fraction, exponent)| {
                let mut value = String::new();
                if negative {
                    value.push('-');
                }
                value.push_str(&integer);
                if let Some(fraction) = fraction {
                    value.push('.');
                    value.push_str(&fraction);
                }

                if let Some(exponent) = exponent {
                    value.push('e');
                    value.push_str(&exponent.to_string());
                }
                value
            })
    }

    proptest! {
        #[rstest]
        fn prop_deserialize_decimal_scientific_roundtrips_representable_values(
            expected in representable_decimal_strategy(),
            zeros in 0usize..=35,
        ) {
            let scientific = format!(
                "{}{}e-{}",
                expected.mantissa(),
                "0".repeat(zeros),
                expected.scale() as usize + zeros,
            );
            let json = serde_json::to_string(&json!({"value": scientific})).unwrap();
            let required: TestDecimalOnly = serde_json::from_str(&json).unwrap();
            let optional: TestOptionalDecimalOnly = serde_json::from_str(&json).unwrap();

            prop_assert_eq!(required.value, expected);
            prop_assert_eq!(optional.value, Some(expected));
        }

        #[rstest]
        fn prop_deserialize_decimal_roundtrips_representable_values(
            expected in representable_decimal_strategy()
        ) {
            // The clamp fallback must never distort a value Decimal can hold
            // exactly.
            let json = format!(r#"{{"value": "{expected}"}}"#);
            let parsed: TestDecimalOnly = serde_json::from_str(&json).unwrap();
            prop_assert_eq!(parsed.value, expected);
        }

        #[rstest]
        fn prop_deserialize_decimal_total_on_arbitrary_strings(value in "\\PC{0,64}") {
            // Any string input must decode or error without panicking.
            let json = serde_json::to_string(&serde_json::json!({"value": value})).unwrap();
            let _ = serde_json::from_str::<TestDecimalOnly>(&json);
        }

        #[rstest]
        fn prop_deserialize_decimal_tracks_f64_reference(value in numeric_string_strategy()) {
            // Accepted values (rounded or not) must agree with an independent
            // f64 parse of the same string within f64 precision.
            let json = format!(r#"{{"value": "{value}"}}"#);
            if let Ok(parsed) = serde_json::from_str::<TestDecimalOnly>(&json) {
                let reference: f64 = value.parse().unwrap();
                let decoded = parsed.value.to_f64().unwrap();
                prop_assert!(
                    (decoded - reference).abs() <= reference.abs() * 1e-9 + 1e-27,
                    "decoded {decoded} diverges from reference {reference} for input {value}",
                );
            }
        }

        #[rstest]
        fn prop_deserialize_optional_decimal_matches_required(
            value in numeric_string_strategy()
        ) {
            let json = format!(r#"{{"value": "{value}"}}"#);
            let required = serde_json::from_str::<TestDecimalOnly>(&json);
            let optional = serde_json::from_str::<TestOptionalDecimalOnly>(&json);
            match (required, optional) {
                (Ok(required), Ok(optional)) => {
                    prop_assert_eq!(optional.value, Some(required.value));
                }
                (Err(_), Err(_)) => {}
                (required, optional) => prop_assert!(
                    false,
                    "required and optional decoding disagree for input {}: {:?} vs {:?}",
                    value,
                    required.map(|r| r.value),
                    optional.map(|o| o.value),
                ),
            }
        }
    }

    #[derive(Debug, Deserialize)]
    struct Token(#[serde(deserialize_with = "deserialize_decimal_token_borrowed")] Decimal);

    #[rstest]
    #[case(r#""1.2300""#, 12300, 4)]
    #[case(r#""\u0031.2300""#, 12300, 4)]
    #[case(r#""1.2300\u0030""#, 123_000, 5)]
    #[case(r#""-0.00001000""#, -1000, 8)]
    #[case("9007199254740993", 9_007_199_254_740_993, 0)]
    #[case("18446744073709551617", 18_446_744_073_709_551_617, 0)]
    fn test_decimal_token_preserves_digits_and_scale(
        #[case] json: &str,
        #[case] mantissa: i128,
        #[case] scale: u32,
    ) {
        let value = serde_json::from_str::<Token>(json).unwrap().0;
        assert_eq!(value.mantissa(), mantissa);
        assert_eq!(value.scale(), scale);
    }

    #[rstest]
    #[case(r#""\uD800""#)]
    #[case(r#""\uDC00""#)]
    #[case(r#""\q""#)]
    #[case(r#""1.2\n3""#)]
    #[case(r#""1.2\"3""#)]
    fn test_decimal_token_rejects_invalid_strings(#[case] json: &str) {
        assert!(serde_json::from_str::<Token>(json).is_err());
    }
}