minervajs-helmet 1.0.11 → 1.0.15

package/LICENSE

@@ -1,6 +1,6 @@
 BSD 2-Clause License
 
-Copyright (c) 2024, Alexander E. Escobar
+Copyright (c) 2024, 2025, Alexander Enrique Escobar O.
 
 Redistribution and use in source and binary forms, with or without
 modification, are permitted provided that the following conditions are met:

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  
 
-Ejemplo: Partiendo de un proyecto 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 Conexion'
-  {
-    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 con 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.
+ * 
  */
  
  /**
@@ -19,8 +21,10 @@ const mysql = require('mysql2/promise'); // Usamos mysql2/promise para async/awa
  * @param {object} config - Configuración de la conexión.
  * @returns {Promise<mysql.Connection>} Objeto de conexión de MySQL.
  */
-async function connect(config) {
-  try {
+async function connect(config) 
+{
+  try 
+  {
     const connection = await mysql.createConnection({
       host: config.host,
       port: config.port,
@@ -29,8 +33,10 @@ async function connect(config) {
       database: config.database,
     });
     return connection;
-  } catch (error) {
-    console.error('Error al conectar a MySQL:', error);
+  } 
+  catch (error) 
+  {
+    console.error('[MySQL][connect]', error.message);
     throw error; // Re-lanzamos el error para que sea manejado por el llamador
   }
 }
@@ -42,19 +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 = []) {
-  try {
-    const [rows, fields] = await connection.execute(sql, values);
+async function query(connection, sql, params = []) 
+{
+  try 
+  {
+    const [rows, fields] = await connection.execute(sql, params);
     return rows;
+  } 
+  catch (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('Error al ejecutar la consulta MySQL:', error);
+    console.error('[MySQL][call]', error.message);
     throw error;
   }
 }
 
+
+
 /**
  * Cierra la conexión a la base de datos MySQL.
  *
@@ -63,13 +141,22 @@ async function query(connection, sql, values = []) {
  * @param {mysql.Connection} connection - Objeto de conexión de MySQL.
  * @returns {Promise<void>}
  */
-async function close(connection) {
-  try {
-    await connection.end();
-  } catch (error) {
-    console.error('Error al cerrar la conexión MySQL:', error);
+async function close(connection) 
+{
+  try 
+  { await connection.end(); }
+  catch (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.11",
+  "version": "1.0.15",
   "main": "src/db.js",
   "scripts": {
     "test": "echo \"Error: no test specified\" && exit 1"
@@ -10,10 +10,12 @@
     "Multi DataBase",
     "connect",
     "MySQL",
-    "Oracle Client"
+    "Oracle Client",
+    "PostGres",
+    "MinervaJS"
   ],
   "author": "alexander.enrique.escobar@gmail.com",
-  "license": "ISC",
+  "license": "BSD-2-Clause",
   "description": "Modulo para la gestion de coneccion a la base de datos, de diferentes tipos mediante el uso de sobre Carga y Herencia de clases",
   "dependencies": {
     "mysql2": "^3.14.0",

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');
@@ -27,41 +26,71 @@ const connections = {};
  */
 async function connect(databaseName, config) 
 {
+	const dbConfig = config[databaseName];
+
+	if (!dbConfig) 
+	{ throw new Error(`Configuración de base de datos '${databaseName}' no encontrada.`); }
+
+	// Ya existe una conexión 
+	if (connections[databaseName]) 
+	{ return connections[databaseName]; }
+
+	switch (dbConfig.type) 
+	{
+		case 'postgres':
+			connections[databaseName] = await postgres.connect(dbConfig);
+			break;
+		case 'mysql':
+			connections[databaseName] = await mysql.connect(dbConfig);
+			break;
+		// case 'mariadb':
+		//   connections[databaseName] = await mariadb.connect(dbConfig);
+		//   break;
+		case 'oracle':
+			connections[databaseName] = await oracle.connect(dbConfig);
+			break;
+		// case 'mongodb':
+		//  connections[databaseName] = await mongodb.connect(dbConfig);
+		//  break;
+		default:
+			throw new Error(`Tipo de base de datos '${dbConfig.type}' no soportado.`);
+	}
+
+	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];
-  
-  if (!dbConfig) {
-    throw new Error(`Configuración de base de datos '${databaseName}' no encontrada.`);
-  }
 
-  if (connections[databaseName]) 
-  {
-    return connections[databaseName]; // Ya existe una conexión
-  }
+  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);
 
-  switch (dbConfig.type) 
+      default:
+        throw new Error(`Tipo de base de datos '${dbConfig.type}' no soportado.`);
+    }
+  } 
+  catch (err) 
   {
-    case 'postgres':
-      connections[databaseName] = await postgres.connect(dbConfig);
-      break;
-    case 'mysql':
-      connections[databaseName] = await mysql.connect(dbConfig);
-      break;
-    // case 'mariadb':
-    //   connections[databaseName] = await mariadb.connect(dbConfig);
-    //   break;
-    case 'oracle':
-      connections[databaseName] = await oracle.connect(dbConfig);
-      break;
-    // case 'mongodb':
-    //  connections[databaseName] = await mongodb.connect(dbConfig);
-    //  break;
-    default:
-      throw new Error(`Tipo de base de datos '${dbConfig.type}' no soportado.`);
+    throw new Error(`[Helmet][${dbConfig.type}][${mode}] ${err.message}`);
   }
-
-  return connections[databaseName];
 }
 
+
+
 /**
  * Ejecuta una consulta en la base de datos especificada.
  *
@@ -75,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');
 }
 
 /**
@@ -112,47 +166,81 @@ 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];
+
 }
 
 
 
 /**
  * @function 
- * @name executeSQL
+ * @name execute
  * @param {string} sql - Sentencia SQL a ejecutar
  * @param {Promise<callback>} callback - objeto, para retornar la promesa
  * @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];
+	
+	// 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
 };

package/js/OLD db.js

@@ -1,76 +0,0 @@
-/**
- * @module 
- * @name db_mysql
- * @description Modulo gestor de la coneccion a la base de datos, MySQL, utiliza el cliente mysql2
- */
-
-var mysql = require('mysql');
-var settings = require('../settings');
-
-/**
- * @function 
- * @name executeSQL
- * @param {string} sql - Sentencia SQL a ejecutar
- * @param {Promise<callback>} callback - objeto, para retornar la promesa
- * @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
- */
-exports.executeSQL = function (sql, callback)
-{
-    var con = new mysql.createConnection(settings.dbConfig);
-    
-    con.connect(function(err) 
-	{
-        if (err) 
-        {
-            callback(null, err);
-            //throw err;
-        }
-        if (settings.servConfig.debug){console.log("Connected!");}
-        con.query(sql, function (err, result) {
-          if (err) 
-          {
-            callback(null, err);
-            //throw err;
-          }
-		  if (settings.servConfig.debug){console.log("Sentencia Ejecutada:"+sql);}
-          callback(result);
-		  
-		  con.end();
-        });
-    });
-};
-
-/**
- * @function 
- * @name executeSQLarray
- * @param {string} sql - Sentencia SQL a ejecutar
- * @param {Promise<callback>} callback - objeto, para retornar la promesa
- * @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, basado en una serie de argumentos y devuelve un objeto en un set de datos
- */
-exports.executeSQLarray = function (sql, array, callback)
-{
-	var con = new mysql.createConnection(settings.dbConfig);
-    
-    con.connect(function(err) 
-	{
-        if (err) 
-        {
-            callback(null, err);
-            //throw err;
-        }
-        if (settings.servConfig.debug){console.log("Connected!");}
-        con.query(sql, array, function (err, result) {
-          if (err) 
-          {
-            callback(null, err);
-            //throw err;
-          }
-          if (settings.servConfig.debug){console.log("Sentencia Ejecutada:"+sql);}
-          callback(result);
-		  
-		  con.end();
-        });
-    });
-}