Ecosyste.ms: Awesome

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

Awesome Lists | Featured Topics | Projects

https://github.com/feross/simple-websocket

Simple, EventEmitter API for WebSockets
https://github.com/feross/simple-websocket

browser nodejs stream streaming websocket

Last synced: 18 days ago
JSON representation

Simple, EventEmitter API for WebSockets

Awesome Lists containing this project

README 

        
# simple-websocket [![travis][travis-image]][travis-url] [![npm][npm-image]][npm-url] [![downloads][downloads-image]][downloads-url] [![javascript style guide][standard-image]][standard-url]



[travis-image]: https://img.shields.io/travis/feross/simple-websocket/master.svg

[travis-url]: https://travis-ci.org/feross/simple-websocket

[npm-image]: https://img.shields.io/npm/v/simple-websocket.svg

[npm-url]: https://npmjs.org/package/simple-websocket

[downloads-image]: https://img.shields.io/npm/dm/simple-websocket.svg

[downloads-url]: https://npmjs.org/package/simple-websocket

[standard-image]: https://img.shields.io/badge/code_style-standard-brightgreen.svg

[standard-url]: https://standardjs.com



#### Simple, EventEmitter API for WebSockets



[![Sauce Test Status](https://saucelabs.com/browser-matrix/simple-websocket.svg)](https://saucelabs.com/u/simple-websocket)



## features



- **super simple** API for working with WebSockets in the browser

- supports **text and binary data**

- node.js [duplex stream](http://nodejs.org/api/stream.html) interface

- client & server implementations



This package is used by [WebTorrent](https://webtorrent.io).



## install



```

npm install simple-websocket

```



This package works in the browser with [browserify](https://browserify.org). If

you do not use a bundler, you can use the `simplewebsocket.min.js` standalone script

directly in a `` tag. This exports a `SimpleWebsocket` constructor on

`window`. Wherever you see `Socket` in the examples below, substitute that with

`SimpleWebsocket`.



## real-world applications that use simple-websocket



- [Virus Cafe](https://virus.cafe) - Make a friend in 2 minutes

- [WebTorrent](https://webtorrent.io) - The streaming torrent app

- [StudyNotes](http://www.apstudynotes.org) - Helping students learn faster and better

- [bittorrent-tracker](https://github.com/feross/bittorrent-tracker) - Simple, robust, BitTorrent tracker (client & server) implementation

- [instant.io](https://github.com/feross/instant.io) - Secure, anonymous, streaming file transfer

- [lxjs-chat](https://github.com/feross/lxjs-chat) - Omegle chat clone

- [Metastream](https://github.com/samuelmaddock/metastream) - Watch streaming media with friends.

- \[ your application here - send a PR \]



## usage



```js

var Socket = require('simple-websocket')



var socket = new Socket('wss://echo.websocket.org')

socket.on('connect', function () {

  // socket is connected!

  socket.send('sup!')

})



socket.on('data', function (data) {

  console.log('got message: ' + data)

})

```



## api



### `socket = new Socket(url)`



Create a new WebSocket connection to the server at `url`. This usage is a shorthand

for `socket = new Socket({ url: url })`



### `socket = new Socket(opts)`



If `opts.url` is specified as a string, then a WebSocket connection will be created

to the server at `opts.url`.



If `opts.socket` is specified as an instance of a raw WebSocket object, then the

given WebSocket object will be used and one will not be automatically be created

internally. (This is for advanced users.)



Other properties on `opts` will be passed through to the underlying superclass,

`stream.Duplex`.



### `socket.send(data)`



Send text/binary data to the WebSocket server. `data` can be any of several types:

`String`, `Buffer` (see [buffer](https://github.com/feross/buffer)), `TypedArrayView`

(`Uint8Array`, etc.), `ArrayBuffer`, or `Blob` (in browsers that support it).



Note: If this method is called before the `socket.on('connect')` event has fired, then

data will be buffered.



### `socket.destroy([err])`



Destroy and cleanup this websocket connection.



If the optional `err` parameter is passed, then it will be emitted as an `'error'`

event on the stream.



### `Socket.WEBSOCKET_SUPPORT`



Detect WebSocket support in the javascript environment.



```js

var Socket = require('simple-websocket')



if (Socket.WEBSOCKET_SUPPORT) {

  // websocket support!

} else {

  // fallback

}

```



## events



### `socket.on('connect', function () {})`



Fired when the websocket connection is ready to use.



### `socket.on('data', function (data) {})`



Received a message from the websocket server.



`data` will be either a `String` or a `Buffer/Uint8Array` (see [buffer](https://github.com/feross/buffer)).

JSON strings will be parsed and the resulting `Object` emitted.



### `socket.on('close', function () {})`



Called when the websocket connection has closed.



### `socket.on('error', function (err) {})`



`err` is an `Error` object.



Fired when a fatal error occurs.



## server



The server implementation is basically `ws` but the `'connection'` event provides

sockets that are instances of `simple-websocket`, i.e. they are duplex streams.



```js

var Server = require('simple-websocket/server')



var server = new Server({ port: port }) // see `ws` docs for other options



server.on('connection', function (socket) {

  socket.write('pong')

  socket.on('data', function (data) {})

  socket.on('close', function () {})

  socket.on('error', function (err) {})

})



server.close()

```



## license



MIT. Copyright (c) [Feross Aboukhadijeh](http://feross.org).