envision 0.16.0

A ratatui framework for collaborative TUI development with headless testing support
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

use std::time::Duration;

use super::Subscription;
use super::combinators::{
    DebounceSubscription, FilterSubscription, MappedSubscription, TakeSubscription,
    ThrottleSubscription,
};

/// Extension trait for subscriptions.
///
/// Provides fluent methods for composing and transforming subscriptions.
///
/// # Example
///
/// ```rust
/// use envision::app::{SubscriptionExt, tick};
/// use std::time::Duration;
///
/// // Create a tick subscription with filtering and limiting
/// let sub = tick(Duration::from_millis(100))
///     .with_message(|| 42i32)
///     .filter(|n| *n > 0)
///     .take(10)
///     .throttle(Duration::from_millis(200));
/// ```
pub trait SubscriptionExt<M>: Subscription<M> + Sized {
    /// Maps the messages of this subscription.
    ///
    /// # Example
    ///
    /// ```rust
    /// use envision::app::{SubscriptionExt, tick};
    /// use std::time::Duration;
    ///
    /// let sub = tick(Duration::from_secs(1))
    ///     .with_message(|| 42)
    ///     .map(|n| format!("value: {}", n));
    /// ```
    fn map<N, F>(self, f: F) -> MappedSubscription<M, N, F, Self>
    where
        F: Fn(M) -> N + Send + 'static,
    {
        MappedSubscription::new(self, f)
    }

    /// Filters messages from this subscription.
    ///
    /// Only messages for which the predicate returns `true` are emitted.
    ///
    /// # Example
    ///
    /// ```rust
    /// use envision::app::{SubscriptionExt, tick};
    /// use std::time::Duration;
    ///
    /// let sub = tick(Duration::from_secs(1))
    ///     .with_message(|| 42i32)
    ///     .filter(|n| *n > 0);
    /// ```
    fn filter<P>(self, predicate: P) -> FilterSubscription<M, Self, P>
    where
        P: Fn(&M) -> bool + Send + 'static,
    {
        FilterSubscription::new(self, predicate)
    }

    /// Takes only the first N messages from this subscription.
    ///
    /// After N messages, the subscription ends.
    ///
    /// # Example
    ///
    /// ```rust
    /// use envision::app::{SubscriptionExt, tick};
    /// use std::time::Duration;
    ///
    /// let sub = tick(Duration::from_secs(1))
    ///     .with_message(|| "tick")
    ///     .take(5);
    /// ```
    fn take(self, count: usize) -> TakeSubscription<M, Self> {
        TakeSubscription::new(self, count)
    }

    /// Debounces messages from this subscription.
    ///
    /// Only emits a message after a quiet period has passed. If a new message
    /// arrives before the quiet period expires, the timer resets. Only the most
    /// recent message is emitted.
    ///
    /// # Example
    ///
    /// ```rust
    /// use envision::app::{SubscriptionExt, tick};
    /// use std::time::Duration;
    ///
    /// // Only emit after 300ms of no new messages
    /// let sub = tick(Duration::from_millis(100))
    ///     .with_message(|| "tick")
    ///     .debounce(Duration::from_millis(300));
    /// ```
    fn debounce(self, duration: Duration) -> DebounceSubscription<M, Self> {
        DebounceSubscription::new(self, duration)
    }

    /// Throttles messages from this subscription.
    ///
    /// Limits the rate of message emission. At most one message is emitted
    /// per duration. The first message passes immediately, subsequent messages
    /// are dropped until the duration has passed.
    ///
    /// # Example
    ///
    /// ```rust
    /// use envision::app::{SubscriptionExt, tick};
    /// use std::time::Duration;
    ///
    /// // Emit at most once every 100ms
    /// let sub = tick(Duration::from_millis(50))
    ///     .with_message(|| "tick")
    ///     .throttle(Duration::from_millis(100));
    /// ```
    fn throttle(self, duration: Duration) -> ThrottleSubscription<M, Self> {
        ThrottleSubscription::new(self, duration)
    }
}

impl<M, S: Subscription<M>> SubscriptionExt<M> for S {}