@sourceregistry/sveltekit-eventsource

@sourceregistry/sveltekit-eventsource

Typed Server-Sent Events (SSE) integration for SvelteKit — strongly-typed client–server communication, custom event channels, and a protocol-level control layer.

---

Features

• Strong typing end-to-end — events are typed via App.Events, giving compile-time guarantees for both event names and payloads
• Bidirectional lifecycle control — server-initiated close via a versioned protocol message; client-initiated close with proper cleanup
• Protocol-level control channel — control messages bypass user serializers and are versioned, validated, and future-proof
• Custom event channels — native SSE event: field support with multiple application events per stream
• Debug hooks — optional structured logging on client and server
• Full TSDoc coverage — TypeDoc generation supported out of the box

---

Installation

npm install @sourceregistry/sveltekit-eventsource

Peer dependency: svelte@^5

---

Core Concept

Events are defined centrally using SvelteKit's App.Events interface:

// src/app.d.ts
declare global {
  namespace App {
    interface Events {
      status: {
        heartbeat: number;
      };
    }
  }
}

export {};

This single definition drives server-side emit() typing, client-side on() typing, and compile-time safety across the entire SSE pipeline.

---

Server Usage

// src/routes/sse/+server.ts
import type { RequestHandler } from "./$types";
import { EventSource } from "@sourceregistry/sveltekit-eventsource/server";

export const GET: RequestHandler = () => {
  const sse = new EventSource("status", { debug: true });

  const timer = setInterval(() => {
    sse.emit("heartbeat", Date.now());
  }, 2000);

  sse.once("close", () => {
    clearInterval(timer);
  });

  // Ask the client to close after 5 s
  setTimeout(() => {
    sse.stop();
  }, 5000);

  return sse.response();
};

Server API

Method / Property	Description
emit(event, payload, id?)	Send a typed application event
stop()	Send a protocol-level close request to the client
response(init?)	Return a Response with Content-Type: text/event-stream
isOpen	Whether the stream is currently open
on(event, handler)	Subscribe to lifecycle events (open, close, ping)
once(event, handler)	Subscribe once to a lifecycle event
off(event, handler)	Unsubscribe from a lifecycle event
unsafe.send(data, opts?)	Send an arbitrary untyped SSE message
unsafe.events	Raw EventEmitter for lifecycle hooks

---

Client Usage

<script lang="ts">
  import { onMount, onDestroy } from "svelte";
  import { EventSource } from "@sourceregistry/sveltekit-eventsource/client";

  const events = $state<number[]>([]);
  let state = $state<"open" | "closed">("closed");

  let es: EventSource<"status">;

  onMount(() => {
    es = new EventSource("/sse", { debug: true });

    es.onOpen(() => (state = "open"));
    es.onClose(() => (state = "closed"));

    es.on("heartbeat", (n) => {
      events.push(n);
    });
  });

  onDestroy(() => {
    es?.close();
  });
</script>

<p>Connection: {state}</p>

<ul>
  {#each events as e}
    <li>{e}</li>
  {/each}
</ul>

Client API

Method	Description
on(event, handler)	Subscribe to a typed application event
once(event, handler)	Subscribe once to a typed application event
off(event, handler)	Unsubscribe a handler registered with on or once
onOpen(handler)	Subscribe to the open lifecycle event
onClose(handler)	Subscribe to the close lifecycle event
onError(handler)	Subscribe to the error lifecycle event
onMessage(handler)	Subscribe to default (unnamed) SSE messages
close()	Initiate client-side close
readyState	Native EventSource.readyState

All handlers are fully typed via App.Events.

---

Control Protocol (SMCP)

This library implements a protocol-level control channel independent of user serialization. User serializers (JSON, base64, msgpack, etc.) must not interfere with control messages such as server-requested close.

Wire format:

event: __MAGIC_EVENT__
data: {"v":1,"op":"close"}

Control messages are always JSON, versioned (v), validated at runtime, and forward-compatible.

Full specification: docs/sse-magic-protocol.md

---

Package Exports

Path	Purpose
@sourceregistry/sveltekit-eventsource/client	Browser client
@sourceregistry/sveltekit-eventsource/server	SvelteKit server endpoint

---

Testing

Protocol compatibility tests are included using Vitest:

npm test

Coverage includes protocol encoding, version mismatch handling, schema validation, and forward-compatibility safeguards.

---

Documentation

Generate API documentation with TypeDoc:

npm run docs:build

Output is written to /docs.

---

Requirements

• Node.js ≥ 16
• SvelteKit application
• Standard SSE (HTTP/1.1 compatible, no polyfills required)

---

Roadmap

• Reconnect strategies and resume tokens
• Backpressure diagnostics
• Stream multiplexing
• Protocol v2 extensions

---

Contributing

Issues and pull requests are welcome. Please follow Conventional Commits — this project uses semantic-release for automated versioning and changelog generation.

---

License

Apache-2.0 A.P.A. Slaa