[feature] Add a 'disconnecting' event to access to socket.rooms upon disconnection (#2332)

Author: darrachequesne

Readme.md

@@ -402,7 +402,24 @@ server.listen(3000);
 
   Disconnects this client. If value of close is `true`, closes the underlying connection. 
   Otherwise, it just disconnects the namespace.
-    
+
+#### Events
+
+- `disconnect`
+    - Fired upon disconnection.
+    - **Arguments**
+      - `String`: the reason of the disconnection (either client or server-side)
+- `error`
+    - Fired when an error occurs.
+    - **Arguments**
+      - `Object`: error data
+- `disconnecting`
+    - Fired when the client is going to be disconnected (but hasn't left its `rooms` yet).
+    - **Arguments**
+      - `String`: the reason of the disconnection (either client or server-side)
+
+These are reserved events (along with `connect`, `newListener` and `removeListener`) which cannot be used as event names.
+
 
 ### Client
 

lib/socket.js

@@ -25,6 +25,7 @@ exports.events = [
   'error',
   'connect',
   'disconnect',
+  'disconnecting',
   'newListener',
   'removeListener'
 ];
@@ -428,6 +429,7 @@ Socket.prototype.onerror = function(err){
 Socket.prototype.onclose = function(reason){
   if (!this.connected) return this;
   debug('closing socket - reason %s', reason);
+  this.emit('disconnecting', reason);
   this.leaveAll();
   this.nsp.remove(this);
   this.client.remove(this);

test/socket.io.js

@@ -644,6 +644,31 @@ describe('socket.io', function(){
       });
     });
 
+    it('should fire a `disconnecting` event just before leaving all rooms', function(done){
+      var srv = http();
+      var sio = io(srv);
+      srv.listen(function(){
+        var socket = client(srv);
+
+        sio.on('connection', function(s){
+          s.join('a', function(){
+            s.disconnect();
+          });
+
+          var total = 2;
+          s.on('disconnecting', function(reason){
+            expect(Object.keys(s.rooms)).to.eql([s.id, 'a']);
+            total--;
+          });
+
+          s.on('disconnect', function(reason){
+            expect(Object.keys(s.rooms)).to.eql([]);
+            --total || done();
+          });
+        });
+      });
+    });
+
     it('should return error connecting to non-existent namespace', function(done){
       var srv = http();
       var sio = io(srv);