LivePerson's Generic JS Channels Mechanism (Events/Commands/ReqRes)
Getting Started
Run npm install chronosjs
Overview
This library provides an ability to develop event driven applications using the included sub-modules of events, commands and request/response.
Together with Courier, one can integrate multiple applications into one, by allowing cross domain cross application event driven communication.
An application developer can integrate/embed a 3rd party application (provided the application uses courier as well) seamlessly and securely without worrying about cross domain issues.
Another use case is for building multi module application where each module can be it's own application and a developer will want to mix and match between them.
Chronos.Events
An events channel for binding and triggering events.
Allows multiple listeners on a single event and wildcards ("*"
) support.
Chronos.Command
A command mechanism for complying and commanding and API call. Allows a single complier per command. Supports async commands with an options to call a callback when done.
Chronos.ReqRes
A request mechanism for replying and requesting and API call that returns a response. Allows a single replier per request. Supports async requests with an options to call a callback when done with a result.
Chronos.Channels
A Channel which includes all communication means (events, commands, reqres). Implements the same API's as all means it contains
Chronos.PostMessageCourier
A generic implementation of Channels over postMessage API. Allows communication between cross domain IFRAMES "sharing" a Channels instance.
Package Contents
The package holds a few artifacts in the dist folder:
- Events.js: The events channel
- Commands.js: The commands channel
- Reqres.js: The request/response channel
- Channels.js: Combination of all 3 channel options
- PostMessageCourierNoDep.js: Channel transport over postmessage
- PostMessageCourier.js: Combination of all 3 channel options with channel transport over postmessage
* Minified compressed versions exist in the min folder.
Usage examples
Events
var events = ; //Listen on the event only onceevents; //Regular bind on the eventevents; //Unbind from the eventevents; //Trigger the eventevents; //Will return an array of fired eventsevents;
There is an option to pass "*"
as event name and "*"
as app name on all APIs which is an ALL indicator.
Commands
var commands = ; { //Do something async with data and call cb when done.} //Comply to a commandcommands; //Stop complying to a commandcommands; var cmd = appName: "Your App Name" cmdName: "Your Event Name" data: {} { if !err console; }//Issue the commandcommands; //Will return an array of fired commandscommands;
The callback on the command is optional.
ReqRes
var reqres = ; { //Do something async with data and call cb when done. return 1; //Whatever you want to return} //Reply to a requestreqres; //Stop replying to a requestreqres; var req = appName: "Your App Name" reqName: "Your Request Name" data: {} { if !err console; }//Issue the requestvar res = reqres; //Will return an array of fired requestsreqres;
The callback on the request is optional.
PostMessageCourier
// Initialize a new Couriervar courier = Chronos; ///// ---- BINDINGS ------ ////courier;courier;courier; ///// ---- INVOCATION ------ ////courier;courier;courier;
LIMITATIONS
- Only supports browsers which implements postMessage API and have native JSON implementation (IE8+, Chrome, FF, Safari, Opera, IOS, Opera Mini, Android)
- IE9-, FF & Opera Mini does not support MessageChannel and therefore we fallback to using basic postMessage. This makes the communication opened to any handler registered for messages on the same origin.
- All passDataByRef flags (in Channels) are obviously ignored
- In case the browser does not support passing object using postMessage (IE8+, Opera Mini), and no special serialize/deserialize methods are supplied to PostMessageCourier, All data is serialized using JSON.stringify/JSON.parse which means that Object data is limited to JSON which supports types like: strings, numbers, null, arrays, and objects (and does not allow circular references). Trying to serialize other types, will result in conversion to null (like Infinity or NaN) or to a string (Dates), that must be manually deserialized on the other side
- When the IFRAME is managed outside of PostMessageCourier (passed by reference to the constructor), a targetOrigin option is expected to be passed to the constructor, and a query parameter with the name "lpHost" is expected on the IFRAME url (unless the PostMessageCourier at the IFRAME side, had also been initialized with a valid targetOrigin option)
Wrappers
- ngChronos for angular js.
License
MIT
Credits
Thanks to Danielle Dimenshtein for the logo
Session on this subject with code examples can be found here.