Fetch Event Source

This package provides a better API for making Event Source requests - also known as server-sent events - with all the features available in the Fetch API.

The default browser EventSource API imposes several restrictions on the type of request you're allowed to make: the only parameters you're allowed to pass in are the url and withCredentials, so:
* You cannot pass in a request body: you have to encode all the information necessary to execute the request inside the URL, which is limited to 2000 characters in most browsers.
* You cannot pass in custom request headers
* You can only make GET requests - there is no way to specify another method.
* If the connection is cut, you don't have any control over the retry strategy: the browser will silently retry for you a few times and then stop, which is not good enough for any sort of robust application.

This library provides an alternate interface for consuming server-sent events, based on the Fetch API. It is fully compatible with the Event Stream format, so if you already have a server emitting these events, you can consume it just like before. However, you now have greater control over the request and response so:

* You can use any request method/headers/body, plus all the other functionality exposed by fetch(). You can even provide an alternate fetch() implementation, if the default browser implementation doesn't work for you.
* You have access to the response object if you want to do some custom validation/processing before parsing the event source. This is useful in case you have API gateways (like nginx) in front of your application server: if the gateway returns an error, you might want to handle it correctly.
* If the connection gets cut or an error occurs, you have full control over the retry strategy.

In addition, this library also plugs into the browser's Page Visibility API so the connection closes if the document is hidden (e.g., the user minimizes the window), and automatically retries with the last event ID when it becomes visible again. This reduces the load on your server by not having open connections unnecessarily (but you can opt out of this behavior if you want.)

Install

``sh
npm install @rayjp2010/fetch-event-source
`

Usage

`ts
// BEFORE:
const sse = new EventSource('/api/sse');
sse.onmessage = (ev) => {
console.log(ev.data);
};

// AFTER:
import { fetchEventSource } from '@rayjp2010/fetch-event-source';

await fetchEventSource('/api/sse', {
onmessage(ev) {
console.log(ev.data);
}
});
`

You can pass in all the other parameters exposed by the default fetch API, for example:
`ts
const ctrl = new AbortController();
fetchEventSource('/api/sse', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
},
body: JSON.stringify({
foo: 'bar'
}),
signal: ctrl.signal,
});
`

You can use a function for headers to get fresh values on each request/retry, useful for refreshing auth tokens:
`ts
fetchEventSource('/api/sse', {
headers: () => ({
Authorization: Bearer ${getLatestToken()},
}),
onmessage(msg) {
console.log(msg.data);
}
});
`

You can add better error handling, for example:
`ts
class RetriableError extends Error { }
class FatalError extends Error { }

fetchEventSource('/api/sse', {
async onopen(response) {
if (response.ok && response.headers.get('content-type') === EventStreamContentType) {
return; // everything's good
} else if (response.status >= 400 && response.status < 500 && response.status !== 429) {
// client-side errors are usually non-retriable:
throw new FatalError();
} else {
throw new RetriableError();
}
},
onmessage(msg) {
// if the server emits an error message, throw an exception
// so it gets handled by the onerror callback below:
if (msg.event === 'FatalError') {
throw new FatalError(msg.data);
}
},
onclose() {
// if the server closes the connection unexpectedly, retry:
throw new RetriableError();
},
onerror(err) {
if (err instanceof FatalError) {
throw err; // rethrow to stop the operation
} else {
// do nothing to automatically retry. You can also
// return a specific retry interval here.
}
}
});
`

You can implement exponential backoff to avoid overwhelming the server during outages:

`ts
let retryCount = 0;

fetchEventSource('/api/sse', {
async onopen(response) {
if (response.ok) {
retryCount = 0; // Reset on successful connection
}
},
onerror(err) {
retryCount++;
// Exponential backoff: 1s, 2s, 4s, 8s... max 30s
const backoff = Math.min(1000 * Math.pow(2, retryCount - 1), 30000);
console.log(Retrying in ${backoff}ms...);
return backoff;
}
});
`

Closing the Connection

To close the connection from the client side, use an AbortController and call abort() when you want to stop:

`ts
const ctrl = new AbortController();

fetchEventSource('/api/sse', {
signal: ctrl.signal,
onmessage(msg) {
console.log(msg.data);

// Close based on a message from the server:
if (msg.event === 'done') {
ctrl.abort();
}
}
});

// Or close from elsewhere, e.g., when the user clicks a button:
document.getElementById('stop').addEventListener('click', () => {
ctrl.abort();
});

// Or close when a component unmounts (React example):
useEffect(() => {
const ctrl = new AbortController();
fetchEventSource('/api/sse', { signal: ctrl.signal, ... });
return () => ctrl.abort();
}, []);
`

Page Visibility

Important: By default, this library closes the connection when the page is hidden (e.g., user switches tabs or minimizes the window) and reconnects when visible again. This differs from the native EventSource which stays connected.

To keep the connection open even when the page is hidden, set openWhenHidden: true:

`ts
fetchEventSource('/api/sse', {
openWhenHidden: true, // Keep connection open when page is hidden
onmessage(msg) {
console.log(msg.data);
}
});
`

| openWhenHidden | Behavior |
|------------------|----------|
| false (default) | Connection closes when hidden, reconnects when visible |
| true | Connection stays open regardless of page visibility |

Compatibility


This library is written in typescript and targets ES2017 features supported by all evergreen browsers (Chrome, Firefox, Safari, Edge.) You might need to polyfill TextDecoder for old Edge (versions < 79), though:
`js
require('fast-text-encoding');
`

Connection Limits

This library does not impose any connection limits, but browsers and servers do. Keep these limitations in mind when designing your application:

| Factor | Typical Limit | Notes |
|--------|---------------|-------|
| HTTP/1.1 connections per domain | ~6 | Browser-enforced limit |
| HTTP/2 streams per connection | ~100-256 | Better multiplexing, but still limited |
| Browser memory | Varies | Each connection consumes memory |
| Server connections | Varies | Depends on server configuration |

Recommendations for applications requiring many concurrent streams:

1. Use HTTP/2 on your server to benefit from connection multiplexing
2. Consolidate streams - use a single SSE connection with event routing instead of many separate connections
3. Consider alternatives - for 100+ real-time streams, WebSockets or a pub/sub architecture may be more appropriate
4. Close unused connections - use the AbortController` to close connections when they're no longer needed

Contributing

This project welcomes contributions and suggestions. Most contributions require you to agree to a
Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us
the rights to use your contribution. For details, visit https://cla.opensource.microsoft.com.

When you submit a pull request, a CLA bot will automatically determine whether you need to provide
a CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions
provided by the bot. You will only need to do this once across all repos using our CLA.

This project has adopted the Microsoft Open Source Code of Conduct.
For more information see the Code of Conduct FAQ or
contact opencode@microsoft.com with any additional questions or comments.