@areumtecnologia/mysql-db-handler 1.0.0

package/README.md

@@ -0,0 +1,218 @@
+# mysql-db-handler
+
+A powerful MySQL wrapper with connection pooling, singleton support, and advanced query handling for Node.js.
+
+## Features
+
+*   **Connection Pooling:** Efficiently manages database connections.
+*   **Promise-based:** Fully supports `async/await` for clean code.
+*   **Table Handler:** An abstraction layer to perform CRUD operations easily.
+*   **Datatables Integration:** Built-in helper to parse and query data specifically for jQuery Datatables server-side processing.
+*   **Singleton Support:** Includes a singleton pattern setup for easy global access.
+
+## Installation
+
+```bash
+npm install mysql-db-handler
+```
+
+## Basic Usage
+
+### 1. Initialize Connection
+You can create a new instance of the database class directly.
+
+```javascript
+const { DataBase } = require('mysql-db-handler');
+
+const db = new DataBase({
+    host: 'localhost',
+    user: 'root',
+    password: 'password',
+    database: 'my_app_db',
+    port: 3306,
+    connectionLimit: 10
+});
+```
+
+### 2. Executing Raw SQL
+Use the `query` method to execute standard SQL.
+
+```javascript
+try {
+    const rows = await db.query('SELECT * FROM users WHERE active = ?', [1]);
+    console.log(rows);
+} catch (error) {
+    console.error(error);
+}
+```
+
+### 3. Using the DataBaseHandler
+The `DataBaseHandler` simplifies interactions with specific tables.
+
+```javascript
+const { DataBaseHandler } = require('mysql-db-handler');
+
+// Initialize handler for 'customers' table
+const customers = new DataBaseHandler(db, 'customers');
+
+// Select all
+const allCustomers = await customers.select();
+
+// Select with conditions
+const activeCustomers = await customers.selectBy({ status: 1 });
+```
+
+---
+
+## Advanced Usage & Examples
+
+### Flexible Selection (`select`)
+
+The `select` method allows you to build complex queries using an array of parameters and a clauses object.
+
+**Parameters:**
+*   `params` (Array): An array where each element is either a condition object or a logical string ('AND', 'OR').
+    *   Simple condition: `{ column: value }` (defaults to `=`)
+    *   Condition with operator: `{ column: value, operator: '>' }`
+*   `clauses` (Object): Optional keys like `ORDER BY`, `LIMIT`, `OFFSET`, `GROUP BY`, `HAVING`.
+
+**Example:**
+
+```javascript
+const products = new DataBaseHandler(db, 'products');
+
+const results = await products.select(
+    // 1. Params: Conditions
+    [
+        { category: 'electronics' },    // WHERE `category` = 'electronics'
+        'AND',
+        { price: 1000, operator: '>' }  // AND `price` > 1000
+    ],
+    // 2. Clauses: SQL Modifiers
+    {
+        'ORDER BY': 'price DESC',
+        'LIMIT': 10,
+        'OFFSET': 0
+    }
+);
+```
+
+### Updating Records (`update`)
+
+The `update` method separates the values to change from the conditions.
+
+**Parameters:**
+*   `params` (Object): Contains:
+    *   `set`: Key-value pairs of columns to update.
+    *   `where`: Key-value pairs for the WHERE clause (uses `AND` implicitly between keys).
+*   `options` (Object): Optional settings, e.g., `{ useRegex: true }` to use REGEXP instead of =.
+
+**Example:**
+
+```javascript
+const users = new DataBaseHandler(db, 'users');
+
+const result = await users.update({
+    set: {
+        status: 'inactive',
+        last_seen: new Date()
+    },
+    where: {
+        id: 123,
+        role: 'guest'
+    }
+});
+// Executes: UPDATE users SET `status` = ?, `last_seen` = ? WHERE `id` = ? AND `role` = ?
+```
+
+### Deleting Records (`delete`)
+
+The `delete` method removes rows matching the provided conditions.
+
+**Parameters:**
+*   `conditions` (Object): Key-value pairs to match rows to delete (uses `AND` implicitly).
+
+**Example:**
+
+```javascript
+const sessions = new DataBaseHandler(db, 'user_sessions');
+
+const result = await sessions.delete({
+    user_id: 55,
+    is_expired: 1
+});
+// Executes: DELETE FROM user_sessions WHERE `user_id` = ? AND `is_expired` = ?
+```
+
+---
+
+## API Documentation
+
+### Class: `DataBase`
+
+#### `constructor(config)`
+Creates a database instance with a connection pool.
+*   **config**: Object. MySQL2 connection configuration (host, user, password, database, port, connectionLimit, etc).
+
+#### `async query(sql, params)`
+Executes a SQL query using a pooled connection.
+*   **sql**: String. The SQL query to execute.
+*   **params**: Array. Parameters for the prepared statement.
+*   **Returns**: `Promise<Array|Object>`. Returns rows on success, or an error object if failed.
+
+#### `async close()`
+Closes the connection pool completely.
+*   **Returns**: `Promise<void>`.
+
+---
+
+### Class: `DataBaseHandler`
+
+#### `constructor(database, table, expression)`
+*   **database**: Instance of `DataBase`.
+*   **table**: String. The name of the table.
+*   **expression**: String (Optional). Additional SQL expression (e.g., extra columns or joins).
+
+#### `async select(params, clauses)`
+See "Flexible Selection" above.
+*   **Returns**: `Promise<Array>`.
+
+#### `async selectBy(params)`
+Quickly select rows matching a specific object condition.
+*   **params**: Object. Key-value pairs for WHERE clause (e.g., `{ id: 5 }`).
+*   **Returns**: `Promise<Array>`.
+
+#### `async insert(params)`
+Inserts a new row.
+*   **params**: Object. Key-value pairs representing column names and values.
+*   **Returns**: `Promise<OkPacket>` (contains insertId, affectedRows, etc).
+
+#### `async update(params, options)`
+See "Updating Records" above.
+*   **Returns**: `Promise<OkPacket>`.
+
+#### `async delete(conditions)`
+See "Deleting Records" above.
+*   **Returns**: `Promise<OkPacket>`.
+
+#### `async selectToDatatable(rawDtQuery, strictCondition)`
+Helper for server-side Datatables.net processing.
+*   **rawDtQuery**: Object. The request object sent by Datatables.
+*   **strictCondition**: Array. Additional strict WHERE clauses not controlled by the frontend.
+*   **Returns**: Object. Format expected by Datatables `{ draw, recordsTotal, recordsFiltered, data }`.
+
+---
+
+## Contributing
+
+Contributions are welcome! Please open an issue or submit a pull request.
+
+1.  Fork the repository
+2.  Create your feature branch (`git checkout -b feature/amazing-feature`)
+3.  Commit your changes (`git commit -m 'Add some amazing feature'`)
+4.  Push to the branch (`git push origin feature/amazing-feature`)
+5.  Open a Pull Request
+
+## License
+
+MIT

package/index.js

@@ -0,0 +1,10 @@
+// Áreum Tecnologia - Renan Moreira - renan.moreira@areum.com.br
+const DataBase = require('./lib/database');
+const DataBaseHandler = require('./lib/databaseHandler');
+// We do not export the singleton by default in a library usually, 
+// but we export the classes so the user can instantiate them.
+
+module.exports = {
+    DataBase,
+    DataBaseHandler
+};

package/lib/database-cache.js

@@ -0,0 +1,77 @@
+// Áreum Tecnologia - Renan Moreira - renan.moreira@areum.com.br
+const mysql = require('mysql2/promise');
+const NodeCache = require('node-cache');
+
+class DataBase {
+    constructor(config = {}) {
+        this.config = config;
+        this.pool = mysql.createPool(this.config); // The pool is created once when the instance is created.
+        this.cache = new NodeCache({ stdTTL: 100, checkperiod: 120 }); // Cache instance with a default TTL and check period.
+    }
+
+    // The createPool method is preserved for compatibility but is not necessary as the pool is already created in the constructor.
+    createPool() {
+        if (!this.pool) {
+            this.pool = mysql.createPool(this.config);
+        }
+        return this.pool;
+    }
+
+    async getConnection() {
+        if (!this.pool) {
+            throw new Error('Pool de conexões não criado.');
+        }
+        return this.pool.getConnection();
+    }
+
+    async query(sql, params) {
+        const key = `query_${sql}_${JSON.stringify(params)}`;
+        const cachedResult = this.cache.get(key);
+
+        if (cachedResult) {
+            return cachedResult;
+        }
+
+        const connection = await this.getConnection();
+        try {
+            const [rows] = await connection.query(sql, params);
+            this.cache.set(key, rows); // Save the result in the cache.
+            return rows;
+        } catch (error) {
+            return { error };
+        } finally {
+            connection.release();
+        }
+    }
+
+    // This method now uses placeholders to prevent SQL injection.
+    async getTableSchema(table) {
+        const key = `schema_${table}`;
+        const cachedResult = this.cache.get(key);
+
+        if (cachedResult) {
+            return cachedResult;
+        }
+
+        const sql = `SELECT column_name FROM information_schema.columns WHERE table_schema = ? AND table_name = ?`;
+        const params = [this.config.database, table];
+
+        const connection = await this.getConnection();
+        try {
+            const [rows] = await connection.execute(sql, params); // Use execute with placeholders
+            this.cache.set(key, rows); // Save the result in the cache.
+            return rows;
+        } catch (error) {
+            return { error };
+        } finally {
+            connection.release();
+        }
+    }
+
+    // Optional: A method to clear the cache if needed.
+    clearCache() {
+        this.cache.flushAll();
+    }
+}
+
+module.exports = DataBase;

package/lib/database-singleton.js

@@ -0,0 +1,19 @@
+// Áreum Tecnologia - Renan Moreira - renan.moreira@areum.com.br
+// src/database/database-singleton.js
+// Exemplo Singleton para a conexão com o banco de dados
+const { DB_HOST, DB_USER, DB_PASS } = require('../constants');
+const DataBase = require("./database");
+
+const dbi = new DataBase({
+    host: DB_HOST,
+    user: DB_USER,
+    password: DB_PASS,
+    database: '',
+    charset: "utf8mb4",
+    timezone: "-03:00",
+    connectionLimit: 1, // Ajustado para um limite de conexão mais comum
+    waitForConnections: true,
+    queueLimit: 0
+});
+// console.log("DATABASE SINGLETON CREATED", dbi.id);
+module.exports = dbi;

package/lib/database.js

@@ -0,0 +1,81 @@
+const mysql = require('mysql2/promise');
+
+class DataBase {
+    /**
+     * Creates a database instance with a connection pool.
+     * @param {Object} [config] - Configuration object for the database connection.
+     */
+    constructor(config) {
+        this.id = Date.now();
+        this.config = config;
+        this.pool = mysql.createPool(config);
+    }
+
+    /**
+     * Retrieves the connection pool.
+     * @returns {Promise<mysql.Pool>} The connection pool.
+     */
+    getPool() {
+        return this.pool;
+    }
+
+    /**
+     * Gets a connection from the pool.
+     * @returns {Promise<mysql.PoolConnection>} A database connection.
+     */
+    async getConnection() {
+        return this.pool.getConnection();
+    }
+
+    /**
+     * Executes a SQL query using a pooled connection.
+     * @param {string} sql - The SQL query to execute.
+     * @param {Array} [params] - The parameters for the SQL query.
+     * @returns {Promise<Array>} The result set from the query.
+     * @throws {Error} Throws an error if the query fails.
+     */
+    async query(sql, params) {
+        let connection; // Mova a declaração da conexão para fora do bloco try
+        try {
+            // Passo 1: Obter uma conexão do pool
+            connection = await this.getConnection();
+
+            // Passo 2: Executar a query
+            const [rows] = await connection.query(sql, params);
+            return rows;
+        } catch (error) {
+            // Passo 3: Se a query falhar, logar e retornar o erro no formato desejado
+            console.error('Erro na execução da query:', error);
+            return { error }; // Mantém o retorno do erro como um objeto
+        } finally {
+            // Passo 4: Este bloco SEMPRE será executado, independentemente de sucesso ou falha no 'try'
+            if (connection) {
+                connection.release(); // Garante que a conexão seja devolvida ao pool
+            }
+        }
+    }
+
+    /**
+     * Retrieves the schema of a given table using prepared statements to prevent SQL injection.
+     * @param {string} table - The name of the table.
+     * @returns {Promise<Array>} The schema of the table.
+     * @throws {Error} Throws an error if the query fails.
+     */
+    async getTableSchema(table) {
+        const sql = `SELECT column_name 
+                     FROM information_schema.columns 
+                     WHERE table_schema = ? AND table_name = ?`;
+        return await this.query(sql, [this.config.database, table]);
+    }
+
+    /**
+     * Closes the connection pool.
+     */
+    async close() {
+        if (this.pool) {
+            await this.pool.end();
+            console.log(new Date().toLocaleString('pt-br'), 'POOL', 'Database connection pool closed.');
+        }
+    }
+}
+module.exports = DataBase;

package/lib/databaseHandler.js

@@ -0,0 +1,249 @@
+class DatabaseHandler {
+    constructor(database, table, expression = '') {
+        this.db = database;
+        this.table = table;
+        this.debug = false;
+        this.expression = expression;
+        this.debug = false;
+        this.onError;
+    }
+
+    async executeQuery(sql, params) {
+        // const connection = await this.db;
+        // const rows = await connection.query(sql, params);
+        const rows = await this.db.query(sql, params);
+        return rows;
+    }
+
+    async getSchema() {
+        return await this.db.getTableSchema(this.table)
+    }
+
+    /**
+     * @private
+     * Converte um objeto "achatado" (form-urlencoded) em um objeto aninhado (JSON).
+     * Ex: { 'columns[0][data]': 'id' } => { columns: [{ data: 'id' }] }
+     */
+    _hydrateObject(flatObject) {
+        const result = {};
+        for (const key in flatObject) {
+            const keys = key.match(/[^[\]']+/g); // Extrai chaves como ['columns', '0', 'data']
+            if (!keys) continue;
+
+            let current = result;
+            while (keys.length > 1) {
+                const k = keys.shift();
+                current[k] = current[k] || (isNaN(keys[0]) ? {} : []);
+                current = current[k];
+            }
+            current[keys[0]] = flatObject[key];
+        }
+        return result;
+    }
+
+    _parseStrictCondition(strictCondition) {
+        if (!strictCondition || !Array.isArray(strictCondition) || strictCondition.length === 0) {
+            return { sql: '', bindings: [] };
+        }
+        const clauses = [];
+        const bindings = [];
+        for (const item of strictCondition) {
+            if (typeof item === 'string') {
+                clauses.push(item.toUpperCase());
+            } else if (typeof item === 'object' && item !== null) {
+                const key = Object.keys(item).find(k => k !== 'operator');
+                if (!key) continue;
+                const value = item[key];
+                const operator = item.operator || '=';
+                clauses.push(`\`${key}\` ${operator} ?`);
+                bindings.push(value);
+            }
+        }
+        return { sql: `(${clauses.join(' ')})`, bindings };
+    }
+
+    async selectToDatatable(rawDtQuery, strictCondition = []) {
+        // NOVO: Hidrata o objeto da requisição para o formato aninhado correto.
+        const dtQuery = this._hydrateObject(rawDtQuery);
+        const { draw, start, length, search, order, columns } = dtQuery;
+
+        try {
+            const baseWhere = this._parseStrictCondition(strictCondition);
+            const finalBindings = [...baseWhere.bindings];
+            const finalWhereClauses = baseWhere.sql ? [baseWhere.sql] : [];
+
+            const dtSearchClauses = [];
+            if (columns) {
+                if (search && search.value !== '') {
+                    const globalSearch = columns
+                        .filter(c => c.data && c.searchable === 'true')
+                        .map(c => `\`${c.data}\` LIKE ?`);
+
+                    if (globalSearch.length > 0) {
+                        const regexSearch = search.regex === 'true' ? `${search.value}` : `%${search.value}%`;
+                        const operator = search.regex === 'true' ? 'REGEXP' : 'LIKE';
+                        const clauses = globalSearch.map(c => c.replace('LIKE ?', `${operator} ?`));
+
+                        dtSearchClauses.push(`(${clauses.join(' OR ')})`);
+                        for (let i = 0; i < globalSearch.length; i++) {
+                            finalBindings.push(regexSearch);
+                        }
+                    }
+                }
+                for (const col of columns) {
+                    if (col.data && col.searchable === 'true' && col.search && col.search.value !== '') {
+                        const regexSearch = col.search.regex === 'true' ? `${col.search.value}` : `%${col.search.value}%`;
+                        const operator = col.search.regex === 'true' ? 'REGEXP' : 'LIKE';
+                        dtSearchClauses.push(`\`${col.data}\` ${operator} ?`);
+                        finalBindings.push(regexSearch);
+                    }
+                }
+            }
+
+            if (dtSearchClauses.length > 0) {
+                finalWhereClauses.push(dtSearchClauses.join(' AND '));
+            }
+
+            const whereSql = finalWhereClauses.length > 0 ? `WHERE ${finalWhereClauses.join(' AND ')}` : '';
+
+            let orderSql = '';
+            if (order && order.length > 0 && columns) {
+                const orderColumnIndex = order[0].column;
+                if (columns[orderColumnIndex] && columns[orderColumnIndex].orderable === 'true' && columns[orderColumnIndex].data) {
+                    const orderColumnName = columns[orderColumnIndex].data;
+                    const orderDir = order[0].dir.toUpperCase() === 'ASC' ? 'ASC' : 'DESC';
+                    orderSql = `ORDER BY \`${orderColumnName}\` ${orderDir}`;
+                }
+            }
+
+            const limitSql = (length && length != '-1') ? `LIMIT ${parseInt(start, 10)}, ${parseInt(length, 10)}` : '';
+
+            // --- Queries ---
+            const baseWhereSql = baseWhere.sql ? `WHERE ${baseWhere.sql}` : '';
+            const totalCountSql = `SELECT COUNT(*) as total FROM ${this.table} ${baseWhereSql}`;
+            const [totalResult] = await this.executeQuery(totalCountSql, baseWhere.bindings);
+            const recordsTotal = totalResult.total;
+
+            const filteredCountSql = `SELECT COUNT(*) as total FROM ${this.table} ${whereSql}`;
+            const [filteredResult] = await this.executeQuery(filteredCountSql, finalBindings);
+            const recordsFiltered = filteredResult.total;
+
+            // CORREÇÃO: Construção segura da cláusula SELECT para evitar vírgulas duplas.
+            const selectFields = ['*'];
+            if (this.expression && this.expression.trim() !== '') {
+                // Remove vírgula do início da expressão, se houver, para evitar duplicação
+                selectFields.push(this.expression.trim().replace(/^,/, '').trim());
+            }
+            const dataSql = `SELECT ${selectFields.join(', ')} FROM ${this.table} ${whereSql} ${orderSql} ${limitSql}`;
+            const data = await this.executeQuery(dataSql, finalBindings);
+
+            return {
+                draw: parseInt(draw || 0),
+                recordsTotal: parseInt(recordsTotal),
+                recordsFiltered: parseInt(recordsFiltered),
+                data: data,
+            };
+
+        } catch (e) {
+            console.error("Erro em selectToDatatable:", e);
+            if (this.onError) this.onError(e);
+            return {
+                draw: parseInt(dtQuery.draw || 0),
+                recordsTotal: 0,
+                recordsFiltered: 0,
+                data: [],
+                error: e.message
+            };
+        }
+    }
+
+    async selectBy(params) {
+        if (params) {
+            const sql = `SELECT *${this.expression ? this.expression : ''} FROM ${this.table} WHERE ?`;
+            const rows = await this.executeQuery(sql, params);
+            return rows;//retorna um array, mesmo que vazio
+        }
+        else {
+            const sql = `SELECT *${this.expression ? this.expression : ''} FROM ${this.table}`;
+            return this.executeQuery(sql);
+        }
+    }
+
+    async select(params, clauses = {}) {
+        if (params != null && !Array.isArray(params)) {
+            return new Error('O parâmetro "params" deve ser um array');
+        }
+
+        const conditions = [];
+        const values = [];
+
+        if (params && params.length) {
+            params.map((param) => {
+                if (typeof param === 'object' && !Array.isArray(param)) {
+                    const entries = Object.entries(param);
+                    const [key, value] = entries[0];
+                    const [operator, opValue] = entries[1] || [];
+
+                    const condition = `\`${key}\` ${opValue ?? '='} ?`;
+                    conditions.push(condition);
+                    values.push(value);
+                } else if (typeof param === 'string') {
+                    conditions.push(param.toUpperCase());
+                }
+            });
+        }
+
+        const whereClause = conditions.length > 0 ? ` WHERE ${conditions.join(' ')}` : '';
+
+        // Cláusulas adicionais
+        const groupByClause = clauses['GROUPBY'] ? ` GROUP BY ${clauses['GROUP BY']}` : '';
+        const havingClause = clauses['HAVING'] ? ` HAVING ${clauses['HAVING']}` : '';
+        const orderClause = clauses['ORDERBY'] ? ` ORDER BY ${clauses['ORDER BY']}` : '';
+        const limitClause = clauses['LIMIT'] ? ` LIMIT ${clauses['LIMIT']}` : '';
+        const offsetClause = clauses['OFFSET'] ? ` OFFSET ${clauses['OFFSET']}` : '';
+
+        const sql = `SELECT *${this.expression ?? ''} FROM ${this.table}${whereClause}${groupByClause}${havingClause}${orderClause}${limitClause}${offsetClause}`;
+
+        const rows = await this.executeQuery(sql, values);
+        return rows;
+    }
+
+    async insert(params) {
+        const sql = `INSERT INTO ${this.table} SET ?`;
+        const result = await this.executeQuery(sql, params);
+        return result;
+    }
+
+    async update(params, options = {}) {
+        // Inicializa a string SQL para a cláusula SET
+        const operator = options.useRegex ? 'REGEXP' : '=';
+        let setClause = Object.keys(params.set).map(key => `\`${key}\` = ?`).join(', ');
+        // Inicializa a string SQL para a cláusula WHERE
+        let whereClause = Object.keys(params.where).map(key => `\`${key}\` ${operator} ?`).join(' AND ');
+        // Constrói a consulta SQL completa
+        const sql = `UPDATE ${this.table} SET ${setClause} WHERE ${whereClause}`;
+        // Combina os valores SET e WHERE em um único array
+        const values = [...Object.values(params.set), ...Object.values(params.where)];
+        // Executa a consulta
+        const result = await this.executeQuery(sql, values);
+
+        return result;
+    }
+
+    async delete(conditions) {
+        const conditionKeys = Object.keys(conditions);
+        if (conditionKeys.length === 0) {
+            // Se o objeto conditions estiver vazio, não faz nada
+            return;
+        }
+
+        const whereConditions = conditionKeys.map((key) => `${key} = ?`).join(' AND ');
+        const sql = `DELETE FROM ${this.table} WHERE ${whereConditions}`;
+        const params = conditionKeys.map((key) => conditions[key]);
+        const result = await this.executeQuery(sql, params);
+        return result;
+    }
+
+}
+
+module.exports = DatabaseHandler;

package/package.json

@@ -0,0 +1,14 @@
+{
+  "name": "@areumtecnologia/mysql-db-handler",
+  "version": "1.0.0",
+  "description": "A powerful MySQL wrapper with connection pooling, singleton support, and advanced query handling for Node.js.",
+  "main": "index.js",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "author": "Renan Moreira / Áreum Tecnologia",
+  "license": "MIT",
+  "dependencies": {
+    "mysql2": "^3.0.0"
+  }
+}