@suckless/sse 0.6.0

package/README.md

@@ -0,0 +1,80 @@
+# @suckless/sse
+
+Server-Sent Events channel for Web API servers. Zero dependencies, runtime-agnostic.
+
+## Install
+
+```sh
+npm install @suckless/sse
+```
+
+## Usage
+
+```ts
+import { createSSEChannel } from "@suckless/sse"
+
+const channel = createSSEChannel({ heartbeat: 15_000, replay: 50 })
+
+// In your request handler
+function handler(req: Request): Response {
+	return channel.connect(req)
+}
+
+// Broadcast from anywhere
+channel.send("message", { text: "hello" })
+channel.send("update", { count: 42 })
+
+// Cleanup
+channel.close()
+```
+
+## How it works
+
+Each call to `connect()` creates a `ReadableStream` wired to the client via the standard `Response` constructor. Events are broadcast to all connected clients as SSE-formatted text chunks. Clients that disconnect (via `AbortSignal` or stream cancellation) are cleaned up automatically.
+
+Optional keepalive comments (`: keepalive`) prevent proxies and load balancers from closing idle connections. An optional replay buffer stores recent events so reconnecting clients can catch up via the `Last-Event-ID` header.
+
+To avoid unbounded memory growth, clients that stop draining their stream are disconnected once their pending buffer exceeds the internal safety limit.
+
+## API
+
+### `createSSEChannel(options?): SSEChannel`
+
+Creates a new SSE channel.
+
+| Option      | Type     | Default | Description                                               |
+| ----------- | -------- | ------- | --------------------------------------------------------- |
+| `heartbeat` | `number` | `15000` | Keepalive interval in ms. Set to `0` to disable.          |
+| `replay`    | `number` | `0`     | Number of recent events to buffer. Set to `0` to disable. |
+
+### `channel.connect(req): Response`
+
+Accepts a `Request` and returns an SSE `Response`. Honors `Last-Event-ID` for replay. Returns a `503` if the channel is closed.
+
+### `channel.send(event, data): void`
+
+Broadcasts an event to all connected clients. `event` must not contain CR/LF characters, and `data` must serialize with `JSON.stringify()`. Throws if validation fails or the channel is closed.
+
+### `channel.close(): void`
+
+Closes the channel, disconnects all clients, and clears the replay buffer. Idempotent.
+
+### `channel.clients: number`
+
+Number of currently connected clients.
+
+### Cleanup
+
+The channel implements the standard disposal protocol:
+
+```ts
+using channel = createSSEChannel()
+```
+
+`using` requires toolchain support for Explicit Resource Management (TypeScript 5.2+).
+
+You can also call `channel[Symbol.dispose]()` directly.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,28 @@
+/** JSON-serializable value. Includes objects with a `toJSON()` method (e.g. `Date`). */
+type JsonValue = string | number | boolean | null | {
+	toJSON(): unknown;
+} | JsonValue[] | {
+	[key: string]: JsonValue;
+};
+interface SSEChannelOptions {
+	/** Keepalive interval in milliseconds. Set to 0 to disable. Default: 15000. */
+	heartbeat?: number;
+	/** Number of recent events to buffer for Last-Event-ID reconnection. Set to 0 to disable. Default: 0. */
+	replay?: number;
+}
+/** Server-Sent Events channel. */
+interface SSEChannel {
+	/** Number of currently connected clients. */
+	readonly clients: number;
+	/** Connect a request and return an SSE response stream. */
+	connect(req: Request): Response;
+	/** Broadcast an event to all connected clients. */
+	send(event: string, data: JsonValue): void;
+	/** Close the channel and disconnect all clients. */
+	close(): void;
+	/** Dispose the channel. Equivalent to calling `close()`. */
+	[Symbol.dispose](): void;
+}
+/** Create a Server-Sent Events channel. */
+declare function createSSEChannel(options?: SSEChannelOptions): SSEChannel;
+export { createSSEChannel, SSEChannelOptions, SSEChannel, JsonValue };

package/dist/index.js

@@ -0,0 +1,168 @@
+// packages/sse/src/index.ts
+var encoder = new TextEncoder;
+var KEEPALIVE_CHUNK = encoder.encode(`: keepalive
+
+`);
+var STREAM_HIGH_WATER_MARK = 64 * 1024;
+function createSSEChannel(options) {
+  const heartbeatMs = options?.heartbeat ?? 15000;
+  const replaySize = options?.replay ?? 0;
+  if (heartbeatMs < 0 || !Number.isFinite(heartbeatMs)) {
+    throw new RangeError("heartbeat must be a non-negative finite number");
+  }
+  if (!Number.isInteger(replaySize) || replaySize < 0) {
+    throw new RangeError("replay must be a non-negative integer");
+  }
+  const replayBuffer = [];
+  const connections = new Map;
+  let nextClientId = 0;
+  let nextEventId = 0;
+  let closed = false;
+  function disconnect(clientId) {
+    const client = connections.get(clientId);
+    if (!client) {
+      return;
+    }
+    connections.delete(clientId);
+    if (client.heartbeat !== undefined) {
+      clearInterval(client.heartbeat);
+    }
+    client.signal.removeEventListener("abort", client.onAbort);
+    try {
+      client.controller.close();
+    } catch {}
+  }
+  function enqueue(clientId, chunk) {
+    const client = connections.get(clientId);
+    if (!client) {
+      return;
+    }
+    const { desiredSize } = client.controller;
+    if (desiredSize !== null && desiredSize < chunk.byteLength) {
+      disconnect(clientId);
+      return;
+    }
+    try {
+      client.controller.enqueue(chunk);
+    } catch {
+      disconnect(clientId);
+    }
+  }
+  function replay(clientId, lastEventId) {
+    if (!/^\d+$/.test(lastEventId)) {
+      return;
+    }
+    const id = Number(lastEventId);
+    if (!Number.isSafeInteger(id)) {
+      return;
+    }
+    for (const entry of replayBuffer) {
+      if (entry.id > id) {
+        enqueue(clientId, entry.chunk);
+      }
+    }
+  }
+  function serializeEvent(id, event, data) {
+    if (event.includes(`
+`) || event.includes("\r")) {
+      throw new RangeError("event must not contain CR or LF");
+    }
+    const payload = JSON.stringify(data);
+    if (payload === undefined) {
+      throw new TypeError("data must be JSON-serializable");
+    }
+    return encoder.encode(`id: ${id}
+event: ${event}
+data: ${payload}
+
+`);
+  }
+  return {
+    get clients() {
+      return connections.size;
+    },
+    connect(req) {
+      if (closed) {
+        return new Response("channel closed", { status: 503 });
+      }
+      const clientId = nextClientId++;
+      const lastEventId = req.headers.get("Last-Event-ID");
+      const stream = new ReadableStream({
+        start: (controller) => {
+          let heartbeat;
+          const onAbort = () => {
+            disconnect(clientId);
+          };
+          if (heartbeatMs > 0) {
+            heartbeat = setInterval(() => {
+              enqueue(clientId, KEEPALIVE_CHUNK);
+            }, heartbeatMs);
+            if (typeof heartbeat === "object" && "unref" in heartbeat) {
+              heartbeat.unref();
+            }
+          }
+          connections.set(clientId, {
+            controller,
+            heartbeat,
+            signal: req.signal,
+            onAbort
+          });
+          if (req.signal.aborted) {
+            disconnect(clientId);
+            return;
+          }
+          req.signal.addEventListener("abort", onAbort, {
+            once: true
+          });
+          if (lastEventId !== null) {
+            replay(clientId, lastEventId);
+          }
+        },
+        cancel: () => {
+          disconnect(clientId);
+        }
+      }, {
+        highWaterMark: STREAM_HIGH_WATER_MARK,
+        size: (chunk) => chunk?.byteLength ?? 0
+      });
+      return new Response(stream, {
+        headers: {
+          "Content-Type": "text/event-stream; charset=utf-8",
+          "Cache-Control": "no-cache, no-transform",
+          "X-Accel-Buffering": "no"
+        }
+      });
+    },
+    send(event, data) {
+      if (closed) {
+        throw new Error("Channel is closed");
+      }
+      const id = nextEventId++;
+      const chunk = serializeEvent(id, event, data);
+      if (replaySize > 0) {
+        replayBuffer.push({ id, chunk });
+        if (replayBuffer.length > replaySize) {
+          replayBuffer.shift();
+        }
+      }
+      for (const clientId of connections.keys()) {
+        enqueue(clientId, chunk);
+      }
+    },
+    close() {
+      closed = true;
+      for (const clientId of connections.keys()) {
+        disconnect(clientId);
+      }
+      replayBuffer.length = 0;
+    },
+    [Symbol.dispose]() {
+      if (!closed) {
+        this.close();
+      }
+    }
+  };
+}
+export {
+  createSSEChannel
+};

package/package.json

@@ -0,0 +1,47 @@
+{
+	"name": "@suckless/sse",
+	"version": "0.6.0",
+	"description": "Server-Sent Events channel for Web API servers",
+	"keywords": [
+		"eventsource",
+		"realtime",
+		"server-sent-events",
+		"sse",
+		"streaming",
+		"suckless",
+		"typescript"
+	],
+	"homepage": "https://github.com/brielov/suckless/tree/master/packages/sse#readme",
+	"bugs": "https://github.com/brielov/suckless/issues",
+	"license": "MIT",
+	"author": "brielov",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/brielov/suckless.git",
+		"directory": "packages/sse"
+	},
+	"files": [
+		"dist"
+	],
+	"type": "module",
+	"sideEffects": false,
+	"module": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"exports": {
+		".": {
+			"import": {
+				"types": "./dist/index.d.ts",
+				"default": "./dist/index.js"
+			}
+		},
+		"./package.json": "./package.json"
+	},
+	"peerDependencies": {
+		"typescript": ">=5.2.0"
+	},
+	"peerDependenciesMeta": {
+		"typescript": {
+			"optional": true
+		}
+	}
+}