Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/isocroft/beamzer-client

JavaScript wrapper script for Server Sent Events with support for JavaScript Workers
https://github.com/isocroft/beamzer-client

eventsourcing javascript realtime-notifications server-sent-events wrapper-script

Last synced: 17 days ago
JSON representation

JavaScript wrapper script for Server Sent Events with support for JavaScript Workers

Awesome Lists containing this project

README

        

# BeamzerClient

This is a wrapper script and libarary which makes use of the JS polyfill for _Server-Sent Events_ located at https://github.com/amvtek/EventSource/ and makes it easy to manage several connections to *push notification* or *event* sources. This library can also be used inside *Web Workers* (Dedicated or Shared workers)

## File Size

- 15.2kb (Minified)

## Usage

```html




BeamzerClient - Example





var beam = new BeamzerClient({
source:"http://www.example.com/beamrays",
params:{
id:"id"
},
options:{loggingEnabled:true, interval:4500,crossdomain:true}
});

// open a connection with relevant callbacks
beam.start(function onopenCalback(e){

}, function onerrorCalback(e){
if (e.readyState == EventSource.CLOSED) {
console.log('Event was closed');
}
}, function onmessageCalback(e){

});
// register an event [update]
beam.on("update", function(e){ });
// register another event [noupdate]
beam.on("noupdate", function(e){ });
// recreate a connection.
beam.newClient({source:"http://www.example.com/beamrays",params:{},options:{}});
// unregister an event [update]
beam.off("update");
// close all the connection(s)
beam.stop(function(e){ });



```

>It is important to note that whenever.

**AngularJS UseCase Example**

The idea here is to loosely couple communications to beamzer-client in an AngularJS app and

```js

/*

The idea here is to loosely couple the different controllers to the beamzer-client event stream from the server.
Instead of having multiple observers for each controller scope listening for incoming streams, we have a single
mediator object powered by $rootScope for this purpose.

*/

;(function(w, angular){

var module = angular.module("TheAppServices"); // assumes this module has been defined before

module.factory("$activityStreamer", [function(){

// assumes that [$values] is another service defined before that contains the stream URL data

var ENDPOINT = 'http://www.example.com/streamer.php',

CLIENT = null,

started = false;

return {

start:function(openCallback, errorCallback, msgCallback){

CLIENT = new w.BeamzerClient({
source:ENDPOINT,
params:{id:'68AWtlwGTE65hDE34j9Lm'},
options:{loggingEnabled:true, interval:4500}
});

CLIENT.start(openCallback, errorCallback, msgCallback);

started = true;
},
addEvent:function(event, callback){

CLIENT.on(event, callback);

},
removeEvent:function(event){

CLIENT.off(event);
},
newConnection:function(settings){

CLIENT.newClient(settings);
},
end:function(closeCallback){

CLIENT.stop(closeCallback);
},
isStarted:function(){

return started;
}

}

}]);

}(this, this.angular));

;(function(w, angular){

var module = angular.module("TheAppServices");

module.factory("$sessionStorage", ['$window', function($window){
var data = null, keys = {};

function setData(){
$window.name = angular.toJSON(data);
}

function clearData(){
$window.name = data ? (data = {}) && '' : '';
}

function getData(){
return data || angular.fromJSON($window.name || '{}');
}

data = getData();

return ('sessionStorage' in $window) ? $window.sessionStorage : {
length:0,
clear:function(){
keys = {};
clearData((this.length = 0));
},
getItem:function(key){
var _data = getData();
return (key in _data)? _data[key] : null;
},
setItem:function(key, value){
var _data = getData();
_data[key] = angular.toJSON(value);
setData(keys[String(++this.length)] = key);
},
key:function(i){
var _i = String(i);
return (_i in keys)? keys[i] : null;
},
removeItem:function(key){
var _data = getData();
delete _data[key];
setData(keys[String(--this.length)] = key);
}
};

}]);

}(this, this.angular));

;(function(w, angular){

var usebuffer = false,
app = angular.module("TheApp", ["TheAppServices"]);

// we assume here that this ficticious app (TheAppServices) has a '#/feeds' route registered prior

app.run(['$activityStreamer',
'$sessionStorage',
'$rootScope',
'$route', function($activityStreamer, $sessionStorage, $rootScope, $route){


$rootScope.$on('newStreamerRequest', function(event, data){

// assuming -- $scope.$emit('newStreamerRequest', {settings:{url:'...',params:{}}}) -- is called

$activityStreamer.newConnection(data.settings);

});


$rootScope.$on('removeStreamerEvent', function(event, data){

// assuming -- $scope.$emit('removeStreamerEvent', {eventName:'update'}) -- is called

$activityStreamer.removeEvent(data.eventName);

});

$rootScope.$on('$destroy', function(event, data){

// if we go off from the app itself, kill it... fast!!

$activityStreamer.end(function(e){

$rootScope.$broadcast('allStreamerExit', e); // notify all listening scopes (perhaps...)

});
});

$rootScope.$on('$routeChangeStart', function(event, current, previous){

// if we move away from a 'feeds' route page, buffer all real-time data in sessionStorage!!

if(previous.url.indexOf('feeds') > -1){

useBuffer = true;

}
});

$rootScope.$on('$routeChangeSuccess', function(event, current, previous){

/*$rootScope.title = current.title;*/

// if we move to a 'feeds' route page, prepare to display real-time data in view

if(current.url.indexOf('feeds') > -1){

useBuffer = false;

if($activityStreamer.isStarted()){

return;
}

$activityStreamer.start(function(e){

$sessionStorage.setItem('ACTIVITY_STREAM_BUFFER', {});

$rootScope.$broadcast('newStreamerSuccess', e); // notify all listening scopes
},

function(e){

$rootScope.$broadcast('newStreamerFailure', e); // notify all listening scopes

},

function(e){

setTimeout(streams.bind(null, e), 0);

});

$activityStreamer.addEvent('update', function(e){

setTimeout(streams.bind(null, e), 0);

});

$activityStreamer.addEvent('noupdate', function(e){

$rootScope.$broadcast('noNewStreamerMessageRecieved', e); // notify all listening scopes

});

}

function streams(e){

var _buffer = $sessionStorage.getItem('ACTIVITY_STREAM_BUFFER');

var _timestamps;

if(useBuffer){

_buffer[String(new Date*1)] = e;

// from here, you can trigger a toast notification on the screen perhaps...

}else{

if($sessionStorage.length){

_timestamps = Object.keys(_buffers);

// we need to make sure that when all 'buffered' messages are sent
// to all $scopes as and at when they were recieved in buffer mode

_timestamps.sort(function(a, b){
return (b - a);
})

angular.forEach(_timestamps, function(value){

$rootScope.$broadcast('newStreamerMessageRecieved', _buffer[value]);

delete _buffer[value];

});

}

$rootScope.$broadcast('newStreamerMessageRecieved', e); // notify all listening scopes
}

$sessionStorage.setItem('ACTIVITY_STREAM_BUFFER', _buffer);
}

});
});

}(this, this.angular));

/* controller action */

;(function(w, angular){

var app = angular.module("TheApp");

app.controller(['$scope', function($scope){

$scope.updatesList = [];

$scope.$on('newStreamerMessageRecieved', function(event, data){

var payload = data.data; // the event object from the handler has a 'data' property...

// assuming [payload] variable is an array...

angular.forEach(payload, function(item){

$scope.updateList.push(item); // this updates the view via 'ng-repeat' in the view...

});
});

}]);

}(this, this.angular));

```

>This is a simple SSE server script written in PHP

```php

# Simple Implementation of event streams on the server - http://www.example.com/streamer.php

sleep(5); // simulate real prod server activity e.g. database read operation

$data = array('status' => 'OK');

$payload = "id: 5RWF637yh9983az021mn \n";
$payload .= "event: update \n";
$payload .= "data: " . json_encode($data) . " \n\n"; // the last line must end with 2 line feed characters

header('Content-Type: text/event-stream');

echo $payload;

exit;

```
>This is another simple SSE server script written in Node.js (using [ssenode](https://github.com/isocroft/ssenode))

```js

// Simple Implementation of event streams on the server - http://www.example.com/stream

const { Source, EventStream } = require('ssenode');
const uuidv4 = require('uuid/v4');
const exp = require('express');

const app = exp()
const source = new Source(uuidv4);

app.use(EventStream.init(source, { no_id:false }));

app.get('/stream', (req, res) => {
setTimeout(() => { // simulate real prod server activity e.g. database read operation
source.send({
status:'OK'
}, null, 'update')
}, 5000);
})

```

### Web Worker example

```js

const worker = new Worker("./push-notifs.js");

worker.addEventListener("message", (event) => {
let data = event.data;
if(data.streamClosed){
setTimeout(function() => {
worker.terminate();
},0);
return;
}
console.log(JSON.stringify({data}));
}, false);

worker.postMessage({start:true});

setTimeout(() => {
worker.postMessage({stop:true});
}, 8900);

// push-notifs.js file

importScripts("./path/to/beamzer-client.min.js");

let globale = self, beam = null;

addEventListener("message", (event) => {
if(event.data.start === true){
beam = new BeamzerClient({
source:"https://stream.stock-details.com",
options:{interval:4500}
});

beam.open((e) => {
globale.postMessage({streamOpened:true});
},

(e) => {
globale.postMessage({streamMalfunction:true});
});

beam.on("notification", (e) => {
globale.postMessage({streamData:e.data});
});
}

if(event.data.stop === true){
if(beam !== null){
beam.close((e) => {
globale.postMessage({streamClosed:true});
beam = null; // reclaim memory
});
}
}
}, false);

```

### Helper Hints

While you implement **beamzer-client**, there are afew things to watch out for.

1. If users create multiple tabs for your beamzer-enabled web app, they will invariably be creating multiple SSE (EventSource) connection to your server.
So, you might want to consider disconnecting from the server, whenever a user minimizes the window where your web app is loaded or
switches from the tab where your web app is loaded. Use the page-visiblity JavaScript API or `document.hasFocus()`. Thankfully,
there's this JavaScript Library called [Idle.js](https://github.com/shawnmclean/Idle.js/) for watching the users' every move and it's
easy to setup and use and i very much recommend it.

2. Use `localStorage` "storage" events to update event-source data across all non-active tabs. Watch out for Edge though (you may have
to use **cookie polling** as a fall back) as it lacks support for cross-tab "storage" events. I think it should be fixed by Edge 16+

## Support

Available on all major browsers including IE8 - If you discover any bugs, please log an issue for it and i'll surely get look into it. If you wish to provide fallback support for web workers in Old IE (IE 8 / 9). Then you can check out [this polyfill library](https://github.com/calvinmetcalf/web-worker)

## Credits

@isocroft.

## Contributing

I welcome all contributions to make this software better. please send an [email](mailto:[email protected]) to communicate your thoughts on imporvements and features.