@areumtecnologia/mysql-db-handler 1.0.7 → 1.0.9

package/README.md

@@ -1,14 +1,48 @@
 # @areumtecnologia/mysql-db-handler
 
-A powerful MySQL wrapper with connection pooling, singleton support, and advanced query handling for Node.js.
+A powerful, robust, and production-ready MySQL wrapper for Node.js. It features connection pooling, query caching (optional), jQuery DataTables server-side processing integration, safe error handling, and a flexible abstraction layer for CRUD operations.
+
+## Table of Contents
+
+* [Features](#features)
+* [Installation](#installation)
+* [Core Classes](#core-classes)
+  * [DataBase (Standard Connection)](#1-database-standard-connection)
+  * [DataBase (With Query & Schema Caching)](#2-database-with-query--schema-caching)
+  * [DataBaseHandler (CRUD Abstraction)](#3-databasehandler-crud-abstraction)
+* [Basic Usage](#basic-usage)
+  * [1. Initializing Connection](#1-initializing-connection)
+  * [2. Executing Raw SQL](#2-executing-raw-sql)
+  * [3. Using the DataBaseHandler](#3-using-the-databasehandler)
+* [Advanced Querying (`select` method)](#advanced-querying-select-method)
+  * [Basic Selection](#basic-selection)
+  * [Working with the `IN` and `NOT IN` Operators](#working-with-the-in-and-not-in-operators)
+    * [Automatic `IN` Detection](#automatic-in-detection)
+    * [Explicit `IN` / `NOT IN` Operator](#explicit-in--not-in-operator)
+    * [Empty Array Safety (`IN ()` Protection)](#empty-array-safety-in-protection)
+  * [Combining Multiple Conditions (AND / OR)](#combining-multiple-conditions-and--or)
+* [CRUD Operations](#crud-operations)
+  * [Inserting Records (`insert`)](#inserting-records-insert)
+  * [Updating Records (`update`)](#updating-records-update)
+  * [Deleting Records (`delete`)](#deleting-records-delete)
+* [jQuery DataTables Server-Side Support](#jquery-datatables-server-side-support)
+* [Database Singleton Pattern](#database-singleton-pattern)
+* [Error Handling Strategy](#error-handling-strategy)
+* [Contributing](#contributing)
+* [License](#license)
+
+---
 
 ## 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.
+* **Connection Pooling:** Efficiently manages and recycles database connections using `mysql2/promise`.
+* **Flexible Query Builder:** Run complex operations without writing manual SQL strings.
+* **Automatic `IN` Handling:** Smart processing of arrays for SQL `IN` and `NOT IN` operations (including prevention of empty array query crashes).
+* **Optional Caching Wrapper:** Native support for query and schema caching using `node-cache` to boost performance.
+* **Server-Side DataTables Integration:** Effortless integration with jQuery DataTables server-side requests, handling filters, sorting, search (global and column-based), regex, and count totals automatically.
+* **Robust Error Handling:** Intercepts and wraps database errors in predictable objects to prevent application crashes.
+
+---
 
 ## Installation
 
@@ -16,206 +50,366 @@ A powerful MySQL wrapper with connection pooling, singleton support, and advance
 npm install @areumtecnologia/mysql-db-handler
 ```
 
+If you wish to use the caching features, ensure `node-cache` is installed:
+```bash
+npm install node-cache
+```
+
+---
+
+## Core Classes
+
+The package exports the following primary components:
+
+### 1. `DataBase` (Standard Connection)
+Located in `lib/database.js`. Manages standard pooled connections, schema discovery, and query execution.
+
+### 2. `DataBase` (With Query & Schema Caching)
+Located in `lib/database-cache.js`. Overrides the standard `DataBase` implementation to provide in-memory query and table schema caching. It is ideal for read-heavy environments.
+
+### 3. `DataBaseHandler` (CRUD Abstraction)
+Located in `lib/databasehandler.js`. Bind this class to a specific table to perform database actions through utility methods (`select`, `selectBy`, `insert`, `update`, `delete`, `selectToDatatable`).
+
+---
+
 ## Basic Usage
 
-### 1. Initialize Connection
-You can create a new instance of the database class directly.
+### 1. Initializing Connection
 
 ```javascript
 const { DataBase } = require('@areumtecnologia/mysql-db-handler');
 
+// Configuration matches mysql2 connection configuration
 const db = new DataBase({
     host: 'localhost',
     user: 'root',
     password: 'password',
     database: 'my_app_db',
     port: 3306,
-    connectionLimit: 10
+    connectionLimit: 10,
+    waitForConnections: true,
+    queueLimit: 0
 });
 ```
 
 ### 2. Executing Raw SQL
-Use the `query` method to execute standard SQL.
+
+Raw queries are executed through connection pooling. The library handles obtaining and releasing the connection automatically.
 
 ```javascript
 try {
-    const rows = await db.query('SELECT * FROM users WHERE active = ?', [1]);
-    console.log(rows);
+    const rows = await db.query('SELECT * FROM users WHERE active = ? AND role = ?', [1, 'editor']);
+    console.log('Active editors:', rows);
 } catch (error) {
-    console.error(error);
+    console.error('Database query failed:', error);
 }
 ```
 
 ### 3. Using the DataBaseHandler
-The `DataBaseHandler` simplifies interactions with specific tables.
+
+Wrap a table with a handler to abstract SQL construction.
 
 ```javascript
-const { DataBaseHandler } = require('@areumtecnologia/mysql-db-handler');
+const { DataBase, DataBaseHandler } = require('@areumtecnologia/mysql-db-handler');
 
-// Initialize handler for 'customers' table
-const customers = new DataBaseHandler(db, 'customers');
+const db = new DataBase({ /* config */ });
+const usersHandler = new DataBaseHandler(db, 'users');
 ```
 
 ---
 
-## Advanced Usage & Examples
-
-### Inserting Records (`insert`)
+## Advanced Querying (`select` method)
 
-The `insert` method adds a new row to the table.
+The `select(params, clauses)` method builds complex SQL `WHERE` clauses from arrays of condition objects.
 
-**Parameters:**
-*   `params` (Object): An object where keys match the column names and values are the data to insert.
+### Basic Selection
 
-**Example:**
+You can pass condition objects where the key is the column name and the value is the target value.
 
 ```javascript
-const logs = new DataBaseHandler(db, 'app_logs');
+// Simple equals comparison (=)
+const users = await usersHandler.select([
+    { role: 'admin' }
+]);
+// Executes: SELECT * FROM users WHERE `role` = ?
+```
 
-const result = await logs.insert({
-    level: 'info',
-    message: 'User logged in',
-    timestamp: new Date()
-});
-// Executes: INSERT INTO app_logs SET `level` = ?, `message` = ?, `timestamp` = ?
-console.log(`Inserted Row ID: ${result.insertId}`);
+### Working with the `IN` and `NOT IN` Operators
+
+The library provides special support for SQL `IN` operations by mapping JavaScript arrays to queries.
+
+#### Automatic `IN` Detection
+If a condition's value is an array, and no operator is explicitly set, the query builder automatically treats it as an `IN` statement:
+
+```javascript
+const activeUsers = await usersHandler.select([
+    { status: ['active', 'pending'] }
+]);
+// Executes: SELECT * FROM users WHERE `status` IN (?, ?)
+// Bindings: ['active', 'pending']
 ```
 
-### Flexible Selection (`select`)
+#### Explicit `IN` / `NOT IN` Operator
+You can explicitly define the `operator` as `'IN'` or `'NOT IN'`:
 
-The `select` method allows you to build complex queries using an array of parameters and a clauses object.
+```javascript
+// Using NOT IN explicitly
+const nonAdminUsers = await usersHandler.select([
+    { role: ['admin', 'superadmin'], operator: 'NOT IN' }
+]);
+// Executes: SELECT * FROM users WHERE `role` NOT IN (?, ?)
+// Bindings: ['admin', 'superadmin']
+```
 
-**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 `ORDERBY`, `DESC`, `LIMIT`, `OFFSET`, `GROUP BY`, `HAVING`.
+#### Empty Array Safety (`IN ()` Protection)
+In standard SQL, executing a query with an empty array in the `IN` clause (e.g., `WHERE status IN ()`) yields a syntax error and crashes the execution. The library automatically mitigates this:
 
-**Example:**
+* **Empty `IN`**: Evaluates to `1 = 0` (always false). No records match this sub-clause, ensuring safe execution.
+* **Empty `NOT IN`**: Evaluates to `1 = 1` (always true). All records match this sub-clause, returning all values since nothing is excluded.
 
 ```javascript
-const products = new DataBaseHandler(db, 'products');
+// Safe empty array handling
+const results = await usersHandler.select([
+    { id: [], operator: 'IN' }
+]);
+// Executes: SELECT * FROM users WHERE 1 = 0
+
+const allResults = await usersHandler.select([
+    { id: [], operator: 'NOT IN' }
+]);
+// Executes: SELECT * FROM users WHERE 1 = 1
+```
 
-const results = await products.select(
-    // 1. Params: Conditions
+### Combining Multiple Conditions (AND / OR)
+
+Interleave condition objects with string elements representing logical operators:
+
+```javascript
+const filteredProducts = await productsHandler.select(
     [
-        { category: 'electronics' },    // WHERE `category` = 'electronics'
+        { category: 'electronics' },
         'AND',
-        { price: 1000, operator: '>' }  // AND `price` > 1000
+        { price: 500, operator: '>' },
+        'AND',
+        { brand: ['Sony', 'LG'] } // Automatically mapped to IN
     ],
-    // 2. Clauses: SQL Modifiers
     {
         'ORDERBY': 'price',
         'DESC': true,
-        'LIMIT': 10,
-        'OFFSET': 0
+        'LIMIT': 20
     }
 );
+// Executes: 
+// SELECT * FROM products WHERE `category` = ? AND `price` > ? AND `brand` IN (?, ?) ORDER BY price DESC LIMIT 20
 ```
 
-### Updating Records (`update`)
+---
 
-The `update` method separates the values to change from the conditions.
+## CRUD Operations
 
-**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 =.
+### Inserting Records (`insert`)
 
-**Example:**
+Adds a new row to the associated table using key-value properties.
 
 ```javascript
-const users = new DataBaseHandler(db, 'users');
+const result = await usersHandler.insert({
+    name: 'John Doe',
+    email: 'john.doe@example.com',
+    role: 'member',
+    created_at: new Date()
+});
+
+console.log('Inserted ID:', result.insertId);
+```
+
+### Updating Records (`update`)
 
-const result = await users.update({
+Performs selective updates by specifying both a `set` payload and a `where` filter. The `where` filter supports both standard flat objects (where conditions are implicitly joined by `AND` using `=` or `REGEXP`) and complex array configurations (with operators, `AND`, and `OR`), sharing the same advanced querying capabilities as the `select` method.
+
+#### 1. Simple Object Syntax (Implicit AND, = operator)
+
+```javascript
+const result = await usersHandler.update({
     set: {
-        status: 'inactive',
-        last_seen: new Date()
+        status: 'suspended',
+        notes: 'Violated terms of service'
     },
     where: {
-        id: 123,
-        role: 'guest'
+        id: 42,
+        status: 'active'
     }
 });
-// Executes: UPDATE users SET `status` = ?, `last_seen` = ? WHERE `id` = ? AND `role` = ?
+
+console.log('Affected rows:', result.affectedRows);
+// Executes: UPDATE users SET `status` = ?, `notes` = ? WHERE `id` = ? AND `status` = ?
+```
+
+#### 2. Advanced Array Syntax (with operators, AND/OR, and IN)
+
+You can pass an array of condition objects interleaved with `AND` or `OR` string elements to construct complex queries:
+
+```javascript
+// Example updating records based on numeric thresholds and logical operators
+const result = await usersHandler.update({
+    set: {
+        status: 'inactive'
+    },
+    where: [
+        { age: 18, operator: '<' },
+        'AND',
+        { status: 'active' }
+    ]
+});
+// Executes: UPDATE users SET `status` = ? WHERE `age` < ? AND `status` = ?
+
+// Example updating records using automatic IN operator detection
+const result = await usersHandler.update({
+    set: {
+        role: 'archived'
+    },
+    where: [
+        { id: [10, 20, 30] } // Automatically builds: WHERE `id` IN (?, ?, ?)
+    ]
+});
+// Executes: UPDATE users SET `role` = ? WHERE `id` IN (?, ?, ?)
+
+// Example combining complex logic (AND/OR)
+const result = await usersHandler.update({
+    set: {
+        category: 'Premium'
+    },
+    where: [
+        { total_purchases: 1000, operator: '>' },
+        'AND',
+        { status: 'active' },
+        'OR',
+        { is_vip: 1 }
+    ]
+});
+// Executes: UPDATE users SET `category` = ? WHERE `total_purchases` > ? AND `status` = ? OR `is_vip` = ?
 ```
 
 ### Deleting Records (`delete`)
 
-The `delete` method removes rows matching the provided conditions.
+Deletes rows matching the conditions object (joined by implicit `AND` operators).
+
+```javascript
+const result = await usersHandler.delete({
+    status: 'temporary',
+    is_expired: 1
+});
 
-**Parameters:**
-*   `conditions` (Object): Key-value pairs to match rows to delete (uses `AND` implicitly).
+console.log('Deleted rows:', result.affectedRows);
+```
+
+---
 
-**Example:**
+## jQuery DataTables Server-Side Support
+
+The `selectToDatatable` method processes the complex nested payloads sent by jQuery DataTables server-side scripts and returns the required format.
 
 ```javascript
-const sessions = new DataBaseHandler(db, 'user_sessions');
+// Express.js Route Example
+app.post('/api/users/dt', async (req, res) => {
+    // req.body contains the DataTables standard payload:
+    // { draw: 1, start: 0, length: 10, search: { value: 'John', regex: false }, columns: [...] }
+    
+    // You can enforce strict conditions that the client cannot bypass (e.g., tenant containment)
+    const strictConditions = [
+        { tenant_id: req.user.tenantId },
+        'AND',
+        { status: 'deleted', operator: '!=' }
+    ];
 
-const result = await sessions.delete({
-    user_id: 55,
-    is_expired: 1
+    const datatableResult = await usersHandler.selectToDatatable(req.body, strictConditions);
+    
+    // Returns: { draw: 1, recordsTotal: 100, recordsFiltered: 12, data: [...] }
+    res.json(datatableResult);
 });
-// Executes: DELETE FROM user_sessions WHERE `user_id` = ? AND `is_expired` = ?
 ```
 
 ---
 
-## API Documentation
+## Database Singleton Pattern
+
+To prevent initializing redundant pool connections across various modules in a Node.js project, it is highly recommended to configure a single shared instance (Singleton).
+
+Create a `db.js` file:
+```javascript
+// db.js
+const { DataBase } = require('@areumtecnologia/mysql-db-handler');
 
-### Class: `DataBase`
+const dbInstance = new DataBase({
+    host: process.env.DB_HOST || 'localhost',
+    user: process.env.DB_USER || 'root',
+    password: process.env.DB_PASSWORD,
+    database: process.env.DB_NAME,
+    connectionLimit: parseInt(process.env.DB_POOL_LIMIT) || 10
+});
 
-#### `constructor(config)`
-Creates a database instance with a connection pool.
-*   **config**: Object. MySQL2 connection configuration (host, user, password, database, port, connectionLimit, etc).
+module.exports = dbInstance;
+```
 
-#### `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.
+Import it in your business controllers/repositories:
+```javascript
+// usersRepository.js
+const db = require('./db');
+const { DataBaseHandler } = require('@areumtecnologia/mysql-db-handler');
 
-#### `async close()`
-Closes the connection pool completely.
-*   **Returns**: `Promise<void>`.
+const usersHandler = new DataBaseHandler(db, 'users');
+
+module.exports = {
+    getUserById: (id) => usersHandler.selectBy({ id })
+};
+```
 
 ---
 
-### Class: `DataBaseHandler`
+## Error Handling Strategy
 
-#### `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).
+Database exceptions generated during execution are caught internally by the `DataBase` instance. This means that instead of raising unhandled exceptions that could crash your Node.js application, the library wraps the error.
 
-#### `async select(params, clauses)`
-See "Flexible Selection" above.
-*   **Returns**: `Promise<Array>`.
+Specifically, the following methods from **`DataBase`** and **`DataBaseHandler`** return an object with an `error` property when an execution error occurs:
+*   `DataBase.query()`
+*   `DataBaseHandler.select()` / `selectBy()`
+*   `DataBaseHandler.insert()`
+*   `DataBaseHandler.update()`
+*   `DataBaseHandler.delete()`
+*   `DataBaseHandler.selectToDatatable()`
 
-#### `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>`. (contains rows array from query)
+### Example: Checking for errors in queries
 
-#### `async insert(params)`
-Inserts a new row.
-*   **params**: Object. Key-value pairs representing column names and values.
-*   **Returns**: `Promise<OkPacket>` (contains insertId, or error).
+```javascript
+// Example with Select if column doesn't exist (triggers database error)
+const users = await usersHandler.select([{ non_existent_column: 'admin' }]);
+if (users.error) {
+    console.error('Failed to select users:', users.error.message);
+}
 
-#### `async update(params, options)`
-See "Updating Records" above.
-*   **Returns**: `Promise<OkPacket>`. (contains affectedRows or error).
+// Example with Insert
+const insertResult = await usersHandler.insert({ name: 'John Doe' });
+if (insertResult.error) {
+    console.error('Failed to insert user:', insertResult.error.message);
+}
 
-#### `async delete(conditions)`
-See "Deleting Records" above.
-*   **Returns**: `Promise<OkPacket>`. (contains affectedRows or error)
+// Example with Update
+const updateResult = await usersHandler.update({
+    set: { status: 'active' },
+    where: { id: 999 }
+});
+if (updateResult.error) {
+    console.error('Failed to update user:', updateResult.error.message);
+}
 
-#### `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 }`.
+// Example with Delete
+const deleteResult = await usersHandler.delete({ id: 999 });
+if (deleteResult.error) {
+    console.error('Failed to delete user:', deleteResult.error.message);
+}
+```
+
+> [!NOTE]
+> If you execute a `select` using valid columns but search for values that do not exist in the table (e.g. `await usersHandler.select([{ role: 'non_existent_role' }])`), this is **not** considered a database error. The query will execute successfully and return an empty array `[]` (without any `error` property). An error is only returned for actual database execution failures (such as syntax errors, missing columns, database connection drops, etc.).
 
 ---
 
@@ -223,12 +417,14 @@ Helper for server-side Datatables.net processing.
 
 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
+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
+MIT

package/lib/databaseHandler.js

@@ -62,6 +62,67 @@ class DatabaseHandler {
         return { sql: `(${clauses.join(' ')})`, bindings };
     }
 
+    /**
+     * @private
+     * Constrói a cláusula WHERE (sem a palavra-chave WHERE) e seus bindings associados.
+     * @param {Object|Array} where - Condições do where.
+     * @param {boolean} useRegex - Se deve usar REGEXP por padrão (para compatibilidade com update).
+     * @returns {{ sql: string, bindings: Array }}
+     */
+    _buildWhereClause(where, useRegex = false) {
+        if (!where) {
+            return { sql: '', bindings: [] };
+        }
+
+        const conditions = [];
+        const bindings = [];
+
+        if (Array.isArray(where)) {
+            where.forEach((param) => {
+                if (typeof param === 'object' && param !== null && !Array.isArray(param)) {
+                    const entries = Object.entries(param);
+                    if (entries.length === 0) return;
+
+                    const [key, value] = entries[0];
+                    const [operatorKey, operatorValue] = entries[1] || [];
+
+                    let op = operatorValue ?? (useRegex ? 'REGEXP' : '=');
+                    let upperOp = String(op).toUpperCase();
+
+                    if (Array.isArray(value) && upperOp === '=') {
+                        op = 'IN';
+                        upperOp = 'IN';
+                    }
+
+                    if (Array.isArray(value) && (upperOp === 'IN' || upperOp === 'NOT IN')) {
+                        if (value.length === 0) {
+                            conditions.push(upperOp === 'IN' ? '1 = 0' : '1 = 1');
+                        } else {
+                            const placeholders = value.map(() => '?').join(', ');
+                            conditions.push(`\`${key}\` ${op} (${placeholders})`);
+                            bindings.push(...value); 
+                        }
+                    } else {
+                        const condition = `\`${key}\` ${op} ?`;
+                        conditions.push(condition);
+                        bindings.push(value);
+                    }
+                } else if (typeof param === 'string') {
+                    conditions.push(param.toUpperCase());
+                }
+            });
+            return { sql: conditions.join(' '), bindings };
+        } else if (typeof where === 'object' && where !== null) {
+            const operator = useRegex ? 'REGEXP' : '=';
+            const keys = Object.keys(where);
+            const sql = keys.map(key => `\`${key}\` ${operator} ?`).join(' AND ');
+            const bindings = Object.values(where);
+            return { sql, bindings };
+        }
+
+        return { sql: '', bindings: [] };
+    }
+
     async selectToDatatable(rawDtQuery, strictCondition = []) {
         // NOVO: Hidrata o objeto da requisição para o formato aninhado correto.
         const dtQuery = this._hydrateObject(rawDtQuery);
@@ -214,61 +275,8 @@ class DatabaseHandler {
             return new Error('O parâmetro "params" deve ser um array');
         }
 
-        const conditions = [];
-        const values = [];
-
-        if (params && params.length) {
-            // Dica: Troquei map por forEach. O map é para transformar arrays, 
-            // como você só está preenchendo variáveis externas, forEach é semanticamente correto.
-            params.forEach((param) => {
-                if (typeof param === 'object' && !Array.isArray(param)) {
-                    const entries = Object.entries(param);
-                    const [key, value] = entries[0];
-                    const [operatorKey, operatorValue] = entries[1] || [];
-
-                    // --- INÍCIO DAS MODIFICAÇÕES PARA SUPORTE AO IN ---
-
-                    // 1. Define o operador (padrão é '=')
-                    let op = operatorValue ?? '=';
-                    const upperOp = op.toUpperCase();
-
-                    // 2. "Magia": Se o valor for um array e não tiver operador (ou for '='), 
-                    // converte automaticamente para 'IN' para facilitar sua vida.
-                    if (Array.isArray(value) && upperOp === '=') {
-                        op = 'IN';
-                    }
-
-                    // 3. Lógica específica para IN e NOT IN
-                    if (Array.isArray(value) && (upperOp === 'IN' || upperOp === 'NOT IN')) {
-                        if (value.length === 0) {
-                            // O SQL não permite "IN ()". 
-                            // Um IN vazio nunca encontra nada (falso), um NOT IN vazio encontra tudo (verdadeiro).
-                            conditions.push(upperOp === 'IN' ? '1 = 0' : '1 = 1');
-                        } else {
-                            // Cria a string de placeholders: "?, ?, ?" baseada no tamanho do array
-                            const placeholders = value.map(() => '?').join(', ');
-                            conditions.push(`\`${key}\` ${op} (${placeholders})`);
-                            
-                            // Espalha os valores do array individualmente no array de values
-                            values.push(...value); 
-                        }
-                    } else {
-                        // 4. Lógica original para valores únicos (string, number, boolean, etc)
-                        // ou outros operadores (LIKE, REGEXP, >, <, etc)
-                        const condition = `\`${key}\` ${op} ?`;
-                        conditions.push(condition);
-                        values.push(value);
-                    }
-
-                    // --- FIM DAS MODIFICAÇÕES ---
-
-                } else if (typeof param === 'string') {
-                    conditions.push(param.toUpperCase());
-                }
-            });
-        }
-
-        const whereClause = conditions.length > 0 ? ` WHERE ${conditions.join(' ')}` : '';
+        const { sql: whereSql, bindings: values } = this._buildWhereClause(params);
+        const whereClause = whereSql ? ` WHERE ${whereSql}` : '';
 
         // Cláusulas adicionais
         const groupByClause = clauses['GROUPBY'] ? ` GROUP BY ${clauses['GROUPBY']}` : '';
@@ -292,14 +300,16 @@ class DatabaseHandler {
 
     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(', ');
+        let setValues = Object.values(params.set);
+
         // Inicializa a string SQL para a cláusula WHERE
-        let whereClause = Object.keys(params.where).map(key => `\`${key}\` ${operator} ?`).join(' AND ');
+        const { sql: whereClause, bindings: whereValues } = this._buildWhereClause(params.where, !!options.useRegex);
+
         // 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)];
+        const values = [...setValues, ...whereValues];
         // Executa a consulta
         const result = await this.executeQuery(sql, values);
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@areumtecnologia/mysql-db-handler",
-  "version": "1.0.7",
+  "version": "1.0.9",
   "description": "A powerful MySQL wrapper with connection pooling, singleton support, and advanced query handling for Node.js.",
   "main": "index.js",
   "scripts": {