Skip to content
Effect 4.0 is here. One ecosystem. Zero dependencies.

Sse unstable

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.

21 exports Since v4.0.0 Source

Decoding

decode

unstable
Since v4.0.0

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 function decode<IE, Done>(options?: DecodeOptions): Channel<readonly [Event, Event], Retry | SseError | IE, Done, readonly [string, string], IE, Done>

decodeDataSchema

unstable
Since v4.0.0

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 function decodeDataSchema<Type, DecodingServices, IE, Done>(schema: ConstraintDecoder<Type, DecodingServices>, options?: DecodeOptions): Channel<readonly [{
  readonly data: Type;
  readonly event: string;
  readonly id: string | undefined;
}, {
  readonly data: Type;
  readonly event: string;
  readonly id: string | undefined;
}], SchemaError | Retry | SseError | IE, Done, readonly [string, string], IE, Done, DecodingServices>

DecodeOptions

interface unstable
Since v4.0.0

Options for decoding Server-Sent Events streams.

Signature

interface DecodeOptions {
  readonly dispatchEmptyNamedEvents?: boolean;
  readonly maxEventSize?: number;
}

decodeSchema

unstable
Since v4.0.0

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

Details

The schema receives { event, data, id? }, with string data. Absent IDs are omitted, even with default options: use Schema.optional(Schema.String), not Schema.UndefinedOr(Schema.String), to accept events without an ID.

With onExcessProperty: "error", declare event (default: "message") and id if the stream carries IDs, including inherited IDs.

Signature

declare function decodeSchema<S extends EventCodec, IE, Done>(schema: S, options?: DecodeOptions, parseOptions?: ParseOptions): Channel<readonly [S["Type"], S["Type"]], SchemaError | Retry | SseError | IE, Done, readonly [string, string], IE, Done, S["DecodingServices"]>

EventCodec

interface unstable
Since v4.0.0

A constraint for schemas that can decode SSE events.

Signature

interface EventCodec extends ConstraintCodec<any, {
  readonly data: string;
  readonly event?: string;
  readonly id?: string;
}, unknown, unknown> {}

makeParser

unstable
Since v4.0.0

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. feed returns an SseError if the pending event exceeds maxEventSize.

Signature

declare function makeParser(onParse: (event: AnyEvent) => void, options?: DecodeOptions): Parser

Parser

interface unstable
Since v4.0.0

Stateful Server-Sent Events parser returned by makeParser.

Details

feed accepts additional text chunks and returns an SseError when the configured pending event size is exceeded. reset clears buffered parser state.

Signature

interface Parser {
  feed(chunk: string): SseError | undefined;
  reset(): void;
}

Encoding

encode

unstable
Since v4.0.0

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 function encode<IE, Done>(): Channel<readonly [string, string], IE, void, readonly [Event, Event], Retry | IE, Done>

encoder

unstable
Since v4.0.0

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

Encoder

interface unstable
Since v4.0.0

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

Signature

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

encodeSchema

unstable
Since v4.0.0

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 function encodeSchema<S extends EventCodec, IE, Done>(schema: S): Channel<readonly [string, string], SchemaError | IE, void, readonly [S["Type"], S["Type"]], Retry | IE, Done, S["EncodingServices"]>

Errors

EventTooLarge

unstable
Since v4.0.0

Error reason raised when pending Server-Sent Events state exceeds the configured maximum size.

Signature

declare class EventTooLarge extends YieldableError<this> & {
  readonly _tag: "EventTooLarge";
} & Readonly<{
  readonly maxEventSize: number;
}> {
  constructor(args: {
    readonly maxEventSize: number;
  });
  message: string;
}

SseError

unstable
Since v4.0.0

Error raised when decoding a Server-Sent Events stream fails.

Signature

declare class SseError extends YieldableError<this> & {
  readonly _tag: "SseError";
} & Readonly<{
  readonly reason: EventTooLarge;
}> {
  constructor(args: {
    readonly reason: EventTooLarge;
  });
  readonly "~effect/encoding/Sse/SseError": "~effect/encoding/Sse/SseError";
  message: string;
}

SseErrorReason

type unstable
Since v4.0.0

Union of Server-Sent Events decoding error reasons.

Signature

type SseErrorReason = EventTooLarge

Models

AnyEvent

type unstable
Since v4.0.0

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

Signature

type AnyEvent = Event | Retry

Event

unstable
Since v4.0.0

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: Struct<{
  readonly _tag: tag<"Event">;
  readonly data: String;
  readonly event: String;
  readonly id: UndefinedOr<String>;
}>

Event

interface unstable
Since v4.0.0

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

Signature

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

EventEncoded

unstable
Since v4.0.0

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 data: Schema.String;
  readonly event: Schema.String;
  readonly id: Schema.optional<Schema.String>;
}>

EventEncoded

interface unstable
Since v4.0.0

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

Signature

interface EventEncoded {
  readonly data: string;
  readonly event: string;
  readonly id?: string;
}

Retry

unstable
Since v4.0.0

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 extends Readonly<{
  readonly duration: Duration;
  readonly lastEventId: string | undefined;
}> & {
  readonly _tag: "Retry";
} & Pipeable {
  constructor(args: {
    readonly duration: Duration;
    readonly lastEventId: string | undefined;
  });
  readonly "~effect/encoding/Sse/Retry": "~effect/encoding/Sse/Retry";
  static filter<A>(u: A): Result<Retry, Exclude<A, Retry>>;
  static is(u: unknown): u is Retry;
}

transformEvent

unstable
Since v4.0.0

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

Signature

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