😎
Flux SSE
A middleware function that brings real-time updates to your server-client communication using server-sent events (SSE).
📚 Core Features 📚
🌍 Browser Compatibility: Ensure cross-browser support.🔄 Connection Management: Handle connections efficiently.📡 Event Streaming: Stream data to clients.❤️ Heartbeat Mechanism: Maintain live connections.🛠️ Custom Configuration: Adjust settings per needs.🚧 Clean Up: Graceful connection termination.
Installation
To use this middleware, install it via npm:
npm install flux-sse
Usage
Import the useSSE
function from the module and add it as middleware to your Express application. Here's an example to get you started:
import express from "express";
import {useSSE} from "flux-sse";
const app = express();
// Add Flux SSE to specific routes
app.get("/sse-events", useSSE, (req, res) => {
// Handle SSE events for this route
});
app.listen(3000, () => {
console.log("Server is up and running on port 3000 🚀");
});
🛠️
Configuration Options The useSSE
middleware function accepts a configuration object with the following options:
Option | Type | Description |
---|---|---|
onClose |
() => void |
A callback function to be executed when the SSE connection is closed. |
heartbeatIntervalMs |
number |
The interval (in milliseconds) at which a heartbeat event should be sent to keep the connection alive. Default: 10000 (10 seconds). |
heartbeatCallback |
() => void |
A callback function to be executed each time a heartbeat event is sent. |
event |
string |
The default event type for SSE events. |
retry |
number |
The time (in milliseconds) that the client should wait before reconnecting if the connection is lost. |
id |
string |
The ID to include in SSE comments. |
bufferSize |
number |
The maximum number of events to store in the event buffer before flushing. |
throttleMs |
number |
The minimum time (in milliseconds) between consecutive SSE events sent to the same client. |
maxRequestsPerSecond |
number |
The maximum number of SSE requests allowed per second from a single client. |
🚀
Extended Response Type The SSEResponse
type extends the ServerResponse
and Response
types from the http
and express
modules, respectively. It includes additional methods for
sending SSE events and managing subscriptions.
SSE Methods
The SSEResponse
object provides the following SSE-specific methods:
sseSend(data: unknown, options?: SSEOptions): void
✉️
Sends an SSE event with the specified data
and options
. The data
can be any JavaScript object or value. The options
parameter is an object that can
contain the following properties:
-
event
(optional): The event type for the SSE event. -
retry
(optional): The time (in milliseconds) that the client should wait before retrying the connection if an error occurs. -
id
(optional): The
ID for the SSE event.
-
eventId
(optional): The ID of the acknowledged event (to be used for acknowledging the event).
sseComment(comment: string): void
💬
Sends an SSE comment with the specified comment
string. SSE comments are non-event messages that can be used for various purposes.
sseAcknowledge(eventId: string): void
✅
Acknowledges an SSE event with the specified eventId
. This is useful for notifying the client that a particular event has been processed or received.
subscribeToEvent(event: string): void
🔔
Subscribes the client to the specified event
type. Once subscribed, the client will receive SSE events of the subscribed type.
unsubscribeFromEvent(event: string): void
🔕
Unsubscribes the client from the specified event
type. The client will no longer receive SSE events of the unsubscribed type.
📄
License This project is licensed under the MIT License.