Syncs
A JavaScript Library for Real-Time Web Applications
Installation
npm install syncs --save
Initialization
Syncs is easy to initialize. Syncs is developed with typescript language.
Sample projects are avilable here.
Server Initialization
Syncs instance works with native nodejs http server.
;; ;server.listen8080;
Developers are able to use light web frameworks like express.
;;; ;;; server.listen8080;
Server Configuration
Sync module contains SyncServer
class which acts as WebSocket server. With TypeScript language there is defualt module export to create SyncServer
instance.
SyncsServer
constructor has two parameter.
Server
: an instance of NodeJshttp
server.config
: an instance ofSyncsConfig
interface:path : string
: real-time serving path. default value is/syncs
.closeTimeout : number
: times in millisecond that server waits after client disconnect, then it will remove the client from list of clients and groups. default value is10000
.debug : boolean
: enables debug mode to log input and output commands. default value isfalse
.
It's also possible to enable debug mode using io.enableDebugMode()
and disable it with io.disableDebugMode()
methods.
Client Initialization
Syncs clients are developed to run on most common platforms :
The rest of this documentation uses Browser Client Script.
There is two way to setup the Browser Client Script.
- Developers can download javascripts file from this link and add the
syncs.js
file to assets directory. - On server side it's possible to access client script from
Syncs
instance:app.get'/syncs.js',
After serving client script, developers should include it in html page and create an instance of Syncs
class.
Client Script constructor has config parameter:
path:string
: WebSocket url begins withws://
protocol. default value isws://domain/realtime
which domain name will sets automatically.autoConnect:boolean
: IfautoConnect
isfalse
then the Syncs instance will not connect to server on creation. To connect manuly to server developers should callio.connect()
method. default value istrue
.autoReconnect:boolean
: This config makes the connection presistent on connection drop. default value istrue
.reconnectDelay: number
: time to wait befor each reconnecting try. default value is10000
.debug:bolean
: This parameter enables debug mode on client side. default value isfalse
.
Handling connections
On both server and client side it's easy to handle client connection status change.
Handling client connection on server side
using onConnection
on server side developers can notify about client connection to Syncs Server.
//io as Syncs instance on server side io.onConnection
By any reason if client disconnects from Syncs Server, server waits for client connection. By using onClientDisconnect
method of SyncsServer
instance or onDisconnect
method of SyncsClient
instance developers can handle disconnect event.
io.onClientDisconnect
client.onDisconnect
After a specific time which developers can change with closeTimeout
, close
event will happen on server side. after this event client instance will be removed from clients list and groups.
Developers can handle this event from both SyncsServer
and SyncsClient
instances.
io.onClientClose
client.onClose
Also server can disconnect and close client by calling close
Handling client connection on client side
On client side when the connection is established and hand shaking process completes, developers can notify with onOpen
event handler.
io.onOpen
Developers can handle disconnect and close event with onDisconnect
and onClose
method.
io.onDisconnect
io.onClose
Also it's possible to disconnect from server using disconnect
method.
io.disconnect;
Client Groups on Server Side
It's possible to manage clients in groups. SyncsGroup
class is responsible to manage group of clients. Using groups developers can send messages and access abstraction functions on group of clients.
group
method of SyncsServer
instance will return named SyncsGroup
instance.
;
Developers can add,remove and exclude client from a group.
io.onConnection
When a client link closed, the instance of that client will remove from all groups.
Abstraction Layers
Syncs provides four abstraction layer over its real-time functionality for developers.
1. onMessage Abstraction Layer
This type of real-time development is primary type between other solutions and uses fundamental functionality of WebSocket. If data and functionality around that in web is simple, onMessage as a simple messaging solution may fit developers need. With Syncs it’s possible to access WebSocket functionality in low level mode. In this mode developer should handle all data transfer controls.
Developers can send messages using send
method of SyncsClient
instance on server side to send JSON
message to the client. on client side, by using onMessage
method of Syncs
instance developers can recive all incoming messages.
//server sideio.onConnection
//client sideio.onMessage
It's possible to send message from client to server.
//client side
io.onMessage
On server side it's possible to send messages to group of clients
//server side
Developers should add extra properties to distinguish between messages.
2. Publish and Subscribe Abstraction Layer
With a Publish and Subscribe solution developers normally subscribe to data using a string identifier. This is normally called a Channel, Topic or Subject.
Both server and client can publish or subscribe to event.
publish
method is accessible from SyncsServer
, SyncsGroup
and SyncsClient
instances on server side.
// server side//sends time too all clients//add client to group and report client entrance to group//publish direct message to single client
io.subscribe'time-report',io.subscribe'new-member',io.subscribe'direct-message',
It's possible to disable subscription to event using unSubscribe
method.
### 3. Shared Data Abstraction Layer Syncs provides Shared Data functionality in form of variable sharing. Shared variables can be accessible in tree level: Global Level, Group Level and Client Level. Global Level and Group Level shared objects are readonly by client. Client Level shared object are write-able by client but server can make readonly client level shared object.
//server side// reporting online users to all clients;info.onlineUsers=0;io.onConnection;io.onClientClose
//client side;
It's possible to get shared variable in Group Level
//server side
Client Level shared object by default is write-able by client.
// server side
//client side
Developers can create read only variables by passing second parameter to share
method.
//server side client.shared'session',true.id=getSessionId;
It's possible to add listener to check shared variable change.
shared variable object returned by shared
method can bee called as a function to add listener.
Developers should pass a callback function to handle change event.
// client side; info;
The callback function has two argument.
values:object
: an object that contains names of changed properties and new values.by:string
a string variable with two value ('server'
and'client'
) which shows who changed these properties.
4. Remote Method Invocation (RMI) Abstraction Layer
With help of RMI developers can call and pass argument to remote function and make it easy to develop robust and web developed application. RMI may abstract things away too much and developers might forget that they are making calls over the wire.
Before calling remote method developer should declare the function on client or server script.
functions
object in io
is the place to declare functions.
//clint sideio.functions.showMessage=
The caller side can access remote method using remote
object.
//server sidecliet.remote.showMessage'welcome...';
The remote side can return a result which is accessible using Promise
object returned by caller side.
//client sideio.functions.getUserVote=
//server sidecliet.remote.getUserVote "Which programming language is better?", .then
Remote side can return another Promise object if the result is not accessible yet.
It's also possible to interfere remote method calling using onRMI
method on server side. This method has two argument. name
the name of remote method or regular expression format of string and the callback
which is handler of interfering.
Return value from this callback will handle next steps of remote method invocation as follow:
- if developer returns nothing next handler invokes and if there is no more handler the target method will be called.
- if developer returns a specific value (synchronously) then the RMI result will be the returned value.
- if developer returns a promise then the result of resolve or reject methods will handles next steps.
// check authentication on before method callio.onRMI'admin.*',