Docs added.

Author: JasminDreasond

docs/PuddySqlEngine.md

@@ -0,0 +1,117 @@
+# 📚 `PuddySqlEngine` Class Documentation
+
+A lightweight class for managing SQL engine state and basic query methods in a pluggable and validated manner.
+
+---
+
+## 🔐 Private Properties
+
+### `#sqlEngine: string`
+
+Holds the SQL engine identifier used internally by this instance. It's set only once and used for engine-specific behaviors.
+
+---
+
+## 🧪 Methods
+
+### 🔎 `isSqlEngineEmpty(): boolean`
+
+Checks if the SQL engine is undefined, null, or an empty string.
+
+* ✅ **Returns**: `true` if not set or empty, otherwise `false`.
+
+---
+
+### 📥 `setSqlEngine(engine: string): void`
+
+Sets the SQL engine to be used by this instance. Can only be set **once**, and only with a valid non-empty string.
+
+* 📌 **Parameters**:
+
+  * `engine` *(string)*: Name of the SQL engine, e.g. `'sqlite3'`, `'postgre'`.
+* ⚠️ **Throws**:
+
+  * If already set.
+  * If provided value is not a valid non-empty string.
+
+---
+
+### 📤 `getSqlEngine(): string`
+
+Returns the currently set SQL engine.
+
+* ✅ **Returns**: SQL engine name.
+* ⚠️ **Throws**: If engine is not set.
+
+---
+
+### ❌ `isConnectionError(err: Error): boolean`
+
+Detects if a given error matches known SQL engine-specific connection issues.
+
+* 📌 **Parameters**:
+
+  * `err` *(Error)*: Error object to check.
+* 🔍 **Behavior**:
+
+  * For **PostgreSQL**, checks for known error codes like:
+
+    * `ECONNREFUSED`, `ETIMEDOUT`, `28P01`, `08006`, etc.
+  * For **SQLite3**, checks if the error message includes `SQLITE_CANTOPEN`.
+* ✅ **Returns**: `true` if a known connection error is detected.
+
+---
+
+## ⚙️ Query Methods
+
+These methods are placeholders but follow the async query signature.
+
+### 📄 `all(query: string, params?: any[], debugName?: string): Promise<any[]>`
+
+Executes an SQL `SELECT` query expected to return **multiple rows**.
+
+* 📌 **Parameters**:
+
+  * `query`: SQL string.
+  * `params`: Optional array of parameters.
+  * `debugName`: Optional debug label.
+* ✅ **Returns**: Array of row results.
+* ⚠️ **Throws**: On query failure.
+
+---
+
+### 📄 `get(query: string, params?: any[], debugName?: string): Promise<object|null>`
+
+Executes an SQL `SELECT` query expected to return **a single row**.
+
+* 📌 **Parameters**:
+
+  * `query`: SQL string.
+  * `params`: Optional array of parameters.
+  * `debugName`: Optional debug label.
+* ✅ **Returns**: Single result object or `null`.
+* ⚠️ **Throws**: On query failure.
+
+---
+
+### ✏️ `run(query: string, params: any[], debugName?: string): Promise<object|null>`
+
+Executes an SQL `INSERT`, `UPDATE`, or `DELETE` statement.
+
+* 📌 **Parameters**:
+
+  * `query`: SQL string.
+  * `params`: Parameters to bind.
+  * `debugName`: Optional debug label.
+* ✅ **Returns**: Result object or `null`.
+* ⚠️ **Throws**: On execution failure.
+
+---
+
+## 🚀 Export
+
+```js
+export default PuddySqlEngine;
+```
+
+This class is ready to be used as a foundational SQL abstraction for SQLite3, PostgreSQL, and others with minimal setup.

docs/PuddySqlInstance.md

@@ -0,0 +1,192 @@
+# 🗃️ `PuddySqlInstance` Class
+
+Extends [`PuddySqlEngine`](./PuddySqlEngine.mjs) to provide high-level SQL operations with table management, debug logging, and support for both **SQLite3** and **PostgreSQL**.
+
+---
+
+## 🧠 Constructor
+
+```js
+new PuddySqlInstance()
+```
+
+Initializes the instance and sets up internal properties.
+
+---
+
+## 🔧 Internal Properties
+
+* `#db`: The internal database instance (`sqlite` or `pg.Pool`).
+* `#tables`: A record of initialized tables using `PuddySqlQuery`.
+* `#debug`: Whether debug logging is enabled.
+* `#debugCount`: Number of debug calls (optional use).
+* `#consoleColors`: Whether debug console output uses colors.
+
+---
+
+## 🎨 Debug Configuration
+
+### 🎛️ `setConsoleColors(state: boolean): void`
+
+Enable or disable ANSI colors in debug output.
+
+### ✅ `getConsoleColors(): boolean`
+
+Returns whether color output is enabled.
+
+---
+
+## 🖌️ SQL Formatting (for Debug Output)
+
+### 📜 `debugSql(value: string): string`
+
+Formats a SQL string with indentation and ANSI color codes for better console readability.
+
+* Adds line breaks and highlights clauses like `SELECT`, `WHERE`, `JOIN`, `LIMIT`, etc.
+* Wraps in decorative box with ANSI colors.
+
+### 🧾 `debugConsoleText(id: string | number, debugName?: string, status?: string): string`
+
+Formats a debug console message with styled tags like:
+
+```txt
+[SQL][123] [DEBUG] [MyQuery] [OK]
+```
+
+---
+
+## 🐞 Debug Mode
+
+### 🔛 `setIsDebug(isDebug: boolean): void`
+
+Turns debug logging on or off.
+
+### 🔍 `isDebug(): boolean`
+
+Returns `true` if debug mode is enabled.
+
+---
+
+## 📦 Table Management
+
+### 🆕 `initTable(settings?: TableSettings, tableData?: SqlTableConfig): Promise<PuddySqlQuery>`
+
+Initializes a new table if it hasn't already been created.
+
+* Throws if the table already exists.
+* Internally creates a `PuddySqlQuery` instance and assigns settings/data.
+
+### 🔍 `getTable(tableName: string): PuddySqlQuery`
+
+Returns the existing table instance for a given name.
+
+* Throws if table does not exist.
+
+### ❓ `hasTable(tableName: string): boolean`
+
+Checks if a table has been initialized.
+
+### 🗑️ `removeTable(tableName: string): void`
+
+Removes a table from the internal map without affecting the actual DB.
+
+* Throws if the table does not exist.
+
+### 💣 `dropTable(tableName: string): Promise<void>`
+
+Drops the table from the database schema, then removes it internally.
+
+* Uses the `dropTable()` method of the `PuddySqlQuery` class.
+
+---
+
+## 🔍 Database Access
+
+### 💾 `getDb(): SqliteDb | PgPool`
+
+Returns the internal database connection instance.
+
+* Useful for advanced custom queries.
+* Throws if the DB has not been initialized.
+
+---
+
+## 🔌 Connection & Engine Initialization
+
+### ✅ `isDbOpen(): Promise<boolean>`
+
+Checks if the database connection is open by running a test query (`SELECT 1`).
+
+---
+
+### 🐿️ `initSqlite3(filePath?: string = ':memory:'): Promise<void>`
+
+Initializes a SQLite3 database connection (requires SQLite ≥ 3.35.0).
+
+* Automatically sets the SQL engine to `"sqlite3"`.
+* Adds graceful shutdown logic (e.g., on `SIGINT`).
+
+---
+
+### 🧩 `setSqlite3(db: SqliteDb): void`
+
+Sets SQLite3-specific methods (`all`, `get`, `run`) using the provided DB instance.
+
+Each method includes:
+
+* SQL validation and parameter checking;
+* Colorized debug output (if enabled);
+* Safe error catching and optional `connection-error` event emission.
+
+---
+
+### 🐘 `initPostgre(config: Pg.PoolConfig): Promise<void>`
+
+Initializes a PostgreSQL client using the provided configuration.
+
+* Automatically connects the pool.
+* Sets the SQL engine to `"postgre"`.
+
+---
+
+### 🔄 `setPostgre(db: Pg.Pool): void`
+
+Sets PostgreSQL-specific methods (`all`, `get`, `run`) using a PostgreSQL Pool.
+
+* Includes debug output;
+* Connection error handling via event emitter;
+* Uses `pg`'s async `query()` method for operations.
+
+---
+
+## 🔧 SQL Operation Overrides
+
+All three methods below are overridden dynamically depending on the SQL engine used:
+
+### 📚 `all(query: string, params?: any[], debugName?: string): Promise<Object[] | null>`
+
+Executes a query expected to return multiple rows.
+
+---
+
+### 🧍 `get(query: string, params?: any[], debugName?: string): Promise<Object | null>`
+
+Executes a query expected to return a single row.
+
+---
+
+### ✍️ `run(query: string, params: any[], debugName?: string): Promise<Object | null>`
+
+Executes a query that modifies data (e.g., `INSERT`, `UPDATE`, `DELETE`).
+
+---
+
+## 🧹 Cleanup
+
+### ❌ `destroy(): Promise<void>`
+
+Gracefully shuts down the current instance:
+
+* Removes all event listeners;
+* Properly closes the DB connection depending on the SQL engine (`sqlite3` or `postgre`);
+* Errors on disconnection are caught and logged.