Merge pull request #84 from malthe/docs

Add code-based documentation via TSDoc annotations

Author: malthe

.github/workflows/main.yml

@@ -11,6 +11,11 @@ on:
 env:
   PGDATADIR: /var/lib/postgresql/data
 
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
 jobs:
   build:
     runs-on: ubuntu-latest
@@ -73,3 +78,18 @@ jobs:
           PGPORT: ${{ job.services.postgres.ports[5432] }}
           PGUSER: postgres
           PGPASSWORD: postgres
+      - name: Docs
+        run: npx typedoc
+      - uses: actions/upload-pages-artifact@v2
+        with:
+          path: ./docs
+  deploy:
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v2

README.md

@@ -1,5 +1,3 @@
-# ts-postgres
-
 ![Build Status](https://github.com/malthe/ts-postgres/actions/workflows/main.yml/badge.svg)
 <span class="badge-npmversion"><a href="https://npmjs.org/package/ts-postgres" title="View this project on NPM"><img src="https://img.shields.io/npm/v/ts-postgres.svg" alt="NPM version" /></a></span>
 <span class="badge-npmdownloads"><a href="https://npmjs.org/package/ts-postgres" title="View this project on NPM"><img src="https://img.shields.io/npm/dm/ts-postgres.svg" alt="NPM downloads" /></a></span>
@@ -26,6 +24,8 @@ $ npm install ts-postgres@latest
   * Promise-based
   * Streaming
 
+See the [documentation](https://malthe.github.io/ts-postgres/) for a complete reference.
+
 ---
 
 ## Usage
@@ -59,7 +59,7 @@ async function main() {
     }
 }
 
-await main()
+await main();
 ```
 Waiting on the result (i.e., result iterator) returns the complete query result.
 

package-lock.json

@@ -74,13 +74,14 @@
         "eslint-config-standard": "^17.1.0",
         "eslint-plugin-import": "^2.29.0",
         "eslint-plugin-node": "^11.1.0",
-        "eslint-plugin-promise": "^6.1.1",
         "eslint-plugin-prettier": "^5.0.1",
+        "eslint-plugin-promise": "^6.1.1",
         "jest": "^29.7.0",
         "lint-staged": "^15.0.2",
         "rimraf": "^3.0.2",
         "ts-jest": "^29.1.1",
         "ts-node": "^10.9.1",
+        "typedoc": "^0.25.4",
         "typescript": "^4.9.5"
     }
 }

package.json

@@ -101,7 +101,7 @@ export interface PreparedStatement<T = ResultRecord> {
     ) => ResultIterator<T>
 }
 
-type Callback<T> = (data: T) => void;
+export type Callback<T> = (data: T) => void;
 
 /* eslint-disable  @typescript-eslint/no-explicit-any */
 type CallbackOf<U> = U extends any ? Callback<U> : never;
@@ -155,6 +155,11 @@ interface PreFlightQueue {
     bind: Bind | null;
 }
 
+/** A database client, opening a single connection to the database.
+ *
+ * @remarks
+ * You must open the connection using {@link connect}, otherwise no query will be processed.
+ */
 export class Client {
     private readonly events = {
         connect: new TypedEvent<Connect>(),
@@ -197,6 +202,11 @@ export class Client {
     public secretKey: number | null = null;
     public transactionStatus: TransactionStatus | null = null;
 
+    /**
+    * @param config - An optional configuration object, comprised of connection details
+    *     and client configuration. Most of the connection details can also be specified
+    *     using environment variables, see {@link Environment}.
+    */
     constructor(public readonly config: Configuration = {}) {
         this.encoding = config.clientEncoding || defaults.clientEncoding as BufferEncoding || 'utf-8';
         this.writer = new Writer(this.encoding);