ssevents/event

Event and item domain values.

Event and Comment are opaque so the package can evolve their representation without a breaking change. Construct via new, from_parts, and the builder helpers (for Event) or comment (for Comment). Item stays transparent so callers and helper modules can pattern match on whether a stream element is an event or a comment.

Types

Comment

opaque </>

A :-prefixed comment line in an SSE stream.

Opaque — construct with comment/1 and inspect with comment_text_of/1. Comment text is sanitised at construction (CR / LF / NUL stripped) so decode(encode([CommentItem(c)])) returns the same Comment value: WHATWG SSE §9.2.6 has no notion of a multi-line comment, so any embedded line break would fan out to multiple comments on the wire and break the round-trip law.

pub opaque type Comment

Event

opaque </>

pub opaque type Event

Item

</>

pub type Item {
  EventItem(Event)
  CommentItem(Comment)
}

Constructors

```
EventItem(Event)
```
```
CommentItem(Comment)
```

Values

comment

</>

pub fn comment(text: String) -> Comment

Build a Comment from a text payload. CR (U+000D), LF (U+000A), and NUL (U+0000) are stripped at construction so the result round-trips through encode → decode without fanning out into multiple comments. Matches the sanitize_field_value posture already used for event_name and id.

comment_item

</>

pub fn comment_item(text: String) -> Item

Wrap a Comment as a stream item. Convenience for the common CommentItem(comment(text)) two-step.

comment_text_of

</>

pub fn comment_text_of(c: Comment) -> String

Extract the sanitised comment text.

data

</>

pub fn data(event: Event, data: String) -> Event

data_of

</>

pub fn data_of(event: Event) -> String

event

</>

pub fn event(event: Event, name: String) -> Event

event_item

</>

pub fn event_item(event: Event) -> Item

from_parts

</>

pub fn from_parts(
  event_name event_name: option.Option(String),
  data data: String,
  id id: option.Option(String),
  retry retry: option.Option(Int),
) -> Event

id

</>

pub fn id(event: Event, id: String) -> Event

id_of

</>

pub fn id_of(event: Event) -> option.Option(String)

message

</>

pub fn message(data: String) -> Event

name_of

</>

pub fn name_of(event: Event) -> option.Option(String)

named

</>

pub fn named(name: String, data: String) -> Event

new

</>

pub fn new(data: String) -> Event

retry

</>

pub fn retry(event: Event, milliseconds: Int) -> Event

Set the SSE retry: reconnection time on an event.

milliseconds must be >= 0. WHATWG SSE §9.2.6 only recognises a retry value whose textual form “consists of only ASCII digits”, so a negative value would be either dropped on the wire (the leading - breaks the digits-only check) or interpreted as 0 and trigger a tight reconnect loop against the server. Either outcome is a contract violation, so the builder panics on ms < 0 with "ssevents.retry: milliseconds must be >= 0 (got <n>); the SSE spec mandates a non-negative reconnection time.". Use retry_clamp/2 instead when the caller wants the lenient (clamp-to-0) behaviour.

Values above limit.default_max_retry_value (24 h in ms) are still silently dropped to None, matching from_parts/4 and the decode(encode(_)) round-trip property pinned in #60.

retry_clamp

</>

pub fn retry_clamp(event: Event, milliseconds: Int) -> Event

Like retry/2, but clamps milliseconds < 0 to 0 instead of panicking. Use this when the caller wants the lenient posture (e.g. when forwarding a value computed from possibly-noisy input). All other behaviour matches retry/2, including the > max_retry silent drop to None for round-trip with the default decoder.

retry_of

</>

pub fn retry_of(event: Event) -> option.Option(Int)