eventsource-extra
v1.0.0
Published
EventSource replacement to POST PATCH DELETE
Downloads
26
Maintainers
Readme
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 ismessage
id
: the event ID, if present;null
otherwisedata
: 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 andEventSourceExtra
events logged toconsole
. 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
thennode index.js
to run express
Credits
Credits to https://github.com/mpetazzoni/sse.js, this work is an extension and partially rewrite of his library.