subscription.js Emit 'connected' event with subscription.id (web3#3028)

* Update subscription.js

* Updates Changelog and Docs

CHANGELOG.md

@@ -43,7 +43,7 @@ Released with 1.0.0-beta.37 code base.
 ### Fixed
 
 - ``websocket`` dependency fixed (#2971, #2976)
-- ``requestOptions`` added to ``WebsocketProvider`` (#2979) 
+- ``requestOptions`` added to ``WebsocketProvider`` (#2979)
 - Node >= v8.0.0 support (#2938)
 
 ## [Unreleased]
@@ -58,6 +58,7 @@ Released with 1.0.0-beta.37 code base.
 - Add `eth.getChainId` method (#3113)
 - Minified file added to web3 package (#3131)
 - The transaction confirmation workflow can now be configured (#3130)
+- Emit `connected` event on subscription creation (#3028)
 - TypeScript type definitions added for all modules (#3132)
 - Bloom filters added to web3.utils (#3137)
 

docs/web3-eth-contract.rst

@@ -953,6 +953,7 @@ Returns
 - ``"data"`` returns ``Object``: Fires on each incoming event with the event object as argument.
 - ``"changed"`` returns ``Object``: Fires on each event which was removed from the blockchain. The event will have the additional property ``"removed: true"``.
 - ``"error"`` returns ``Object``: Fires when an error in the subscription occours.
+- ``"connected"`` returns ``String``: Fires once after the subscription successfully connected. Returns the subscription id.
 
 
 The structure of the returned event ``Object`` looks as follows:
@@ -979,6 +980,9 @@ Example
         filter: {myIndexedParam: [20,23], myOtherIndexedParam: '0x123456789...'}, // Using an array means OR: e.g. 20 or 23
         fromBlock: 0
     }, function(error, event){ console.log(event); })
+    .on("connected", function(subscriptionId){
+        console.log(subscriptionId);
+    })
     .on('data', function(event){
         console.log(event); // same results as the optional callback above
     })

docs/web3-eth-subscribe.rst

@@ -38,6 +38,7 @@ Returns
     - ``on("data")`` returns ``Object``: Fires on each incoming log with the log object as argument.
     - ``on("changed")`` returns ``Object``: Fires on each log which was removed from the blockchain. The log will have the additional property ``"removed: true"``.
     - ``on("error")`` returns ``Object``: Fires when an error in the subscription occurs.
+    - ``on("connected")`` returns ``String``: Fires once after the subscription successfully connected. Returns the subscription id.
 
 ----------------
 Notification returns
@@ -189,6 +190,7 @@ Returns
 
 - ``"data"`` returns ``Object``: Fires on each incoming block header.
 - ``"error"`` returns ``Object``: Fires when an error in the subscription occurs.
+- ``"connected"`` returns ``Number``: Fires once after the subscription successfully connected. Returns the subscription id.
 
 The structure of a returned block header is as follows:
 
@@ -230,6 +232,9 @@ Example
 
         console.error(error);
     })
+    .on("connected", function(subscriptionId){
+        console.log(subscriptionId);
+    })
     .on("data", function(blockHeader){
         console.log(blockHeader);
     })
@@ -340,6 +345,7 @@ Returns
 - ``"data"`` returns ``Object``: Fires on each incoming log with the log object as argument.
 - ``"changed"`` returns ``Object``: Fires on each log which was removed from the blockchain. The log will have the additional property ``"removed: true"``.
 - ``"error"`` returns ``Object``: Fires when an error in the subscription occurs.
+- ``"connected"`` returns ``Number``: Fires once after the subscription successfully connected. Returns the subscription id.
 
 For the structure of a returned event ``Object`` see :ref:`web3.eth.getPastEvents return values <eth-getpastlogs-return>`.
 
@@ -364,6 +370,9 @@ Example
         if (!error)
             console.log(result);
     })
+    .on("connected", function(subscriptionId){
+        console.log(subscriptionId);
+    })
     .on("data", function(log){
         console.log(log);
     })

packages/web3-core-subscriptions/src/subscription.js

@@ -249,6 +249,7 @@ Subscription.prototype.subscribe = function() {
     this.options.requestManager.send(payload, function (err, result) {
         if(!err && result) {
             _this.id = result;
+            _this.emit('connected', result);
 
             // call callback on notifications
             _this.options.requestManager.addSubscription(_this.id, payload.params[0] , _this.options.type, function(err, result) {