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.

comment_text_of_item

</>

pub fn comment_text_of_item(item: Item) -> option.Option(String)

Return the comment text when the item is a comment, None otherwise. Mirrors event_of_item/1 for the comment side.

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

event_of_item

</>

pub fn event_of_item(item: Item) -> option.Option(Event)

Return the event payload when the item is an event, None otherwise. Use with option.then / case for stream processing that ignores comments.

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)

is_comment

</>

pub fn is_comment(item: Item) -> Bool

True when the item is a :-prefixed comment line.

is_event

</>

pub fn is_event(item: Item) -> Bool

Issue #77: Item-level accessors. The Item variants EventItem / CommentItem are not visible through the top-level ssevents module (a Gleam type alias does not re-export its constructors), so callers that decode an SSE stream and want to pattern-match on the result would otherwise need to reach into ssevents/event directly. These helpers let ssevents-only callers walk decoded items without the second import. True when the item is an event (carries an SSE Event payload).

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)