[feat] Add a 'binary' flag (#3185)

So that the call to the `has-binary` method can be skipped. Usage:

```
// with binary data
socket.binary(true).emit("binary", obj);

// without binary data
socket.binary(false).emit("string", obj);

// call to hasBin
socket.emit("guess", obj);
```

Author: darrachequesne

docs/API.md

@@ -33,6 +33,7 @@
     - [Event: 'connection'](#event-connect)
     - [Flag: 'volatile'](#flag-volatile)
     - [Flag: 'local'](#flag-local)
+    - [Flag: 'binary'](#flag-binary)
   - [Class: Socket](#socket)
     - [socket.id](#socketid)
     - [socket.rooms](#socketrooms)
@@ -57,6 +58,7 @@
     - [socket.disconnect(close)](#socketdisconnectclose)
     - [Flag: 'broadcast'](#flag-broadcast)
     - [Flag: 'volatile'](#flag-volatile-1)
+    - [Flag: 'binary'](#flag-binary-1)
     - [Event: 'disconnect'](#event-disconnect)
     - [Event: 'error'](#event-error)
     - [Event: 'disconnecting'](#event-disconnecting)
@@ -470,6 +472,14 @@ Sets a modifier for a subsequent event emission that the event data may be lost
 io.volatile.emit('an event', { some: 'data' }); // the clients may or may not receive it
 ```
 
+#### Flag: 'binary'
+
+Specifies whether there is binary data in the emitted data. Increases performance when specified. Can be `true` or `false`.
+
+```js
+io.binary(false).emit('an event', { some: 'data' });
+```
+
 #### Flag: 'local'
 
 Sets a modifier for a subsequent event emission that the event data will only be _broadcast_ to the current node (when the [Redis adapter](https://github.com/socketio/socket.io-redis) is used).
@@ -769,6 +779,17 @@ io.on('connection', (socket) => {
 });
 ```
 
+#### Flag: 'binary'
+
+Specifies whether there is binary data in the emitted data. Increases performance when specified. Can be `true` or `false`.
+
+```js
+var io = require('socket.io')();
+io.on('connection', function(socket){
+  socket.binary(false).emit('an event', { some: 'data' }); // The data to send has no binary data
+});
+```
+
 #### Event: 'disconnect'
 
   - `reason` _(String)_ the reason of the disconnection (either client or server-side)

docs/emit.md

@@ -40,9 +40,12 @@ function onConnect(socket){
   // sending a message that might be dropped if the client is not ready to receive messages
   socket.volatile.emit('maybe', 'do you really need it?');
 
+  // specifying whether the data to send has binary data
+  socket.binary(false).emit('what', 'I have no binaries!');
+
   // sending to all clients on this node (when using multiple nodes)
   io.local.emit('hi', 'my lovely babies');
-  
+
   // sending to all connected clients
   io.emit('an event sent to all connected clients');
 

lib/index.js

@@ -451,7 +451,7 @@ var emitterMethods = Object.keys(Emitter.prototype).filter(function(key){
   return typeof Emitter.prototype[key] === 'function';
 });
 
-emitterMethods.concat(['to', 'in', 'use', 'send', 'write', 'clients', 'compress']).forEach(function(fn){
+emitterMethods.concat(['to', 'in', 'use', 'send', 'write', 'clients', 'compress', 'binary']).forEach(function(fn){
   Server.prototype[fn] = function(){
     return this.sockets[fn].apply(this.sockets, arguments);
   };

lib/namespace.js

@@ -6,6 +6,7 @@
 var Socket = require('./socket');
 var Emitter = require('events').EventEmitter;
 var parser = require('socket.io-parser');
+var hasBin = require('has-binary2');
 var debug = require('debug')('socket.io:namespace');
 
 /**
@@ -214,7 +215,10 @@ Namespace.prototype.emit = function(ev){
   }
   // set up packet object
   var args = Array.prototype.slice.call(arguments);
-  var packet = { type: parser.EVENT, data: args };
+  var packet = {
+    type: (this.flags.binary !== undefined ? this.flags.binary : hasBin(args)) ? parser.BINARY_EVENT : parser.EVENT,
+    data: args
+  };
 
   if ('function' == typeof args[args.length - 1]) {
     throw new Error('Callbacks are not supported when broadcasting');
@@ -277,3 +281,16 @@ Namespace.prototype.compress = function(compress){
   this.flags.compress = compress;
   return this;
 };
+
+/**
+ * Sets the binary flag
+ *
+ * @param {Boolean} Encode as if it has binary data if `true`, Encode as if it doesnt have binary data if `false`
+ * @return {Socket} self
+ * @api public
+ */
+
+ Namespace.prototype.binary = function (binary) {
+   this.flags.binary = binary;
+   return this;
+ };

lib/socket.js

@@ -5,6 +5,7 @@
 
 var Emitter = require('events').EventEmitter;
 var parser = require('socket.io-parser');
+var hasBin = require('has-binary2');
 var url = require('url');
 var debug = require('debug')('socket.io:socket');
 
@@ -143,7 +144,7 @@ Socket.prototype.emit = function(ev){
 
   var args = Array.prototype.slice.call(arguments);
   var packet = {
-    type: parser.EVENT,
+    type: (this.flags.binary !== undefined ? this.flags.binary : hasBin(args)) ? parser.BINARY_EVENT : parser.EVENT,
     data: args
   };
 
@@ -380,7 +381,7 @@ Socket.prototype.ack = function(id){
 
     self.packet({
       id: id,
-      type: parser.ACK,
+      type: hasBin(args) ? parser.BINARY_ACK : parser.ACK,
       data: args
     });
 
@@ -495,6 +496,19 @@ Socket.prototype.compress = function(compress){
   return this;
 };
 
+/**
+ * Sets the binary flag
+ *
+ * @param {Boolean} Encode as if it has binary data if `true`, Encode as if it doesnt have binary data if `false`
+ * @return {Socket} self
+ * @api public
+ */
+
+ Socket.prototype.binary = function (binary) {
+   this.flags.binary = binary;
+   return this;
+ };
+
 /**
  * Dispatch incoming event to socket listeners.
  *

package.json

@@ -26,9 +26,10 @@
   "dependencies": {
     "debug": "~3.1.0",
     "engine.io": "~3.1.0",
+    "has-binary2": "~1.0.2",
     "socket.io-adapter": "~1.1.0",
     "socket.io-client": "2.0.4",
-    "socket.io-parser": "~3.1.1"
+    "socket.io-parser": "~3.2.0"
   },
   "devDependencies": {
     "expect.js": "0.3.1",