A tiny (736b) utility for Server Sent Event (SSE) streaming via
fetch
and Web Streams API
- Allows any HTTP method
- Built with native Web Streams API
- Works with browser, Node.js, Cloudflare Workers, Deno, and Bun
- Supports WebWorker or Service Worker environments
- Accepts
AbortController
for cancellable streams
Why?
-
Even though
EventSource
exists in browsers (and Deno!), it only sendsGET
requests and does not allow for custom HTTP headers. Most APIs (eg, Anthropic, OpenAI) requirePOST
requests with anAuthorization
header and a JSON payload. -
Web Streams are new, not very well understood, and are sometimes confused with NodeJS Streams. Because of this, many other libraries embed large polyfills or manually reconstruct desired behaviors through non-standard approaches. These polyfills are generally not necessary anymore, but still make large impacts on SDK size; for example,
openai
is17kB
(gzip).
$ npm install --save fetch-event-stream
import { events, stream } from 'fetch-event-stream';
// or
import { events, stream } from 'https://deno.land/x/fetch_event_stream';
Convert a Response
body containing Server Sent Events (SSE) into an Async Iterator that yields
ServerSentEventMessage
objects.
Example
// Optional
let abort = new AbortController();
// Manually fetch a Response
let res = await fetch('https://...', {
method: 'POST',
signal: abort.signal,
headers: {
'api-key': 'token <value>',
'content-type': 'application/json',
},
body: JSON.stringify({
stream: true, // <- hypothetical
// ...
}),
});
if (res.ok) {
let stream = events(res, abort.signal);
for await (let event of stream) {
console.log('<<', event.data);
}
}
Type: Response
The Response
to consume. Must contain a body that follows the Server-Sent Event message protocol.
Type: AbortSignal
Optional. Use the AbortController
interface to stop iteration. The stream will be destroyed.
Convenience function that will fetch
with the given arguments and, if ok, will return the events
async iterator.
Note: Accepts the same arguments as
fetch
but does not return aResponse
!
Important: Will
throw
theResponse
if received non-2xx
status code.
Example
// NOTE: throws `Response` if not 2xx status
let events = await stream('https://api.openai.com/...', {
method: 'POST',
headers: {
'Authorization': 'Bearer <token>',
'Content-Type': 'application/json',
},
body: JSON.stringify({
stream: true,
// ...
}),
});
for await (let event of events) {
console.log('<<', JSON.parse(event.data));
}
Type: Request | URL | string
Refer to fetch#resource
documentation.
Type: RequestInit
Refer to fetch#options
documentation.
MIT © Luke Edwards