From 2c6d32623a0af88d5b258b0df9eb9b6fb8b6f9c0 Mon Sep 17 00:00:00 2001
From: Justin Wind <justin.wind+git@gmail.com>
Date: Fri, 25 Jul 2025 15:40:40 -0700
Subject: [PATCH] doc updates

---
 README.md               | 51 +++++++++++++++++++++++++++++++++++------
 lib/postgres-creator.js |  8 +++++++
 lib/sqlite-creator.js   |  8 +++++++
 3 files changed, 60 insertions(+), 7 deletions(-)

diff --git a/README.md b/README.md
index ca918e1..52eb426 100644
--- 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 5e124aa..6273fa4 100644
--- 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 8eb5777..76f53c6 100644
--- 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 {
-- 
2.49.1