WebSocket support for angular
Available items
No Items, yet!
The developer of this repository has not created any items for sale yet. Need a bug fixed? Help with integration? A different license? Create a request here:
Readme
ngSocket 
Status: In-Development
An AngularJS 1.x service for connecting applications to servers with WebSocket support.
Usage
bower install ngSocket
.controller('SomeController', function (ngSocket) {
//Open a WebSocket connection
var ws = ngSocket('ws://foo/bar');
//Can call before socket has opened
ws.send({foo: 'bar'});
});
API
Factory: ngSocket
(in module ngSocket
)
returns instance of NGWebSocket
Methods
name |
arguments | description |
|---|---|---|
| ngSocket constructor |
url:String | Creates and opens a WebSocket instance. var ws = ngSocket('ws://foo'); |
| send | data:String,Object returns | Adds data to a queue, and attempts to send if socket is ready. Accepts string or object, and will stringify objects before sending to socket. |
| onMessage | callback:Function options{filter:String,RegExp, autoApply:Boolean=true} |
Register a callback to be fired on every message received from the websocket, or optionally just when the message's dataproperty matches the filter provided in the options object. Each message handled will safely call $rootScope.$digest()unless autoApplyis set to false in the options. Callback gets called with a MessageEvent object. |
| onOpen | callback:Function | Function to be executed each time a socket connection is opened for this instance. |
| close | force:Boolean:optional | Close the underlying socket, as long as no data is still being sent from the client. Optionally force close, even if data is still being sent, by passingtrueas theforce parameter. To check if data is being sent, read the value ofsocket.bufferedAmount`. |
Properties
name |
type | description |
|---|---|---|
| socket | window.WebSocket | WebSocket instance. |
| sendQueue | Array | Queue of sendcalls to be made on socket when socket is able to receive data. List is populated by calls to the sendmethod, but this array can be spliced if data needs to be manually removed before it's been sent to a socket. Data is removed from the array after it's been sent to the socket. |
| onOpenCallbacks | Array | List of callbacks to be executed when the socket is opened, initially or on re-connection after broken connection. Callbacks should be added to this list through the onOpenmethod. |
| onMessageCallbacks | Array | List of callbacks to be executed when a message is received from the socket. Callbacks should be added via the onMessagemethod. |
| readyState | Number:readonly | Returns either the readyState value from the underlying WebSocket instance, or a proprietary value representing the internal state of the lib, e.g. if the lib is in a state of re-connecting. |
CancelablePromise
This type is returned from the
send()instance method of ngSocket, inherits from $q.defer().promise.
Methods
name |
arguments | description |
|---|---|---|
| cancel | Alias to deferred.reject(), allows preventing an unsent message from being sent to socket for any arbitrary reason. |
|
| then | resolve:Function, reject:Function | Resolves when message has been passed to socket, presuming the socket has a readyStateof 1. Rejects if the socket is hopelessly disconnected now or in the future (i.e. the library is no longer attempting to reconnect). All messages are immediately rejected when the library has determined that re-establishing a connection is unlikely. |
Service: ngSocketBackend
(in module ngSocketMock
)
httpBackendmock in AngularJS's
ngMockmodule
Methods
name |
arguments | description |
|---|---|---|
| flush | Executes all pending requests | |
| expectConnect | url:String | Specify the url of an expected WebSocket connection |
| expectClose | Expect "close" to be called on the WebSocket | |
| expectSend | msg:String | Expectation of send to be called, with required message |
| verifyNoOutstandingExpectation | Makes sure all expectations have been satisfied, should be called in afterEach | |
| verifyNoOutstandingRequest | Makes sure no requests are pending, should be called in afterEach |
Logical Questions
- Q.: What if the browser doesn't support WebSockets?
- A.: This module will not help; it does not have a fallback story for browsers that do not support WebSockets.
Development
$ npm install $ bower install
Unit Tests
$ npm testStarts karma and watches files for changes
Manual Tests
In the project root directory:
$ node test-serverStarts a sample web socket server to send/receive messages
$ ./node_modules/.bin http-server- Basic http server to seve a static file Open localhost:8081/test-app.html and watch browser console and node console to see messages passing
Distribute
$ ./dist.shFor now just copies
src/ngSocket.jsto
dist/(bower is configured to ignore src/ and test, plus pretty much everything else)
TODO
- Automatic re-connection when connection lost
- Add
onerror
to allow applications to respond to socket errors in their own ways - Consider support for ArrayBuffer and Blob datatypes
- Add
protocols
parameter to constructor