feat: preserve_order feature

Cargo.toml

@@ -17,6 +17,7 @@ json = ["serde_json"]
 yaml = ["serde_yaml"]
 parse-value = ["pear"]
 test = ["tempfile", "parking_lot"]
+preserve_order = ["indexmap", "toml?/preserve_order", "serde_json?/preserve_order"]
 # toml = ["toml"]
 
 [dependencies]
@@ -28,6 +29,7 @@ serde_json = { version = "1.0", optional = true }
 serde_yaml = { version = "0.9", optional = true }
 tempfile = { version = "3", optional = true }
 parking_lot = { version = "0.12", optional = true }
+indexmap = { version = "2.1.0", features = ["serde"], optional = true }
 
 [target.'cfg(any(target_pointer_width = "8", target_pointer_width = "16", target_pointer_width = "32"))'.dependencies]
 atomic = "0.6.0"

src/lib.rs

@@ -292,14 +292,15 @@
 //! To help with compilation times, types, modules, and providers are gated by
 //! features. They are:
 //!
-//! | feature | gated namespace             | description                               |
-//! |---------|-----------------------------|-------------------------------------------|
-//! | `test`  | [`Jail`]                    | Semi-sandboxed environment for testing.   |
-//! | `env`   | [`providers::Env`]          | Environment variable [`Provider`].        |
-//! | `toml`  | [`providers::Toml`]         | TOML file/string [`Provider`].            |
-//! | `json`  | [`providers::Json`]         | JSON file/string [`Provider`].            |
-//! | `yaml`  | [`providers::Yaml`]         | YAML file/string [`Provider`].            |
-//! | `yaml`  | [`providers::YamlExtended`] | [YAML Extended] file/string [`Provider`]. |
+//! | feature          | gated namespace             | description                                                                |
+//! |------------------|-----------------------------|----------------------------------------------------------------------------|
+//! | `test`           | [`Jail`]                    | Semi-sandboxed environment for testing.                                    |
+//! | `env`            | [`providers::Env`]          | Environment variable [`Provider`].                                         |
+//! | `toml`           | [`providers::Toml`]         | TOML file/string [`Provider`].                                             |
+//! | `json`           | [`providers::Json`]         | JSON file/string [`Provider`].                                             |
+//! | `yaml`           | [`providers::Yaml`]         | YAML file/string [`Provider`].                                             |
+//! | `yaml`           | [`providers::YamlExtended`] | [YAML Extended] file/string [`Provider`].                                  |
+//! | `preserve_order` | nil                         | Preserve map order by using [IndexMap](https://github.com/bluss/indexmap). |
 //!
 //! [YAML Extended]: providers::YamlExtended::from_str()
 //!

src/value/de.rs

@@ -121,7 +121,10 @@ impl<'de: 'c, 'c> Deserializer<'de> for ConfiguredValueDe<'c> {
     }
 }
 
+#[cfg(not(feature = "preserve_order"))]
 use std::collections::btree_map::Iter;
+#[cfg(feature = "preserve_order")]
+use indexmap::map::Iter;
 
 pub struct MapDe<'m, D, F: Fn(&'m Value) -> D> {
     iter: Iter<'m, String, Value>,

src/value/value.rs

@@ -1,14 +1,19 @@
 use std::str::Split;
-use std::collections::BTreeMap;
-
 use serde::Serialize;
+#[cfg(not(feature = "preserve_order"))]
+use std::collections::BTreeMap;
 
 use crate::value::{Tag, ValueSerializer};
 use crate::error::{Error, Actual};
 
 /// An alias to the type of map used in [`Value::Dict`].
+#[cfg(not(feature = "preserve_order"))]
 pub type Map<K, V> = BTreeMap<K, V>;
 
+/// An alias to the type of map used in [`Value::Dict`].
+#[cfg(feature = "preserve_order")]
+pub type Map<K, V> = indexmap::IndexMap<K, V>;
+
 /// An alias to a [`Map`] from `String` to [`Value`]s.
 pub type Dict = Map<String, Value>;