Updates Changelog and Docs

Author: lbertenasco

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]
@@ -74,3 +74,9 @@ Released with 1.0.0-beta.37 code base.
 - Gas check fixed (#2381)
 - Signing issues #1998, #2033, and #1074 fixed (#3125)
 - Fix hexToNumber and hexToNumberString prefix validation (#3086)
+
+## [1.2.2]
+
+### Added
+
+- Emit `connected` event on subscription creation (#3028)

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 ``Number``: 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);
     })