EventSourceExtra.js

EventSourceExtra.js is a Javascript EventSource replacement designed to consume Server-Sent Events (SSE) streams with more options than the standard EventSource.
The main limitation of EventSource are:

• does not support POST DELETE PATCH requests
• no payload can be added to the request
• custom headers can not be added to requests

This package is designed to provide a usable replacement to EventSource that makes all of this possible: EventSourceExtra. It is a fully compatible EventSource polyfill so you should be able to:

EventSource = EventSourceExtra;

Basic usage

Installation:

npm install eventsource-extra
# or
git clone https://github.com/delcon/eventsource-extra .

The most simple way to use EventSourceExtra is to use it as documented as an EventSource replacement.

Create the EventSourceExtra object, attach one or more listeners, and activate the stream:

var source = new EventSourceExtra(url);

// subscribe by addEventListener:
source.addEventListener('message', function(e) {
  console.log(e);
});

source.stream();

For Documentation refer to: , documented here:
https://developer.mozilla.org/en-US/docs/Web/API/EventSource

Extra API

In addition to the standard API you have the following functions and apis:

Events

EventSourceExtra implements the EventTarget interface (just like EventSource) and emits fully constructed Event objects. The type of the event corresponds to the Server-Sent Event's name.

The sse events have the following fields:

• event: the event type, default is message
• id: the event ID, if present; null otherwise
• data: the event data, unparsed

In addition to Server-Sent EventsEventSourceExtra, will emit the following events:

• open, when the first block of data is received from the event stream;
• error, if an error occurs while making the request;
• readystatechange, to notify of a change in the ready state of the event source.

Additional Extra Event Features by EventSourceExtra:

• Subscribe by source.on('eventname', function(data){ ... }) to receive data only instead of the whole event
• Subscribe by source.on('data', function(data){ ... }) to receive all default events / messages
• If you subscribe by source.on(<eventname>, ... ) the data will be JSON - parsed if sent as JSON.
• Debug events by providing options.debug = true to see all Server-Sent and EventSourceExtra events logged to console. This is very useful for development.

Example: listening for specific event types

var source = new EventSourceExtra(url);

// subscribe by addEventListener:
source.addEventListener('status', function(e) {
  console.log('System status is now: ' + e.data);
});

// subscribe by on<eventname>:
source.onstatus = function(e) { 
  console.log('System status is now: ' + e.data);
};

// subscribe to data only (parsed):
source.on('status', function(data){
  console.log('System status is now: ' + data);
});

source.stream();

Sendig request

There are different ways to send requests:

• use the EventSource api: const sse = new EventSourceExtra(url, options ); sse.stram()
• use the added extra fetch api: const sse = new EventSourceExtra(); sse.fetch(url, options )

Request options

The options used in the constructor new EventSourceExtra(url, options )or used by calling sse.fetch(url, 'options') behave the same.

const options = {
  method: 'POST', // optional, GET POST PATCH DELETE, default is GET
  headers: {'Authorization': 'Bearer secret-key'}, // optional
  payload: '{ "foo" : "bar" }', // optional, String, FromData, Buffer ...
  withCredentials: true, // optional, default is false
  debug: true // optional, default is false
}

Options reference

Name	Description
headers	A map of additional headers to use on the HTTP request
method	Override HTTP method (defaults to GET, unless a payload is given, in which case it defaults to POST)
payload	An optional request payload to sent with the request
withCredentials	If set to true, CORS requests will be set to include credentials
debug	If set to true, all events will be logged to console

Examples

• cd to examples/express, npm install then node index.js to run express

Credits

Credit to https://github.com/mpetazzoni/sse.js, this work is inspired by his library.