Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/riaevangelist/ws-share
A module allowing sharing of websockets between different functions, modules, scripts, actions, stores, and/or components with vanilla js (plain javascript), react, webpack or browserify
https://github.com/riaevangelist/ws-share
Last synced: 3 months ago
JSON representation
A module allowing sharing of websockets between different functions, modules, scripts, actions, stores, and/or components with vanilla js (plain javascript), react, webpack or browserify
- Host: GitHub
- URL: https://github.com/riaevangelist/ws-share
- Owner: RIAEvangelist
- License: other
- Created: 2015-09-26T22:07:29.000Z (over 9 years ago)
- Default Branch: master
- Last Pushed: 2021-03-10T21:20:36.000Z (almost 4 years ago)
- Last Synced: 2024-10-01T05:42:21.686Z (3 months ago)
- Language: JavaScript
- Homepage: http://riaevangelist.github.io/ws-share
- Size: 66.4 KB
- Stars: 8
- Watchers: 5
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# ws-share
A module allowing isomorphic sharing of websockets between different functions, modules, scripts, actions, stores, and/or components with vanilla js (plain js), react, webpack or browserify.
npm ws-share info : [See npm trends and stats for ws-share](http://npm-stat.com/charts.html?package=ws-share&author=&from=&to=)
[](http://packagequality.com/#?package=ws-share)
    
` npm install --save ws-share `
[](https://github.com/RIAEvangelist)
GitHub info :
[  ](http://riaevangelist.github.io/ws-share/)
[ws-share site](http://riaevangelist.github.io/ws-share/)
## What does ws-share do?
ws-share extends and normalizes both node ws and the browser WebSocket normalizing events ***and manages of a list of open websockets and protocols allowing websockets to be easily shared*** between multiple vanilla js (plain js), or common js modules. Each module can create a new WS instance for a given uri and protocol. However, if a socket with that uri & protocol list has already been opened, WS will reference the open socket instead of creating a new socket for the same uri and protocol list.
ws-share is designed to feel like you are naturally working with a standard WebSocket
***ws-share makes your WebSocket code isomorphic, the same code will run both in node AND in the browser!***
## Tips
For vanilla js (just plain old js) include the browser.js file
You should check ws.readyState upon creation.
***Why?***
If the shared websocket was already opened `ws.on('open',callback)` wont be called. So checking the ready state will allow you to perform any initialization needed in your node module, browser code, react component, action or store.
Everything normally available on the WebSocket is available plus the normalized methods and members added to the shared WebSockets below, this helps your code stay isomorphic so it can run on the server and browser :
|method or value |type |mutable|description|
|-------------------|-------|-------|-----------|
|uri |string |false |the uri of the shared ws|
|protocols |array/string|false |the protocols of the shared ws|
|on |func |false |bind event listener to shared websocket|
|off |func |false |UNbind event listener to shared websocket|
## Contributing
1. Pull or Fork code.
2. from the cloned directory run ` npm install ` (this will install required dependencies, depending on your system may require)
3. be awesome!
## Running Example React Shared WebSocket Echo App
This very basic react.js example app has two components share the same websocket. Neither is aware they are sharing though. The Input component sends info upto the server while the Output listens for messages from the server. The [websocket.org](https://websocket.org/) server here just echo's all information back for demo purposes.
#### Browser
1. ` npm install `
2. ` npm start echo `
3. goto [localhost:8080](http://localhost:8080)
4. type some stuff and watch both components use the same websocket
#### Node
1. ` node examples/echo/node/echo.js `
## Create or Use Existing Shared WebSocket
This follows the [standard WebSocket interface](https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_API/Writing_WebSocket_client_applications).
```javascript
//commonjs
var WS=require('ws-share');
//or vanilla js
var basicWS=new WS('wss://echo.websocket.org/?encoding=text');
var wsWithOneProtocol=new WS('wss://echo.websocket.org/?encoding=text','stream');
var wsWithManyProtocols=new WS(
'wss://echo.websocket.org/?encoding=text',
[
'stream',
'chat',
'whatever'
]
);
```
## Bind Events on a Shared WebSocket
This follows the [standard WebSocket interface](https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_API/Writing_WebSocket_client_applications) and also extends that interface with ` .on ` and ` .off ` as shortcuts for ` .addEventListener ` and ` .removeEventListener ` as on/off is commonly used in node applications and may be more intuitive for some developers. All standard events are supported. ***Remember the scope of your callback is the shared websocket! if you want to use the react modules scope use*** ` .bind(this) ` ***on the callback***
```javascript
//commonjs
var WS=require('ws-share');
//or vanilla js
var ws=new WS('wss://echo.websocket.org/?encoding=text');
ws.on(
'open',
function(e){
console.log('shared websocket open!');
}
)
ws.on(
'close',
function(e){
console.log('shared websocket closed!');
}
)
ws.on(
'error',
function(e){
console.log('OMG there\'s been an error!',e);
}
)
ws.on(
'message',
function(e){
console.log('got message on shared ws!',e.data);
}
)
```
## Basic Example :
You will notice this looks just like a standard websocket creation, but behind the scenes it stores a refrence to share with any other component, store, or action which may also need access to this same websocket.
```javascript
//commonjs
var WS=require('ws-share');
//or vanilla js
var ws=new WS('wss://echo.websocket.org/?encoding=text');
ws.on(
'message',
function(e){
console.log(e.data);
}
);
```
## Basic Node Example :
```javascript
var WS=require('ws-share');
var ws=new WS('wss://echo.websocket.org/?encoding=text');
ws.on(
'open',
function(){
ws.send('hello world!');
}
);
ws.on(
'message',
function (message){
console.log(message);
}
);
ws.on(
'error',
function (err){
console.log('error encountered :', err);
}
);
```
## Basic React Send Example :
You will notice this looks just like a standard websocket creation, but behind the scenes it stores a refrence to share with any other component, store, or action which may also need access to this same websocket. For example, the next example, Output would share this same ws without needing a different format.
```javascript
var React=require('react');
var WS=require('ws-share');
var Input=React.createClass(
{
componentWillMount:function(){
this.ws=new WS('wss://echo.websocket.org/?encoding=text');
},
componentWillUnmount:function(){
this.ws=null;
},
_change:function(e){
if(this.ws.readyState!==1){
console.log('WS not yet connected or already disconnected. Can not send message.');
return;
}
this.ws.send(e.target.value);
},
render:function(){
return (
Send To Server
)
}
}
);
module.exports=Input;
```
## Basic React Listen for Message Example :
You will notice this looks just like a standard websocket creation, but behind the scenes it stores a refrence to share with any other component, store, or action which may also need access to this same websocket. For example, the previous example, Input would share this same ws without needing a different format.
```javascript
var React=require('react');
var WS=require('ws-share');
var Output=React.createClass(
{
getInitialState:function(){
return {
message:''
}
},
componentWillMount:function(){
this.ws=new WS('wss://echo.websocket.org/?encoding=text');
this.ws.on(
'message',
function(e){
this.setState(
{
message:e.data
}
)
//We want to use this.state,
//so we have to bind the react component
//scope to the callback
}.bind(this)
);
},
componentWillUnmount:function(){
this.ws=null;
},
_change:function(e){
if(this.ws.readyState!==1){
console.log('WS not yet connected or already disconnected. Can not send message.');
return;
}
this.ws.send(e.target.value);
},
render:function(){
return (
Got From Server
)
}
}
);
module.exports=Output;
```
---
This work is licenced via the [DBAD Public Licence](http://www.dbad-license.org/).