puddysql
Version:
🍮 Powerful SQL toolkit for Node.js, built with flexibility and structure in mind. Easily manage SQLite3/PostgreSQL, advanced queries, smart tag systems, and full JSON-friendly filters.
193 lines (106 loc) • 4.73 kB
Markdown
# 🗃️ `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.