ssevents - v0.10.0

ssevents

Canonical public surface for the ssevents package.

The focused modules (ssevents/event, ssevents/encoder, ssevents/decoder, ssevents/reconnect, ssevents/validate, ssevents/limit, ssevents/heartbeat, ssevents/stream, ssevents/error) carry the actual implementation, but they are an implementation detail: external code should prefer the spellings re-exported here. This is the surface the README and the published HexDocs documentation consider authoritative, and it is the surface that follows semver — the submodule shapes may be reorganized between releases.

Reach into a submodule directly only when the facade does not yet expose what you need; in that case, opening an issue so the missing entry point can be added at this level is preferred to scattering submodule imports across user code.

Types

DecodeState

</> 
pub type DecodeState =
  decoder.DecodeState

Event

</> 
pub type Event =
  event.Event

Item

</> 
pub type Item =
  event.Item

Iterator

</> 
pub type Iterator(a) =
  stream.Iterator(a)

IteratorStep

</> 
pub type IteratorStep(a) =
  stream.Step(a)

Limits

</> 
pub type Limits =
  limit.Limits

LineEnding

</> 
pub type LineEnding =
  encoder.LineEnding

ReconnectState

</> 
pub type ReconnectState =
  reconnect.ReconnectState

SseError

</> 
pub type SseError =
  error.SseError

Values

comment

</> 
pub fn comment(text: String) -> event.Item

comment_text_of_item

</> 
pub fn comment_text_of_item(
  item: event.Item,
) -> option.Option(String)

Return the comment text when the item is a comment, None otherwise.

comment_texts_of

</> 
pub fn comment_texts_of(items: List(event.Item)) -> List(String)

Filter a decoded item list down to its comment texts, dropping events. Pairs with events_of/1.

content_type

</> 
pub fn content_type() -> String

data

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

data_of

</> 
pub fn data_of(event: event.Event) -> String

decode

</> 
pub fn decode(
  input: String,
) -> Result(List(event.Item), error.SseError)

decode_bytes

</> 
pub fn decode_bytes(
  input: BitArray,
) -> Result(List(event.Item), error.SseError)

decode_bytes_with_limits

</> 
pub fn decode_bytes_with_limits(
  input: BitArray,
  limits limits: limit.Limits,
) -> Result(List(event.Item), error.SseError)

decode_stream

</> 
pub fn decode_stream(
  chunks: stream.Iterator(BitArray),
) -> stream.Iterator(Result(event.Item, error.SseError))

decode_stream_with_limits

</> 
pub fn decode_stream_with_limits(
  chunks: stream.Iterator(BitArray),
  limits limits: limit.Limits,
) -> stream.Iterator(Result(event.Item, error.SseError))

decode_with_limits

</> 
pub fn decode_with_limits(
  input: String,
  limits limits: limit.Limits,
) -> Result(List(event.Item), error.SseError)

default_content_type

</> 
pub const default_content_type: String

default_limits

</> 
pub fn default_limits() -> limit.Limits

default_line_ending

</> 
pub fn default_line_ending() -> encoder.LineEnding

empty_iterator

</> 
pub fn empty_iterator() -> stream.Iterator(a)

encode

</> 
pub fn encode(event: event.Event) -> String

Encode one semantic SSE Event to its wire-format String.

Use this when you want a text representation for logging, inspection, fixtures, or a caller that still expects String.

encode_bytes

</> 
pub fn encode_bytes(event: event.Event) -> BitArray

Encode one semantic SSE Event to its wire-format BitArray.

Use this for HTTP responses and other byte-oriented transports.

encode_item

</> 
pub fn encode_item(item: event.Item) -> String

Encode one Item (either an event or a comment) to String.

encode_item_bytes

</> 
pub fn encode_item_bytes(item: event.Item) -> BitArray

Encode one Item (either an event or a comment) to BitArray.

encode_item_with_line_ending

</> 
pub fn encode_item_with_line_ending(
  item: event.Item,
  line_ending: encoder.LineEnding,
) -> String

encode_items

</> 
pub fn encode_items(items: List(event.Item)) -> String

Encode a whole sequence of SSE items to one String.

encode_items_bytes

</> 
pub fn encode_items_bytes(items: List(event.Item)) -> BitArray

Encode a whole sequence of SSE items to one BitArray.

encode_items_with_line_ending

</> 
pub fn encode_items_with_line_ending(
  items: List(event.Item),
  line_ending: encoder.LineEnding,
) -> String

encode_stream

</> 
pub fn encode_stream(
  items: stream.Iterator(event.Item),
) -> stream.Iterator(BitArray)

encode_with_line_ending

</> 
pub fn encode_with_line_ending(
  event: event.Event,
  line_ending: encoder.LineEnding,
) -> String

error_to_string

</> 
pub fn error_to_string(error: error.SseError) -> String

event

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

event_item

</> 
pub fn event_item(event: event.Event) -> event.Item

event_of_item

</> 
pub fn event_of_item(
  item: event.Item,
) -> option.Option(event.Event)

Return the event payload when the item is an event, None otherwise. Pairs with comment_text_of_item/1 for the comment side.

events_of

</> 
pub fn events_of(items: List(event.Item)) -> List(event.Event)

Filter a decoded item list down to its events, dropping comments. Convenience for the common “I just want the events” pattern after decode/1.

finish

</> 
pub fn finish(
  state: decoder.DecodeState,
) -> Result(List(event.Item), error.SseError)

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.Event

heartbeat

</> 
pub fn heartbeat() -> event.Item

id

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

id_of

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

is_comment

</> 
pub fn is_comment(item: event.Item) -> Bool

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

is_event

</> 
pub fn is_event(item: event.Item) -> Bool

Issue #77: Item-level inspection helpers exposed through the facade. The Item type is re-exported as a type alias from this module, but Gleam’s type aliases do not carry the underlying EventItem / CommentItem constructors — pattern-matching on a decoded Item therefore requires reaching into ssevents/event for the variants. These accessors let callers stay inside the facade for the common cases. True when the item is an event (carries an SSE Event payload).

iterator_from_list

</> 
pub fn iterator_from_list(items: List(a)) -> stream.Iterator(a)

iterator_next

</> 
pub fn iterator_next(
  iterator: stream.Iterator(a),
) -> stream.Step(a)

iterator_to_list

</> 
pub fn iterator_to_list(iterator: stream.Iterator(a)) -> List(a)

last_event_id

</> 
pub fn last_event_id(
  state: reconnect.ReconnectState,
) -> option.Option(String)

last_event_id_header

</> 
pub fn last_event_id_header(
  state: reconnect.ReconnectState,
) -> option.Option(#(String, String))

limits

</> 
pub fn limits() -> limit.Limits

max_data_bytes

</> 
pub fn max_data_bytes(
  event: event.Event,
  max: Int,
) -> Result(event.Event, error.SseError)

max_data_lines

</> 
pub fn max_data_lines(limits: limit.Limits) -> Int

max_event_bytes

</> 
pub fn max_event_bytes(limits: limit.Limits) -> Int

max_line_bytes

</> 
pub fn max_line_bytes(limits: limit.Limits) -> Int

max_retry_value

</> 
pub fn max_retry_value(limits: limit.Limits) -> Int

message

</> 
pub fn message(data: String) -> event.Event

name_of

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

named

</> 
pub fn named(name: String, data: String) -> event.Event

new

</> 
pub fn new(data: String) -> event.Event

new_decoder

</> 
pub fn new_decoder() -> decoder.DecodeState

new_decoder_with_limits

</> 
pub fn new_decoder_with_limits(
  limits: limit.Limits,
) -> decoder.DecodeState

new_limits

</> 
pub fn new_limits(
  max_line_bytes max_line_bytes: Int,
  max_event_bytes max_event_bytes: Int,
  max_data_lines max_data_lines: Int,
  max_retry_value max_retry_value: Int,
) -> limit.Limits

new_reconnect_state

</> 
pub fn new_reconnect_state() -> reconnect.ReconnectState

package_name

</> 
pub const package_name: String

push

</> 
pub fn push(
  state: decoder.DecodeState,
  chunk: BitArray,
) -> Result(
  #(decoder.DecodeState, List(event.Item)),
  error.SseError,
)

retry

</> 
pub fn retry(
  event: event.Event,
  milliseconds: Int,
) -> event.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. The builder panics on ms < 0; reach for retry_clamp/2 when the caller wants the lenient (clamp-to-0) posture.

retry_clamp

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

Like retry/2, but clamps milliseconds < 0 to 0 instead of panicking. Use this when forwarding a value computed from possibly- noisy input (e.g. a CLI flag, a deserialised config) and the caller would rather “publish a spec-valid retry” than crash.

retry_interval

</> 
pub fn retry_interval(
  state: reconnect.ReconnectState,
) -> option.Option(Int)

retry_of

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

update_reconnect

</> 
pub fn update_reconnect(
  state: reconnect.ReconnectState,
  item: event.Item,
) -> reconnect.ReconnectState

validate_event_name

</> 
pub fn validate_event_name(
  name: String,
) -> Result(String, error.SseError)

validate_id

</> 
pub fn validate_id(id: String) -> Result(String, error.SseError)

validate_retry

</> 
pub fn validate_retry(
  milliseconds: Int,
) -> Result(Int, error.SseError)
✨ Search Document