`SseEvent` + `sseEventSchema`

(no submodules)

Purpose

SseEvent is the wire-shape contract for a single Server-Sent-Events field block: id, optional event, data, optional retry. The Zod schema sseEventSchema validates the shape at every host → engine boundary so plugin authors catch typos (eventName vs event) at parse time instead of silently dropping fields on the wire.

The fields follow WHATWG and W3C SSE: every concrete engine serialises the parsed shape onto the wire as id: <id>\nevent: <event>\ndata: <data>\nretry: <ms>\n\n. Multi-line data is the engine's responsibility — splitting newlines into multiple data: lines is a wire-format concern, not part of this contract.

Features

strict() schema: unknown keys fail parse.
id is non-empty (powers the replay buffer's since(lastEventId) lookup).
event is non-empty when supplied; absent stays absent (no default).
retry is a non-negative integer; floats and negatives are rejected at parse.

Usage: Basic

import { sseEventSchema } from "@suaveplan/api-sse/event/event";

const event = sseEventSchema.parse({ id: "1", data: "hello" });

Usage: Advanced

import { sseEventSchema, type SseEvent } from "@suaveplan/api-sse/event/event";

function validatedSend(input: unknown): SseEvent {
    return sseEventSchema.parse(input);
}

const ping: SseEvent = validatedSend({
    id: "evt-42",
    event: "ping",
    data: JSON.stringify({ ts: Date.now() }),
    retry: 15_000,
});

API Reference

sseEventSchema: z.ZodObject<...> — strict Zod schema; parse(input) returns a typed SseEvent.
interface SseEvent — compile-time view: { id: string; event?: string; data: string; retry?: number }.

Implementation Notes

The interface is declared separately from the inferred Zod type so consumers can annotate handler arguments without paying for Zod inference cost in their public surface. The runtime schema is the only validator; engines MUST call sseEventSchema.parse(input) before queueing for the wire so the replay buffer can rely on a valid id field.

2.1 KiB Raw Blame History

SseEvent + sseEventSchema