Merge pull request #5 from meilisearch/fix-bug-with-empty-vec

Rewrite everything

Author: irevoire

Cargo.toml

@@ -1,19 +1,22 @@
 [package]
 name = "yaup"
-version = "0.2.1"
-authors = ["boxdot <[email protected]>, tamo <[email protected]>"]
+version = "0.3.0"
+authors = ["tamo <[email protected]>"]
 license = "MIT/Apache-2.0"
 description = "URL parameters serialization"
-repository = "https://github.com/irevoire/yaup"
-keywords = ["serde", "serialization", "url"]
+repository = "https://github.com/meilisearch/yaup"
+keywords = ["serde", "serialization", "url", "meilisearch"]
 categories = ["encoding"]
 readme = "README.md"
 include = ["Cargo.toml", "src/**/*.rs", "README.md", "LICENSE-APACHE", "LICENSE-MIT"]
 edition = "2021"
 
 [dependencies]
 serde = "1"
-url = "2"
+form_urlencoded = "1.2.1"
+thiserror = "1.0.61"
 
 [dev-dependencies]
+insta = "1.39.0"
+maplit = "1.0.2"
 serde = { version = "1", features = ["derive"] }

README.md

@@ -1,20 +1,22 @@
 # Yaup - Yet Another URL Params crate
 
-This is a fork of [`serde_url_params`](https://github.com/boxdot/serde-url-params-rs).
-I updated the way of serializing arrays:
-Serializing `{ "food": ["baguette", "with", "cheese"] }`
-- With `serde_url_params` returns `food=baguette&food=with&food=cheese`.
-- With `yaup` it returns `food=baguette,with,cheese`.
+Serialize your structures as query parameters.
+I made this crate because I didn't find anything that matched the structure of the query parameters used in Meilisearch.
 
-And I got rids of the serialization of embedded structures.
+Specificities of this query parameters format:
+- The crate writes the initial `?` if there are parameters to send.
+- You can only serialize structures that follow a "key-value" shape, like structures, `HashMap`, `BTreeMap`, etc.
+- Sequences (arrays, vectors, tuples, etc) are comma-separated. `{ doggo: vec!["kefir", "echo"] }` serialize as `?doggo=kefir,echo`.
+- Empty and `null` values are not ignored. `{ doggo: Vec::new(), catto: None }` serialize as `?doggo=&catto=null`. 
+- Return an error if you try to serialize a structure with multiple levels of key-value structures (i.e., an object containing a `HashMap` for example).
 
 ## Example
 
 ```rust
-#[derive(Debug, Serialize)]
+#[derive(Debug, serde::Serialize)]
 enum Filter { New, Registered, Blocked }
 
-#[derive(Debug, Serialize)]
+#[derive(Debug, serde::Serialize)]
 struct Params {
     cursor: Option<usize>,
     per_page: Option<usize>,
@@ -30,16 +32,22 @@ let params = Params {
 };
 assert_eq!(
     yaup::to_string(&params).unwrap(),
-    "cursor=42&username=boxdot&filter=New,Blocked"
+    "?cursor=42&per_page=null&username=tamo&filter=New,Blocked"
 );
 ```
+## Thanks
+
+This was originally a fork of [`serde_url_params`](https://github.com/boxdot/serde-url-params-rs) which is still maintained.
+Thanks, `boxdot`, for the initial code.
+
+Everything has been rewritten from scratch for the v0.3.0.
 
 ## License
 
  * Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or
-   http://www.apache.org/licenses/LICENSE-2.0)
+   <http://www.apache.org/licenses/LICENSE-2.0>)
  * MIT License ([LICENSE-MIT](LICENSE-MIT) or
-   http://opensource.org/licenses/MIT)
+   <http://opensource.org/licenses/MIT>)
 
 ### Contribution
 

src/error.rs

@@ -1,47 +1,25 @@
 //! When serializing to URL parameters fails.
 
-use serde::ser;
-use std::fmt;
-
-#[derive(Debug)]
+#[derive(Debug, thiserror::Error)]
 /// Represents all possible errors that can occur when serializing into URL
 /// parameters.
 pub enum Error {
     /// External error caused by e.g. utf8 string conversion or io.
+    #[error(transparent)]
     Extern(Box<dyn std::error::Error + Send + Sync>),
-    /// Error when tried to serialize an unsupported type.
-    Unsupported(String),
-    /// Custom error caused by any error while serializing a type.
+    /// Error when trying to serialize a value without any key.
+    #[error("Tried to serialize a {0} at the top level. Only key-value shapes are supported at the top level of a query parameter.")]
+    UnsupportedAtTopLevel(&'static str),
+    /// Error when trying to serialize a key-value in place of a simple value.
+    #[error("Tried to serialize a {0} in place of a value. Only simple values are supported on the right-hand side of a parameter.")]
+    UnsupportedNestedStruct(&'static str),
+    /// Custom user defined error
+    #[error("{0}")]
     Custom(String),
 }
 
 /// Alias for `Result` with error type `serde_url_params::Error`.
-pub type Result<T> = std::result::Result<T, Error>;
-
-impl Error {
-    /// Creates a new error when a type is not supported for serializing into
-    /// URL parameters.
-    pub fn unsupported<T: fmt::Display>(msg: T) -> Self {
-        Error::Unsupported(format!("{}", msg))
-    }
-}
-
-impl fmt::Display for Error {
-    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
-        match *self {
-            Error::Extern(ref err) => fmt::Display::fmt(err, f),
-            Error::Unsupported(ref msg) | Error::Custom(ref msg) => fmt::Display::fmt(msg, f),
-        }
-    }
-}
-
-impl std::error::Error for Error {}
-
-impl ser::Error for Error {
-    fn custom<T: fmt::Display>(msg: T) -> Error {
-        Error::Custom(msg.to_string())
-    }
-}
+pub type Result<T, E = Error> = std::result::Result<T, E>;
 
 impl From<std::io::Error> for Error {
     fn from(err: std::io::Error) -> Self {
@@ -54,3 +32,12 @@ impl From<std::string::FromUtf8Error> for Error {
         Error::Extern(Box::new(err))
     }
 }
+
+impl serde::ser::Error for Error {
+    fn custom<T>(msg: T) -> Self
+    where
+        T: std::fmt::Display,
+    {
+        Error::Custom(msg.to_string())
+    }
+}