node_modules/express-ws/README.md

   1 # express-ws [![Dependency Status](https://snyk.io/test/github/henningm/express-ws/badge.svg)](https://snyk.io/test/github/henningm/express-ws)
   2
   3 [WebSocket](https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_API) endpoints for [Express](http://expressjs.com/) applications. Lets you define WebSocket endpoints like any other type of route, and applies regular Express middleware. The WebSocket support is implemented with the help of the [ws](https://github.com/websockets/ws) library.
   4
   5 ## Installation
   6
   7 `npm install --save express-ws`
   8
   9 ## Usage
  10
  11 __Full documentation can be found in the API section below. This section only shows a brief example.__
  12
  13 Add this line to your Express application:
  14
  15 ```javascript
  16 var expressWs = require('express-ws')(app);
  17 ```
  18
  19 __Important: Make sure to set up the `express-ws` module like above *before* loading or defining your routers!__ Otherwise, `express-ws` won't get a chance to set up support for Express routers, and you might run into an error along the lines of `router.ws is not a function`.
  20
  21 After setting up `express-ws`, you will be able to add WebSocket routes (almost) the same way you add other routes. The following snippet sets up a simple echo server at `/echo`.  The `ws` parameter is an instance of the WebSocket class described [here](https://github.com/websockets/ws/blob/master/doc/ws.md#class-websocket).
  22
  23 ```javascript
  24 app.ws('/echo', function(ws, req) {
  25   ws.on('message', function(msg) {
  26     ws.send(msg);
  27   });
  28 });
  29 ```
  30
  31 It works with routers, too, this time at `/ws-stuff/echo`:
  32
  33 ```javascript
  34 var router = express.Router();
  35
  36 router.ws('/echo', function(ws, req) {
  37   ws.on('message', function(msg) {
  38     ws.send(msg);
  39   });
  40 });
  41
  42 app.use("/ws-stuff", router);
  43 ```
  44
  45 ## Full example
  46
  47 ```javascript
  48 var express = require('express');
  49 var app = express();
  50 var expressWs = require('express-ws')(app);
  51
  52 app.use(function (req, res, next) {
  53   console.log('middleware');
  54   req.testing = 'testing';
  55   return next();
  56 });
  57
  58 app.get('/', function(req, res, next){
  59   console.log('get route', req.testing);
  60   res.end();
  61 });
  62
  63 app.ws('/', function(ws, req) {
  64   ws.on('message', function(msg) {
  65     console.log(msg);
  66   });
  67   console.log('socket', req.testing);
  68 });
  69
  70 app.listen(3000);
  71 ```
  72
  73 ## API
  74
  75 ### expressWs(app, *server*, *options*)
  76
  77 Sets up `express-ws` on the specified `app`. This will modify the global Router prototype for Express as well - see the `leaveRouterUntouched` option for more information on disabling this.
  78
  79 * __app__: The Express application to set up `express-ws` on.
  80 * __server__: *Optional.* When using a custom `http.Server`, you should pass it in here, so that `express-ws` can use it to set up the WebSocket upgrade handlers. If you don't specify a `server`, you will only be able to use it with the server that is created automatically when you call `app.listen`.
  81 * __options__: *Optional.* An object containing further options.
  82   * __leaveRouterUntouched:__ Set this to `true` to keep `express-ws` from modifying the Router prototype. You will have to manually `applyTo` every Router that you wish to make `.ws` available on, when this is enabled.
  83   * __wsOptions:__ Options object passed to WebSocketServer constructor. Necessary for any ws specific features.
  84
  85 This function will return a new `express-ws` API object, which will be referred to as `wsInstance` in the rest of the documentation.
  86
  87 ### wsInstance.app
  88
  89 This property contains the `app` that `express-ws` was set up on.
  90
  91 ### wsInstance.getWss()
  92
  93 Returns the underlying WebSocket server/handler. You can use `wsInstance.getWss().clients` to obtain a list of all the connected WebSocket clients for this server.
  94
  95 Note that this list will include *all* clients, not just those for a specific route - this means that it's often *not* a good idea to use this for broadcasts, for example.
  96
  97 ### wsInstance.applyTo(router)
  98
  99 Sets up `express-ws` on the given `router` (or other Router-like object). You will only need this in two scenarios:
 100
 101 1. You have enabled `options.leaveRouterUntouched`, or
 102 2. You are using a custom router that is not based on the express.Router prototype.
 103
 104 In most cases, you won't need this at all.
 105
 106 ## Development
 107
 108 This module is written in ES6, and uses Babel for compilation. What this means in practice:
 109
 110 * The source code lives in the `src/` directory.
 111 * After changing this code, make sure to run `npm run build` to compile it.