datastar 0.2.0

Datastar SDK 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

//! Datastar is a Rust implementation of the [Datastar](https://data-star.dev) SDK specification.

#![forbid(missing_docs)]
#![forbid(missing_debug_implementations)]

#[cfg(feature = "axum")]
pub mod axum;
#[cfg(feature = "rama")]
pub mod rama;
#[cfg(feature = "rocket")]
pub mod rocket;

pub mod execute_script;
pub mod merge_fragments;
pub mod merge_signals;
pub mod remove_fragments;
pub mod remove_signals;

#[cfg(test)]
mod testing;

pub mod consts;

/// The prelude for the `datastar` crate
pub mod prelude {
    #[cfg(feature = "axum")]
    pub use crate::axum::ReadSignals;
    #[cfg(all(feature = "rama", not(feature = "axum")))]
    pub use crate::rama::ReadSignals;
    pub use crate::{
        DatastarEvent, Sse, TrySse, consts::FragmentMergeMode, execute_script::ExecuteScript,
        merge_fragments::MergeFragments, merge_signals::MergeSignals,
        remove_fragments::RemoveFragments, remove_signals::RemoveSignals,
    };
}

use core::{fmt::Display, time::Duration};

/// [`DatastarEvent`] is a struct that represents a generic Datastar event.
/// All Datastar events implement `Into<DatastarEvent>`.
#[derive(Debug)]
pub struct DatastarEvent {
    /// `event` is the type of event.
    pub event: consts::EventType,
    /// `id` is can be used by the backend to replay events.
    /// This is part of the SSE spec and is used to tell the browser how to handle the event.
    /// For more details see <https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events#id>
    pub id: Option<String>,
    /// `retry` is part of the SSE spec and is used to tell the browser how long to wait before reconnecting if the connection is lost.
    /// For more details see <https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events#retry>
    pub retry: Duration,
    /// `data` is the data that is sent with the event.
    pub data: Vec<String>,
}

impl Display for DatastarEvent {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        writeln!(f, "event: {}", self.event.as_str())?;

        if let Some(id) = &self.id {
            writeln!(f, "id: {}", id)?;
        }

        let millis = self.retry.as_millis();
        if millis != consts::DEFAULT_SSE_RETRY_DURATION as u128 {
            writeln!(f, "retry: {}", millis)?;
        }

        for line in &self.data {
            writeln!(f, "data: {}", line)?;
        }

        write!(f, "\n\n")?;

        Ok(())
    }
}

/// [`Sse`] is a wrapper around a stream of [`DatastarEvent`]s.
#[derive(Debug)]
pub struct Sse<S>(pub S);

/// [`TrySse`] is a wrapper around a stream of [`DatastarEvent`]s that can fail.
#[derive(Debug)]
pub struct TrySse<S>(pub S);