stillwater 1.0.1

Pragmatic effect composition and validation for Rust - pure core, imperative shell
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
133

//! Ensure combinator for validating effect outputs with closure predicates.

use crate::effect::Effect;

/// Validates the effect's output with a closure predicate.
///
/// If the predicate returns true, the value passes through.
/// If the predicate returns false, the effect fails with the provided error.
///
/// This is the closure-based version. For composable predicates from the
/// predicate module, use `ensure_pred` instead.
///
/// # Example
///
/// ```rust,ignore
/// use stillwater::effect::prelude::*;
///
/// let effect = pure::<_, String, ()>(25)
///     .ensure(|age| *age >= 18, "Must be 18 or older".to_string());
///
/// assert_eq!(effect.execute(&()).await, Ok(25));
/// ```
pub struct Ensure<E, P, Err> {
    pub(crate) inner: E,
    pub(crate) predicate: P,
    pub(crate) error: Err,
}

impl<E, P, Err> std::fmt::Debug for Ensure<E, P, Err> {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("Ensure")
            .field("inner", &"<effect>")
            .field("predicate", &"<function>")
            .field("error", &"<error>")
            .finish()
    }
}

impl<E, P, Err> Ensure<E, P, Err> {
    /// Create a new Ensure combinator.
    pub fn new(inner: E, predicate: P, error: Err) -> Self {
        Ensure {
            inner,
            predicate,
            error,
        }
    }
}

impl<E, P, Err> Effect for Ensure<E, P, Err>
where
    E: Effect,
    P: FnOnce(&E::Output) -> bool + Send,
    Err: Into<E::Error> + Send,
{
    type Output = E::Output;
    type Error = E::Error;
    type Env = E::Env;

    async fn run(self, env: &Self::Env) -> Result<Self::Output, Self::Error> {
        let value = self.inner.run(env).await?;
        if (self.predicate)(&value) {
            Ok(value)
        } else {
            Err(self.error.into())
        }
    }
}

#[cfg(test)]
mod tests {
    use crate::effect::constructors::{fail, pure};
    use crate::effect::EffectExt;

    #[tokio::test]
    async fn test_ensure_passes_when_true() {
        let effect = pure::<_, String, ()>(5).ensure(|x| *x > 0, "must be positive".to_string());
        assert_eq!(effect.execute(&()).await, Ok(5));
    }

    #[tokio::test]
    async fn test_ensure_fails_when_false() {
        let effect = pure::<_, String, ()>(-5).ensure(|x| *x > 0, "must be positive".to_string());
        assert_eq!(
            effect.execute(&()).await,
            Err("must be positive".to_string())
        );
    }

    #[tokio::test]
    async fn test_ensure_short_circuits_on_prior_error() {
        let effect = fail::<i32, _, ()>("prior error".to_string())
            .ensure(|_| panic!("should not be called"), "other".to_string());
        assert_eq!(effect.execute(&()).await, Err("prior error".to_string()));
    }

    #[tokio::test]
    async fn test_chained_ensures() {
        let effect = pure::<_, String, ()>(50)
            .ensure(|x| *x > 0, "must be positive".to_string())
            .ensure(|x| *x < 100, "must be less than 100".to_string())
            .ensure(|x| *x % 2 == 0, "must be even".to_string());
        assert_eq!(effect.execute(&()).await, Ok(50));
    }

    #[tokio::test]
    async fn test_chained_ensures_first_fails() {
        let effect = pure::<_, String, ()>(-5)
            .ensure(|x| *x > 0, "must be positive".to_string())
            .ensure(|_| panic!("should not reach"), "other".to_string());
        assert_eq!(
            effect.execute(&()).await,
            Err("must be positive".to_string())
        );
    }

    #[tokio::test]
    async fn test_ensure_with_map() {
        let effect = pure::<_, String, ()>(5)
            .map(|x| x * 2)
            .ensure(|x| *x > 5, "must be greater than 5".to_string())
            .map(|x| x + 1);
        assert_eq!(effect.execute(&()).await, Ok(11));
    }

    #[tokio::test]
    async fn test_ensure_with_and_then() {
        let effect = pure::<_, String, ()>(5)
            .ensure(|x| *x > 0, "must be positive".to_string())
            .and_then(|x| pure(x * 2));
        assert_eq!(effect.execute(&()).await, Ok(10));
    }
}