Event Source Plus

The default browser EventSource API has too many restrictions. Event Source Plus fixes that.

Features

• Use any HTTP method
• Send custom headers
• Pass data as body or query params
• Runs in browsers, NodeJS, and workers
• Automatic retry with exponential backoff and hooks for customizing behavior
• ESM and CommonJS support

Table of Contents

• Usage
  • Basic Request
  • Canceling Requests
  • Additional Options
  • Working with Headers
• Listen Hooks

Usage

Basic Request

import { EventSourcePlus } from "event-source-plus";

const eventSource = new EventSourcePlus("https://example.com");

eventSource.listen({
    onMessage(message) {
        console.log(message);
    },
});

Canceling Requests

The listen() method returns a controller that you can use to abort the request.

const controller = eventSource.listen({
    onMessage(message) {
        console.log(message);
    },
});
controller.abort();

Additional Options

The EventSourcePlus constructor allows you to pass additional fetch options such as method, body, and headers.

const eventSource = new EventSourcePlus("https://example.com", {
    method: "post",
    body: JSON.stringify({ message: "hello world" }),
    headers: {
        "Content-Type": "application/json",
    },
});

Working with Headers

Headers can be set by passing an object or a function.

// object syntax //
const eventSource = new EventSourcePlus("https://example.com", {
    // this value will remain the same for every request
    headers: {
        Authorization: "some-token",
    },
});

// function syntax //
function getHeaders() {
    return {
        Authorization: "some-token",
    };
}
const eventSource = new EventSourcePlus("https://example.com", {
    // this function will rerun every time a request is sent
    headers: getHeaders,
});

The function syntax is especially useful when dealing with authentication because it allows you to always get a fresh auth token. This usually a pain point when working other SSE client libraries.

Listen Hooks

The listen() method has the following hooks:

• onMessage
• onRequest
• onRequestError
• onResponse
• onResponseError

The only required hook is onMessage.

onMessage(message)

onMessage is called whenever receiving a new Server Sent Event from the server.

eventSource.listen({
    onMessage(message) {
        console.log(message);
    },
});

onRequest({ request, options })

onRequest is called as soon as a request is constructed. This allows you to modify the request or do simple logging.

eventSource.listen({
    onRequest({ request, options }) {
        console.log(request, options);

        // add current time query search params
        options.query = options.query || {};
        options.query.t = new Date();
    },
});

onRequestError({request, options, error})

onRequestError will be called when the request fails.

eventSource.listen({
    async onRequestError({ request, options, error }) {
        console.log(`[request error]`, request, error);
    },
});

Some example errors might be Connection refused or Failed to parse URL

onResponse({ request, options, response })

onResponse will be called after receiving a response from the server.

eventSource.listen({
    async onResponse({ request, response, options }) {
        console.log(`Received status code: ${response.status}`);
    },
});

onResponseError({ request, options, response })

onResponseError will fire if one of the following conditions have been met

• response.ok is not true (i.e. server returned an error status code)
• The Content-Type header sent by the server doesn't include text/event-stream

eventSource.listen({
    async onResponseError({ request, response, options }) {
        console.log(
            `[response error]`,
            request,
            response.status,
            response.body,
        );
    },
});