Introduces the FromQuery and IntoQuery traits.

[xfbs]

Introduces the FromQuery and IntoQuery traits to allow for customizing how query strings are encoded and decoded. Introduces the

• This PR is related to issue gloo-histroy Support custom query decoder / encoder #362.
• I have taken care to make sure that this PR does not break any consumers of this crate.

Because this PR introduces quite a few new things, allow me to walk through it an explain what is happening here.

Query Encoding

Previous Behaviour

The History trait has some methods that allow specifying a query parameter. This query parameter must implement Serialize. It is encoded using serde_urlencoded. These return a HistoryResult<()>, which expands to a Result<(), HistoryError>.

impl History {
    fn push_with_query<'a, Q>(&self, route: impl Into<Cow<'a, str>>, query: Q) -> HistoryResult<()>
        where Q: Serialize;
    fn replace_with_query<'a, Q>(&self, route: impl Into<Cow<'a, str>>, query: Q) -> HistoryResult<()>
        where Q: Serialize;
    ...
}

New Behaviour

We introduce a helper trait, IntoQuery, to help us encode any arbitrary type that implements this into a query string. It has a configurable error (because different strategies might fail in different ways) and a method to encode that takes &self.

pub trait IntoQuery {
    type Error;
    fn encode(&self) -> Result<Cow<'_, str>, Self::Error>;
}

We also add a blanket implementation of this type for any type that implements Serialize with the Error set to HistoryError.

impl<T: Serialize> IntoQuery for T {
    type Error = HistoryError;

    fn encode(&self) -> Result<Cow<'_, str>, Self::Error> {
        serde_urlencoded::to_string(self)
            .map(Into::into)
            .map_err(Into::into)
    }
}

Now, we change the methods in the History trait to constrain on anything that implements IntoQuery instead of Serialize. Since we have a blanket implementation of IntoQuery for anything that implements Serialize, these two constraints are identical at this point. These now return a IntoQuery::Error as an error instead.

impl History {
    fn push_with_query<'a, Q>(&self, route: impl Into<Cow<'a, str>>, query: Q) -> HistoryResult<(),Q::Error>
        where Q: IntoQuery;
    fn replace_with_query<'a, Q>(&self, route: impl Into<Cow<'a, str>>, query: Q) -> HistoryResult<(), Q::Error>
        where Q: IntoQuery;
    ...
}

Before, it was only possible to call these methods with Q: Serialize and it returned a Result<(), HistoryError>. Now, calling it with any type that is Q: Serialize is still possible, and returns the same value. However, it is now possible to implement IntoQuery manually to override an encoding scheme. This is done with the Qs type and the Raw type.

Breaking Changes

Because the new History trait API is a superset of the previous API, this does not constitute a breaking change for consumers of this trait. It does however change the trait, which means that anyone who manually implements the History trait for a custom type (I don't know why anyone would do that, but you could) needs to adjust their implementation slightly. It might be worth looking into sealing the History trait for future-proofing it, otherwise any change, even addition of a method, is a potential (hypothetical) breaking change.

Query Decoding

Previous Behaviour

Query decoding happens in the Location struct, which has a query method.

impl Location {
        pub fn query<T>(&self) -> HistoryResult<T> where T: DeserializeOwned;
}

New Behaviour

We introduce a trait to capture the idea of decoding a query string. This has a Target type parameter, so that a MyCustomStrategy can decode into a String if it wanted to, and an Error parameter, as well as a decode() method.

pub trait FromQuery {
    type Target;
    type Error;
    fn decode(query: &str) -> Result<Self::Target, Self::Error>;
}

Again, we add a blanket implementation for any T that implements DeserializeOwned.

impl<T: DeserializeOwned> FromQuery for T {
    type Target = T;
    type Error = HistoryError;

    fn decode(query: &str) -> Result<Self::Target, Self::Error> {
        serde_urlencoded::from_str(query).map_err(Into::into)
    }
}

With this, we change the method to return a T::Target and an T::Error instead.

impl Location {
pub fn query<T>(&self) -> HistoryResult<T::Target, T::Error> where T: FromQuery;

With this change, all previous invocations still work the exact same way. However, we can now implement FromQuery for custom types to use a custom decoding strategy.

Breaking Changes

Since this is not a trait, and the new definition is a superset of the old, this does not constitute a breaking change.

Tests

Tests have been added for the traits. The test coverage exceeds 80%.

Documentation

Documentation has been added, however it could still be improved with more examples.

[futursolo]

It might be worth looking into sealing the History trait for future-proofing it, otherwise any change, even addition of a method, is a potential (hypothetical) breaking change.

I am not too concerned about sealing History as the ultimate goal is to have a way to provide AnyHistory with any type that is 'static + History. So users can implement their own History should they wish to link History to a different data store.

This is a major change (any non-trivial change to item signatures), which means the minor version needs to be bumped.

We have a pending minor release for the next pull request already, i.e.: bumping the MSRV.

[futursolo]

Could you please update changelog.md, including your change?

[ranile]

I wonder if there is a way to use URLSearchParams with serde

[xfbs]

I wonder if there is a way to use URLSearchParams with serde

Do you mean something like extracting key-value pairs from a URLSearchParams and feeding that into a serde deserializer?

[ranile]

I wonder if there is a way to use URLSearchParams with serde

Do you mean something like extracting key-value pairs from a URLSearchParams and feeding that into a serde deserializer?

I mean the opposite of that: using serde to serialize into a URLSearchParams

[xfbs]

That should be possible, actually. Although, you would probably not want to couple it so strongly. So ideally, you'd want something that serializes into a Vec<(String, String)>, and then you feed that into a URLSearchParams. Sounds like a fun weekend project.

[futursolo]

I think URLSearchParams might not be the best choice for gloo-history as it needs to work with server-side rendering, in which URLSearchParams is not available.

[futursolo]

Thanks! LGTM.

I am approving this pull request as I do not have more comments with the current implementation and we can proceed with it after the change log is updated.

[ranile]

Thanks for making this change!