Sse
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.
Decoding
Signature
declare function decode<IE, Done>(
options?: DecodeOptions,
): Channel<
readonly [Event, Event],
Retry | SseError | IE,
Done,
readonly [string, string],
IE,
Done
>;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 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
Options for decoding Server-Sent Events streams.
Signature
interface DecodeOptions {
readonly maxEventSize?: number;
}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 function decodeSchema<S extends EventCodec, IE, Done>(
schema: S,
options?: DecodeOptions,
): Channel<
readonly [S["Type"], S["Type"]],
SchemaError | Retry | SseError | IE,
Done,
readonly [string, string],
IE,
Done,
S["DecodingServices"]
>;EventCodec interface
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
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;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
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
>;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 capable of rendering an Event or Retry value as Server-Sent Events text.
Signature
interface Encoder {
write(event: AnyEvent): string;
}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 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
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;
}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
Union of Server-Sent Events decoding error reasons.
Signature
type SseErrorReason = EventTooLarge;Models
Union of SSE values that can be rendered by an Encoder: regular events and retry directives.
Signature
type AnyEvent = Event | Retry;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>;
}>;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
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
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;
}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
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
>;
Creates a channel that parses Server-Sent Events text chunks into
Eventvalues.Details
SSE
retrydirectives are emitted asRetryfailures so callers can reconnect with the requested delay.