better-sse Documentation

The examples directory contains several implementations of Better SSE categorized by use case, framework compatibility, and connection adapters:

Use Cases

• Getting Started: Basic introduction to the library.
• Channels: Using channels for organized event distribution.
• Streams: Working with streaming data.
• Benchmarks: Performance comparisons.
• Chat room: Implementing real-time chat functionality.
• System Resource Monitor: Monitoring system resources via SSE.

Frameworks & APIs

• Node HTTP/1 API: Implementation using standard Node.js HTTP/1.
• Node HTTP/2 Compatibility API: Implementation using Node.js HTTP/2.
• Fetch API: Implementation compatible with the Fetch API.

Connection Adapters

• Koa: Using the Koa connection adapter.

Better SSE is designed for high-performance real-time communication with the following capabilities:

• Easy real-time communication: Operates directly over HTTP without WebSockets, pinging, or long-polling.
• Multi-client broadcasting: Send events to specific individual clients or broadcast to many clients simultaneously using broadcast channels.
• Web standards compliant: Full compliance with the WHATWG SSE specification and support for frameworks using the Fetch API.
• Event batching: Improves performance and reduces bandwidth by batching multiple events into a single transmission.
• First-class TypeScript: Ships with built-in types, allowing you to define types for state and event data.
• Highly configurable: Supports customization of reconnection time, message serialization, data sanitization, and response headers.

Channels allow you to group multiple sessions together and broadcast a single event to all registered clients simultaneously.

1. Create a channel using createChannel().
2. Register a session to the channel using channel.register(session).
3. Send a message to all clients in the channel using channel.broadcast(data, eventName).

import { createSession, createChannel } from "better-sse"

const channel = createChannel()

app.get("/sse", async (req, res) => {
	const session = await createSession(req, res)

	channel.register(session)

	channel.broadcast("A user has joined.", "join-notification")
})

If your framework is not supported by the built-in NodeHttp1Connection, NodeHttp2CompatConnection, or FetchConnection, you can implement the Connection abstract class.

To implement a Connection, you must provide:

• url: The URL of the connection.
• request: A Request object representing the incoming request. Its signal should trigger when the connection closes.
• response: A Response object representing the outgoing response.
• sendHead(): An abstract method to send the response status and headers.
• sendChunk(chunk: string): An abstract method to write data chunks (UTF-8 encoded).
• cleanup(): An abstract method for resource cleanup.

Connection.applyHeaders is a static utility available to help merge header objects into a Headers instance.

In Better SSE, connection adapters implement the underlying connection logic, acting as the bridge between the library and your specific protocol, framework, or runtime.

While sessions manage the high-level request/response lifecycle and SSE-specific data formatting, connection adapters are responsible for:

• Extracting request headers and query parameters.
• Sending response headers and data chunks.
• Reporting when the connection closes.

Better SSE automatically detects and uses the appropriate built-in adapter based on the arguments you pass to createResponse or createSession.

Better SSE provides a dead simple, dependency-less, and spec-compliant implementation for real-time server-to-client communication over HTTP. It allows for multi-client broadcasting, event batching, and full TypeScript support without requiring WebSockets or long-polling.

// Server-side setup example
import { createSSE } from 'better-sse';

const sse = createSSE();

// In your HTTP handler:
// return sse.respond(res);

For Fetch-based environments like Hono or Cloudflare Workers, use createResponse.

• Hono: Pass the raw request object c.req.raw to createResponse.
• Cloudflare Workers: Requires enabling nodejs_compat in your wrangler.jsonc configuration to support the necessary polyfills.

// Hono Example
import { Hono } from "hono"
import { serve } from "@hono/node-server"
import { createResponse } from "better-sse"

const app = new Hono()

app.get("/sse", (c) =>
    createResponse(c.req.raw, (session) => {
        session.push("Hello world!")
    })
)

serve({ fetch: app.fetch, port: 8080 })

To explore the provided examples, follow these steps to install dependencies and start a specific example project:

1. Navigate to the examples directory and install dependencies:

   cd examples
   npm i

2. Navigate to the specific example directory you wish to run (e.g., getting-started):

   cd getting-started

3. Start the example:

   npm run start

cd examples && npm i
cd getting-started && npm run start

NestJS integration depends on the underlying platform used:

• @nestjs/platform-express: Use await createSession(req, res) where req and res are standard Express objects.
• @nestjs/platform-fastify: Use await createSession(req.raw, res.raw) to pass the underlying Node.js HTTP objects to Better SSE.

// NestJS Fastify Example
import { Controller, Get, Req, Res } from "@nestjs/common"
import { FastifyReply, FastifyRequest } from "fastify"
import { createSession } from "better-sse"

@Controller()
export class SseController {
  @Get("sse")
  async sse(@Req() req: FastifyRequest, @Res() res: FastifyReply) {
    const session = await createSession(req.raw, res.raw)
    session.push("Hello world!")
  }
}

When working with the standard Node.js HTTP/1 API (such as with Express), passing IncomingMessage and ServerResponse objects to createSession will trigger the use of the NodeHttp1Connection adapter.

import { createSession } from "better-sse"

// Example using Express
app.get("/sse", async (req, res) => {
    const session = await createSession(req, res)
    session.push("Hello world!")
})