minervajs-helmet 1.0.12 → 1.0.15

package/README.md

@@ -1,64 +1,231 @@
-# MinervaJS.Helmet
-Modulo para la gestion de las conección a la base de datos, permite conectarse a varios tipos utilizando sobrecarga de metodos, tolera MySQL y Oracle Client  
+# MinervaJS-Helmet
 
-Ejemplo: Partiendo de un proyecto NodeJS en blanco recien creado  
-`$ npm i minervajs-helmet  `
+## 🛡️ Descripción
 
-#### Archivo: ./config/settings.js  
-Adicionas una Entrada, por cada tipo y base de datos
-```javascript
+**MinervaJS-Helmet** es el módulo encargado de la **gestión unificada de conexiones y operaciones de base de datos** dentro del ecosistema **MinervaJS**.
+
+Su función principal es abstraer el motor de base de datos (MySQL, PostgreSQL, Oracle, etc.) y exponer una **API homogénea**, permitiendo que el resto del sistema funcione de forma **JSON-driven**, desacoplada y extensible.
+
+---
+
+## 🎯 Objetivos
+
+* Centralizar la gestión de conexiones a bases de datos
+* Soportar múltiples motores de forma transparente
+* Proveer una API común para:
+
+  * Consultas de lectura (SELECT)
+  * Operaciones de escritura (INSERT / UPDATE / DELETE / DDL)
+  * Procedimientos almacenados
+* Facilitar la construcción de backends genéricos y dinámicos
+
+---
+
+## 🧱 Arquitectura
+
+```
+MinervaJS
+ └── Helmet
+     ├── db_mysql.js
+     ├── db_postgres.js
+     ├── db_oracle.js
+     └── connections (cache interno)
+```
+
+Helmet actúa como un **dispatcher**, delegando la ejecución a proveedores específicos que implementan un contrato estándar.
+
+---
+
+## 🔌 Contrato estándar de proveedores
+
+Cada proveedor de base de datos debe implementar las siguientes funciones:
+
+```js
+connect(config)
+query(connection, sql, params = [])
+execute(connection, sql, params = [])
+call(connection, procedureName, params = {})
+close(connection)
+closeAll(config)
+```
+
+Este contrato garantiza que Helmet pueda operar sin conocer los detalles del motor subyacente.
+
+---
+
+## 📦 Instalación
+
+```bash
+npm install minervajs-helmet
+```
+
+> *(o incluir el módulo directamente dentro del proyecto MinervaJS)*
+
+---
+
+## ⚙️ Configuración de base de datos
+
+Ejemplo de archivo `database.json`:
+
+```json
 {
-  'my_mysql':				// 'Perfil de Conexión'
-  {
-    type: 'mysql',
-    host: 'sql3.freesqldatabase.com',	// 'localhost',
-    port: 3306, 			// 'puerto',
-    user: 'sql3772729', 		// 'usuario',
-    password: 'esUA3qpGKD', 		// 'contraseña',
-    database: 'sql3772729' 		// 'nombre_db'
+  "mysqlMain": {
+    "type": "mysql",
+    "host": "localhost",
+    "port": 3306,
+    "user": "user",
+    "password": "password",
+    "database": "minerva"
   }
 }
 ```
 
-#### Archivo: index.js
-
-```javascript
-var db = require('minervajs-helmet');
-var config = require('./config/settings.js');	// Configuración de Conexión
-
-async function main() {
-  try {
-    // Conexión a MySQL
-    const mysqlConnection = await db.connect('my_mysql', config);
-    const mysqlResult = await db.query('my_mysql', ' SELECT * FROM test ;', [], config); // Ejemplo sin parámetros
-    console.log('Resultados de MySQL:', mysqlResult);
-    await db.close('my_mysql', config);
-  } catch (error) {
-    console.error('Error:', error);
-  }
-}
+En la instalacion, puedes hacer uso del archivo muestra que esta en *\node_modules\minervajs-helmet\example\settings.js*
+
+---
+
+## 🚀 Uso básico
 
-main();
+```js
+const helmet = require('./helmet');
+const config = require('./database.json');
 ```
 
-#### Salida de resultados
-```javascript
-Resultados de MySQL: [
+---
+
+### 🔍 Consultas de lectura (SELECT)
+
+```js
+const rows = await helmet.query(
+  'mysqlMain',
+  'SELECT * FROM pais WHERE iso3 = ?',
+  ['SLV'],
+  config
+);
+```
+
+---
+
+### ✏️ Operaciones de escritura
+
+```js
+const result = await helmet.execute(
+  'mysqlMain',
+  'UPDATE pais SET nombre = ? WHERE iso3 = ?',
+  ['El Salvador', 'SLV'],
+  config
+);
+
+console.log(result.rowsAffected);
+```
+
+---
+
+### 🧠 Procedimientos almacenados
+
+```js
+const result = await helmet.call(
+  'mysqlMain',
+  'sp_pais_insert',
   {
-    id: 1,
-    codigo: 'SV',
-    descripcion: 'El Salvador',
-    fecha: 2025-04-02T06:00:00.000Z
+    p_iso3: 'SLV',
+    p_nombre: 'El Salvador',
+    p_leyenda: 'Centroamérica',
+    p_iso2: 'SV',
+    p_existe: { out: true }
   },
-  {
-    id: 2,
-    codigo: 'EU',
-    descripcion: 'Estados Unidos',
-    fecha: 2025-04-02T06:00:00.000Z
+  config
+);
+```
+
+**Resultado estándar:**
+
+```js
+{
+  resultSets: [...],
+  out: {
+    p_existe: 0
   }
-]
+}
 ```
 
-En la instalacion, puedes hacer uso del archivo muestra que esta en *\node_modules\minervajs-helmet\config\settings.js*
+---
+
+## 🔐 Gestión de conexiones
+
+* Una conexión por perfil de base de datos
+* Reutilización automática
+* Cache interno
+* Cierre explícito
+
+```js
+await helmet.close('mysqlMain', config);
+await helmet.closeAll(config);
+```
+
+---
+
+## ⚠️ Manejo de errores
+
+Helmet agrega contexto a los errores:
+
+```
+[Helmet][mysql][execute] Duplicate entry
+```
+
+Esto facilita el logging y el diagnóstico.
+
+---
+
+## 🧩 Integración JSON-driven (MinervaJS)
+
+Helmet está diseñado para ejecutarse a partir de manifiestos JSON:
+
+```json
+{
+  "database": "mysqlMain",
+  "procedure": "sp_pais_insert",
+  "params": {
+    "p_iso3": "$body.iso3",
+    "p_nombre": "$body.nombre",
+    "p_existe": { "out": true }
+  }
+}
+```
+
+La API ejecuta la operación sin conocer SQL ni lógica de negocio.
+
+---
+
+## ✅ Buenas prácticas
+
+* Usar `query()` exclusivamente para SELECT
+* Usar `execute()` para DML / DDL
+* Encapsular lógica compleja en Stored Procedures
+* Cerrar conexiones en shutdown de la aplicación
+* Mantener la configuración desacoplada
+
+
+---
+
+## 🔮 Evolución futura
+
+* Pooling de conexiones
+* Transacciones (`begin / commit / rollback`)
+* Multi-tenant
+* Logging estructurado
+* Métricas
+* Soporte para nuevos motores
+
+---
+
+## 📌 Conclusión
+
+**MinervaJS-Helmet** es el pilar de acceso a datos de MinervaJS.
+
+Su diseño modular, homogéneo y desacoplado permite construir aplicaciones dinámicas, escalables y mantenibles, donde la lógica de negocio puede definirse de forma declarativa y evolucionar sin reescribir el backend.
+
+
+
 
 

package/js/db_mysql.js

@@ -1,7 +1,9 @@
 /**
  * @module js/mysql
  * @name Provider DB js/mysql
- * @description Módulo para la conexión y operaciones del Proveedor MySQL.
+ * @description Módulo proveedor MySQL para MinervaJS-Helmet.
+ * Implementa operaciones estándar: query, execute y call.
+ * 
  */
  
  /**
@@ -34,7 +36,7 @@ async function connect(config)
   } 
   catch (error) 
   {
-    console.error('Error al conectar a MySQL:', error);
+    console.error('[MySQL][connect]', error.message);
     throw error; // Re-lanzamos el error para que sea manejado por el llamador
   }
 }
@@ -46,23 +48,91 @@ async function connect(config)
  * @function query
  * @param {mysql.Connection} connection - Objeto de conexión de MySQL.
  * @param {string} sql - Consulta SQL.
- * @param {Array} [values] - Parámetros para la consulta.
+ * @param {Array} [params] - Parámetros para la consulta.
  * @returns {Promise<Array>} Filas resultantes de la consulta.
  */
-async function query(connection, sql, values = []) 
+async function query(connection, sql, params = []) 
 {
   try 
   {
-    const [rows, fields] = await connection.execute(sql, values);
+    const [rows, fields] = await connection.execute(sql, params);
     return rows;
   } 
   catch (error) 
   {
-    console.error('Error al ejecutar la consulta MySQL:', error);
+    console.error('[MySQL][query]', error.message);
     throw error;
   }
 }
 
+
+
+/**
+ * Ejecuta una sentencia de escritura (INSERT, UPDATE, DELETE, DDL).
+ */
+async function execute(connection, sql, params = []) 
+{
+  try {
+    const [result] = await connection.execute(sql, params);
+
+    return {
+      rowsAffected: result.affectedRows,
+      insertId: result.insertId || null
+    };
+  } 
+  catch (error) 
+  {
+    console.error('[MySQL][execute]', error.message);
+    throw error;
+  }
+}
+
+
+/**
+ * Ejecuta un procedimiento almacenado.
+ *
+ * Nota:
+ * MySQL maneja OUT params mediante variables de sesión (@var).
+ */
+async function call(connection, procedureName, params = {}) {
+  try {
+    const keys = Object.keys(params);
+    const values = [];
+
+    const placeholders = keys.map(key => {
+      if (params[key]?.out) {
+        return `@${key}`;
+      }
+      values.push(params[key]);
+      return '?';
+    }).join(',');
+
+    // 1️ - Ejecutar CALL
+    const callSQL = `CALL ${procedureName}(${placeholders})`;
+    const [resultSets] = await connection.query(callSQL, values);
+
+    // 2️ - Recuperar OUT params
+    const outParams = keys.filter(k => params[k]?.out);
+    let out = {};
+
+    if (outParams.length > 0) {
+      const selectOut = `SELECT ${outParams.map(k => `@${k} AS ${k}`).join(',')}`;
+      const [rows] = await connection.query(selectOut);
+      out = rows[0];
+    }
+
+    return {
+      resultSets,
+      out
+    };
+  } catch (error) {
+    console.error('[MySQL][call]', error.message);
+    throw error;
+  }
+}
+
+
+
 /**
  * Cierra la conexión a la base de datos MySQL.
  *
@@ -77,9 +147,16 @@ async function close(connection)
   { await connection.end(); }
   catch (error) 
   {
-    console.error('Error al cerrar la conexión MySQL:', error);
+    console.error('[MySQL][close]', error.message);
     throw error;
   }
 }
 
-module.exports = { connect, query, close };
+module.exports = 
+{
+  connect,
+  query,
+  execute,
+  call,
+  close
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "minervajs-helmet",
-  "version": "1.0.12",
+  "version": "1.0.15",
   "main": "src/db.js",
   "scripts": {
     "test": "echo \"Error: no test specified\" && exit 1"
@@ -11,8 +11,8 @@
     "connect",
     "MySQL",
     "Oracle Client",
-	"PostGres",
-	"MinervaJS"
+    "PostGres",
+    "MinervaJS"
   ],
   "author": "alexander.enrique.escobar@gmail.com",
   "license": "BSD-2-Clause",

package/src/db.js

@@ -2,8 +2,7 @@
  * 
  * @name MinervaJS-Helmet
  * @module MinervaJS-Helmet
- * @description Modulo gestor de la coneccion a la base de datos, con capacidad de realizar consultas en múltiples bases de datos.
- *
+ * @description Gestor unificado de conexiones y ejecución de operaciones en múltiples motores de bases de datos.
  */
 
 const postgres = require('../js/db_postgres');
@@ -60,6 +59,38 @@ async function connect(databaseName, config)
 	return connections[databaseName];
 }
 
+
+/**
+ * Dispatcher interno para query / execute / call
+ */
+async function run(databaseName, target, params, config, mode) 
+{
+  const connection = await connect(databaseName, config);
+  const dbConfig = config[databaseName];
+
+  try {
+    switch (dbConfig.type) {
+      case 'postgres':
+        return await postgres[mode](connection, target, params);
+
+      case 'mysql':
+        return await mysql[mode](connection, target, params);
+
+      case 'oracle':
+        return await oracle[mode](connection, target, params);
+
+      default:
+        throw new Error(`Tipo de base de datos '${dbConfig.type}' no soportado.`);
+    }
+  } 
+  catch (err) 
+  {
+    throw new Error(`[Helmet][${dbConfig.type}][${mode}] ${err.message}`);
+  }
+}
+
+
+
 /**
  * Ejecuta una consulta en la base de datos especificada.
  *
@@ -73,29 +104,54 @@ async function connect(databaseName, config)
  * @throws {Error} Si el tipo de base de datos no es soportado para la operación 'query'.
  * @description Ejecuta una sentencia SQL en la base de datos especificada y devuelve un objeto en un set de datos
  */
-async function query(databaseName, sql, values = [], config) 
+// async function query(databaseName, sql, values = [], config) 
+// {
+  // const connection = await connect(databaseName, config);
+  // const dbConfig = config[databaseName];
+
+  // switch (dbConfig.type) 
+  // {
+    // case 'postgres':
+      // return postgres.query(connection, sql);
+    // case 'mysql':
+      // return mysql.query(connection, sql, values);
+    // // case 'mariadb': // agregamos el caso MariaDB
+    // //   return mariadb.query(connection, sql, binds);
+    // //   break;
+    // case 'oracle':
+      // return oracle.query(connection, sql);
+    // // case 'mongodb':
+    // //  // Adaptar la consulta SQL a la sintaxis de MongoDB
+    // //  console.warn("La función 'query' no es directamente aplicable a MongoDB con sintaxis SQL.");
+    // //  return null; // O lanzar un error
+    // default:
+      // throw new Error(`Tipo de base de datos '${dbConfig.type}' no soportado para la operación 'query'.`);
+  // }
+// }
+
+/**
+ * Ejecuta consultas de lectura (SELECT).
+ */
+async function query(databaseName, sql, params = [], config) 
 {
-  const connection = await connect(databaseName, config);
-  const dbConfig = config[databaseName];
+  return run(databaseName, sql, params, config, 'query');
+}
 
-  switch (dbConfig.type) 
-  {
-    case 'postgres':
-      return postgres.query(connection, sql);
-    case 'mysql':
-      return mysql.query(connection, sql, values);
-    // case 'mariadb': // agregamos el caso MariaDB
-    //   return mariadb.query(connection, sql, binds);
-    //   break;
-    case 'oracle':
-      return oracle.query(connection, sql);
-    // case 'mongodb':
-    //  // Adaptar la consulta SQL a la sintaxis de MongoDB
-    //  console.warn("La función 'query' no es directamente aplicable a MongoDB con sintaxis SQL.");
-    //  return null; // O lanzar un error
-    default:
-      throw new Error(`Tipo de base de datos '${dbConfig.type}' no soportado para la operación 'query'.`);
-  }
+/**
+ * Ejecuta sentencias de escritura (INSERT, UPDATE, DELETE, DDL).
+ */
+async function execute(databaseName, sql, params = [], config) 
+{
+  return run(databaseName, sql, params, config, 'execute');
+}
+
+
+/**
+ * Ejecuta procedimientos almacenados o funciones.
+ */
+async function call(databaseName, procedureName, params = {}, config) 
+{
+  return run(databaseName, procedureName, params, config, 'call');
 }
 
 /**
@@ -110,28 +166,28 @@ async function query(databaseName, sql, values = [], config)
  */
 async function close(databaseName, config) 
 {
-  if (connections[databaseName]) 
-  {
-    const dbConfig = config[databaseName];
-    switch (dbConfig.type) {
-      case 'postgres':
-        await postgres.close(connections[databaseName]);
-        break;
-      case 'mysql':
-        await mysql.close(connections[databaseName]);
-        break;
-    //  case 'mariadb': // agregamos el caso MariaDB
-    //    await mariadb.close(connections[databaseName]);
-    //    break;
-      case 'oracle':
-        await oracle.close(connections[databaseName]);
-        break;
-    //  case 'mongodb':
-    //    await mongodb.close(connections[databaseName]);
-    //    break;
-    }
-    delete connections[databaseName];
+  if (!connections[databaseName]) return;
+  
+  const dbConfig = config[databaseName];
+  switch (dbConfig.type) {
+  case 'postgres':
+	await postgres.close(connections[databaseName]);
+	break;
+  case 'mysql':
+	await mysql.close(connections[databaseName]);
+	break;
+//  case 'mariadb': // agregamos el caso MariaDB
+//    await mariadb.close(connections[databaseName]);
+//    break;
+  case 'oracle':
+	await oracle.close(connections[databaseName]);
+	break;
+//  case 'mongodb':
+//    await mongodb.close(connections[databaseName]);
+//    break;
   }
+    delete connections[databaseName];
+
 }
 
 
@@ -144,38 +200,47 @@ async function close(databaseName, config)
  * @returns {result} result/err - Devuelve un objeto con el set de datos o un objeto err con la respuesta del error
  * @description Ejecuta una sentencia SQL y devuelve un objeto en un set de datos
  */
-async function execute(databaseName, sql, values = [], config) 
-{
-	const connection = await connect(databaseName, config);
-	const dbConfig = config[databaseName];
+// async function execute(databaseName, sql, values = [], config) 
+// {
+	// const connection = await connect(databaseName, config);
+	// const dbConfig = config[databaseName];
 	
-	switch (dbConfig.type) 
-	{
-		case 'postgres':
-			return postgres.query(connection, sql);
-		case 'mysql':
-			return mysql.query(connection, sql, values);
-	// case 'mariadb': // agregamos el caso MariaDB
-	//   return mariadb.query(connection, sql, binds);
-	//   break;
-		case 'oracle':
-			return oracle.query(connection, sql);
-	// case 'mongodb':
-	//  // Adaptar la consulta SQL a la sintaxis de MongoDB
-	//  console.warn("La función 'query' no es directamente aplicable a MongoDB con sintaxis SQL.");
-	//  return null; // O lanzar un error
-		default:
-			throw new Error(`Tipo de base de datos '${dbConfig.type}' no soportado para la operación 'query'.`);
-	}
-}
+	// switch (dbConfig.type) 
+	// {
+		// case 'postgres':
+			// return postgres.query(connection, sql);
+		// case 'mysql':
+			// return mysql.query(connection, sql, values);
+	// // case 'mariadb': // agregamos el caso MariaDB
+	// //   return mariadb.query(connection, sql, binds);
+	// //   break;
+		// case 'oracle':
+			// return oracle.query(connection, sql);
+	// // case 'mongodb':
+	// //  // Adaptar la consulta SQL a la sintaxis de MongoDB
+	// //  console.warn("La función 'query' no es directamente aplicable a MongoDB con sintaxis SQL.");
+	// //  return null; // O lanzar un error
+		// default:
+			// throw new Error(`Tipo de base de datos '${dbConfig.type}' no soportado para la operación 'query'.`);
+	// }
+// }
 
- 
+/**
+ * Cierra todas las conexiones activas.
+ */
+async function closeAll(config) 
+{
+  for (const dbName of Object.keys(connections)) 
+  { await close(dbName, config); }
+}
 
 module.exports = 
 {
   connect,
   query,
   execute,
+  call,
   close,
+  closeAll
   // ... otras funciones comunes
 };