serde_versioned 0.2.0

//! # `serde_versioned`
//!
//! A library for handling versioned serialization and deserialization of Rust structs.
//! This crate provides traits and derive macros to support multiple versions of data structures
//! while maintaining backward compatibility.
//!
//! ## Usage
//!
//! ```rust,no_run
//! use serde_versioned::{Versioned, FromVersion};
//! use serde::{Serialize, Deserialize};
//!
//! #[derive(Versioned, Serialize, Deserialize, Clone)]
//! #[versioned(versions = [UserV1, UserV2])]
//! struct User {
//!     pub name: String,
//!     pub age: u32,
//! }
//!
//! #[derive(Serialize, Deserialize, Clone)]
//! pub struct UserV1 {
//!     pub name: String,
//! }
//!
//! #[derive(Serialize, Deserialize, Clone)]
//! pub struct UserV2 {
//!     pub name: String,
//!     pub age: u32,
//! }
//!
//! impl FromVersion<User> for UserV1 {
//!     fn convert(self) -> User {
//!         User { name: self.name, age: 0 }
//!     }
//! }
//!
//! impl FromVersion<User> for UserV2 {
//!     fn convert(self) -> User {
//!         User { name: self.name, age: self.age }
//!     }
//! }
//! ```

use serde::{Deserialize, Serialize};
use std::error::Error;

pub use serde_versioned_derive::Versioned;

/// Trait for converting from a versioned struct to the current struct.
///
/// This trait must be implemented for each version struct to define how it converts
/// to the current version of the struct.
///
/// # Example
///
/// ```rust,no_run
/// use serde_versioned::FromVersion;
///
/// struct User { name: String, age: u32 }
/// struct UserV1 { name: String }
///
/// impl FromVersion<User> for UserV1 {
///     fn convert(self) -> User {
///         User { name: self.name, age: 0 }
///     }
/// }
/// ```
pub trait FromVersion<T>: Sized {
    /// Converts a versioned struct instance to the current struct type.
    ///
    /// # Arguments
    ///
    /// * `self` - The versioned struct instance to convert
    ///
    /// # Returns
    ///
    /// The converted current struct instance
    fn convert(self) -> T;
}

/// Trait for handling versioned serialization and deserialization.
///
/// This trait is automatically derived using the `#[derive(Versioned)]` macro.
/// It provides methods to convert between the current struct and its versioned enum.
///
/// # Example
///
/// ```rust,no_run
/// use serde_versioned::Versioned;
/// use serde::{Deserialize, Serialize};
///
/// #[derive(Versioned, Serialize, Deserialize)]
/// #[versioned(versions = [UserV1, UserV2])]
/// struct User {
///     name: String,
///     age: u32,
/// }
///
/// #[derive(Serialize, Deserialize)]
/// struct UserV1 {
///     name: String,
/// }
///
/// #[derive(Serialize, Deserialize)]
/// struct UserV2 {
///     name: String,
///     age: u32,
/// }
///
/// impl serde_versioned::FromVersion<User> for UserV1 {
///     fn convert(self) -> User {
///         User { name: self.name, age: 0 }
///     }
/// }
///
/// impl serde_versioned::FromVersion<User> for UserV2 {
///     fn convert(self) -> User {
///         User { name: self.name, age: self.age }
///     }
/// }
///
/// // Convert to versioned enum
/// let user = User { name: "Alice".to_string(), age: 30 };
/// let version = user.to_version();
///
/// // Serialize to JSON
/// let json = serde_json::to_string(&version).unwrap();
///
/// // Deserialize and convert back
/// let version: UserVersion = serde_json::from_str(&json).unwrap();
/// let user = User::from_version(version).unwrap();
/// ```
pub trait Versioned: Sized {
    /// The version enum type that represents all versions of this struct.
    ///
    /// This enum is automatically generated by the `#[derive(Versioned)]` macro
    /// and contains variants for each version specified in the `versions` attribute.
    type VersionEnum: for<'a> Deserialize<'a> + Serialize;

    /// Converts a versioned enum instance back to the current struct.
    ///
    /// # Arguments
    ///
    /// * `version` - The versioned enum instance to convert
    ///
    /// # Returns
    ///
    /// * `Ok(Self)` - Successfully converted struct
    /// * `Err(VersionConversionError)` - Error during conversion with version information
    ///
    /// # Errors
    ///
    /// Returns a `VersionConversionError` if the conversion from the versioned struct to the current struct fails.
    /// This typically happens when the `FromVersion` implementation fails.
    /// The error includes the version number that failed to convert.
    fn from_version(version: Self::VersionEnum) -> Result<Self, VersionConversionError>;

    /// Converts the current struct instance to its versioned enum representation.
    ///
    /// This always uses the latest version specified in the `versions` attribute.
    ///
    /// # Returns
    ///
    /// The versioned enum instance representing this struct in its latest version.
    fn to_version(&self) -> Self::VersionEnum;

    /// Deserializes from a string format and converts to the current struct.
    ///
    /// This is a convenience method that combines deserialization and version conversion.
    ///
    /// # Arguments
    ///
    /// * `input` - The string to deserialize from
    /// * `deserializer` - A function that deserializes the string into `Self::VersionEnum`
    ///
    /// # Returns
    ///
    /// * `Ok(Self)` - Successfully deserialized and converted struct
    /// * `Err(FormatError<E>)` - Error during deserialization or conversion
    ///
    /// # Errors
    ///
    /// Returns `FormatError::Deserialize` if deserialization fails, or
    /// `FormatError::VersionConversion` if version conversion fails.
    ///
    /// # Example
    ///
    /// ```rust,no_run
    /// use serde_versioned::Versioned;
    /// use serde::{Deserialize, Serialize};
    ///
    /// #[derive(Versioned, Serialize, Deserialize)]
    /// #[versioned(versions = [UserV1, UserV2])]
    /// struct User {
    ///     name: String,
    ///     age: u32,
    /// }
    ///
    /// #[derive(Serialize, Deserialize)]
    /// struct UserV1 {
    ///     name: String,
    /// }
    ///
    /// #[derive(Serialize, Deserialize)]
    /// struct UserV2 {
    ///     name: String,
    ///     age: u32,
    /// }
    ///
    /// impl serde_versioned::FromVersion<User> for UserV1 {
    ///     fn convert(self) -> User {
    ///         User { name: self.name, age: 0 }
    ///     }
    /// }
    ///
    /// impl serde_versioned::FromVersion<User> for UserV2 {
    ///     fn convert(self) -> User {
    ///         User { name: self.name, age: self.age }
    ///     }
    /// }
    ///
    /// let json = r#"{"version":"1","name":"Alice"}"#;
    /// let user = User::from_format(json, serde_json::from_str).unwrap();
    /// ```
    fn from_format<'a, F, E>(input: &'a str, deserializer: F) -> Result<Self, FormatError<E>>
    where
        F: FnOnce(&'a str) -> Result<Self::VersionEnum, E>,
        E: Error + Send + Sync + 'static,
    {
        deserializer(input)
            .map_err(|e| FormatError::deserialize(e, Some(input.to_string())))
            .and_then(|version| Self::from_version(version).map_err(FormatError::VersionConversion))
    }

    /// Extracts version string from the version enum for error reporting.
    ///
    /// This is a helper method that attempts to extract the version number
    /// from the version enum for use in error messages.
    ///
    /// # Arguments
    ///
    /// * `version` - The version enum instance
    ///
    /// # Returns
    ///
    /// A string representation of the version number, or "unknown" if it cannot be determined.
    #[doc(hidden)]
    fn extract_version_string(_version: &Self::VersionEnum) -> String {
        // This is a default implementation that returns "unknown".
        // The derive macro should override this with a proper implementation
        // that can extract the version from the enum.
        "unknown".to_string()
    }

    /// Serializes the current struct to a string format via its versioned enum.
    ///
    /// This is a convenience method that converts the struct to its versioned enum
    /// and then serializes it using the provided serializer function.
    ///
    /// # Arguments
    ///
    /// * `serializer` - A function that serializes `Self::VersionEnum` to the desired format
    ///
    /// # Returns
    ///
    /// * `Ok(T)` - Successfully serialized data
    /// * `Err(E)` - Error during serialization
    ///
    /// # Errors
    ///
    /// Returns an error if serialization fails.
    ///
    /// # Example
    ///
    /// ```rust,no_run
    /// use serde_versioned::Versioned;
    /// use serde::{Deserialize, Serialize};
    ///
    /// #[derive(Versioned, Serialize, Deserialize)]
    /// #[versioned(versions = [UserV1, UserV2])]
    /// struct User {
    ///     name: String,
    ///     age: u32,
    /// }
    ///
    /// #[derive(Serialize, Deserialize)]
    /// struct UserV1 {
    ///     name: String,
    /// }
    ///
    /// #[derive(Serialize, Deserialize)]
    /// struct UserV2 {
    ///     name: String,
    ///     age: u32,
    /// }
    ///
    /// impl serde_versioned::FromVersion<User> for UserV1 {
    ///     fn convert(self) -> User {
    ///         User { name: self.name, age: 0 }
    ///     }
    /// }
    ///
    /// impl serde_versioned::FromVersion<User> for UserV2 {
    ///     fn convert(self) -> User {
    ///         User { name: self.name, age: self.age }
    ///     }
    /// }
    ///
    /// let user = User { name: "Alice".to_string(), age: 30 };
    /// let json = user.to_format(serde_json::to_string).unwrap();
    /// ```
    fn to_format<F, T, E>(&self, serializer: F) -> Result<T, E>
    where
        F: FnOnce(&Self::VersionEnum) -> Result<T, E>,
    {
        let version = self.to_version();
        serializer(&version)
    }
}

/// Error type for version conversion operations.
///
/// This error provides detailed information about failures during version conversion,
/// including which version was being converted from.
#[derive(Debug)]
pub struct VersionConversionError {
    /// The version number that failed to convert (e.g., "1", "2")
    pub version: String,
    /// The underlying error that occurred during conversion
    pub source: Box<dyn Error + Send + Sync + 'static>,
    /// Additional context about the conversion failure
    pub context: Option<String>,
}

impl VersionConversionError {
    /// Creates a new `VersionConversionError` with the specified version and source error.
    ///
    /// # Arguments
    ///
    /// * `version` - The version number that failed to convert
    /// * `source` - The underlying error that occurred
    pub fn new(version: impl Into<String>, source: Box<dyn Error + Send + Sync + 'static>) -> Self {
        Self {
            version: version.into(),
            source,
            context: None,
        }
    }

    /// Creates a new `VersionConversionError` with additional context.
    ///
    /// # Arguments
    ///
    /// * `version` - The version number that failed to convert
    /// * `source` - The underlying error that occurred
    /// * `context` - Additional context about the failure
    pub fn with_context(
        version: impl Into<String>,
        source: Box<dyn Error + Send + Sync + 'static>,
        context: impl Into<String>,
    ) -> Self {
        Self {
            version: version.into(),
            source,
            context: Some(context.into()),
        }
    }

    /// Returns the version number that failed to convert.
    #[must_use]
    pub fn version(&self) -> &str {
        &self.version
    }
}

impl Error for VersionConversionError {
    fn source(&self) -> Option<&(dyn Error + 'static)> {
        Some(self.source.as_ref())
    }
}

impl std::fmt::Display for VersionConversionError {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(
            f,
            "Failed to convert from version {}: {}",
            self.version, self.source
        )?;
        if let Some(ref context) = self.context {
            write!(f, " ({context})")?;
        }
        Ok(())
    }
}

/// Error type for format conversion operations.
///
/// This enum represents errors that can occur when using `from_format` or `to_format` methods.
#[derive(Debug)]
pub enum FormatError<E> {
    /// Error occurred during deserialization of the input string.
    ///
    /// This variant contains the original deserialization error from the format parser.
    Deserialize {
        /// The original deserialization error
        error: E,
        /// The input string that failed to deserialize (if available)
        input: Option<String>,
    },
    /// Error occurred during conversion from a versioned struct to the current struct.
    ///
    /// This variant contains detailed information about the version conversion failure.
    VersionConversion(VersionConversionError),
}

impl<E: Error + Send + Sync + 'static> FormatError<E> {
    /// Creates a new `Deserialize` variant with the error and optional input.
    pub const fn deserialize(error: E, input: Option<String>) -> Self {
        Self::Deserialize { error, input }
    }

    /// Creates a new `VersionConversion` variant from a version conversion error.
    pub fn version_conversion(
        version: impl Into<String>,
        source: Box<dyn Error + Send + Sync + 'static>,
    ) -> Self {
        Self::VersionConversion(VersionConversionError::new(version, source))
    }

    /// Returns `true` if this is a deserialization error.
    pub const fn is_deserialize(&self) -> bool {
        matches!(self, Self::Deserialize { .. })
    }

    /// Returns `true` if this is a version conversion error.
    pub const fn is_version_conversion(&self) -> bool {
        matches!(self, Self::VersionConversion(_))
    }
}

impl<E: Error + Send + Sync + 'static> Error for FormatError<E> {
    fn source(&self) -> Option<&(dyn Error + 'static)> {
        match self {
            Self::Deserialize { error, .. } => Some(error),
            Self::VersionConversion(e) => e.source(),
        }
    }
}

impl<E: Error + Send + Sync + 'static> std::fmt::Display for FormatError<E> {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            Self::Deserialize { error, input } => {
                write!(f, "Deserialization error: {error}")?;
                if let Some(input_str) = input {
                    // Truncate long inputs for readability
                    if input_str.len() > 100 {
                        write!(f, " (input: {:?}...)", &input_str[..100])?;
                    } else {
                        write!(f, " (input: {input_str:?})")?;
                    }
                }
                Ok(())
            }
            Self::VersionConversion(e) => {
                write!(f, "Version conversion error: {e}")
            }
        }
    }
}