outlining docs

Author: cblanquera

docs/Connections.md

@@ -2,18 +2,30 @@
 
 Connection classes provide database-specific implementations for interacting with different SQL engines. Each connection class implements the `Connection` interface from the Inquire library, ensuring a consistent API across all supported databases.
 
-## Overview
+## Table of Contents
+
+ 1. [Overview](#1-overview)
+ 2. [Mysql2Connection](#2-mysql2connection)
+ 3. [PGConnection](#3-pgconnection)
+ 4. [PGLiteConnection](#4-pgliteconnection)
+ 5. [BetterSqlite3Connection](#5-bettersqlite3connection)
+ 6. [Common Interface](#6-common-interface)
+ 7. [Database-Specific Features](#7-database-specific-features)
+
+## 1. Overview
+
+This section provides an overview of the available connection classes and their specific database implementations. Each connection class is designed to work with a particular database engine while maintaining a consistent interface.
 
 Inquire supports multiple database engines through dedicated connection packages:
 
-- **Mysql2Connection** - MySQL via `@stackpress/inquire-mysql2`
-- **PGConnection** - PostgreSQL via `@stackpress/inquire-pg`
-- **PGLiteConnection** - PGLite via `@stackpress/inquire-pglite`
-- **BetterSqlite3Connection** - SQLite via `@stackpress/inquire-sqlite3`
+ - **Mysql2Connection** - MySQL via `@stackpress/inquire-mysql2`
+ - **PGConnection** - PostgreSQL via `@stackpress/inquire-pg`
+ - **PGLiteConnection** - PGLite via `@stackpress/inquire-pglite`
+ - **BetterSqlite3Connection** - SQLite via `@stackpress/inquire-sqlite3`
 
-## Mysql2Connection
+## 2. Mysql2Connection
 
-The `Mysql2Connection` class provides a connection interface for interacting with MySQL databases using the mysql2 library.
+The `Mysql2Connection` class provides a connection interface for interacting with MySQL databases using the mysql2 library. This connection class handles MySQL-specific data formatting and query execution patterns.
 
 ```typescript
 import mysql from 'mysql2/promise';
@@ -28,7 +40,7 @@ const resource = await mysql.createConnection({
 const engine = connect(resource);
 ```
 
-### Properties
+### 2.1. Properties
 
 The following properties are available when using Mysql2Connection.
 
@@ -37,9 +49,11 @@ The following properties are available when using Mysql2Connection.
 | `dialect` | `Dialect` | The SQL dialect used by the connection (Mysql) |
 | `lastId` | `number\|string\|undefined` | The last inserted ID from the database |
 
-### Methods
+### 2.2. Methods
+
+The following methods provide MySQL-specific functionality for query execution and data management.
 
-#### Formatting Queries
+#### 2.2.1. Formatting Queries
 
 The following example shows how the connection formats queries and values for MySQL.
 
@@ -62,7 +76,7 @@ const formatted = connection.format({
 
 A formatted `QueryObject` with values converted for MySQL compatibility.
 
-#### Executing Queries
+#### 2.2.2. Executing Queries
 
 The following example shows how to execute queries and get results.
 
@@ -84,7 +98,7 @@ const users = await connection.query<User>({
 
 A promise that resolves to an array of results typed as `R[]`.
 
-#### Managing Transactions
+#### 2.2.3. Managing Transactions
 
 The following example shows how to execute transactions with MySQL.
 
@@ -106,9 +120,9 @@ const result = await connection.transaction(async (trx) => {
 
 A promise that resolves to the return value of the callback function.
 
-## PGConnection
+## 3. PGConnection
 
-The `PGConnection` class provides a connection interface for interacting with PostgreSQL databases.
+The `PGConnection` class provides a connection interface for interacting with PostgreSQL databases. This connection class handles PostgreSQL-specific parameter placeholders and advanced features.
 
 ```typescript
 import { Client } from 'pg';
@@ -123,17 +137,19 @@ await client.connect();
 const engine = connect(client);
 ```
 
-### Properties
+### 3.1. Properties
 
 The following properties are available when using PGConnection.
 
 | Property | Type | Description |
 |----------|------|-------------|
 | `dialect` | `Dialect` | The SQL dialect used by the connection (Pgsql) |
 
-### Methods
+### 3.2. Methods
 
-#### Formatting Queries
+The following methods provide PostgreSQL-specific functionality for query execution and advanced database operations.
+
+#### 3.2.1. Formatting Queries
 
 The following example shows how the connection formats queries for PostgreSQL.
 
@@ -156,7 +172,7 @@ const formatted = connection.format({
 
 A formatted `QueryObject` with PostgreSQL-style parameter placeholders ($1, $2, etc.).
 
-#### Executing Queries
+#### 3.2.2. Executing Queries
 
 The following example shows how to execute queries and get results.
 
@@ -178,7 +194,7 @@ const users = await connection.query<User>({
 
 A promise that resolves to an array of results typed as `R[]`.
 
-#### Managing Transactions
+#### 3.2.3. Managing Transactions
 
 The following example shows how to execute transactions with PostgreSQL.
 
@@ -200,9 +216,9 @@ const result = await connection.transaction(async (trx) => {
 
 A promise that resolves to the return value of the callback function.
 
-## PGLiteConnection
+## 4. PGLiteConnection
 
-The `PGLiteConnection` class provides a connection interface for interacting with PGLite databases.
+The `PGLiteConnection` class provides a connection interface for interacting with PGLite databases. This connection class offers PostgreSQL compatibility in a lightweight, client-side environment.
 
 ```typescript
 import { PGlite } from '@electric-sql/pglite';
@@ -212,17 +228,19 @@ const db = new PGlite();
 const engine = connect(db);
 ```
 
-### Properties
+### 4.1. Properties
 
 The following properties are available when using PGLiteConnection.
 
 | Property | Type | Description |
 |----------|------|-------------|
 | `dialect` | `Dialect` | The SQL dialect used by the connection (Pgsql) |
 
-### Methods
+### 4.2. Methods
+
+The following methods provide PGLite-specific functionality optimized for client-side and edge environments.
 
-#### Formatting Queries
+#### 4.2.1. Formatting Queries
 
 The following example shows how the connection formats queries for PGLite.
 
@@ -245,7 +263,7 @@ const formatted = connection.format({
 
 A formatted `QueryObject` with PostgreSQL-style parameter placeholders.
 
-#### Executing Queries
+#### 4.2.2. Executing Queries
 
 The following example shows how to execute queries with PGLite.
 
@@ -267,7 +285,7 @@ const users = await connection.query<User>({
 
 A promise that resolves to an array of results typed as `R[]`.
 
-#### Managing Transactions
+#### 4.2.3. Managing Transactions
 
 The following example shows how to execute transactions with PGLite.
 
@@ -289,9 +307,9 @@ const result = await connection.transaction(async (trx) => {
 
 A promise that resolves to the return value of the callback function.
 
-## BetterSqlite3Connection
+## 5. BetterSqlite3Connection
 
-The `BetterSqlite3Connection` class provides a connection interface for interacting with SQLite databases using the better-sqlite3 library.
+The `BetterSqlite3Connection` class provides a connection interface for interacting with SQLite databases using the better-sqlite3 library. This connection class handles SQLite-specific data type conversions and synchronous operations.
 
 ```typescript
 import sqlite from 'better-sqlite3';
@@ -301,7 +319,7 @@ const db = sqlite(':memory:');
 const engine = connect(db);
 ```
 
-### Properties
+### 5.1. Properties
 
 The following properties are available when using BetterSqlite3Connection.
 
@@ -310,9 +328,11 @@ The following properties are available when using BetterSqlite3Connection.
 | `dialect` | `Dialect` | The SQL dialect used by the connection (Sqlite) |
 | `lastId` | `number\|string\|undefined` | The last inserted row ID from the database |
 
-### Methods
+### 5.2. Methods
+
+The following methods provide SQLite-specific functionality for efficient local database operations.
 
-#### Formatting Queries
+#### 5.2.1. Formatting Queries
 
 The following example shows how the connection formats queries for SQLite.
 
@@ -336,7 +356,7 @@ const formatted = connection.format({
 
 A formatted `QueryObject` with values converted for SQLite compatibility.
 
-#### Executing Queries
+#### 5.2.2. Executing Queries
 
 The following example shows how to execute queries with SQLite.
 
@@ -358,7 +378,7 @@ const users = await connection.query<User>({
 
 A promise that resolves to an array of results typed as `R[]`.
 
-#### Managing Transactions
+#### 5.2.3. Managing Transactions
 
 The following example shows how to execute transactions with SQLite.
 
@@ -380,19 +400,21 @@ const result = await connection.transaction(async (trx) => {
 
 A promise that resolves to the return value of the callback function.
 
-## Common Interface
+## 6. Common Interface
 
-All connection classes implement the same `Connection<R>` interface, providing:
+All connection classes implement the same `Connection<R>` interface, providing consistent functionality across different database engines. This unified interface ensures that switching between databases requires minimal code changes.
 
-### Core Methods
+### 6.1. Core Methods
 
-- **`format(request: QueryObject)`** - Formats queries and values for the specific database
-- **`query<R>(request: QueryObject)`** - Executes queries and returns typed results
-- **`raw<R>(request: QueryObject)`** - Executes queries and returns raw database results
-- **`resource()`** - Returns the underlying database connection resource
-- **`transaction<R>(callback: Transaction<R>)`** - Manages database transactions
+The following core methods are available across all connection implementations:
 
-### Type Safety
+ - **`format(request: QueryObject)`** - Formats queries and values for the specific database
+ - **`query<R>(request: QueryObject)`** - Executes queries and returns typed results
+ - **`raw<R>(request: QueryObject)`** - Executes queries and returns raw database results
+ - **`resource()`** - Returns the underlying database connection resource
+ - **`transaction<R>(callback: Transaction<R>)`** - Manages database transactions
+
+### 6.2. Type Safety
 
 All connection classes support TypeScript generics for type-safe operations:
 
@@ -411,7 +433,7 @@ const users = await connection.query<User>({
 // users is typed as User[]
 ```
 
-### Error Handling
+### 6.3. Error Handling
 
 All connections use consistent error handling through the `InquireException`:
 
@@ -427,29 +449,39 @@ try {
 }
 ```
 
-## Database-Specific Features
+## 7. Database-Specific Features
+
+Each connection class provides unique features tailored to its respective database engine. Understanding these differences helps in choosing the right database for your application needs.
+
+### 7.1. MySQL Features
+
+MySQL connections provide the following specific capabilities:
+
+ - **Auto-increment tracking**: Automatically tracks `lastId` for inserted records
+ - **Date handling**: Converts JavaScript Date objects to ISO strings
+ - **Transaction support**: Uses `BEGIN`, `COMMIT`, and `ROLLBACK`
+
+### 7.2. PostgreSQL Features
 
-### MySQL Features
+PostgreSQL connections offer advanced database functionality:
 
-- **Auto-increment tracking**: Automatically tracks `lastId` for inserted records
-- **Date handling**: Converts JavaScript Date objects to ISO strings
-- **Transaction support**: Uses `BEGIN`, `COMMIT`, and `ROLLBACK`
+ - **Parameter placeholders**: Converts `?` placeholders to `$1`, `$2`, etc.
+ - **Strict parameter matching**: Validates that query placeholders match provided values
+ - **Transaction support**: Uses `BEGIN`, `COMMIT`, and `ROLLBACK`
 
-### PostgreSQL Features
+### 7.3. SQLite Features
 
-- **Parameter placeholders**: Converts `?` placeholders to `$1`, `$2`, etc.
-- **Strict parameter matching**: Validates that query placeholders match provided values
-- **Transaction support**: Uses `BEGIN`, `COMMIT`, and `ROLLBACK`
+SQLite connections provide lightweight, local database capabilities:
 
-### SQLite Features
+ - **Boolean conversion**: Converts boolean values to numbers (0/1)
+ - **Row ID tracking**: Automatically tracks `lastInsertRowid`
+ - **Query optimization**: Uses `stmt.all()` for SELECT queries and `stmt.run()` for others
+ - **Transaction support**: Uses `BEGIN TRANSACTION`, `COMMIT`, and `ROLLBACK`
 
-- **Boolean conversion**: Converts boolean values to numbers (0/1)
-- **Row ID tracking**: Automatically tracks `lastInsertRowid`
-- **Query optimization**: Uses `stmt.all()` for SELECT queries and `stmt.run()` for others
-- **Transaction support**: Uses `BEGIN TRANSACTION`, `COMMIT`, and `ROLLBACK`
+### 7.4. PGLite Features
 
-### PGLite Features
+PGLite connections combine PostgreSQL compatibility with client-side optimization:
 
-- **PostgreSQL compatibility**: Uses PostgreSQL syntax and parameter placeholders
-- **Lightweight**: Optimized for client-side and edge environments
-- **Exec optimization**: Uses `exec()` for queries without parameters
+ - **PostgreSQL compatibility**: Uses PostgreSQL syntax and parameter placeholders
+ - **Lightweight**: Optimized for client-side and edge environments
+ - **Exec optimization**: Uses `exec()` for queries without parameters