Skip to main content

nautilus_core/
serialization.rs

1// -------------------------------------------------------------------------------------------------
2//  Copyright (C) 2015-2026 Nautech Systems Pty Ltd. All rights reserved.
3//  https://nautechsystems.io
4//
5//  Licensed under the GNU Lesser General Public License Version 3.0 (the "License");
6//  You may not use this file except in compliance with the License.
7//  You may obtain a copy of the License at https://www.gnu.org/licenses/lgpl-3.0.en.html
8//
9//  Unless required by applicable law or agreed to in writing, software
10//  distributed under the License is distributed on an "AS IS" BASIS,
11//  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12//  See the License for the specific language governing permissions and
13//  limitations under the License.
14// -------------------------------------------------------------------------------------------------
15
16//! Common serialization traits and functions.
17//!
18//! This module provides custom serde deserializers and serializers for common
19//! patterns encountered when parsing exchange API responses, particularly:
20//!
21//! - Empty strings that should be interpreted as `None` or zero.
22//! - Type conversions from strings to primitives.
23//! - Decimal values represented as strings.
24
25use std::{borrow::Cow, str::FromStr};
26
27use bytes::Bytes;
28use rust_decimal::Decimal;
29use serde::{
30    Deserialize, Deserializer, Serialize, Serializer,
31    de::{Error, MapAccess, Unexpected, Visitor, value::MapAccessDeserializer},
32    ser::SerializeSeq,
33};
34use serde_json::value::RawValue;
35use ustr::Ustr;
36
37pub mod decimal;
38pub mod timestamps;
39
40/// Sorted serialization for `AHashSet<T>` where element order must be deterministic.
41///
42/// Use with `#[serde(with = "nautilus_core::serialization::sorted_hashset")]`.
43pub mod sorted_hashset {
44    use ahash::AHashSet;
45    use serde::{Deserialize, Deserializer, Serialize, Serializer};
46
47    /// Serializes an `AHashSet<T>` as a sorted array for deterministic output.
48    ///
49    /// # Errors
50    ///
51    /// Returns an error if the underlying [`Serializer`] fails when writing the sorted vector.
52    pub fn serialize<T, S>(set: &AHashSet<T>, s: S) -> Result<S::Ok, S::Error>
53    where
54        T: Serialize + Ord,
55        S: Serializer,
56    {
57        let mut sorted: Vec<&T> = set.iter().collect();
58        sorted.sort_unstable();
59        sorted.serialize(s)
60    }
61
62    /// Deserializes an array into an `AHashSet<T>`.
63    ///
64    /// # Errors
65    ///
66    /// Returns an error if the underlying [`Deserializer`] fails when reading the source array.
67    pub fn deserialize<'de, T, D>(d: D) -> Result<AHashSet<T>, D::Error>
68    where
69        T: Deserialize<'de> + Eq + std::hash::Hash,
70        D: Deserializer<'de>,
71    {
72        let vec = Vec::<T>::deserialize(d)?;
73        Ok(vec.into_iter().collect())
74    }
75}
76
77/// Decimal visitor for direct JSON token conversion.
78///
79/// Directly visits JSON tokens without intermediate `serde_json::Value` allocation.
80/// Handles all JSON numeric representations: strings, integers, floats, and null.
81struct DecimalVisitor;
82
83impl<'de> Visitor<'de> for DecimalVisitor {
84    type Value = Decimal;
85
86    fn expecting(&self, formatter: &mut std::fmt::Formatter) -> std::fmt::Result {
87        formatter.write_str("a decimal number as string, integer, or float")
88    }
89
90    // Fast path: borrowed string (zero-copy)
91    fn visit_str<E: Error>(self, v: &str) -> Result<Self::Value, E> {
92        if v.is_empty() {
93            return Ok(Decimal::ZERO);
94        }
95        parse_decimal_str(v).map_err(E::custom)
96    }
97
98    // Owned string (rare case, delegates to visit_str)
99    fn visit_string<E: Error>(self, v: String) -> Result<Self::Value, E> {
100        self.visit_str(&v)
101    }
102
103    // Direct integer handling - no string conversion needed
104    fn visit_i64<E: Error>(self, v: i64) -> Result<Self::Value, E> {
105        Ok(Decimal::from(v))
106    }
107
108    fn visit_u64<E: Error>(self, v: u64) -> Result<Self::Value, E> {
109        Ok(Decimal::from(v))
110    }
111
112    fn visit_i128<E: Error>(self, v: i128) -> Result<Self::Value, E> {
113        Decimal::try_from_i128_with_scale(v, 0).map_err(E::custom)
114    }
115
116    fn visit_u128<E: Error>(self, v: u128) -> Result<Self::Value, E> {
117        let v = i128::try_from(v).map_err(E::custom)?;
118        Decimal::try_from_i128_with_scale(v, 0).map_err(E::custom)
119    }
120
121    // Float handling - direct conversion
122    fn visit_f64<E: Error>(self, v: f64) -> Result<Self::Value, E> {
123        if !v.is_finite() {
124            return Err(E::invalid_value(Unexpected::Float(v), &self));
125        }
126        Decimal::try_from(v).map_err(E::custom)
127    }
128
129    fn visit_map<A: MapAccess<'de>>(self, map: A) -> Result<Self::Value, A::Error> {
130        let number = serde_json::Number::deserialize(MapAccessDeserializer::new(map))?;
131        self.visit_str(&number.to_string())
132    }
133
134    // Null → zero (matches existing behavior)
135    fn visit_unit<E: Error>(self) -> Result<Self::Value, E> {
136        Ok(Decimal::ZERO)
137    }
138
139    fn visit_none<E: Error>(self) -> Result<Self::Value, E> {
140        Ok(Decimal::ZERO)
141    }
142}
143
144/// Optional decimal visitor for direct JSON token conversion.
145///
146/// Handles null values as `None` and empty strings as `None`.
147/// Uses `deserialize_any` approach to handle all JSON value types uniformly.
148struct OptionalDecimalVisitor;
149
150impl<'de> Visitor<'de> for OptionalDecimalVisitor {
151    type Value = Option<Decimal>;
152
153    fn expecting(&self, formatter: &mut std::fmt::Formatter) -> std::fmt::Result {
154        formatter.write_str("null or a decimal number as string, integer, or float")
155    }
156
157    // Fast path: borrowed string (zero-copy)
158    // Empty string → None (different from DecimalVisitor which returns ZERO)
159    fn visit_str<E: Error>(self, v: &str) -> Result<Self::Value, E> {
160        if v.is_empty() {
161            return Ok(None);
162        }
163        DecimalVisitor.visit_str(v).map(Some)
164    }
165
166    fn visit_string<E: Error>(self, v: String) -> Result<Self::Value, E> {
167        self.visit_str(&v)
168    }
169
170    fn visit_i64<E: Error>(self, v: i64) -> Result<Self::Value, E> {
171        DecimalVisitor.visit_i64(v).map(Some)
172    }
173
174    fn visit_u64<E: Error>(self, v: u64) -> Result<Self::Value, E> {
175        DecimalVisitor.visit_u64(v).map(Some)
176    }
177
178    fn visit_i128<E: Error>(self, v: i128) -> Result<Self::Value, E> {
179        DecimalVisitor.visit_i128(v).map(Some)
180    }
181
182    fn visit_u128<E: Error>(self, v: u128) -> Result<Self::Value, E> {
183        DecimalVisitor.visit_u128(v).map(Some)
184    }
185
186    fn visit_f64<E: Error>(self, v: f64) -> Result<Self::Value, E> {
187        DecimalVisitor.visit_f64(v).map(Some)
188    }
189
190    fn visit_map<A: MapAccess<'de>>(self, map: A) -> Result<Self::Value, A::Error> {
191        DecimalVisitor.visit_map(map).map(Some)
192    }
193
194    // Null → None
195    fn visit_unit<E: Error>(self) -> Result<Self::Value, E> {
196        Ok(None)
197    }
198
199    fn visit_none<E: Error>(self) -> Result<Self::Value, E> {
200        Ok(None)
201    }
202}
203
204fn json_token_text(raw: &RawValue) -> serde_json::Result<Cow<'_, str>> {
205    let text = raw.get();
206    if text.starts_with('"') {
207        // Generic deserializers can supply RawValue text without lexical validation.
208        if let Some(contents) = text
209            .strip_prefix('"')
210            .and_then(|text| text.strip_suffix('"'))
211            && !contents
212                .bytes()
213                .any(|byte| byte < 0x20 || byte == b'"' || byte == b'\\')
214        {
215            return Ok(Cow::Borrowed(contents));
216        }
217        serde_json::from_str::<String>(text).map(Cow::Owned)
218    } else {
219        Ok(Cow::Borrowed(text))
220    }
221}
222
223fn parse_decimal_str(value: &str) -> Result<Decimal, String> {
224    let parsed = if value.contains('e') || value.contains('E') {
225        if value.len() <= Decimal::MAX_SCALE as usize {
226            Decimal::from_scientific(value)
227        } else {
228            decimal::parse(value).or_else(|_| Decimal::from_scientific(value))
229        }
230    } else {
231        Decimal::from_str(value)
232    };
233
234    match parsed {
235        Ok(decimal) => Ok(decimal),
236        Err(e) => decimal_str_rounded(value).ok_or_else(|| e.to_string()),
237    }
238}
239
240// Fractional digits beyond Decimal's maximum scale are sub-representable; round to the highest
241// scale that fits (venues quoting 18-decimal on-chain units emit such values)
242fn decimal_str_rounded(value: &str) -> Option<Decimal> {
243    for scale in (0..=Decimal::MAX_SCALE as usize).rev() {
244        let clamped = decimal_string_clamped_to_scale(value, scale)?;
245
246        if let Ok(decimal) = Decimal::from_str(&clamped) {
247            return Some(decimal);
248        }
249    }
250
251    None
252}
253
254fn decimal_string_clamped_to_scale(value: &str, max_scale: usize) -> Option<String> {
255    let (coefficient, exponent) = match value.find(['e', 'E']) {
256        Some(index) => {
257            let exponent = value[index + 1..].parse::<i32>().ok()?;
258            (&value[..index], exponent)
259        }
260        None => (value, 0),
261    };
262
263    let (sign, unsigned) = match coefficient.as_bytes().first()? {
264        b'+' => ("", &coefficient[1..]),
265        b'-' => ("-", &coefficient[1..]),
266        _ => ("", coefficient),
267    };
268    let (integer, fractional) = decimal_components(unsigned)?;
269    let digits = format!("{integer}{fractional}");
270    if decimal_digits_are_zero(&digits, "") {
271        return Some("0".to_string());
272    }
273
274    let point = i32::try_from(integer.len()).ok()?.checked_add(exponent)?;
275
276    // Decimal can hold at most 29 significant integer digits, and
277    // `Decimal::from_str` below still rejects values above Decimal::MAX.
278    // Check significant digits before expansion so absurd exponents keep the
279    // original parse error without allocating an absurd string.
280    if decimal_integer_digits_exceed_max(&digits, point) {
281        return None;
282    }
283
284    let (integer, fractional) = if point <= 0 {
285        // Digits past the rounding position are leading zeros, so the cap
286        // cannot change the result; bounds allocation for absurd exponents.
287        let zero_count = usize::try_from(point.checked_neg()?)
288            .ok()?
289            .min(max_scale + 1);
290        (
291            "0".to_string(),
292            format!("{}{digits}", "0".repeat(zero_count)),
293        )
294    } else {
295        let point = usize::try_from(point).ok()?;
296        if point >= digits.len() {
297            (
298                format!("{}{}", digits, "0".repeat(point - digits.len())),
299                String::new(),
300            )
301        } else {
302            (digits[..point].to_string(), digits[point..].to_string())
303        }
304    };
305
306    let (integer, fractional) = round_decimal_components(integer, fractional, max_scale);
307    let sign = if sign == "-" && decimal_digits_are_zero(&integer, &fractional) {
308        ""
309    } else {
310        sign
311    };
312
313    if fractional.is_empty() {
314        Some(format!("{sign}{integer}"))
315    } else {
316        Some(format!("{sign}{integer}.{fractional}"))
317    }
318}
319
320fn decimal_components(value: &str) -> Option<(&str, &str)> {
321    let mut split = value.split('.');
322    let integer = split.next()?;
323    let fractional = split.next().unwrap_or("");
324    if split.next().is_some()
325        || (integer.is_empty() && fractional.is_empty())
326        || !integer.chars().all(|c| c.is_ascii_digit())
327        || !fractional.chars().all(|c| c.is_ascii_digit())
328    {
329        return None;
330    }
331    Some((integer, fractional))
332}
333
334fn decimal_integer_digits_exceed_max(digits: &str, point: i32) -> bool {
335    const DECIMAL_MAX_INTEGER_DIGITS: i32 = 29;
336
337    if point <= 0 {
338        return false;
339    }
340
341    let Some(first_non_zero) = digits.bytes().position(|digit| digit != b'0') else {
342        return false;
343    };
344    let Ok(first_non_zero) = i32::try_from(first_non_zero) else {
345        return true;
346    };
347
348    point.saturating_sub(first_non_zero) > DECIMAL_MAX_INTEGER_DIGITS
349}
350
351fn round_decimal_components(
352    mut integer: String,
353    fractional: String,
354    max_scale: usize,
355) -> (String, String) {
356    if fractional.len() <= max_scale {
357        return (integer, fractional);
358    }
359
360    let mut rounded = fractional.as_bytes()[..max_scale].to_vec();
361    if fractional.as_bytes()[max_scale] >= b'5' {
362        increment_decimal_digits(&mut integer, &mut rounded);
363    }
364
365    (
366        integer,
367        String::from_utf8(rounded).expect("decimal digits are ASCII"),
368    )
369}
370
371fn increment_decimal_digits(integer: &mut String, fractional: &mut [u8]) {
372    for digit in fractional.iter_mut().rev() {
373        if *digit < b'9' {
374            *digit += 1;
375            return;
376        }
377        *digit = b'0';
378    }
379
380    let mut integer_digits = integer.as_bytes().to_vec();
381    for digit in integer_digits.iter_mut().rev() {
382        if *digit < b'9' {
383            *digit += 1;
384            *integer = String::from_utf8(integer_digits).expect("decimal digits are ASCII");
385            return;
386        }
387        *digit = b'0';
388    }
389    integer_digits.insert(0, b'1');
390    *integer = String::from_utf8(integer_digits).expect("decimal digits are ASCII");
391}
392
393fn decimal_digits_are_zero(integer: &str, fractional: &str) -> bool {
394    integer
395        .bytes()
396        .chain(fractional.bytes())
397        .all(|digit| digit == b'0')
398}
399
400/// Represents types which are serializable for JSON specifications.
401pub trait Serializable: Serialize + for<'de> Deserialize<'de> {
402    /// Deserialize an object from JSON encoded bytes.
403    ///
404    /// # Errors
405    ///
406    /// Returns an error if JSON deserialization fails.
407    fn from_json_bytes(data: &[u8]) -> Result<Self, serde_json::Error> {
408        serde_json::from_slice(data)
409    }
410
411    /// Serialize an object to JSON encoded bytes.
412    ///
413    /// # Errors
414    ///
415    /// Returns an error if JSON serialization fails.
416    fn to_json_bytes(&self) -> Result<Bytes, serde_json::Error> {
417        serde_json::to_vec(self).map(Bytes::from)
418    }
419}
420
421pub use self::msgpack::{FromMsgPack, MsgPackSerializable, ToMsgPack};
422
423/// Provides `MsgPack` serialization support for types implementing [`Serializable`].
424///
425/// This module contains traits for `MsgPack` serialization and deserialization,
426/// separated from the core [`Serializable`] trait to allow independent opt-in.
427pub mod msgpack {
428    use bytes::Bytes;
429    use serde::{Deserialize, Serialize};
430
431    use super::Serializable;
432
433    /// Provides deserialization from `MsgPack` encoded bytes.
434    pub trait FromMsgPack: for<'de> Deserialize<'de> + Sized {
435        /// Deserialize an object from `MsgPack` encoded bytes.
436        ///
437        /// # Errors
438        ///
439        /// Returns an error if MessagePack deserialization fails.
440        fn from_msgpack_bytes(data: &[u8]) -> Result<Self, rmp_serde::decode::Error> {
441            rmp_serde::from_slice(data)
442        }
443    }
444
445    /// Provides serialization to `MsgPack` encoded bytes.
446    pub trait ToMsgPack: Serialize {
447        /// Serialize an object to `MsgPack` encoded bytes.
448        ///
449        /// # Errors
450        ///
451        /// Returns an error if MessagePack serialization fails.
452        fn to_msgpack_bytes(&self) -> Result<Bytes, rmp_serde::encode::Error> {
453            rmp_serde::to_vec_named(self).map(Bytes::from)
454        }
455    }
456
457    /// Marker trait combining [`Serializable`], [`FromMsgPack`], and [`ToMsgPack`].
458    ///
459    /// This trait is automatically implemented for all types that implement [`Serializable`].
460    pub trait MsgPackSerializable: Serializable + FromMsgPack + ToMsgPack {}
461
462    impl<T> FromMsgPack for T where T: Serializable {}
463
464    impl<T> ToMsgPack for T where T: Serializable {}
465
466    impl<T> MsgPackSerializable for T where T: Serializable {}
467}
468
469/// Serde default value function that returns `true`.
470///
471/// Use with `#[serde(default = "default_true")]` on boolean fields.
472#[must_use]
473pub const fn default_true() -> bool {
474    true
475}
476
477/// Serde default value function that returns `false`.
478///
479/// Use with `#[serde(default = "default_false")]` on boolean fields.
480#[must_use]
481pub const fn default_false() -> bool {
482    false
483}
484
485/// Deserializes a `Decimal` from either a JSON string or number.
486///
487/// High-performance implementation using a custom visitor that avoids intermediate
488/// `serde_json::Value` allocations. Handles all JSON numeric representations:
489///
490/// - JSON string: `"123.456"` → Decimal (zero-copy for borrowed strings)
491/// - JSON integer: `123` → Decimal (direct conversion, no string allocation)
492/// - JSON float: `123.456` → Decimal
493/// - JSON null: → `Decimal::ZERO`
494/// - Scientific notation: `"1.5e-8"` → Decimal
495/// - Fractional digits beyond `Decimal`'s maximum scale (28) are rounded
496/// - Scientific strings preserve exactly representable values after exponent normalization
497///
498/// # Performance
499///
500/// This implementation is optimized for high-frequency trading scenarios:
501/// - Zero allocations for exactly representable plain borrowed strings
502/// - Scientific normalization and high-scale rounding may allocate
503/// - Direct integer conversion without string intermediary
504/// - No intermediate `serde_json::Value` heap allocation
505///
506/// # Errors
507///
508/// Returns an error if the value cannot be parsed as a valid decimal.
509pub fn deserialize_decimal<'de, D>(deserializer: D) -> Result<Decimal, D::Error>
510where
511    D: Deserializer<'de>,
512{
513    deserializer.deserialize_any(DecimalVisitor)
514}
515
516/// Deserializes a `Decimal` through `rust_decimal`'s own `Deserialize` implementation, keeping
517/// its rounding and scale.
518///
519/// When `rust_decimal`'s arbitrary-precision integration is disabled, `serde_json`
520/// arbitrary-precision numbers parse from their text as `rust_decimal` parses a string, which
521/// matches the result with that integration enabled. Unlike [`deserialize_decimal`], null and
522/// empty strings are errors.
523///
524/// # Errors
525///
526/// Returns an error if:
527/// - The value is null or an empty string.
528/// - The value is a non-numeric type.
529/// - `rust_decimal` rejects the value.
530pub fn deserialize_decimal_native<'de, D>(deserializer: D) -> Result<Decimal, D::Error>
531where
532    D: Deserializer<'de>,
533{
534    #[derive(Deserialize)]
535    #[serde(untagged)]
536    enum Value {
537        Decimal(Decimal),
538        Number(serde_json::Number),
539    }
540
541    match Value::deserialize(deserializer)? {
542        Value::Decimal(value) => Ok(value),
543
544        // Handle serde_json's numeric map when rust_decimal's AP integration is disabled
545        Value::Number(value) => <Decimal as Deserialize>::deserialize(
546            serde::de::value::StringDeserializer::<D::Error>::new(value.to_string()),
547        ),
548    }
549}
550
551/// Deserializes an `Option<Decimal>` from a JSON string, number, or null.
552///
553/// High-performance implementation using a custom visitor that avoids intermediate
554/// `serde_json::Value` allocations. Handles all JSON numeric representations:
555///
556/// - JSON string: `"123.456"` → Some(Decimal) (zero-copy for borrowed strings)
557/// - JSON integer: `123` → Some(Decimal) (direct conversion)
558/// - JSON float: `123.456` → Some(Decimal)
559/// - JSON null: → `None`
560/// - Empty string: `""` → `None`
561/// - Scientific notation: `"1.5e-8"` → Some(Decimal)
562/// - Fractional digits beyond `Decimal`'s maximum scale (28) are rounded
563/// - Scientific strings preserve exactly representable values after exponent normalization
564///
565/// # Performance
566///
567/// This implementation is optimized for high-frequency trading scenarios:
568/// - Zero allocations for exactly representable plain borrowed strings
569/// - Scientific normalization and high-scale rounding may allocate
570/// - Direct integer conversion without string intermediary
571/// - No intermediate `serde_json::Value` heap allocation
572///
573/// # Errors
574///
575/// Returns an error if the value cannot be parsed as a valid decimal.
576pub fn deserialize_optional_decimal<'de, D>(deserializer: D) -> Result<Option<Decimal>, D::Error>
577where
578    D: Deserializer<'de>,
579{
580    // Use deserialize_any to handle all JSON value types uniformly
581    // (deserialize_option would route non-null through visit_some, losing empty string handling)
582    deserializer.deserialize_any(OptionalDecimalVisitor)
583}
584
585/// Deserializes a `Decimal` from the source text of a JSON number or numeric string.
586///
587/// Numeric tokens keep their source digits instead of passing through `f64`. Representable
588/// values, including scientific notation, parse exactly. Values with fractional digits beyond
589/// `Decimal`'s maximum scale (28) round as strings do in [`deserialize_decimal`]. Unlike
590/// [`deserialize_decimal`], null and empty strings are errors.
591///
592/// The raw token is only available from direct JSON input: serde's internally tagged and
593/// untagged enum buffers cannot carry it. A buffered `serde_json::Value` renders its number,
594/// which keeps the source digits only with `serde_json/arbitrary_precision`. For borrowed JSON
595/// text, [`deserialize_decimal_token_borrowed`] reads the same tokens without copying them.
596///
597/// # Errors
598///
599/// Returns an error if the token is null, an empty string, not a decimal, or outside `Decimal`'s
600/// range.
601pub fn deserialize_decimal_token<'de, D>(deserializer: D) -> Result<Decimal, D::Error>
602where
603    D: Deserializer<'de>,
604{
605    deserialize_optional_decimal_token(deserializer)?
606        .ok_or_else(|| D::Error::custom(DECIMAL_TOKEN_MISSING))
607}
608
609/// Deserializes an `Option<Decimal>` from the source text of a JSON number, numeric string, or
610/// null.
611///
612/// Null and empty strings read as `None`; other tokens parse as in
613/// [`deserialize_decimal_token`]. Add `#[serde(default)]` to accept a missing field.
614///
615/// # Errors
616///
617/// Returns an error if a token other than null or an empty string is not a decimal or is outside
618/// `Decimal`'s range.
619pub fn deserialize_optional_decimal_token<'de, D>(
620    deserializer: D,
621) -> Result<Option<Decimal>, D::Error>
622where
623    D: Deserializer<'de>,
624{
625    Option::<Box<RawValue>>::deserialize(deserializer)?
626        .map_or(Ok(None), |raw| parse_decimal_token(&raw))
627}
628
629/// Deserializes a `Decimal` as [`deserialize_decimal_token`] does, borrowing the token from the
630/// input instead of copying it.
631///
632/// Requires a deserializer that borrows from its input, such as `serde_json::from_str` or
633/// `serde_json::from_slice`. Use [`deserialize_decimal_token`] for `serde_json::from_reader` and
634/// `serde_json::Value` input.
635///
636/// # Errors
637///
638/// Returns an error if the deserializer cannot lend the token, or for any token that
639/// [`deserialize_decimal_token`] rejects.
640pub fn deserialize_decimal_token_borrowed<'de, D>(deserializer: D) -> Result<Decimal, D::Error>
641where
642    D: Deserializer<'de>,
643{
644    deserialize_optional_decimal_token_borrowed(deserializer)?
645        .ok_or_else(|| D::Error::custom(DECIMAL_TOKEN_MISSING))
646}
647
648/// Deserializes an `Option<Decimal>` as [`deserialize_optional_decimal_token`] does, borrowing
649/// the token from the input instead of copying it.
650///
651/// Requires borrowed input, as described for [`deserialize_decimal_token_borrowed`].
652///
653/// # Errors
654///
655/// Returns an error if the deserializer cannot lend the token, or for any token that
656/// [`deserialize_optional_decimal_token`] rejects.
657pub fn deserialize_optional_decimal_token_borrowed<'de, D>(
658    deserializer: D,
659) -> Result<Option<Decimal>, D::Error>
660where
661    D: Deserializer<'de>,
662{
663    Option::<&'de RawValue>::deserialize(deserializer)?.map_or(Ok(None), parse_decimal_token)
664}
665
666const DECIMAL_TOKEN_MISSING: &str = "expected a decimal, was null or an empty string";
667
668fn parse_decimal_token<E: Error>(raw: &RawValue) -> Result<Option<Decimal>, E> {
669    let text = json_token_text(raw).map_err(E::custom)?;
670
671    if let Ok(value) = decimal::parse(&text) {
672        return Ok(Some(value));
673    }
674
675    // `Decimal::from_scientific` rounds the significand before applying the exponent
676    if text.contains(['e', 'E'])
677        && let Some(value) = decimal_str_rounded(&text)
678    {
679        return Ok(Some(value));
680    }
681
682    OptionalDecimalVisitor.visit_str(&text)
683}
684
685/// Deserializes a `Decimal` from a JSON string.
686///
687/// This is the strict form that requires the value to be a string, rejecting
688/// numeric JSON values to avoid precision loss.
689///
690/// # Errors
691///
692/// Returns an error if the string cannot be parsed as a valid decimal.
693pub fn deserialize_decimal_from_str<'de, D>(deserializer: D) -> Result<Decimal, D::Error>
694where
695    D: Deserializer<'de>,
696{
697    deserializer.deserialize_str(DecimalStringVisitor::<false>)
698}
699
700/// Deserializes a `Decimal` from a string field that might be empty.
701///
702/// Handles edge cases where empty string "" or "0" becomes `Decimal::ZERO`.
703///
704/// # Errors
705///
706/// Returns an error if the string cannot be parsed as a valid decimal.
707pub fn deserialize_decimal_or_zero<'de, D>(deserializer: D) -> Result<Decimal, D::Error>
708where
709    D: Deserializer<'de>,
710{
711    deserializer.deserialize_str(DecimalStringVisitor::<true>)
712}
713
714// Cow::deserialize always constructs Cow::Owned
715struct DecimalStringVisitor<const EMPTY_AS_ZERO: bool>;
716
717impl<const EMPTY_AS_ZERO: bool> Visitor<'_> for DecimalStringVisitor<EMPTY_AS_ZERO> {
718    type Value = Decimal;
719
720    fn expecting(&self, formatter: &mut std::fmt::Formatter) -> std::fmt::Result {
721        formatter.write_str("a string")
722    }
723
724    fn visit_str<E: Error>(self, value: &str) -> Result<Self::Value, E> {
725        if EMPTY_AS_ZERO && (value.is_empty() || value == "0") {
726            return Ok(Decimal::ZERO);
727        }
728
729        Decimal::from_str(value).map_err(E::custom)
730    }
731
732    fn visit_bytes<E: Error>(self, value: &[u8]) -> Result<Self::Value, E> {
733        let text = std::str::from_utf8(value)
734            .map_err(|_| E::invalid_value(Unexpected::Bytes(value), &self))?;
735        self.visit_str(text)
736    }
737}
738
739/// Deserializes an optional `Decimal` from a string field.
740///
741/// Returns `None` if the string is empty or "0", otherwise parses to `Decimal`.
742/// This is a strict string-only deserializer; for flexible handling of strings,
743/// numbers, and null, use [`deserialize_optional_decimal`].
744///
745/// # Errors
746///
747/// Returns an error if the string cannot be parsed as a valid decimal.
748pub fn deserialize_optional_decimal_str<'de, D>(
749    deserializer: D,
750) -> Result<Option<Decimal>, D::Error>
751where
752    D: Deserializer<'de>,
753{
754    let s: std::borrow::Cow<'de, str> = Deserialize::deserialize(deserializer)?;
755    if s.is_empty() || s == "0" {
756        Ok(None)
757    } else {
758        Decimal::from_str(s.as_ref())
759            .map(Some)
760            .map_err(D::Error::custom)
761    }
762}
763
764/// Deserializes an optional `Decimal` from a string-only field.
765///
766/// Returns `None` if the value is null or the string is empty, otherwise
767/// parses to `Decimal`.
768///
769/// # Errors
770///
771/// Returns an error if the string cannot be parsed as a valid decimal.
772pub fn deserialize_optional_decimal_from_str<'de, D>(
773    deserializer: D,
774) -> Result<Option<Decimal>, D::Error>
775where
776    D: Deserializer<'de>,
777{
778    let opt = Option::<String>::deserialize(deserializer)?;
779    match opt {
780        Some(s) if !s.is_empty() => Decimal::from_str(&s).map(Some).map_err(D::Error::custom),
781        _ => Ok(None),
782    }
783}
784
785/// Deserializes a `Decimal` from an optional string field, defaulting to zero.
786///
787/// Handles edge cases: `None`, empty string "", or "0" all become `Decimal::ZERO`.
788///
789/// # Errors
790///
791/// Returns an error if the string cannot be parsed as a valid decimal.
792pub fn deserialize_optional_decimal_or_zero<'de, D>(deserializer: D) -> Result<Decimal, D::Error>
793where
794    D: Deserializer<'de>,
795{
796    let opt: Option<String> = Deserialize::deserialize(deserializer)?;
797    match opt {
798        None => Ok(Decimal::ZERO),
799        Some(s) if s.is_empty() || s == "0" => Ok(Decimal::ZERO),
800        Some(s) => Decimal::from_str(&s).map_err(D::Error::custom),
801    }
802}
803
804/// Deserializes a `Vec<Decimal>` from a JSON array of strings.
805///
806/// # Errors
807///
808/// Returns an error if any string cannot be parsed as a valid decimal.
809pub fn deserialize_vec_decimal_from_str<'de, D>(deserializer: D) -> Result<Vec<Decimal>, D::Error>
810where
811    D: Deserializer<'de>,
812{
813    let strings = Vec::<String>::deserialize(deserializer)?;
814    strings
815        .into_iter()
816        .map(|s| Decimal::from_str(&s).map_err(D::Error::custom))
817        .collect()
818}
819
820/// Serializes a `Decimal` as a string (lossless, no scientific notation).
821///
822/// # Errors
823///
824/// Returns an error if serialization fails.
825pub fn serialize_decimal_as_str<S>(decimal: &Decimal, serializer: S) -> Result<S::Ok, S::Error>
826where
827    S: Serializer,
828{
829    serializer.serialize_str(&decimal.to_string())
830}
831
832/// Serializes an optional `Decimal` as a string.
833///
834/// # Errors
835///
836/// Returns an error if serialization fails.
837pub fn serialize_optional_decimal_as_str<S>(
838    decimal: &Option<Decimal>,
839    serializer: S,
840) -> Result<S::Ok, S::Error>
841where
842    S: Serializer,
843{
844    match decimal {
845        Some(d) => serializer.serialize_str(&d.to_string()),
846        None => serializer.serialize_none(),
847    }
848}
849
850/// Serializes a `Vec<Decimal>` as an array of strings.
851///
852/// # Errors
853///
854/// Returns an error if serialization fails.
855pub fn serialize_vec_decimal_as_str<S>(
856    decimals: &Vec<Decimal>,
857    serializer: S,
858) -> Result<S::Ok, S::Error>
859where
860    S: Serializer,
861{
862    let mut seq = serializer.serialize_seq(Some(decimals.len()))?;
863    for decimal in decimals {
864        seq.serialize_element(&decimal.to_string())?;
865    }
866    seq.end()
867}
868
869/// Parses a string to `Decimal`, returning an error if parsing fails.
870///
871/// # Errors
872///
873/// Returns an error if the string cannot be parsed as a Decimal.
874pub fn parse_decimal(s: &str) -> anyhow::Result<Decimal> {
875    Decimal::from_str(s).map_err(|e| anyhow::anyhow!("Failed to parse decimal from '{s}': {e}"))
876}
877
878/// Parses an optional string to `Decimal`, returning `None` if the string is `None` or empty.
879///
880/// # Errors
881///
882/// Returns an error if the string cannot be parsed as a Decimal.
883pub fn parse_optional_decimal(s: &Option<String>) -> anyhow::Result<Option<Decimal>> {
884    match s {
885        None => Ok(None),
886        Some(s) if s.is_empty() => Ok(None),
887        Some(s) => parse_decimal(s).map(Some),
888    }
889}
890
891/// Deserializes an empty string into `None`.
892///
893/// Many exchange APIs represent null string fields as an empty string (`""`).
894/// When such a payload is mapped onto `Option<String>` the default behavior
895/// would yield `Some("")`, which is semantically different from the intended
896/// absence of a value. This deserializer normalizes empty strings
897/// to `None` during deserialization.
898///
899/// # Errors
900///
901/// Returns an error if the JSON value cannot be deserialized into a string.
902pub fn deserialize_empty_string_as_none<'de, D>(deserializer: D) -> Result<Option<String>, D::Error>
903where
904    D: Deserializer<'de>,
905{
906    let opt = Option::<String>::deserialize(deserializer)?;
907    Ok(opt.filter(|s| !s.is_empty()))
908}
909
910/// Deserializes an empty [`Ustr`] into `None`.
911///
912/// # Errors
913///
914/// Returns an error if the JSON value cannot be deserialized into a string.
915pub fn deserialize_empty_ustr_as_none<'de, D>(deserializer: D) -> Result<Option<Ustr>, D::Error>
916where
917    D: Deserializer<'de>,
918{
919    let opt = Option::<Ustr>::deserialize(deserializer)?;
920    Ok(opt.filter(|s| !s.is_empty()))
921}
922
923/// Deserializes a `u8` from a string field.
924///
925/// Returns 0 if the string is empty.
926///
927/// # Errors
928///
929/// Returns an error if the string cannot be parsed as a u8.
930pub fn deserialize_string_to_u8<'de, D>(deserializer: D) -> Result<u8, D::Error>
931where
932    D: Deserializer<'de>,
933{
934    let s: std::borrow::Cow<'de, str> = Deserialize::deserialize(deserializer)?;
935    if s.is_empty() {
936        return Ok(0);
937    }
938    s.as_ref().parse::<u8>().map_err(D::Error::custom)
939}
940
941/// Deserializes a `u64` from a string field.
942///
943/// Returns 0 if the string is empty.
944///
945/// # Errors
946///
947/// Returns an error if the string cannot be parsed as a u64.
948pub fn deserialize_string_to_u64<'de, D>(deserializer: D) -> Result<u64, D::Error>
949where
950    D: Deserializer<'de>,
951{
952    let s: std::borrow::Cow<'de, str> = Deserialize::deserialize(deserializer)?;
953    if s.is_empty() {
954        Ok(0)
955    } else {
956        s.as_ref().parse::<u64>().map_err(D::Error::custom)
957    }
958}
959
960/// Deserializes an optional `u64` from a string field.
961///
962/// Returns `None` if the value is null or the string is empty.
963///
964/// # Errors
965///
966/// Returns an error if the string cannot be parsed as a u64.
967pub fn deserialize_optional_string_to_u64<'de, D>(deserializer: D) -> Result<Option<u64>, D::Error>
968where
969    D: Deserializer<'de>,
970{
971    let s: Option<String> = Option::deserialize(deserializer)?;
972    match s {
973        Some(s) if s.is_empty() => Ok(None),
974        Some(s) => s.parse().map(Some).map_err(D::Error::custom),
975        None => Ok(None),
976    }
977}
978
979#[cfg(test)]
980mod tests {
981    use ahash::AHashSet;
982    use rstest::*;
983    use rust_decimal::Decimal;
984    use rust_decimal_macros::dec;
985    use serde::{
986        Deserialize, Serialize,
987        de::{Visitor, value::Error as ValueError},
988    };
989    use serde_json::json;
990    use ustr::Ustr;
991
992    use super::{
993        DecimalVisitor, OptionalDecimalVisitor, Serializable, decimal, default_false, default_true,
994        deserialize_decimal, deserialize_decimal_from_str, deserialize_decimal_native,
995        deserialize_decimal_or_zero, deserialize_decimal_token, deserialize_decimal_token_borrowed,
996        deserialize_empty_string_as_none, deserialize_empty_ustr_as_none,
997        deserialize_optional_decimal, deserialize_optional_decimal_or_zero,
998        deserialize_optional_decimal_str, deserialize_optional_decimal_token,
999        deserialize_optional_decimal_token_borrowed, deserialize_optional_string_to_u64,
1000        deserialize_string_to_u8, deserialize_string_to_u64, deserialize_vec_decimal_from_str,
1001        msgpack::{FromMsgPack, ToMsgPack},
1002        parse_decimal, parse_optional_decimal, serialize_decimal_as_str,
1003        serialize_optional_decimal_as_str, serialize_vec_decimal_as_str, sorted_hashset,
1004    };
1005
1006    #[derive(Debug, PartialEq, Serialize, Deserialize)]
1007    struct SortedSetPayload {
1008        #[serde(with = "sorted_hashset")]
1009        values: AHashSet<i32>,
1010    }
1011
1012    #[derive(Serialize, Deserialize, PartialEq, Debug)]
1013    struct SerializableTestStruct {
1014        id: u32,
1015        name: String,
1016        value: f64,
1017    }
1018
1019    impl Serializable for SerializableTestStruct {}
1020
1021    #[rstest]
1022    #[case("\"")]
1023    #[case("\"1x")]
1024    #[case("\"1\u{e9}")]
1025    #[case("\"1\0")]
1026    #[case("\"1\n")]
1027    #[case("\"1\"\"")]
1028    #[case("\"1\0\"")]
1029    #[case("\"1\n\"")]
1030    fn test_json_decimal_rejects_malformed_raw_strings(#[case] raw: &str) {
1031        // A generic deserializer can supply RawValue text without serde_json's lexical validation.
1032        let expected = serde_json::from_str::<String>(raw).unwrap_err().to_string();
1033        let deserializer = serde::de::value::MapDeserializer::<_, ValueError>::new(
1034            [("$serde_json::private::RawValue", raw)].into_iter(),
1035        );
1036        let error = decimal::deserialize_json(deserializer).unwrap_err();
1037        assert_eq!(error.to_string(), expected);
1038    }
1039
1040    #[rstest]
1041    #[case("0.125", "0.125", 3)]
1042    #[case("9007199254740993", "9007199254740993", 0)]
1043    #[case("\"1.2500\"", "1.2500", 4)]
1044    #[case(
1045        "\"0.12345678901234567890123456789\"",
1046        "0.1234567890123456789012345679",
1047        28
1048    )]
1049    fn test_native_decimal_preserves_rounding_and_scale(
1050        #[case] token: &str,
1051        #[case] expected: &str,
1052        #[case] scale: u32,
1053    ) {
1054        let direct =
1055            deserialize_decimal_native(&mut serde_json::Deserializer::from_str(token)).unwrap();
1056        let buffered =
1057            deserialize_decimal_native(serde_json::from_str::<serde_json::Value>(token).unwrap())
1058                .unwrap();
1059        let expected = Decimal::from_str_exact(expected).unwrap();
1060
1061        assert_eq!(direct, expected);
1062        assert_eq!(direct.scale(), scale);
1063        assert_eq!(buffered, expected);
1064        assert_eq!(buffered.scale(), scale);
1065    }
1066
1067    #[rstest]
1068    #[case("null")]
1069    #[case("true")]
1070    #[case("\"\"")]
1071    #[case("\"NaN\"")]
1072    #[case("\"79228162514264337593543950336\"")]
1073    fn test_native_decimal_rejects_invalid_values(#[case] token: &str) {
1074        let direct = deserialize_decimal_native(&mut serde_json::Deserializer::from_str(token));
1075        let buffered =
1076            deserialize_decimal_native(serde_json::from_str::<serde_json::Value>(token).unwrap());
1077
1078        assert!(direct.is_err());
1079        assert!(buffered.is_err());
1080    }
1081
1082    #[rstest]
1083    #[case("1.25")]
1084    #[case("2.0")]
1085    #[case("1.2500")]
1086    #[case("-0.0")]
1087    #[case("1e-7")]
1088    #[case("1.5E3")]
1089    #[case("1e-30")]
1090    #[case("1e30")]
1091    #[case("13.223699999999997")]
1092    #[case("9007199254740993")]
1093    #[case("18446744073709551615")]
1094    #[case("-9223372036854775808")]
1095    #[case("\"1.2500\"")]
1096    #[case("\"1e5\"")]
1097    #[case("\"0.12345678901234567890123456789\"")]
1098    #[case("\"79228162514264337593543950336\"")]
1099    #[case("\"not-a-number\"")]
1100    fn test_native_decimal_matches_rust_decimal(#[case] token: &str) {
1101        let value = serde_json::from_str::<serde_json::Value>(token).unwrap();
1102
1103        // Where rust_decimal rejects an arbitrary-precision number map, the token digits must
1104        // parse as rust_decimal parses them when its own AP integration is enabled.
1105        let fallback = (is_arbitrary_precision() && value.is_number())
1106            .then(|| serde_json::from_value::<Decimal>(serde_json::json!(token)).ok())
1107            .flatten();
1108        let routes = [
1109            (
1110                serde_json::from_str::<Decimal>(token).ok(),
1111                deserialize_decimal_native(&mut serde_json::Deserializer::from_str(token)).ok(),
1112            ),
1113            (
1114                serde_json::from_value::<Decimal>(value.clone()).ok(),
1115                deserialize_decimal_native(value).ok(),
1116            ),
1117        ];
1118
1119        for (native, consolidated) in routes {
1120            let expected = native.or(fallback);
1121            assert_eq!(
1122                consolidated.map(|value| (value, value.scale())),
1123                expected.map(|value| (value, value.scale()))
1124            );
1125        }
1126    }
1127
1128    #[rstest]
1129    #[case("10.0", Decimal::from(10), 0, 1, 0)]
1130    #[case("1.2500", Decimal::new(125, 2), 2, 4, 4)]
1131    #[case("1.25e1", Decimal::new(125, 1), 1, 1, 1)]
1132    fn test_numeric_decimal_preserves_route_scale(
1133        #[case] token: &str,
1134        #[case] expected: Decimal,
1135        #[case] float_scale: u32,
1136        #[case] token_scale: u32,
1137        #[case] buffered_token_scale: u32,
1138    ) {
1139        let arbitrary_precision = is_arbitrary_precision();
1140
1141        let scale = if arbitrary_precision {
1142            token_scale
1143        } else {
1144            float_scale
1145        };
1146
1147        let buffered_scale = if arbitrary_precision {
1148            buffered_token_scale
1149        } else {
1150            float_scale
1151        };
1152
1153        let direct = deserialize_decimal(&mut serde_json::Deserializer::from_str(token)).unwrap();
1154        let buffered =
1155            deserialize_decimal(serde_json::from_str::<serde_json::Value>(token).unwrap()).unwrap();
1156        let quoted = deserialize_decimal(serde_json::Value::String("1.2500".to_string())).unwrap();
1157        assert_eq!(direct, expected);
1158        assert_eq!(direct.scale(), scale);
1159        assert_eq!(buffered, expected);
1160        assert_eq!(buffered.scale(), buffered_scale);
1161        assert_eq!(quoted, Decimal::new(12500, 4));
1162        assert_eq!(quoted.scale(), 4);
1163    }
1164
1165    fn is_arbitrary_precision() -> bool {
1166        serde_json::from_str::<serde_json::Number>("1.2500")
1167            .unwrap()
1168            .to_string()
1169            == "1.2500"
1170    }
1171
1172    #[rstest]
1173    fn test_sorted_hashset_serialization_is_deterministic() {
1174        let payload = SortedSetPayload {
1175            values: [29, 3, 17, 5, 23, 11].into_iter().collect(),
1176        };
1177
1178        let encoded = serde_json::to_string(&payload).unwrap();
1179        let expected = serde_json::to_string(&json!({ "values": [3, 5, 11, 17, 23, 29] })).unwrap();
1180        let restored: SortedSetPayload = serde_json::from_str(&encoded).unwrap();
1181
1182        assert_eq!(encoded, expected);
1183        assert_eq!(restored, payload);
1184    }
1185
1186    #[rstest]
1187    fn test_serializable_json_roundtrip() {
1188        let original = SerializableTestStruct {
1189            id: 42,
1190            name: "test".to_string(),
1191            value: std::f64::consts::PI,
1192        };
1193
1194        let json_bytes = original.to_json_bytes().unwrap();
1195        let deserialized = SerializableTestStruct::from_json_bytes(&json_bytes).unwrap();
1196
1197        assert_eq!(original, deserialized);
1198    }
1199
1200    #[rstest]
1201    fn test_serializable_msgpack_roundtrip() {
1202        let original = SerializableTestStruct {
1203            id: 123,
1204            name: "msgpack_test".to_string(),
1205            value: std::f64::consts::E,
1206        };
1207
1208        let msgpack_bytes = original.to_msgpack_bytes().unwrap();
1209        let deserialized = SerializableTestStruct::from_msgpack_bytes(&msgpack_bytes).unwrap();
1210
1211        assert_eq!(original, deserialized);
1212    }
1213
1214    #[rstest]
1215    fn test_serializable_json_invalid_data() {
1216        let invalid_json = b"invalid json data";
1217        let result = SerializableTestStruct::from_json_bytes(invalid_json);
1218        assert!(result.is_err());
1219    }
1220
1221    #[rstest]
1222    fn test_serializable_msgpack_invalid_data() {
1223        let invalid_msgpack = b"invalid msgpack data";
1224        let result = SerializableTestStruct::from_msgpack_bytes(invalid_msgpack);
1225        assert!(result.is_err());
1226    }
1227
1228    #[rstest]
1229    fn test_serializable_json_empty_values() {
1230        let test_struct = SerializableTestStruct {
1231            id: 0,
1232            name: String::new(),
1233            value: 0.0,
1234        };
1235
1236        let json_bytes = test_struct.to_json_bytes().unwrap();
1237        let deserialized = SerializableTestStruct::from_json_bytes(&json_bytes).unwrap();
1238
1239        assert_eq!(test_struct, deserialized);
1240    }
1241
1242    #[rstest]
1243    fn test_serializable_msgpack_empty_values() {
1244        let test_struct = SerializableTestStruct {
1245            id: 0,
1246            name: String::new(),
1247            value: 0.0,
1248        };
1249
1250        let msgpack_bytes = test_struct.to_msgpack_bytes().unwrap();
1251        let deserialized = SerializableTestStruct::from_msgpack_bytes(&msgpack_bytes).unwrap();
1252
1253        assert_eq!(test_struct, deserialized);
1254    }
1255
1256    #[derive(Deserialize)]
1257    struct TestOptionalDecimalStr {
1258        #[serde(deserialize_with = "deserialize_optional_decimal_str")]
1259        value: Option<Decimal>,
1260    }
1261
1262    #[derive(Deserialize)]
1263    struct TestDecimalOrZero {
1264        #[serde(deserialize_with = "deserialize_decimal_or_zero")]
1265        value: Decimal,
1266    }
1267
1268    #[derive(Deserialize)]
1269    struct TestOptionalDecimalOrZero {
1270        #[serde(deserialize_with = "deserialize_optional_decimal_or_zero")]
1271        value: Decimal,
1272    }
1273
1274    #[derive(Serialize, Deserialize, PartialEq, Debug)]
1275    struct TestDecimalRoundtrip {
1276        #[serde(
1277            serialize_with = "serialize_decimal_as_str",
1278            deserialize_with = "deserialize_decimal_from_str"
1279        )]
1280        value: Decimal,
1281        #[serde(
1282            serialize_with = "serialize_optional_decimal_as_str",
1283            deserialize_with = "super::deserialize_optional_decimal_from_str"
1284        )]
1285        optional_value: Option<Decimal>,
1286    }
1287
1288    #[rstest]
1289    #[case(r#"{"value":"123.45"}"#, Some(dec!(123.45)))]
1290    #[case(r#"{"value":"0"}"#, None)]
1291    #[case(r#"{"value":""}"#, None)]
1292    fn test_deserialize_optional_decimal_str(
1293        #[case] json: &str,
1294        #[case] expected: Option<Decimal>,
1295    ) {
1296        let result: TestOptionalDecimalStr = serde_json::from_str(json).unwrap();
1297        assert_eq!(result.value, expected);
1298    }
1299
1300    #[rstest]
1301    fn test_deserialize_optional_decimal_from_str_empty_is_none() {
1302        let json = r#"{"value": "1.5", "optional_value": ""}"#;
1303        let result: TestDecimalRoundtrip = serde_json::from_str(json).unwrap();
1304        assert_eq!(result.optional_value, None);
1305    }
1306
1307    #[rstest]
1308    #[case(r#"{"value":"123.45"}"#, dec!(123.45))]
1309    #[case(r#"{"value":"0"}"#, Decimal::ZERO)]
1310    #[case(r#"{"value":""}"#, Decimal::ZERO)]
1311    fn test_deserialize_decimal_or_zero(#[case] json: &str, #[case] expected: Decimal) {
1312        let results: [TestDecimalOrZero; 3] = [
1313            serde_json::from_str(json).unwrap(),
1314            serde_json::from_reader(json.as_bytes()).unwrap(),
1315            serde_json::from_value(serde_json::from_str(json).unwrap()).unwrap(),
1316        ];
1317
1318        for result in results {
1319            assert_eq!(result.value.serialize(), expected.serialize());
1320        }
1321    }
1322
1323    #[rstest]
1324    #[case(r#""-12345.067800""#, dec!(-12345.067800))]
1325    #[case(r#""0.0000000000000000000000000001""#, dec!(0.0000000000000000000000000001))]
1326    #[case(r#""\u0031\u0032.3400""#, dec!(12.3400))]
1327    #[case(r#""0.0000""#, dec!(0.0000))]
1328    #[case(r#""79228162514264337593543950335""#, Decimal::MAX)]
1329    fn test_deserialize_decimal_strings_preserve_representation(
1330        #[case] token: &str,
1331        #[case] expected: Decimal,
1332    ) {
1333        let json = format!(r#"{{"value":{token},"optional_value":null}}"#);
1334        let strict: [TestDecimalRoundtrip; 3] = [
1335            serde_json::from_str(&json).unwrap(),
1336            serde_json::from_reader(json.as_bytes()).unwrap(),
1337            serde_json::from_value(serde_json::from_str(&json).unwrap()).unwrap(),
1338        ];
1339        let or_zero: [TestDecimalOrZero; 3] = [
1340            serde_json::from_str(&json).unwrap(),
1341            serde_json::from_reader(json.as_bytes()).unwrap(),
1342            serde_json::from_value(serde_json::from_str(&json).unwrap()).unwrap(),
1343        ];
1344
1345        for result in strict {
1346            assert_eq!(result.value.serialize(), expected.serialize());
1347            assert_eq!(result.optional_value, None);
1348        }
1349
1350        for result in or_zero {
1351            assert_eq!(result.value.serialize(), expected.serialize());
1352        }
1353    }
1354
1355    #[rstest]
1356    #[case("123")]
1357    #[case("123.45")]
1358    #[case("null")]
1359    #[case("true")]
1360    #[case("[]")]
1361    #[case("{}")]
1362    #[case(r#""invalid""#)]
1363    #[case(r#""79228162514264337593543950336""#)]
1364    fn test_deserialize_decimal_strings_reject_invalid_values(#[case] token: &str) {
1365        let json = format!(r#"{{"value":{token},"optional_value":null}}"#);
1366        let value: serde_json::Value = serde_json::from_str(&json).unwrap();
1367
1368        assert!(serde_json::from_str::<TestDecimalRoundtrip>(&json).is_err());
1369        assert!(serde_json::from_reader::<_, TestDecimalRoundtrip>(json.as_bytes()).is_err());
1370        assert!(serde_json::from_value::<TestDecimalRoundtrip>(value.clone()).is_err());
1371        assert!(serde_json::from_str::<TestDecimalOrZero>(&json).is_err());
1372        assert!(serde_json::from_reader::<_, TestDecimalOrZero>(json.as_bytes()).is_err());
1373        assert!(serde_json::from_value::<TestDecimalOrZero>(value).is_err());
1374    }
1375
1376    #[rstest]
1377    fn test_deserialize_decimal_from_str_rejects_empty_string() {
1378        let json = r#"{"value":"","optional_value":null}"#;
1379
1380        assert!(serde_json::from_str::<TestDecimalRoundtrip>(json).is_err());
1381        assert!(serde_json::from_reader::<_, TestDecimalRoundtrip>(json.as_bytes()).is_err());
1382        assert!(
1383            serde_json::from_value::<TestDecimalRoundtrip>(serde_json::from_str(json).unwrap())
1384                .is_err()
1385        );
1386    }
1387
1388    #[rstest]
1389    fn test_deserialize_decimal_strings_accept_utf8_bytes() {
1390        let strict = deserialize_decimal_from_str(
1391            serde::de::value::BytesDeserializer::<ValueError>::new(b"-12.3400"),
1392        )
1393        .unwrap();
1394        let or_zero = deserialize_decimal_or_zero(
1395            serde::de::value::BytesDeserializer::<ValueError>::new(b"-12.3400"),
1396        )
1397        .unwrap();
1398
1399        assert_eq!(strict.serialize(), dec!(-12.3400).serialize());
1400        assert_eq!(or_zero.serialize(), dec!(-12.3400).serialize());
1401    }
1402
1403    #[rstest]
1404    fn test_deserialize_decimal_strings_reject_invalid_utf8() {
1405        let strict = deserialize_decimal_from_str(
1406            serde::de::value::BytesDeserializer::<ValueError>::new(&[0xff]),
1407        );
1408        let or_zero =
1409            deserialize_decimal_or_zero(serde::de::value::BytesDeserializer::<ValueError>::new(&[
1410                0xff,
1411            ]));
1412
1413        assert!(strict.is_err());
1414        assert!(or_zero.is_err());
1415    }
1416
1417    #[rstest]
1418    #[case(r#"{"value":"123.45"}"#, dec!(123.45))]
1419    #[case(r#"{"value":"0"}"#, Decimal::ZERO)]
1420    #[case(r#"{"value":null}"#, Decimal::ZERO)]
1421    #[case(r#"{"value":""}"#, Decimal::ZERO)]
1422    fn test_deserialize_optional_decimal_or_zero(#[case] json: &str, #[case] expected: Decimal) {
1423        let result: TestOptionalDecimalOrZero = serde_json::from_str(json).unwrap();
1424        assert_eq!(result.value, expected);
1425    }
1426
1427    #[rstest]
1428    fn test_decimal_serialization_roundtrip() {
1429        let original = TestDecimalRoundtrip {
1430            value: dec!(123.456789012345678),
1431            optional_value: Some(dec!(0.000000001)),
1432        };
1433
1434        let json = serde_json::to_string(&original).unwrap();
1435
1436        // Check that it's serialized as strings
1437        assert!(json.contains("\"123.456789012345678\""));
1438        assert!(json.contains("\"0.000000001\""));
1439
1440        let deserialized: TestDecimalRoundtrip = serde_json::from_str(&json).unwrap();
1441        assert_eq!(original.value, deserialized.value);
1442        assert_eq!(original.optional_value, deserialized.optional_value);
1443    }
1444
1445    #[rstest]
1446    fn test_decimal_optional_none_handling() {
1447        let test_struct = TestDecimalRoundtrip {
1448            value: dec!(42.0),
1449            optional_value: None,
1450        };
1451
1452        let json = serde_json::to_string(&test_struct).unwrap();
1453        assert!(json.contains("null"));
1454
1455        let parsed: TestDecimalRoundtrip = serde_json::from_str(&json).unwrap();
1456        assert_eq!(test_struct.value, parsed.value);
1457        assert_eq!(None, parsed.optional_value);
1458    }
1459
1460    #[derive(Deserialize)]
1461    struct TestEmptyStringAsNone {
1462        #[serde(deserialize_with = "deserialize_empty_string_as_none")]
1463        value: Option<String>,
1464    }
1465
1466    #[rstest]
1467    #[case(r#"{"value":"hello"}"#, Some("hello".to_string()))]
1468    #[case(r#"{"value":""}"#, None)]
1469    #[case(r#"{"value":null}"#, None)]
1470    fn test_deserialize_empty_string_as_none(#[case] json: &str, #[case] expected: Option<String>) {
1471        let result: TestEmptyStringAsNone = serde_json::from_str(json).unwrap();
1472        assert_eq!(result.value, expected);
1473    }
1474
1475    #[derive(Deserialize)]
1476    struct TestEmptyUstrAsNone {
1477        #[serde(deserialize_with = "deserialize_empty_ustr_as_none")]
1478        value: Option<Ustr>,
1479    }
1480
1481    #[rstest]
1482    #[case(r#"{"value":"hello"}"#, Some(Ustr::from("hello")))]
1483    #[case(r#"{"value":""}"#, None)]
1484    #[case(r#"{"value":null}"#, None)]
1485    fn test_deserialize_empty_ustr_as_none(#[case] json: &str, #[case] expected: Option<Ustr>) {
1486        let result: TestEmptyUstrAsNone = serde_json::from_str(json).unwrap();
1487        assert_eq!(result.value, expected);
1488    }
1489
1490    #[derive(Serialize, Deserialize, PartialEq, Debug)]
1491    struct TestVecDecimal {
1492        #[serde(
1493            serialize_with = "serialize_vec_decimal_as_str",
1494            deserialize_with = "deserialize_vec_decimal_from_str"
1495        )]
1496        values: Vec<Decimal>,
1497    }
1498
1499    #[rstest]
1500    fn test_vec_decimal_roundtrip() {
1501        let original = TestVecDecimal {
1502            values: vec![dec!(1.5), dec!(2.25), dec!(100.001)],
1503        };
1504
1505        let json = serde_json::to_string(&original).unwrap();
1506        assert!(json.contains("[\"1.5\",\"2.25\",\"100.001\"]"));
1507
1508        let parsed: TestVecDecimal = serde_json::from_str(&json).unwrap();
1509        assert_eq!(original.values, parsed.values);
1510    }
1511
1512    #[rstest]
1513    fn test_vec_decimal_empty() {
1514        let original = TestVecDecimal { values: vec![] };
1515
1516        let json = serde_json::to_string(&original).unwrap();
1517        let parsed: TestVecDecimal = serde_json::from_str(&json).unwrap();
1518        assert_eq!(original.values, parsed.values);
1519    }
1520
1521    #[derive(Deserialize)]
1522    struct TestStringToU8 {
1523        #[serde(deserialize_with = "deserialize_string_to_u8")]
1524        value: u8,
1525    }
1526
1527    #[rstest]
1528    #[case(r#"{"value":"42"}"#, 42)]
1529    #[case(r#"{"value":"0"}"#, 0)]
1530    #[case(r#"{"value":"255"}"#, 255)]
1531    #[case(r#"{"value":""}"#, 0)]
1532    fn test_deserialize_string_to_u8(#[case] json: &str, #[case] expected: u8) {
1533        let result: TestStringToU8 = serde_json::from_str(json).unwrap();
1534        assert_eq!(result.value, expected);
1535    }
1536
1537    #[rstest]
1538    #[case(r#"{"value":"256"}"#)]
1539    #[case(r#"{"value":"999"}"#)]
1540    #[case(r#"{"value":"abc"}"#)]
1541    fn test_deserialize_string_to_u8_invalid(#[case] json: &str) {
1542        let result: Result<TestStringToU8, _> = serde_json::from_str(json);
1543        assert!(result.is_err());
1544    }
1545
1546    #[derive(Deserialize)]
1547    struct TestStringToU64 {
1548        #[serde(deserialize_with = "deserialize_string_to_u64")]
1549        value: u64,
1550    }
1551
1552    #[rstest]
1553    #[case(r#"{"value":"12345678901234"}"#, 12_345_678_901_234)]
1554    #[case(r#"{"value":"0"}"#, 0)]
1555    #[case(r#"{"value":"18446744073709551615"}"#, u64::MAX)]
1556    #[case(r#"{"value":""}"#, 0)]
1557    fn test_deserialize_string_to_u64(#[case] json: &str, #[case] expected: u64) {
1558        let result: TestStringToU64 = serde_json::from_str(json).unwrap();
1559        assert_eq!(result.value, expected);
1560    }
1561
1562    #[rstest]
1563    #[case(r#"{"value":"18446744073709551616"}"#)]
1564    #[case(r#"{"value":"abc"}"#)]
1565    #[case(r#"{"value":"-1"}"#)]
1566    fn test_deserialize_string_to_u64_invalid(#[case] json: &str) {
1567        let result: Result<TestStringToU64, _> = serde_json::from_str(json);
1568        assert!(result.is_err());
1569    }
1570
1571    #[derive(Deserialize)]
1572    struct TestOptionalStringToU64 {
1573        #[serde(deserialize_with = "deserialize_optional_string_to_u64")]
1574        value: Option<u64>,
1575    }
1576
1577    #[rstest]
1578    #[case(r#"{"value":"12345678901234"}"#, Some(12_345_678_901_234))]
1579    #[case(r#"{"value":"0"}"#, Some(0))]
1580    #[case(r#"{"value":""}"#, None)]
1581    #[case(r#"{"value":null}"#, None)]
1582    fn test_deserialize_optional_string_to_u64(#[case] json: &str, #[case] expected: Option<u64>) {
1583        let result: TestOptionalStringToU64 = serde_json::from_str(json).unwrap();
1584        assert_eq!(result.value, expected);
1585    }
1586
1587    #[rstest]
1588    #[case("123.45", dec!(123.45))]
1589    #[case("0", Decimal::ZERO)]
1590    #[case("0.0", Decimal::ZERO)]
1591    fn test_parse_decimal(#[case] input: &str, #[case] expected: Decimal) {
1592        let result = parse_decimal(input).unwrap();
1593        assert_eq!(result, expected);
1594    }
1595
1596    #[rstest]
1597    fn test_parse_decimal_invalid() {
1598        assert!(parse_decimal("invalid").is_err());
1599        assert!(parse_decimal("").is_err());
1600    }
1601
1602    #[rstest]
1603    #[case(&Some("123.45".to_string()), Some(dec!(123.45)))]
1604    #[case(&Some("0".to_string()), Some(Decimal::ZERO))]
1605    #[case(&Some(String::new()), None)]
1606    #[case(&None, None)]
1607    fn test_parse_optional_decimal(
1608        #[case] input: &Option<String>,
1609        #[case] expected: Option<Decimal>,
1610    ) {
1611        let result = parse_optional_decimal(input).unwrap();
1612        assert_eq!(result, expected);
1613    }
1614
1615    // Tests for flexible decimal deserializers (handles both string and number JSON values)
1616
1617    #[derive(Debug, Serialize, Deserialize, PartialEq)]
1618    struct TestFlexibleDecimal {
1619        #[serde(
1620            serialize_with = "decimal::serialize",
1621            deserialize_with = "deserialize_decimal"
1622        )]
1623        value: Decimal,
1624        #[serde(
1625            serialize_with = "decimal::serialize_optional",
1626            deserialize_with = "deserialize_optional_decimal"
1627        )]
1628        optional_value: Option<Decimal>,
1629    }
1630
1631    #[rstest]
1632    #[case(r#"{"value": 123.456, "optional_value": 789.012}"#, dec!(123.456), Some(dec!(789.012)))]
1633    #[case(r#"{"value": "123.456", "optional_value": "789.012"}"#, dec!(123.456), Some(dec!(789.012)))]
1634    #[case(r#"{"value": 1.25e-3, "optional_value": 2.5e2}"#, dec!(0.00125), Some(dec!(250)))]
1635    #[case(r#"{"value": 100, "optional_value": null}"#, dec!(100), None)]
1636    #[case(r#"{"value": null, "optional_value": null}"#, Decimal::ZERO, None)]
1637    fn test_deserialize_flexible_decimal(
1638        #[case] json: &str,
1639        #[case] expected_value: Decimal,
1640        #[case] expected_optional: Option<Decimal>,
1641    ) {
1642        let result: TestFlexibleDecimal = serde_json::from_str(json).unwrap();
1643        assert_eq!(result.value, expected_value);
1644        assert_eq!(result.optional_value, expected_optional);
1645    }
1646
1647    #[rstest]
1648    fn test_flexible_decimal_roundtrip() {
1649        let original = TestFlexibleDecimal {
1650            value: dec!(123.456),
1651            optional_value: Some(dec!(789.012)),
1652        };
1653
1654        let json = serde_json::to_string(&original).unwrap();
1655        let deserialized: TestFlexibleDecimal = serde_json::from_str(&json).unwrap();
1656
1657        assert_eq!(original.value, deserialized.value);
1658        assert_eq!(original.optional_value, deserialized.optional_value);
1659    }
1660
1661    #[rstest]
1662    fn test_flexible_decimal_scientific_notation() {
1663        // Test that scientific notation from serde_json is handled correctly.
1664        // serde_json outputs very small numbers like 0.00000001 as "1e-8".
1665        // Note: JSON numbers are parsed as f64, so values are limited to ~15 significant digits.
1666        let json = r#"{"value": 0.00000001, "optional_value": 12345678.12345}"#;
1667        let parsed: TestFlexibleDecimal = serde_json::from_str(json).unwrap();
1668        assert_eq!(parsed.value, dec!(0.00000001));
1669        assert_eq!(parsed.optional_value, Some(dec!(12345678.12345)));
1670    }
1671
1672    #[rstest]
1673    fn test_flexible_decimal_empty_string_optional() {
1674        let json = r#"{"value": 100, "optional_value": ""}"#;
1675        let parsed: TestFlexibleDecimal = serde_json::from_str(json).unwrap();
1676        assert_eq!(parsed.value, dec!(100));
1677        assert_eq!(parsed.optional_value, None);
1678    }
1679
1680    #[derive(Debug, Deserialize)]
1681    struct TestDecimalToken {
1682        #[serde(deserialize_with = "deserialize_decimal_token")]
1683        value: Decimal,
1684        #[serde(default, deserialize_with = "deserialize_optional_decimal_token")]
1685        optional_value: Option<Decimal>,
1686    }
1687
1688    #[derive(Debug, Deserialize)]
1689    struct TestDecimalTokenBorrowed {
1690        #[serde(deserialize_with = "deserialize_decimal_token_borrowed")]
1691        value: Decimal,
1692        #[serde(
1693            default,
1694            deserialize_with = "deserialize_optional_decimal_token_borrowed"
1695        )]
1696        optional_value: Option<Decimal>,
1697    }
1698
1699    #[rstest]
1700    #[case(r#"{"value": 100000000.123456789}"#, "100000000.123456789", None)]
1701    #[case(
1702        r#"{"value": 100000000.123456788, "optional_value": null}"#,
1703        "100000000.123456788",
1704        None
1705    )]
1706    #[case(r#"{"value": "0.10", "optional_value": ""}"#, "0.10", None)]
1707    #[case(
1708        r#"{"value": 18446744073709551617, "optional_value": 0.30000000000000004}"#,
1709        "18446744073709551617",
1710        Some("0.30000000000000004")
1711    )]
1712    #[case(
1713        r#"{"value": 1.1403e-4, "optional_value": "2.5e2"}"#,
1714        "0.00011403",
1715        Some("250")
1716    )]
1717    #[case(
1718        r#"{"value": 5.551115123125783e-17}"#,
1719        "0.0000000000000000555111512313",
1720        None
1721    )]
1722    #[case(r#"{"value": 0.00000000000000000000000000001e28}"#, "0.1", None)]
1723    #[case(
1724        r#"{"value": 0.000000000000000000000000000012345678901234567890123456789e28}"#,
1725        "0.1234567890123456789012345679",
1726        None
1727    )]
1728    #[case(
1729        r#"{"value": 0.12345678901234567890123456789}"#,
1730        "0.1234567890123456789012345679",
1731        None
1732    )]
1733    #[case(
1734        r#"{"value": "-7.50", "optional_value": -0.001}"#,
1735        "-7.50",
1736        Some("-0.001")
1737    )]
1738    fn test_deserialize_decimal_token(
1739        #[case] json: &str,
1740        #[case] expected_value: &str,
1741        #[case] expected_optional: Option<&str>,
1742    ) {
1743        let result: TestDecimalToken = serde_json::from_str(json).unwrap();
1744        let borrowed: TestDecimalTokenBorrowed = serde_json::from_str(json).unwrap();
1745
1746        assert_eq!(result.value.to_string(), expected_value);
1747        assert_eq!(
1748            result
1749                .optional_value
1750                .map(|value| value.to_string())
1751                .as_deref(),
1752            expected_optional
1753        );
1754        assert_eq!(borrowed.value.to_string(), expected_value);
1755        assert_eq!(
1756            borrowed
1757                .optional_value
1758                .map(|value| value.to_string())
1759                .as_deref(),
1760            expected_optional
1761        );
1762    }
1763
1764    #[rstest]
1765    fn test_deserialize_decimal_token_keeps_decimals_that_collapse_in_f64() {
1766        let first: TestDecimalToken =
1767            serde_json::from_str(r#"{"value": 100000000.123456789}"#).unwrap();
1768        let second: TestDecimalToken =
1769            serde_json::from_str(r#"{"value": 100000000.123456788}"#).unwrap();
1770        let first_f64 = "100000000.123456789".parse::<f64>().unwrap();
1771        let second_f64 = "100000000.123456788".parse::<f64>().unwrap();
1772
1773        assert_eq!(first_f64.to_bits(), second_f64.to_bits());
1774        assert_eq!(first.value, dec!(100000000.123456789));
1775        assert_eq!(second.value, dec!(100000000.123456788));
1776    }
1777
1778    #[rstest]
1779    #[case(r#"{"value": null}"#)]
1780    #[case(r#"{"value": ""}"#)]
1781    #[case(r#"{"value": "abc"}"#)]
1782    #[case(r#"{"value": true}"#)]
1783    #[case(r#"{"value": {}}"#)]
1784    #[case(r#"{"value": [1]}"#)]
1785    #[case(r#"{"value": 1e400}"#)]
1786    #[case(r#"{"value": 79228162514264337593543950336}"#)]
1787    #[case(r#"{"value": 1, "optional_value": "abc"}"#)]
1788    #[case(r#"{"optional_value": 1}"#)]
1789    fn test_deserialize_decimal_token_rejects_invalid(#[case] json: &str) {
1790        assert!(serde_json::from_str::<TestDecimalToken>(json).is_err());
1791        assert!(serde_json::from_str::<TestDecimalTokenBorrowed>(json).is_err());
1792    }
1793
1794    #[rstest]
1795    fn test_deserialize_decimal_token_borrowed_requires_borrowed_input() {
1796        let json = r#"{"value": 1.25}"#;
1797        let value: serde_json::Value = serde_json::from_str(json).unwrap();
1798
1799        let from_slice: TestDecimalTokenBorrowed = serde_json::from_slice(json.as_bytes()).unwrap();
1800        let from_reader =
1801            serde_json::from_reader::<_, TestDecimalTokenBorrowed>(json.as_bytes()).unwrap_err();
1802        let from_value = serde_json::from_value::<TestDecimalTokenBorrowed>(value).unwrap_err();
1803
1804        assert_eq!(from_slice.value, dec!(1.25));
1805        assert_eq!(
1806            from_reader.to_string(),
1807            "invalid type: string \"1.25\", expected raw value at line 1 column 15"
1808        );
1809        assert_eq!(
1810            from_value.to_string(),
1811            "invalid type: string \"1.25\", expected raw value"
1812        );
1813    }
1814
1815    #[rstest]
1816    fn test_deserialize_decimal_token_buffered_value_renders_number() {
1817        let value = json!({"value": 65000.5, "optional_value": "0.10"});
1818
1819        let result: TestDecimalToken = serde_json::from_value(value).unwrap();
1820
1821        assert_eq!(result.value.to_string(), "65000.5");
1822        assert_eq!(
1823            result
1824                .optional_value
1825                .map(|value| value.to_string())
1826                .as_deref(),
1827            Some("0.10")
1828        );
1829    }
1830
1831    #[rstest]
1832    fn test_deserialize_decimal_token_rejects_tagged_enum_buffer() {
1833        #[derive(Debug, Deserialize)]
1834        #[serde(tag = "type")]
1835        #[allow(dead_code, reason = "the test only checks that decoding fails")]
1836        enum Tagged {
1837            Token(TestDecimalToken),
1838        }
1839
1840        let result = serde_json::from_str::<Tagged>(r#"{"type": "Token", "value": 1.5}"#);
1841
1842        assert!(result.is_err());
1843    }
1844
1845    // Additional tests for DecimalVisitor edge cases
1846
1847    #[derive(Debug, Deserialize)]
1848    struct TestDecimalOnly {
1849        #[serde(deserialize_with = "deserialize_decimal")]
1850        value: Decimal,
1851    }
1852
1853    #[rstest]
1854    #[case("0.12345678901234567890123456789e1", dec!(1.2345678901234567890123456789))]
1855    #[case("-0.12345678901234567890123456789E1", dec!(-1.2345678901234567890123456789))]
1856    #[case("0.00000000000000000000000000001e1", dec!(0.0000000000000000000000000001))]
1857    fn test_deserialize_decimal_scientific_representable(
1858        #[case] value: &str,
1859        #[case] expected: Decimal,
1860        #[values(false, true)] optional: bool,
1861    ) {
1862        let json = serde_json::to_string(&json!({"value": value})).unwrap();
1863
1864        let actual = if optional {
1865            serde_json::from_str::<TestOptionalDecimalOnly>(&json)
1866                .unwrap()
1867                .value
1868        } else {
1869            Some(
1870                serde_json::from_str::<TestDecimalOnly>(&json)
1871                    .unwrap()
1872                    .value,
1873            )
1874        };
1875
1876        assert_eq!(actual, Some(expected));
1877    }
1878
1879    #[rstest]
1880    #[case(23, 28, 23)]
1881    #[case(24, 29, 0)]
1882    fn test_deserialize_decimal_scientific_length_boundary(
1883        #[case] zeros: usize,
1884        #[case] length: usize,
1885        #[case] scale: u32,
1886    ) {
1887        let value = format!("1.5{}e1", "0".repeat(zeros));
1888        let json = serde_json::to_string(&json!({"value": value})).unwrap();
1889        let required: TestDecimalOnly = serde_json::from_str(&json).unwrap();
1890        let optional: TestOptionalDecimalOnly = serde_json::from_str(&json).unwrap();
1891
1892        assert_eq!(value.len(), length);
1893        assert_eq!(required.value, dec!(15));
1894        assert_eq!(required.value.scale(), scale);
1895        assert_eq!(optional.value, Some(dec!(15)));
1896        assert_eq!(optional.value.unwrap().scale(), scale);
1897    }
1898
1899    #[rstest]
1900    #[case(".1e-2147483648")]
1901    #[case("-.1E-2147483648")]
1902    #[case("+.1e-2147483648")]
1903    fn test_deserialize_decimal_rejects_min_exponent(
1904        #[case] value: &str,
1905        #[values("visitor", "token", "token_borrowed")] route: &str,
1906        #[values(false, true)] optional: bool,
1907    ) {
1908        let json = serde_json::to_string(value).unwrap();
1909        let mut deserializer = serde_json::Deserializer::from_str(&json);
1910        let result = match (route, optional) {
1911            ("visitor", false) => deserialize_decimal(&mut deserializer).map(Some),
1912            ("visitor", true) => deserialize_optional_decimal(&mut deserializer),
1913            ("token", false) => deserialize_decimal_token(&mut deserializer).map(Some),
1914            ("token", true) => deserialize_optional_decimal_token(&mut deserializer),
1915            ("token_borrowed", false) => {
1916                deserialize_decimal_token_borrowed(&mut deserializer).map(Some)
1917            }
1918            ("token_borrowed", true) => {
1919                deserialize_optional_decimal_token_borrowed(&mut deserializer)
1920            }
1921            _ => unreachable!(),
1922        };
1923
1924        let error = result.unwrap_err();
1925        let expected = "Scale exceeds the maximum precision allowed: 2147483648 > 28";
1926
1927        assert_eq!(error.classify(), serde_json::error::Category::Data);
1928        assert_eq!(error.to_string().split(" at line ").next(), Some(expected));
1929    }
1930
1931    #[rstest]
1932    #[case(r#"{"value": "1.5e-8"}"#, dec!(0.000000015))]
1933    #[case(r#"{"value": "1E10"}"#, dec!(10000000000))]
1934    #[case(r#"{"value": "-1.23e5"}"#, dec!(-123000))]
1935    fn test_deserialize_decimal_scientific_string(#[case] json: &str, #[case] expected: Decimal) {
1936        let result: TestDecimalOnly = serde_json::from_str(json).unwrap();
1937        assert_eq!(result.value, expected);
1938    }
1939
1940    #[rstest]
1941    #[case(r#"{"value": 9223372036854775807}"#, dec!(9223372036854775807))] // i64::MAX
1942    #[case(r#"{"value": -9223372036854775808}"#, dec!(-9223372036854775808))] // i64::MIN
1943    #[case(r#"{"value": 0}"#, Decimal::ZERO)]
1944    fn test_deserialize_decimal_large_integers(#[case] json: &str, #[case] expected: Decimal) {
1945        let result: TestDecimalOnly = serde_json::from_str(json).unwrap();
1946        assert_eq!(result.value, expected);
1947    }
1948
1949    #[rstest]
1950    #[case(r#"{"value": "-123.456789"}"#, dec!(-123.456789))]
1951    #[case(r#"{"value": -999.99}"#, dec!(-999.99))]
1952    fn test_deserialize_decimal_negative(#[case] json: &str, #[case] expected: Decimal) {
1953        let result: TestDecimalOnly = serde_json::from_str(json).unwrap();
1954        assert_eq!(result.value, expected);
1955    }
1956
1957    #[rstest]
1958    #[case(r#"{"value": "123456789.123456789012345678"}"#)] // High precision string
1959    fn test_deserialize_decimal_high_precision(#[case] json: &str) {
1960        let result: TestDecimalOnly = serde_json::from_str(json).unwrap();
1961        assert_eq!(result.value, dec!(123456789.123456789012345678));
1962    }
1963
1964    #[rstest]
1965    #[case(
1966        r#"{"value": "1.234567890123456789012345678912345e-1"}"#,
1967        "0.1234567890123456789012345679"
1968    )]
1969    #[case(
1970        r#"{"value": "0.1234567890123456789012345678912345"}"#,
1971        "0.1234567890123456789012345679"
1972    )]
1973    #[case(
1974        r#"{"value": "999999999999999999999999999995e-29"}"#,
1975        "10.000000000000000000000000000"
1976    )]
1977    #[case(r#"{"value": "0.5e29"}"#, "50000000000000000000000000000")]
1978    #[case(r#"{"value": "-4e-29"}"#, "0.0000000000000000000000000000")]
1979    #[case(r#"{"value": "1.5e-999999"}"#, "0.0000000000000000000000000000")]
1980    #[case(r#"{"value": "9e-999999"}"#, "0.0000000000000000000000000000")]
1981    #[case(r#"{"value": "0e2000000000"}"#, "0")]
1982    fn test_deserialize_decimal_rounds_high_scale_values(
1983        #[case] json: &str,
1984        #[case] expected: &str,
1985    ) {
1986        // Carries propagate and a rounded-away negative loses its sign.
1987        let result: TestDecimalOnly = serde_json::from_str(json).unwrap();
1988        assert_eq!(result.value.to_string(), expected);
1989    }
1990
1991    #[rstest]
1992    #[rstest]
1993    fn test_deserialize_decimal_negative_rounding_to_zero_loses_sign() {
1994        let json = r#"{"value": "-1.5e-999999"}"#;
1995        let result: TestDecimalOnly = serde_json::from_str(json).unwrap();
1996        assert_eq!(result.value.to_string(), "0.0000000000000000000000000000");
1997    }
1998
1999    #[rstest]
2000    #[case(r#"{"value": "899999999999999999999999999995e-29"}"#)]
2001    #[case(r#"{"value": "+899999999999999999999999999995e-29"}"#)]
2002    fn test_deserialize_decimal_rounding_carries_into_integer(#[case] json: &str) {
2003        // Thirty-digit mantissas fail scientific parsing and round up into a non-nine digit
2004        let result: TestDecimalOnly = serde_json::from_str(json).unwrap();
2005        assert_eq!(result.value.to_string(), "9.000000000000000000000000000");
2006    }
2007
2008    #[rstest]
2009    #[case(r#"{"value": "8e28"}"#)] // above Decimal::MAX
2010    #[case(r#"{"value": "1e1000000000"}"#)] // absurd exponent must fail without expansion
2011    #[case(r#"{"value": {"number": "1.5"}}"#)]
2012    #[case(r#"{"value": "not-a-number"}"#)]
2013    #[case(r#"{"value": "1.2.3e1"}"#)] // multiple decimal points
2014    #[case(r#"{"value": ".e1"}"#)] // empty coefficient
2015    fn test_deserialize_decimal_rejects_unrepresentable_values(#[case] json: &str) {
2016        // The fallback rounds fractional digits only; oversized magnitudes
2017        // keep their original parse error.
2018        let result: Result<TestDecimalOnly, _> = serde_json::from_str(json);
2019        assert!(result.is_err());
2020    }
2021
2022    #[rstest]
2023    fn test_deserialize_optional_decimal_rounds_high_scale_values() {
2024        let json = r#"{"value": "51.234567890123456789012345678912345e-1"}"#;
2025        let result: TestOptionalDecimalOnly = serde_json::from_str(json).unwrap();
2026        assert_eq!(
2027            result.value.map(|v| v.to_string()),
2028            Some("5.1234567890123456789012345679".into()),
2029        );
2030    }
2031
2032    #[derive(Debug, Deserialize)]
2033    struct TestOptionalDecimalOnly {
2034        #[serde(deserialize_with = "deserialize_optional_decimal")]
2035        value: Option<Decimal>,
2036    }
2037
2038    #[rstest]
2039    #[case(r#"{"value": "1.5e-8"}"#, Some(dec!(0.000000015)))]
2040    #[case(r#"{"value": null}"#, None)]
2041    #[case(r#"{"value": ""}"#, None)]
2042    #[case(r#"{"value": 42}"#, Some(dec!(42)))]
2043    #[case(r#"{"value": -100.5}"#, Some(dec!(-100.5)))]
2044    fn test_deserialize_optional_decimal_various(
2045        #[case] json: &str,
2046        #[case] expected: Option<Decimal>,
2047    ) {
2048        let result: TestOptionalDecimalOnly = serde_json::from_str(json).unwrap();
2049        assert_eq!(result.value, expected);
2050    }
2051
2052    #[rstest]
2053    fn test_decimal_visitor_direct_owned_and_wide_integer_paths() {
2054        assert_eq!(
2055            DecimalVisitor
2056                .visit_string::<ValueError>("1.5".to_string())
2057                .unwrap(),
2058            dec!(1.5)
2059        );
2060        assert_eq!(
2061            DecimalVisitor.visit_i128::<ValueError>(5).unwrap(),
2062            Decimal::from(5i128)
2063        );
2064        assert_eq!(
2065            DecimalVisitor.visit_u128::<ValueError>(5).unwrap(),
2066            Decimal::from(5u128)
2067        );
2068        assert_eq!(
2069            DecimalVisitor.visit_none::<ValueError>().unwrap(),
2070            Decimal::ZERO
2071        );
2072    }
2073
2074    #[rstest]
2075    fn test_decimal_visitor_rejects_non_finite_float() {
2076        assert!(
2077            DecimalVisitor
2078                .visit_f64::<ValueError>(f64::INFINITY)
2079                .is_err()
2080        );
2081        assert!(
2082            DecimalVisitor
2083                .visit_f64::<ValueError>(f64::NEG_INFINITY)
2084                .is_err()
2085        );
2086        assert!(DecimalVisitor.visit_f64::<ValueError>(f64::NAN).is_err());
2087    }
2088
2089    #[rstest]
2090    fn test_optional_decimal_visitor_direct_paths() {
2091        assert_eq!(
2092            OptionalDecimalVisitor
2093                .visit_string::<ValueError>("1.5".to_string())
2094                .unwrap(),
2095            Some(dec!(1.5))
2096        );
2097        assert_eq!(
2098            OptionalDecimalVisitor.visit_i64::<ValueError>(42).unwrap(),
2099            Some(dec!(42))
2100        );
2101        assert_eq!(
2102            OptionalDecimalVisitor.visit_i128::<ValueError>(5).unwrap(),
2103            Some(Decimal::from(5i128))
2104        );
2105        assert_eq!(
2106            OptionalDecimalVisitor.visit_u128::<ValueError>(5).unwrap(),
2107            Some(Decimal::from(5u128))
2108        );
2109        assert_eq!(
2110            OptionalDecimalVisitor.visit_none::<ValueError>().unwrap(),
2111            None
2112        );
2113    }
2114
2115    #[rstest]
2116    fn test_serialize_optional_decimal_none_serializes_null() {
2117        let original = TestFlexibleDecimal {
2118            value: dec!(1),
2119            optional_value: None,
2120        };
2121
2122        let json = serde_json::to_string(&original).unwrap();
2123        let parsed: serde_json::Value = serde_json::from_str(&json).unwrap();
2124        assert_eq!(parsed["optional_value"], json!(null));
2125    }
2126
2127    #[rstest]
2128    fn test_serde_bool_defaults() {
2129        assert!(default_true());
2130        assert!(!default_false());
2131    }
2132
2133    use proptest::prelude::*;
2134    use rust_decimal::prelude::ToPrimitive;
2135
2136    fn representable_decimal_strategy() -> impl Strategy<Value = Decimal> {
2137        // Mantissa spans Decimal's full 96-bit range; every generated value is
2138        // exactly representable.
2139        (
2140            -79_228_162_514_264_337_593_543_950_335i128
2141                ..=79_228_162_514_264_337_593_543_950_335i128,
2142            0u32..=28u32,
2143        )
2144            .prop_map(|(mantissa, scale)| Decimal::from_i128_with_scale(mantissa, scale))
2145    }
2146
2147    fn numeric_string_strategy() -> impl Strategy<Value = String> {
2148        // Signed digit strings with long fractions and exponents, covering
2149        // both natively-parsed shapes and the high-scale clamp fallback.
2150        (
2151            proptest::bool::ANY,
2152            "[0-9]{1,30}",
2153            proptest::option::of("[0-9]{1,40}"),
2154            proptest::option::of(-40i32..=40),
2155        )
2156            .prop_map(|(negative, integer, fraction, exponent)| {
2157                let mut value = String::new();
2158                if negative {
2159                    value.push('-');
2160                }
2161                value.push_str(&integer);
2162                if let Some(fraction) = fraction {
2163                    value.push('.');
2164                    value.push_str(&fraction);
2165                }
2166
2167                if let Some(exponent) = exponent {
2168                    value.push('e');
2169                    value.push_str(&exponent.to_string());
2170                }
2171                value
2172            })
2173    }
2174
2175    proptest! {
2176        #[rstest]
2177        fn prop_deserialize_decimal_scientific_roundtrips_representable_values(
2178            expected in representable_decimal_strategy(),
2179            zeros in 0usize..=35,
2180        ) {
2181            let scientific = format!(
2182                "{}{}e-{}",
2183                expected.mantissa(),
2184                "0".repeat(zeros),
2185                expected.scale() as usize + zeros,
2186            );
2187            let json = serde_json::to_string(&json!({"value": scientific})).unwrap();
2188            let required: TestDecimalOnly = serde_json::from_str(&json).unwrap();
2189            let optional: TestOptionalDecimalOnly = serde_json::from_str(&json).unwrap();
2190
2191            prop_assert_eq!(required.value, expected);
2192            prop_assert_eq!(optional.value, Some(expected));
2193        }
2194
2195        #[rstest]
2196        fn prop_deserialize_decimal_roundtrips_representable_values(
2197            expected in representable_decimal_strategy()
2198        ) {
2199            // The clamp fallback must never distort a value Decimal can hold
2200            // exactly.
2201            let json = format!(r#"{{"value": "{expected}"}}"#);
2202            let parsed: TestDecimalOnly = serde_json::from_str(&json).unwrap();
2203            prop_assert_eq!(parsed.value, expected);
2204        }
2205
2206        #[rstest]
2207        fn prop_deserialize_decimal_total_on_arbitrary_strings(value in "\\PC{0,64}") {
2208            // Any string input must decode or error without panicking.
2209            let json = serde_json::to_string(&serde_json::json!({"value": value})).unwrap();
2210            let _ = serde_json::from_str::<TestDecimalOnly>(&json);
2211        }
2212
2213        #[rstest]
2214        fn prop_deserialize_decimal_tracks_f64_reference(value in numeric_string_strategy()) {
2215            // Accepted values (rounded or not) must agree with an independent
2216            // f64 parse of the same string within f64 precision.
2217            let json = format!(r#"{{"value": "{value}"}}"#);
2218            if let Ok(parsed) = serde_json::from_str::<TestDecimalOnly>(&json) {
2219                let reference: f64 = value.parse().unwrap();
2220                let decoded = parsed.value.to_f64().unwrap();
2221                prop_assert!(
2222                    (decoded - reference).abs() <= reference.abs() * 1e-9 + 1e-27,
2223                    "decoded {decoded} diverges from reference {reference} for input {value}",
2224                );
2225            }
2226        }
2227
2228        #[rstest]
2229        fn prop_deserialize_optional_decimal_matches_required(
2230            value in numeric_string_strategy()
2231        ) {
2232            let json = format!(r#"{{"value": "{value}"}}"#);
2233            let required = serde_json::from_str::<TestDecimalOnly>(&json);
2234            let optional = serde_json::from_str::<TestOptionalDecimalOnly>(&json);
2235            match (required, optional) {
2236                (Ok(required), Ok(optional)) => {
2237                    prop_assert_eq!(optional.value, Some(required.value));
2238                }
2239                (Err(_), Err(_)) => {}
2240                (required, optional) => prop_assert!(
2241                    false,
2242                    "required and optional decoding disagree for input {}: {:?} vs {:?}",
2243                    value,
2244                    required.map(|r| r.value),
2245                    optional.map(|o| o.value),
2246                ),
2247            }
2248        }
2249    }
2250
2251    #[derive(Debug, Deserialize)]
2252    struct Token(#[serde(deserialize_with = "deserialize_decimal_token_borrowed")] Decimal);
2253
2254    #[rstest]
2255    #[case(r#""1.2300""#, 12300, 4)]
2256    #[case(r#""\u0031.2300""#, 12300, 4)]
2257    #[case(r#""1.2300\u0030""#, 123_000, 5)]
2258    #[case(r#""-0.00001000""#, -1000, 8)]
2259    #[case("9007199254740993", 9_007_199_254_740_993, 0)]
2260    #[case("18446744073709551617", 18_446_744_073_709_551_617, 0)]
2261    fn test_decimal_token_preserves_digits_and_scale(
2262        #[case] json: &str,
2263        #[case] mantissa: i128,
2264        #[case] scale: u32,
2265    ) {
2266        let value = serde_json::from_str::<Token>(json).unwrap().0;
2267        assert_eq!(value.mantissa(), mantissa);
2268        assert_eq!(value.scale(), scale);
2269    }
2270
2271    #[rstest]
2272    #[case(r#""\uD800""#)]
2273    #[case(r#""\uDC00""#)]
2274    #[case(r#""\q""#)]
2275    #[case(r#""1.2\n3""#)]
2276    #[case(r#""1.2\"3""#)]
2277    fn test_decimal_token_rejects_invalid_strings(#[case] json: &str) {
2278        assert!(serde_json::from_str::<Token>(json).is_err());
2279    }
2280}