osteak 0.1.1

Elm for ratatui — you bring the loop
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

//! Subscriptions — external event sources wired into the TEA loop.
//!
//! A [`Sub`] pairs an identity string with a [`Stream`] of messages.
//! The identity enables lifecycle management: the runner can diff
//! subscriptions between updates, starting new ones and cancelling
//! stale ones automatically.
//!
//! [`Stream`]: futures_core::Stream

/// A subscription to an external event source.
///
/// Subscriptions produce messages from outside the normal update cycle:
/// timers, file watchers, channels, WebSocket connections, etc.
///
/// The `id` field is a stable identity for lifecycle management. The
/// optional [`runner`](crate::runner) uses it to diff subscriptions:
/// - Same `id` across updates: keep the existing stream running.
/// - New `id`: start the stream and forward its items as messages.
/// - Missing `id`: cancel the stream.
///
/// If you manage your own event loop, you handle subscription lifecycle
/// yourself — the `id` is just a convenience.
///
/// # Examples
///
/// ```
/// use osteak::Sub;
///
/// // A subscription from a channel receiver (using futures Stream)
/// fn from_stream(stream: impl futures_core::Stream<Item = String> + Send + Unpin + 'static) -> Sub<String> {
///     Sub::new("messages", stream)
/// }
/// ```
pub struct Sub<Msg> {
    /// Stable identity for diffing subscriptions across updates.
    pub id: &'static str,

    /// The stream that produces messages.
    pub stream: Box<dyn futures_core::Stream<Item = Msg> + Send + Unpin>,
}

impl<Msg> Sub<Msg> {
    /// Create a new subscription with the given identity and stream.
    pub fn new<S>(id: &'static str, stream: S) -> Self
    where
        S: futures_core::Stream<Item = Msg> + Send + Unpin + 'static,
    {
        Sub {
            id,
            stream: Box::new(stream),
        }
    }
}

impl<Msg> std::fmt::Debug for Sub<Msg> {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("Sub")
            .field("id", &self.id)
            .finish_non_exhaustive()
    }
}