compress_json_rs/
config.rs

1//! Configuration options for compression behavior.
2//!
3//! This module provides the [`Config`] struct and the global [`CONFIG`] constant
4//! that controls how JSON values are compressed.
5//!
6//! # Current Limitations
7//!
8//! Configuration is currently compile-time only via the [`CONFIG`] constant.
9//! Runtime configuration may be added in future versions.
10//!
11//! # Example
12//!
13//! ```rust
14//! use compress_json_rs::CONFIG;
15//!
16//! // Check current configuration
17//! println!("Sort keys: {}", CONFIG.sort_key);
18//! println!("Preserve NaN: {}", CONFIG.preserve_nan);
19//! println!("Preserve Infinity: {}", CONFIG.preserve_infinite);
20//! ```
21
22/// Global configuration for compression behavior.
23///
24/// This struct defines options that control how JSON values are processed
25/// during compression. The library uses a compile-time constant [`CONFIG`]
26/// with these settings.
27///
28/// # Fields
29///
30/// | Field | Default | Description |
31/// |-------|---------|-------------|
32/// | `sort_key` | `false` | Sort object keys alphabetically |
33/// | `preserve_nan` | `false` | Encode NaN as `N\|0` (vs convert to null) |
34/// | `error_on_nan` | `false` | Panic on NaN (only if `preserve_nan` is false) |
35/// | `preserve_infinite` | `false` | Encode Infinity as `N\|+`/`N\|-` (vs convert to null) |
36/// | `error_on_infinite` | `false` | Panic on Infinity (only if `preserve_infinite` is false) |
37///
38/// # Key Sorting
39///
40/// When `sort_key` is `true`, object keys are sorted alphabetically before
41/// compression. This ensures consistent output regardless of insertion order,
42/// which is useful for:
43/// - Deterministic compression output
44/// - Easier diff comparison
45/// - Consistent hashing of compressed data
46///
47/// # Special Number Handling (v3.4.0+)
48///
49/// JSON doesn't support `NaN` or `Infinity`. The handling depends on config:
50///
51/// | Value | `preserve_*` = true | `preserve_*` = false, `error_*` = true | Both false |
52/// |-------|---------------------|----------------------------------------|------------|
53/// | NaN | Encoded as `N\|0` | Panic | Becomes `null` |
54/// | Infinity | Encoded as `N\|+` | Panic | Becomes `null` |
55/// | -Infinity | Encoded as `N\|-` | Panic | Becomes `null` |
56///
57/// Note: `error_on_nan` and `error_on_infinite` only take effect when
58/// their corresponding `preserve_*` option is `false`.
59///
60/// # Example
61///
62/// ```rust
63/// use compress_json_rs::{Config, CONFIG};
64///
65/// // View the default configuration
66/// assert_eq!(CONFIG.sort_key, false);
67/// assert_eq!(CONFIG.preserve_nan, false);
68/// assert_eq!(CONFIG.error_on_nan, false);
69/// assert_eq!(CONFIG.preserve_infinite, false);
70/// assert_eq!(CONFIG.error_on_infinite, false);
71/// ```
72#[derive(Debug, Copy, Clone, PartialEq, Eq)]
73pub struct Config {
74    /// Whether to sort object keys alphabetically.
75    ///
76    /// When `true`, object keys are sorted before compression, ensuring
77    /// consistent output regardless of key insertion order.
78    ///
79    /// **Default:** `false`
80    pub sort_key: bool,
81
82    /// Whether to preserve NaN values with special encoding.
83    ///
84    /// When `true`, NaN values are encoded as `N|0` for cross-platform
85    /// compatibility with JavaScript/Python implementations.
86    /// When `false`, NaN is converted to `null` (like `JSON.stringify`).
87    ///
88    /// **Default:** `false`
89    ///
90    /// **Added in:** v3.4.0
91    pub preserve_nan: bool,
92
93    /// Whether to panic when encountering NaN values.
94    ///
95    /// Only effective when `preserve_nan` is `false`.
96    /// When `true`, the library will panic if a NaN is encountered.
97    /// When `false`, NaN is silently converted to `null`.
98    ///
99    /// **Default:** `false`
100    pub error_on_nan: bool,
101
102    /// Whether to preserve infinite values with special encoding.
103    ///
104    /// When `true`, `Infinity` and `-Infinity` are encoded as `N|+` and `N|-`
105    /// for cross-platform compatibility with JavaScript/Python implementations.
106    /// When `false`, infinite values are converted to `null` (like `JSON.stringify`).
107    ///
108    /// **Default:** `false`
109    ///
110    /// **Added in:** v3.4.0
111    pub preserve_infinite: bool,
112
113    /// Whether to panic when encountering infinite values.
114    ///
115    /// Only effective when `preserve_infinite` is `false`.
116    /// When `true`, the library will panic if `Infinity` or `-Infinity` is encountered.
117    /// When `false`, infinite values are silently converted to `null`.
118    ///
119    /// **Default:** `false`
120    pub error_on_infinite: bool,
121}
122
123/// Default configuration matching the TypeScript implementation.
124///
125/// This constant provides the default behavior for compression:
126/// - Object keys maintain their original order
127/// - NaN values become `null` (like `JSON.stringify`)
128/// - Infinity values become `null` (like `JSON.stringify`)
129///
130/// To preserve special values, set `preserve_nan` and/or `preserve_infinite` to `true`.
131///
132/// # Values
133///
134/// ```rust
135/// use compress_json_rs::CONFIG;
136///
137/// // All options default to false
138/// assert!(!CONFIG.sort_key);
139/// assert!(!CONFIG.preserve_nan);
140/// assert!(!CONFIG.error_on_nan);
141/// assert!(!CONFIG.preserve_infinite);
142/// assert!(!CONFIG.error_on_infinite);
143/// ```
144///
145/// # Compatibility
146///
147/// These defaults match the JavaScript [compress-json](https://github.com/beenotung/compress-json)
148/// library v3.4.0+, ensuring cross-platform compatibility.
149pub const CONFIG: Config = Config {
150    sort_key: false,
151    preserve_nan: false,
152    error_on_nan: false,
153    preserve_infinite: false,
154    error_on_infinite: false,
155};
compress_json_rs/config.rs

compress_json_rs/
config.rs
