sse-events
SSE event source polyfill wrapped in Node.js like EventEmitter with performance fixes and custom api. Compatible with React/React-Native.
Motivation
- Improved retry algorithm to avoid loops and memory leaks
- Automatic close of connection upon server error codes (4xx, 5xx, ...)
- EventEmitter api
- Singletron pattern
- Listeners persisting across retries and/or connection close events
- Dynamic change of headers, path and parameters
- Random retry interval to reduce server request concurrency
- Dynamic progressive fallback interval for long lasting connection retries
- React/React-Native compatible
Implementation based on:
Installing
Run the following command in your project's directory to grab the latest published version of this code:
$ npm install sse-events --save
or
$ yarn add sse-events
Using in your project
;
Create an instance, providing the configuration options (optional)
const sse = url: SSE_BASE_URL path: '/some/path' options: headers: 'User-Agent': USER_AGENT Authorization: '...' reconnectInterval: 500 retryOnNetworkError: false;
Bind few event listeners:
const ON_ERROR ON_OPEN = EventSourcetypes; sse;sse; sse;
Now call the open
method to establish the connection. No matter how may times this method is called, just
one AND ONLY ONE connection is open a time. Some errors can interrupt the SSE retry algorithm and thus further call to this method is required to re-establish the connection. Listeners DON'T CLOSE if this method is called.
sse;
SSE connection can be suspended calling the close
method. Instance headers, params or other options don't apply to the on-going connection unless manually closed and open again.
sse;
To close the connection and remove all listeners call the destroy
method. Following calls to open
WILL NOT restore previous event listeners.
sse;
Headers params can be set/updated calling this method.
sse;
Url params can be set/updated calling this method.
sse;
Connection url and path can be set/updated directly from instance properties.
ssepath = '/path/to/sse/resource';sseurl = 'example.com'
Connection States
// Statesconst CONNECTING = 0 // trying to connect. No events. OPEN = 1 // connection established and running. Auto-retry enabled and events CLOSED = 2 // connection is closed. Auto-retry disabled and no events} = sse;
Event Types
const ON_OPEN = 'open' // readyState goes from CONNECTING -> OPEN ON_ERROR = 'error' // SSE, network or server response errors ON_CLOSE = 'close' // readyState goes to CLOSED ON_STATE = 'state' // readyState has changed ON_TIMEOUT = 'timeout' // server closed connection} = EventSourcetypes;
Configuration Options
/** * Reference time interval between retry attempts in ms. Actual interval is randomly selected * between 100ms and this value to reduce server request blocking. For retry attempts, after * network errors, actual interval is randomly selected using a fallback progressive. * Default value 1000 ms. * @type */ssereconnectInterval || 1000; /** * Max fallback retry interval in ms. * Default value 15000 ms * @type */ssemaxInterval || 15000; /** * Min fallback retry interval in ms. * Default value 1000 ms * @type */sseminInterval || 1000; /** * Max number of retry attempts before closing the connection. Negative value means unlimited * attempts. * Default value -1 (no limit). * @type */ssemaxAttempts || -1; /** * Retry to connect on network or other internal errors. * Default value true. * @type */sseretryOnNetworkError || true; /** * Retry to connect on server error response. * Default value false. * @type */sseretryOnServerError || false; /** * Server error status codes to retry connection. * Default value [502, 503, 504] * @type */sseserverErrorCodes || 502 503 504; /** * Connection URL * @type */sseurl /** * SSE Connection Options * @type */sseoptions /** * Connection URL params * @type */sseparams /** * Connection URL path * @type */ssepath /** * SSE Connection State * @type */ssereadyState
License
This project is licensed under the MIT License