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.
118 lines (69 loc) • 2.95 kB
Markdown
# 📚 `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.