Pg-promise: Make Client extendable within TypeScript

[vitaly-t]

The library's TypeScript presently exposes interface IClient from the underlying driver.

However, the recent updates in the driver allow a dynamic Client to be provided by the Pool, if such is specified within the connection parameters.

---

Make changes in the TypeScript to allow use of a custom Client, with automatic type inference.

[vitaly-t]

There were no breaking changes in the end, only a thorough incremental revamp of the TypeScript declarations, which should provide full backward compatibility.

Below is a complete example of how we can set the connection pool to use our own custom Client type. In the example, we extend the type to contain the server version.

import * as pgPromise from 'pg-promise';

const pgp = pgPromise(/* initialization options */);

/* our custom Client class */
class MyClient extends pgp.pg.Client {

    version?: string; // PostgreSQL server version

    constructor(config: any) {
        super(config);

        //  we can handle useful connection events here:
        this.connection.on('parameterStatus', (msg: any) => {
            if (msg.parameterName === 'server_version') {
                this.version = msg.parameterValue;
            }
        });

       // and we can handle events on the connection stream:
       // this.connection.stream.on('event', () => {});

    }
}

const cn = {
    database: 'db-name',
    user: 'postgres',
    password: 'bla-bla',

    Client: MyClient /* our custom Client type to be created by the connection pool */
};

const db = pgp(cn);

/* using manual connection below just to test the Client type inference */
db.connect()
    .then(c => {
        // client type is inferred correctly, from the Client connection parameter:
        console.log('Server Version:', c.client.version);
        c.done();
    })
    .catch(console.error)
    .finally(pgp.end);

On my test PC I am getting:

Server Version: 11.2

It can be useful to handle the server version detection properly this way. PostgreSQL is developing fast, and there are many new features being brought in with the new versions, and you can make conditional use of those, based on the server version. For example, see this related question, where stored procedure calls can be used with PostgreSQL v11 and later.

See also prior research I did for this example.

Note that the example above does not work with the Native Bindings, because with those, the client does not expose its connection.

UPDATE

After releasing #673 in v10.1.0, the specific example of getting version is no longer of much use, because now we have the version automatically everywhere.

[vitaly-t]

Released in version 9.3.4

[JCMais]

Generics ftw

[vitaly-t]

9.3.5 update improves it a little.

[vitaly-t]

@realcarbonneau Is there a reason you down-voted the 9.3.5 update?

[realcarbonneau]

Misclick, sorry, thanks for pointing that out.

[vitaly-t]

Added update to the original example. Basically, #673 made the example kind of obsolete, i.e. it still will work, you just no longer would use it specifically for detecting the server version.