h3-sse v0.0.12

H3 SSE

H3 utilities for server sent events

Table of Contents

• Installation
• Basic Usage
  • Autoclose Parameter
• Advanced Messages
• Accessing Last Event ID
• Closing the stream and connection

Installation

npm install h3-sse

pnpm install h3-sse

Basic Usage

import { eventHandler } from 'h3';
import { createEventStream, sendEventStream } from 'h3-sse';

eventHandler((event) => {
    const eventStream = createEventStream(event);

    // send a message every second
    const interval = setInterval(async () => {
        await eventStream.push('hello world');
    }, 1000);

    // cleanup when the connection is closed
    eventStream.onClose(async () => {
        clearInterval(interval);
    });

    // send the stream to the client
    await eventStream.send();
});

It's important to note that sendEventStream() must be called before you can start pushing messages. So if you want to send an initial message you would have to do it like so.

eventHandler(async (event) => {
    const eventStream = createEventStream(event);

    // this must be called before pushing the first message;
    // additionally this should NOT be awaited because it will block everything until the stream is closed
    eventStream.send();
    await eventStream.push('hello world');

    const interval = setInterval(async () => {
        await eventStream.push('hello world');
    }, 1000);

    eventStream.onClose(async () => {
        clearInterval(interval);
    });
});

Autoclose Parameter

By default EventStreams will automatically be closed when the request has been closed by either the client or the server. If you wish to change this behavior you can set autoclose to false like so:

const eventStream = createEventStream(event, { autoclose: false });

This means if you want to close the stream after a connection has closes you will need to listen to it yourself:

const eventStream = createEventStream(event, { autoclose: false });

event.node.req.on('close', async () => {
    await eventStream.close();
});

Advanced Messages

eventStream.push() accepts a string or an EventStreamMessage

When sending a string the input will be placed into the "data" field.

When sending EventStreamMessage you are able to send additional metadata such as an eventId and eventName. However the main data should be placed in the "data" field. For info on what all of these fields do please read here

// this
await eventStream.push('hello world');
// is equivalent to this
await eventStream.push({
    data: 'hello world',
});

// however the EventStreamMessage let's you add additional metadata fields
await eventStream.push({
    id: '1', // the event id
    event: 'message' // the event name. When blank the client assumes this is "message"
    data: 'hello world',
    retry: 200, // how long the client should wait before trying to reconnect

});

If you want to send an object you must first serialize it to a string.

const user = {
    id: '1',
    name: 'john doe',
    email: 'johndoe@gmail.com',
};
// without metadata
await eventStream.push(JSON.stringify(user));

// with metadata
await eventStream.push({
    data: JSON.stringify(user),
});

Accessing Last Event ID

For details about this header see here.

const eventStream = createEventStream(event);
eventStream.lastEventId; // string | undefined;

Closing the Stream and Connection

Calling eventStream.close() will close the stream and if the stream has been handed to the client it will also close the connection.

eventHandler((event) => {
    const eventStream = createEventStream(event);
    // send 10 messages then close the stream and connection
    let msgCount = 0;
    setInterval(async () => {
        msgCount++;
        await eventStream.push(`hello world ${msgCount}`);
        if (msgCount >= 10) {
            clearInterval(interval);
            await eventStream.close();
        }
    }, 1000);
    await eventStream.send();
});

Be aware that spec compliant SSE clients will auto-reconnect when the connection is closed. To get around this you can send a "done" or "finished" event and then add logic to the client application to stop reconnecting.

eventHandler((event) => {
    const eventStream = createEventStream(event);
    let msgCount = 0;
    setInterval(async () => {
        msgCount++;
        await eventStream.push(`hello world ${msgCount}`);
        if (msgCount >= 0) {
            // send some kind of "finished" 'event
            // then add logic to the client to stop
            await eventStream.push('done');
            // alternative
            await eventStream.push({
                event: 'done',
                data: 'No more data',
            });
            // cleanup
            clearInterval(interval);
            await eventStream.close();
        }
    }, 1000);
    await eventStream.send();
});