update docs - clean up interface (brianc#2863)

* update docs - clean up interface

* Remove node v8.x from test matrix

Author: brianc

.github/workflows/ci.yml

@@ -20,7 +20,7 @@ jobs:
         options: --health-cmd pg_isready --health-interval 10s --health-timeout 5s --health-retries 5
     strategy:
       matrix:
-        node: ['8', '10', '12', '14', '16', '18']
+        node: ['10', '12', '14', '16', '18']
         os: [ubuntu-latest, windows-latest, macos-latest]
     name: Node.js ${{ matrix.node }} (${{ matrix.os }})
     steps:

SPONSORS.md

@@ -16,6 +16,7 @@ node-postgres is made possible by the helpful contributors from the community as
 - [@BLUE-DEVIL1134](https://github.com/BLUE-DEVIL1134)
 - [bubble.io](https://bubble.io/)
 - GitHub[https://github.com/github]
+- loveland [https://github.com/loveland]
 
 # Supporters
 
@@ -48,3 +49,4 @@ node-postgres is made possible by the helpful contributors from the community as
 - [Scout APM](https://github.com/scoutapm-sponsorships)
 - [Sideline Sports](https://github.com/SidelineSports)
 - [Gadget](https://github.com/gadget-inc)
+- [Sentry](https://sentry.io/welcome/)

docs/pages/apis/client.mdx

@@ -41,8 +41,6 @@ const client = new Client({
 
 ## client.connect
 
-### `client.connect(callback: (err: Error) => void) => void`
-
 Calling `client.connect` with a callback:
 
 ```js
@@ -57,8 +55,6 @@ client.connect((err) => {
 })
 ```
 
-### `client.connect() => Promise<void>`
-
 Calling `client.connect` without a callback yields a promise:
 
 ```js
@@ -74,19 +70,35 @@ _note: connect returning a promise only available in [email protected] or above_
 
 ## client.query
 
-### `client.query` - text, optional values, and callback.
+### QueryConfig
 
-Passing query text, optional query parameters, and a callback to `client.query` results in a type-signature of:
+You can pass an object to `client.query` with the signature of:
 
 ```ts
-client.query(
-  text: string,
-  values?: Array<any>,
-  callback: (err: Error, result: Result) => void
-) => void
+type QueryConfig {
+  // the raw query text
+  text: string;
+
+  // an array of query parameters
+  values?: Array<any>;
+
+  // name of the query - used for prepared statements
+  name?: string;
+
+  // by default rows come out as a key/value pair for each row
+  // pass the string 'array' here to receive rows as an array of values
+  rowMode?: string;
+
+  // custom type parsers just for this query result
+  types?: Types;
+}
 ```
 
-That is a kinda gross type signature but it translates out to this:
+### callback API
+
+```ts
+client.query(text: string, values?: any[], callback?: (err: Error, result: QueryResult) => void) => void
+```
 
 **Plain text query with a callback:**
 
@@ -114,15 +126,12 @@ client.query('SELECT $1::text as name', ['brianc'], (err, res) => {
 })
 ```
 
-### `client.query` - text, optional values: Promise
+### Promise API
 
 If you call `client.query` with query text and optional parameters but **don't** pass a callback, then you will receive a `Promise` for a query result.
 
 ```ts
-client.query(
-  text: string,
-  values?: Array<any>
-) => Promise<Result>
+client.query(text: string, values?: any[]) => Promise<Result>
 ```
 
 **Plain text query with a promise**
@@ -151,30 +160,8 @@ client
   .then(() => client.end())
 ```
 
-### `client.query(config: QueryConfig, callback: (err?: Error, result?: Result) => void) => void`
-
-### `client.query(config: QueryConfig) => Promise<Result>`
-
-You can pass an object to `client.query` with the signature of:
-
 ```ts
-type QueryConfig {
-  // the raw query text
-  text: string;
-
-  // an array of query parameters
-  values?: Array<any>;
-
-  // name of the query - used for prepared statements
-  name?: string;
-
-  // by default rows come out as a key/value pair for each row
-  // pass the string 'array' here to receive rows as an array of values
-  rowMode?: string;
-
-  // custom type parsers just for this query result
-  types?: Types;
-}
+client.query(config: QueryConfig) => Promise<Result>
 ```
 
 **client.query with a QueryConfig and a callback**
@@ -246,8 +233,6 @@ query.on('error', (err) => {
 
 ## client.end
 
-### client.end(cb?: (err?: Error) => void) => void
-
 Disconnects the client from the PostgreSQL server.
 
 ```js
@@ -259,8 +244,6 @@ client.end((err) => {
 })
 ```
 
-### `client.end() => Promise<void>`
-
 Calling end without a callback yields a promise:
 
 ```js
@@ -274,7 +257,11 @@ _note: end returning a promise is only available in pg7.0 and above_
 
 ## events
 
-### client.on('error', (err: Error) => void) => void
+### error
+
+```ts
+client.on('error', (err: Error) => void) => void
+```
 
 When the client is in the process of connecting, dispatching a query, or disconnecting it will catch and foward errors from the PostgreSQL server to the respective `client.connect` `client.query` or `client.end` callback/promise; however, the client maintains a long-lived connection to the PostgreSQL back-end and due to network partitions, back-end crashes, fail-overs, etc the client can (and over a long enough time period _will_) eventually be disconnected while it is idle. To handle this you may want to attach an error listener to a client to catch errors. Here's a contrived example:
 
@@ -291,11 +278,15 @@ client.on('error', (err) => {
 // process output: 'something bad has happened!' followed by stacktrace :P
 ```
 
-### client.on('end') => void
+### end
+
+```ts
+client.on('end') => void
+```
 
 When the client disconnects from the PostgreSQL server it will emit an end event once.
 
-### client.on('notification', (notification: Notification) => void) => void
+### notification
 
 Used for `listen/notify` events:
 
@@ -321,7 +312,11 @@ client.on('notification', (msg) => {
 client.query(`NOTIFY foo, 'bar!'`)
 ```
 
-### client.on('notice', (notice: Error) => void) => void
+### notice
+
+```ts
+client.on('notice', (notice: Error) => void) => void
+```
 
 Used to log out [notice messages](https://www.postgresql.org/docs/9.6/static/plpgsql-errors-and-messages.html) from the PostgreSQL server.
 

docs/pages/apis/pool.mdx

@@ -63,7 +63,9 @@ const pool = new Pool({
 
 Often we only need to run a single query on the database, so as convenience the pool has a method to run a query on the first available idle client and return its result.
 
-`pool.query() => Promise<pg.Result>`
+```ts
+pool.query(text: string, values?: any[]) => Promise<pg.Result>
+```
 
 ```js
 const { Pool } = require('pg')
@@ -78,7 +80,9 @@ pool
 
 Callbacks are also supported:
 
-`pool.query(callback: (err?: Error, result: pg.Result)) => void`
+```ts
+pool.query(text: string, values?: any[], callback?: (err?: Error, result: pg.Result)) => void
+```
 
 ```js
 const { Pool } = require('pg')

docs/pages/index.mdx

@@ -13,20 +13,7 @@ $ npm install pg
 
 ## Supporters
 
-node-postgres continued development and support is made possible by the many [supporters](https://github.com/brianc/node-postgres/blob/master/SPONSORS.md) with a special thanks to our featured supporters:
-
-<div className="sponsors">
-  <div className="sponsor">
-    <a href="https://www.crate.io">
-      <img src="crate-io.png" style={{ height: 80 }} alt="crate.io" />
-    </a>
-  </div>
-  <div className="sponsor">
-    <a href="https://www.eaze.com/">
-      <img src="eaze.png" style={{ height: 80 }} alt="eaze.com" />
-    </a>
-  </div>
-</div>
+node-postgres continued development and support is made possible by the many [supporters](https://github.com/brianc/node-postgres/blob/master/SPONSORS.md).
 
 If you or your company would like to sponsor node-postgres stop by [github sponsors](https://github.com/sponsors/brianc) and sign up or feel free to [email me](mailto:[email protected]) if you want to add your logo to the documentation or discuss higher tiers of sponsorship!