feat: Add functional client creator and documentation (#9)

Author: hofmeister

README.md

@@ -1,9 +1,26 @@
-# Postgres support for Kapeta
+# NodeJS Postgres support for Kapeta
+
+Creates a client using Prisma and connects to a Postgres database.
+
+Is meant to be used with Kapeta and resources defined in a NodeJS Kapeta block.
 
 Uses Prisma to make it simple to work with Postgres from Kapeta - and 
 add support for DB migrations.
 
 Also exposes a CLI tool called ```kap-postgres-url``` that can be used
 to generate a PG database URL from within a Kapeta block - for a given environment.
 
+To learn more about Kapeta, visit [kapeta.com](https://kapeta.com).
+
+## Usage
+
+This library exposes a class and function that can be used to create a client.
+
+Normal usage is generated using Kapeta - but it can also be used directly.
+
+### `createPostgresDBClient`
+Async function that creates a client using Prisma and connects to a Postgres database
 
+### `PostgresDB`
+Class that creates a client using Prisma and connects to a Postgres database.
+It will auto-initialize once the configuration provider is ready.

src/PostgresDB.ts

@@ -11,12 +11,41 @@ interface PrismaClient {
     $disconnect(): Promise<void>;
 }
 
+/**
+ * Create a postgres client and connect it to the database
+ *
+ * @param config the kapeta config provider
+ * @param resourceName the resource name within the block
+ * @param createClient a function that creates the prisma client
+ */
+export const createPostgresDBClient = async <T extends PrismaClient>(config:ConfigProvider, resourceName: string, createClient: (opts: any) => T) => {
+    const url = await createDBURI(config, resourceName);
+    console.log('Connecting to postgres database: %s', resourceName);
+
+    const prisma = createClient({
+        datasources: {
+            db: {
+                url
+            },
+        },
+    });
+
+    await prisma.$connect();
+    console.log('Connected successfully to postgres database: %s', resourceName);
+    return prisma;
+}
 
+/**
+ * A base class for postgres databases.
+ *
+ * See also {@link createPostgresDBClient} which is the recommended way to create a postgres client.
+ */
 export abstract class PostgresDB<T extends PrismaClient> {
     private readonly _resourceName: string;
     private _ready: boolean = false;
     private _prisma?: T;
-    constructor(resourceName:string) {
+
+    protected constructor(resourceName:string) {
         this._resourceName = resourceName;
         Config.onReady(async (provider) => {
             await this.init(provider);
@@ -26,19 +55,7 @@ export abstract class PostgresDB<T extends PrismaClient> {
     abstract createClient(opts: any): T;
 
     async init(provider: ConfigProvider) {
-        const url = await createDBURI(provider, this._resourceName);
-        console.log('Connecting to postgres database: %s', url);
-
-        this._prisma = this.createClient({
-            datasources: {
-                db: {
-                    url
-                },
-            },
-        });
-
-        await this._prisma.$connect();
-        console.log('Connected successfully to postgres database: %s', url);
+        this._prisma = await createPostgresDBClient(provider, this._resourceName, this.createClient);
         this._ready = true;
     }