async_reciprocals/

api.rs

/// Provides asynchronous, fallible type conversion traits and utilities.
///
/// This module defines two primary traits:
/// - `AsyncTryFrom`: Allows asynchronous conversion from one type to another that may fail
/// - `AsyncTryInto`: Enables asynchronous conversion attempts with potential failure
///
/// The traits support async conversion operations similar to standard `TryFrom` and `TryInto`,
/// but with asynchronous semantics. They include blanket implementations and helper methods
/// to simplify conversion between types in async contexts.
///
/// # Examples
///
///
/// async fn convert<T: AsyncTryInto<U>>(value: T) -> Result<U, T::Error> {
///     value.async_try_into().await
/// }
///
///
/// Provides extension methods and adapters to facilitate flexible type conversions
/// in asynchronous code.
use std::marker::PhantomData;

/// Enables asynchronous trait methods by generating boilerplate code for async fn in traits
///
/// This macro allows defining async methods in traits, which is not natively supported in Rust.
/// It automatically generates the necessary associated types and implementation details to make
/// async trait methods work across different async runtimes.
///
/// # Examples
///
/// ```
///
#[async_trait::async_trait]
pub trait AsyncTryFrom<T>: Sized {
    type Error;
    async fn async_try_from(value: T)
    -> std::result::Result<Self, Self::Error>;
}

#[async_trait::async_trait]
/// A trait for performing fallible, asynchronous conversions from one type to another.
///
/// Similar to `TryInto`, but with support for asynchronous conversion operations.
/// Allows a type to be converted into another type, with the possibility of failure,
/// using an asynchronous method.
///
/// # Examples
///
///
/// async fn convert<T: AsyncTryInto<U>>(value: T) -> Result<U, T::Error> {
///     value.async_try_into().await
/// }
///
pub trait AsyncTryInto<T>: Sized {
    type Error;
    #[allow(dead_code)]
    async fn async_try_into(self) -> std::result::Result<T, Self::Error>;
}

#[allow(dead_code)]
/// An adapter struct for facilitating asynchronous type conversions from one type to another.
///
/// This zero-sized type uses `PhantomData` to represent a conversion between generic types `T` and `U`,
/// providing a marker for conversion-related operations in asynchronous contexts.
///
/// # Examples
///
///
/// // Used as a type-level marker for async conversion strategies
/// let _adapter = FromAdapter::<SourceType, TargetType>(PhantomData);
///
pub struct FromAdapter<T, U>(PhantomData<(T, U)>);

#[allow(dead_code)]
/// An adapter struct for facilitating asynchronous type conversions to another type.
///
/// This zero-sized type uses `PhantomData` to represent a conversion between generic types `T` and `U`,
/// providing a marker for conversion-related operations in asynchronous contexts.
///
/// # Examples
///
/// // Used as a type-level marker for async conversion strategies
/// let _adapter = IntoAdapter::<SourceType, TargetType>(PhantomData);
pub struct IntoAdapter<T, U>(PhantomData<(T, U)>);

#[async_trait::async_trait]
/// Provides a generic implementation of `AsyncTryInto` for types that can be converted
/// asynchronously using `AsyncTryFrom`.
///
/// This implementation allows any type `T` to be converted into type `U` if `U` implements
/// `AsyncTryFrom<T>`. The conversion is performed asynchronously and can potentially fail.
///
/// # Type Parameters
///
/// - `T`: The source type being converted from
/// - `U`: The target type being converted into
///
/// # Constraints
///
/// - `U` must implement `AsyncTryFrom<T>`
/// - `T` must be `Send`
///
/// # Returns
///
/// A `Result` containing the converted value or an error if the conversion fails
impl<T, U> AsyncTryInto<U> for T
where
    U: AsyncTryFrom<T>,
    T: Send,
{
    type Error = U::Error;

    async fn async_try_into(self) -> std::result::Result<U, Self::Error> {
        U::async_try_from(self).await
    }
}

#[async_trait::async_trait]
/// Provides a trivial implementation of `AsyncTryFrom` for a type converting to itself.
///
/// This implementation allows any `Send` type to be converted asynchronously to itself
/// without any possibility of failure, always returning `Ok(value)`.
///
/// # Type Parameters
///
/// - `T`: The type being converted, which must implement `Send`
///
/// # Returns
///
/// Always returns `Ok(value)` with an `Infallible` error type, representing a guaranteed successful conversion
impl<T: Send> AsyncTryFrom<T> for T {
    type Error = std::convert::Infallible;

    async fn async_try_from(
        value: T,
    ) -> std::result::Result<Self, Self::Error> {
        Ok(value)
    }
}

// If user implements AsyncTryInto, they can use this adapter to get AsyncTryFrom
// #[async_trait::async_trait]
// impl<T, U> AsyncTryFrom<U> for T
// where
//     U: AsyncTryInto<T>,
//     U: Send,
// {
//     type Error = U::Error;

//     async fn async_try_from(value: U) -> std::result::Result<T, Self::Error>
//     where
//         U: 'async_trait,
//     {
//         value.async_try_into().await
//     }
// }

/// Extension methods and utilities for asynchronous type conversions
///
/// This module provides additional functionality and helper methods
/// for working with asynchronous type conversion traits like `AsyncTryFrom` and `AsyncTryInto`.
pub mod extensions {
    use super::*;

    #[allow(dead_code)]
    /// Creates a `FromAdapter` for converting between types using `AsyncTryFrom`.
    ///
    /// This utility function helps in creating type adapters for asynchronous conversions
    /// between different types that implement `AsyncTryFrom`.
    ///
    /// # Type Parameters
    ///
    /// - `T`: The source type being converted from
    /// - `U`: The target type being converted to
    ///
    /// # Returns
    ///
    /// A `FromAdapter` that can be used for type conversions
    pub fn from_to_into<T, U>(_: &impl AsyncTryFrom<T>) -> FromAdapter<T, U> {
        FromAdapter(PhantomData)
    }

    #[allow(dead_code)]
    /// Creates an `IntoAdapter` for converting between types using `AsyncTryInto`.
    ///
    /// This utility function helps in creating type adapters for asynchronous conversions
    /// between different types that implement `AsyncTryInto`.
    ///
    /// # Type Parameters
    ///
    /// - `T`: The source type being converted from
    /// - `U`: The target type being converted to
    ///
    /// # Returns
    ///
    /// An `IntoAdapter` that can be used for type conversions
    pub fn into_to_from<T, U>(_: &impl AsyncTryInto<U>) -> IntoAdapter<T, U> {
        IntoAdapter(PhantomData)
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use std::error::Error;

    // Existing tests...

    // Test AsyncTryFrom and AsyncTryInto separately to avoid conflicts
    mod async_try_from_tests {

        use super::*;

        struct TestFromType(String);

        #[async_trait::async_trait]
        impl AsyncTryFrom<String> for TestFromType {
            type Error = Box<dyn Error>;

            async fn async_try_from(
                value: String,
            ) -> std::result::Result<Self, Self::Error> {
                Ok(TestFromType(value))
            }
        }

        #[tokio::test]
        async fn test_async_try_from_and_into() {
            // Test direct AsyncTryFrom usage
            let input = "test string".to_string();
            let result = TestFromType::async_try_from(input.clone()).await;
            assert!(result.is_ok());
            assert_eq!(result.unwrap().0, input);

            // Test that AsyncTryInto is automatically available through blanket impl
            let input = "another test".to_string();
            let result: Result<TestFromType, _> = input.async_try_into().await;
            assert!(result.is_ok());
            assert_eq!(result.unwrap().0, "another test");
        }
    }

    mod async_try_into_tests {
        use super::*;
        use std::error::Error;

        struct TestIntoType(String);

        #[async_trait::async_trait]
        impl AsyncTryInto<String> for TestIntoType {
            type Error = Box<dyn Error>;

            async fn async_try_into(
                self,
            ) -> std::result::Result<String, Self::Error> {
                Ok(self.0)
            }
        }

        #[tokio::test]
        async fn test_async_try_into_and_from() {
            // Test direct AsyncTryInto usage
            let test_into = TestIntoType("test data".to_string());
            let result: Result<String, Box<dyn Error>> =
                test_into.async_try_into().await;
            assert!(result.is_ok());
            assert_eq!(result.unwrap(), "test data");

            // Test that AsyncTryFrom is automatically available through blanket impl
            // No automatic AsyncTryFrom implementation in this direction
            // Users would need to implement AsyncTryFrom manually if needed
        }
    }
}