doc updates

diff --git a/README.md b/README.md
index ca918e19e66dba8d3f39f548460063957381baa3..52eb426c7bda9680e7d10509b227505dc03db3b5 100644 (file)
--- a/README.md
+++ b/README.md
@@ -4,30 +4,67 @@ Helper classes, utilities, and opinions for supporting multiple database engines
 
 - Postgres and SQLite.
 - Application SQL statements loaded from individual files.
-- Column names from DB are automatically converted to JS style.
+- Column names from DB are automatically converted to JS style. (Snake-case to camel-case.)
 - A simple automated schema migration system is provided.
 
+Nota bene: this is not an ORM, but a framework for applying an abstract database interface onto specific underlying engines, while hiding some engine-specific boilerplate.
+Bring your own SQL.
+
 See files in `test-integration` for example implementation, and tree-layout explainer below.
 
-The Abstract class provides boilerplate initialization, and defines some abstract methods which the engines implement.
+## What's In The Box
+
+### Abstract – class
+
+The Abstract class provides boilerplate initialization, and defines some abstract methods which each engine implements.
 Your database interface is defined by extending this Abstract class with your abstract interface methods.
 
 Your abstract interface class is then provided to a function for an engine, which creates an abstract engine class that includes engine-specific boilerplate and implements some of the base abstract methods.
 Your engine implementations extend this abstract engine class.
 
-File-layout is opinionated.  In your application:
+### Factory – class
+
+Instantiates the corresponding engine implementation based on provided database connection configuration.
+
+### SQLiteCreator – class-creator function
+
+Creates an abstract SQLite class using a provided Abstract class.  Extend this with your implmentation.
+
+### PostgresCreator – class-creator function
+
+Creates an abstract PostgreSQL class using a provided Abstract class.  Extend this with your implementation.
+
+### PostgresListener – class
+
+Wrangle a persistent postgres connection for handling notification events.
+
+### EncryptionHelper – class
+
+Class providing simple helpers for wrangling Field Level Encryption.  Currently utilizes chacha20-poly1305.
+
+### validate – function
+
+Very simple type-checker can be used for ensuring parameters are as expected.
+
+### Other Stuff
+
+Test helpers for covering your implementations, and some internals are also exposed.
+
+## Usage
+
+File-layout in your application is opinionated:
 
 - my-db-layer/
        - abstract.js <- extend Abstract with your not-implemented interface methods here
-       - index.js <- extend the engine Factory here
+       - index.js <- extend the engine Factory here to be able to reference the local paths below
        - postgresql/ <- an engine implementation
-               - index.js <- extends the class generated by your Abstract and the engine creator
+               - index.js <- extends the class generated by the engine creator and your Abstract interface
                - sql/ <- statements and schemas for this engine implementation
                        - my-statement.sql <- all sql files at this level are loaded as statements, e.g. db.statement.myStatement
-                       - schema/ <- collection of versioned schemas
+                       - schema/ <- collection of versioned database schemas
                                - init.sql <- optional sql to be executed before creating meta table
                                - init-hooks.js <- optional functions invoked during initialization
-                               - 1.0.0/
+                               - 1.0.0/ <- major.minor.patch versions are applied in order
                                        - apply.sql <- a migration file for creating or altering tables et cetera
                                        - revert.sql <- undo this migration
                                        - hooks.js <- optional functions invoked before and after executing the migration sql

diff --git a/lib/postgres-creator.js b/lib/postgres-creator.js
index 5e124aafdb4d1576d42bd4d8bd8433dcf494f666..6273fa4913b498325fa70bf164058962823dd1d7 100644 (file)
--- a/lib/postgres-creator.js
+++ b/lib/postgres-creator.js
@@ -12,6 +12,14 @@ const PGTypeId = {
   INT8Array: 1016, // Type Id 1016 == INT8[] (BIGINT[])
 };
 
+/**
+ * @typedef {import('./abstract')} Database
+ */
+/**
+ * Return a class extending an Abstract Database with Postgres specifics.
+ * @param {Database} Abstract Abstract Database class
+ * @returns {Database} Abstract Postgres class
+ */
 const PostgresCreator = (Abstract) => {
 
   class DatabasePostgres extends Abstract {

diff --git a/lib/sqlite-creator.js b/lib/sqlite-creator.js
index 8eb5777453e97d992a469b3afef8ebebcc301a26..76f53c62c43ff3f24b78851c0de77d70873a0d51 100644 (file)
--- a/lib/sqlite-creator.js
+++ b/lib/sqlite-creator.js
@@ -11,6 +11,14 @@ const { fileScope } = require('@squeep/log-helper');
 
 const _fileScope = fileScope(__filename);
 
+/**
+ * @typedef {import('./abstract')} Database
+ */
+/**
+ * Return a class extending an Abstract Database with SQLite specifics.
+ * @param {Database} Abstract Abstract Database class
+ * @returns {Database} Abstract SQLite class
+ */
 const SQLiteCreator = (Abstract) => {
 
   class DatabaseSQLite extends Abstract {