Sse.ts

Sse.ts overview

Parses and renders Server-Sent Events text streams.

Server-Sent Events, or SSE, are the text format used by EventSource for one-way server-to-client updates. This module includes parsers, encoders, channel helpers, and schema-based helpers for the id, event, and data fields of each event.

Since v4.0.0

decoding

EventCodec (interface)

A constraint for schemas that can decode SSE events.

Signature

export interface EventCodec extends Schema.Codec<
  any,
  {
    readonly id?: string | undefined
    readonly event?: string | undefined
    readonly data: string
  },
  any,
  any
> {}

Source

Since v4.0.0

Parser (interface)

Stateful Server-Sent Events parser returned by makeParser.

Details

feed accepts additional text chunks and reset clears buffered parser state.

Signature

export interface Parser {
  feed(chunk: string): void
  reset(): void
}

Source

Since v4.0.0

decode

Creates a channel that parses Server-Sent Events text chunks into Event values.

Details

SSE retry directives are emitted as Retry failures so callers can reconnect with the requested delay.

Signature

declare const decode: <IE, Done>() => Channel.Channel<
  NonEmptyReadonlyArray<Event>,
  IE | Retry,
  Done,
  NonEmptyReadonlyArray<string>,
  IE,
  Done
>

Source

Since v4.0.0

decodeDataSchema

Creates an SSE decoder channel that JSON-decodes each event data field with a schema.

Details

The output preserves the SSE event name and optional id while replacing data with the decoded value.

Signature

declare const decodeDataSchema: <Type, DecodingServices, IE, Done>(
  schema: Schema.ConstraintDecoder<Type, DecodingServices>
) => Channel.Channel<
  NonEmptyReadonlyArray<{ readonly event: string; readonly id: string | undefined; readonly data: Type }>,
  IE | Retry | Schema.SchemaError,
  Done,
  NonEmptyReadonlyArray<string>,
  IE,
  Done,
  DecodingServices
>

Source

Since v4.0.0

decodeSchema

Creates an SSE decoder channel that decodes each parsed event with a schema.

Details

The schema receives the untagged event shape containing id, event, and string data.

Signature

declare const decodeSchema: <S extends EventCodec, IE, Done>(
  schema: S
) => Channel.Channel<
  NonEmptyReadonlyArray<S["Type"]>,
  IE | Retry | Schema.SchemaError,
  Done,
  NonEmptyReadonlyArray<string>,
  IE,
  Done,
  S["DecodingServices"]
>

Source

Since v4.0.0

makeParser

Creates a stateful Server-Sent Events parser.

Details

Call feed with text chunks to parse Event and Retry values through the callback, and call reset to clear any buffered event state.

Signature

declare const makeParser: (onParse: (event: AnyEvent) => void) => Parser

Source

Since v4.0.0

encoding

Encoder (interface)

Encoder capable of rendering an Event or Retry value as Server-Sent Events text.

Signature

export interface Encoder {
  write(event: AnyEvent): string
}

Source

Since v4.0.0

encode

Creates a channel that encodes Event values as Server-Sent Events text.

Details

If the upstream channel fails with Retry, the retry directive is written and the encoder completes.

Signature

declare const encode: <IE, Done>() => Channel.Channel<
  NonEmptyReadonlyArray<string>,
  IE,
  void,
  NonEmptyReadonlyArray<Event>,
  IE | Retry,
  Done
>

Source

Since v4.0.0

encodeSchema

Creates an SSE encoder channel for values accepted by a schema.

Details

Values are schema-encoded to the untagged SSE event shape, transformed to Event, and then written as Server-Sent Events text.

Signature

declare const encodeSchema: <S extends EventCodec, IE, Done>(
  schema: S
) => Channel.Channel<
  NonEmptyReadonlyArray<string>,
  IE | Schema.SchemaError,
  void,
  NonEmptyReadonlyArray<S["Type"]>,
  IE | Retry,
  Done,
  S["EncodingServices"]
>

Source

Since v4.0.0

encoder

Default Server-Sent Events encoder.

Details

It renders Event values as id, event, and data lines and renders Retry values as retry: directives.

Signature

declare const encoder: Encoder

Source

Since v4.0.0

models

AnyEvent (type alias)

Union of SSE values that can be rendered by an Encoder: regular events and retry directives.

Signature

type AnyEvent = Event | Retry

Source

Since v4.0.0

Event

Schema for the tagged Server-Sent Events message model that adds _tag: "Event" to the event name, optional event ID, and string data payload.

Signature

declare const Event: Schema.Struct<{
  readonly _tag: Schema.tag<"Event">
  readonly id: Schema.UndefinedOr<Schema.String>
  readonly event: Schema.String
  readonly data: Schema.String
}>

Source

Since v4.0.0

Event (interface)

Tagged model for a Server-Sent Events message containing the event name, optional event ID, and string data payload.

Signature

export interface Event {
  readonly _tag: "Event"
  readonly event: string
  readonly id: string | undefined
  readonly data: string
}

Source

Since v4.0.0

EventEncoded

Schema for the untagged Server-Sent Events payload shape containing an optional id, event, and string data fields.

Signature

declare const EventEncoded: Schema.Struct<{
  readonly id: Schema.optional<Schema.String>
  readonly event: Schema.String
  readonly data: Schema.String
}>

Source

Since v4.0.0

EventEncoded (interface)

Untagged Server-Sent Events payload shape containing the event name, optional event ID, and string data payload.

Signature

export interface EventEncoded {
  readonly event: string
  readonly id?: string | undefined
  readonly data: string
}

Source

Since v4.0.0

Retry (class)

Represents a Server-Sent Events retry directive.

Details

Decoders surface this value as a failure to request reconnection after duration; encoders serialize an upstream Retry failure as a retry: line.

Signature

declare class Retry

Source

Since v4.0.0

is (static method)

Returns true when the value is an SSE retry directive.

Signature

declare const is: (u: unknown) => u is Retry

Source

Since v4.0.0

filter (static method)

Separates SSE retry directives from regular event values.

Signature

declare const filter: <A>(u: A) => Result.Result<Retry, Exclude<A, Retry>>

Source

Since v4.0.0

[RetryTypeId] (property)

Marks this value as an SSE retry directive for runtime guards.

Signature

readonly [RetryTypeId]: "~effect/encoding/Sse/Retry"

Source

Since v4.0.0

transformEvent

Schema for transforming untagged SSE event payloads into tagged Event models.

Signature

declare const transformEvent: SchemaTransformation.Transformation<
  { readonly id?: string | undefined; readonly event?: string | undefined; readonly data: string },
  { readonly _tag: "Event"; readonly id: string | undefined; readonly event: string; readonly data: string },
  never,
  never
>

Source

Since v4.0.0