transactional 0.3.1

A simple optimistic lock-free confirmation-based transactional model for Rust.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132

pub type UserError = Box<dyn std::error::Error + Send + Sync + 'static>;

#[cfg(test)]
/// Converts a string slice to an `InternalFromTests` error variant for testing purposes.
///
/// This implementation allows creating a test error directly from a string slice,
/// which is useful for generating test-specific error scenarios.
///
impl From<&str> for Error {
    fn from(message: &str) -> Self {
        Error::InternalFromTests {
            message: message.to_string(),
        }
    }
}

#[derive(thiserror::Error, Debug)]
/// Represents different types of errors that can occur in the application
///
/// This enum covers scenarios related to concurrent modifications and transaction rejections,
/// with an additional test-specific error variant for internal testing purposes.
///
/// # Variants
/// - `ConcurrentModification`: Indicates an attempt to modify state while a transaction is ongoing
/// - `TransactionRejected`: Represents a modification that was rejected, with an underlying source error
/// - `InternalFromTests`: A test-specific error variant for generating errors during testing
///
/// # Examples
///
/// # Examples
///
/// Creating a `ConcurrentModification` error:
/// ```
/// use transactional::prelude::*;
///
/// let error = Error::ConcurrentModification {
///     previous: "old_value".to_string(),
///     current: "new_value".to_string(),
/// };
///
/// assert!(error.to_string().contains("attempt of modification"));
/// assert!(error.to_string().contains("old_value"));
/// assert!(error.to_string().contains("new_value"));
/// ```
///
/// Creating a `TransactionRejected` error:
/// ```
/// use std::error::Error as StdError;
/// use std::fmt;
/// use transactional::error::Error;
///
/// // A simple error type for the example
/// #[derive(Debug)]
/// struct ValidationError(String);
///
/// impl fmt::Display for ValidationError {
///     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
///         write!(f, "Validation error: {}", self.0)
///     }
/// }
///
/// impl StdError for ValidationError {}
///
/// // Create the TransactionRejected error
/// let source_error = ValidationError("invalid data".to_string());
/// let error = Error::TransactionRejected {
///     previous: "old_state".to_string(),
///     current: "new_state".to_string(),
///     source: Box::new(source_error),
/// };
///
/// assert!(error.to_string().contains("rejected"));
/// assert!(error.to_string().contains("old_state"));
/// assert!(error.to_string().contains("new_state"));
/// ```
pub enum Error {
    #[error(
        "attempt of modification {previous} -> {current} while transaction is ongoing"
    )]
    ConcurrentModification { previous: String, current: String },

    #[error("modification {previous} -> {current}  rejected: {source}")]
    TransactionRejected {
        previous: String,
        current: String,
        #[source]
        source: Box<dyn std::error::Error>,
    },

    #[cfg(test)]
    #[error("Test error: {message}")]
    InternalFromTests { message: String },
}

impl Error {
    pub fn transaction_rejected<T>(
        previous: Option<&T>,
        current: Option<&T>,
        error: UserError,
    ) -> Self
    where
        T: ToString,
    {
        Error::TransactionRejected {
            previous: previous
                .map_or("**none**".to_string(), ToString::to_string)
                .to_string(),
            current: current
                .map_or("**none**".to_string(), ToString::to_string)
                .to_string(),
            source: error,
        }
    }
}

#[cfg(test)]
mod tests {
    use insta::assert_debug_snapshot;

    use super::*;

    #[test]
    fn test_from_str() {
        let message = "test message";
        let error: Error = message.into();
        assert_debug_snapshot!(error, @r#"
        InternalFromTests {
            message: "test message",
        }
        "#);
    }
}