Return the client instance in the connect() method (#3564)

* Return the client instance in the `connect()` method

* Added one basic test

* Renamed

* Testing the result

* Added equality check

* Simplified docs for connecting

* Added it to the native client as well

* Added this to the callback

Author: franciscop

docs/pages/index.mdx

@@ -44,8 +44,7 @@ The simplest possible way to connect, query, and disconnect is with async/await:
 
 ```js
 import { Client } from 'pg'
-const client = new Client()
-await client.connect()
+const client = await new Client().connect();
 
 const res = await client.query('SELECT $1::text as message', ['Hello world!'])
 console.log(res.rows[0].message) // Hello world!
@@ -83,5 +82,3 @@ console.log(res.rows[0].message) // Hello world!
 ```
 
 Our real-world apps are almost always more complicated than that, and I urge you to read on!
-
-

packages/pg/lib/client.js

@@ -213,7 +213,7 @@ class Client extends EventEmitter {
         if (error) {
           reject(error)
         } else {
-          resolve()
+          resolve(this)
         }
       })
     })

packages/pg/lib/native/client.js

@@ -119,7 +119,7 @@ Client.prototype._connect = function (cb) {
       self.emit('connect')
       self._pulseQueryQueue(true)
 
-      cb()
+      cb(null, this)
     })
   })
 }
@@ -135,7 +135,7 @@ Client.prototype.connect = function (callback) {
       if (error) {
         reject(error)
       } else {
-        resolve()
+        resolve(this)
       }
     })
   })

packages/pg/test/integration/client/promise-api-tests.js

@@ -20,6 +20,14 @@ suite.test('valid connection completes promise', () => {
   })
 })
 
+suite.test('valid connection returns the client in a promise', () => {
+  const client = new pg.Client()
+  return client.connect().then((clientInside) => {
+    assert.equal(client, clientInside)
+    return client.end().then(() => {})
+  })
+})
+
 suite.test('invalid connection rejects promise', (done) => {
   const client = new pg.Client({ host: 'alksdjflaskdfj', port: 1234 })
   return client.connect().catch((e) => {