jerkjs 2.2.0 → 2.3.1

package/docs/frontend-and-sessions.md

@@ -0,0 +1,353 @@
+# Frontend y Sesiones con API SDK JS
+
+## Introducción
+
+API SDK JS no solo es un framework para crear APIs, sino que ahora también soporta la creación de aplicaciones web completas con frontend y sistema de sesiones. Esta funcionalidad permite a los desarrolladores crear aplicaciones web completas con autenticación basada en sesiones, almacenamiento de datos y mucho más.
+
+## Características del Frontend
+
+### Especificación de Content-Type en routes.json
+
+Una de las nuevas características es la capacidad de especificar el content-type directamente en el archivo routes.json:
+
+```json
+[
+  {
+    "path": "/",
+    "method": "GET",
+    "controller": "./controllers/pageController.js",
+    "handler": "homePage",
+    "auth": "none",
+    "contentType": "text/html"
+  },
+  {
+    "path": "/api/data",
+    "method": "GET",
+    "controller": "./controllers/apiController.js",
+    "handler": "getData",
+    "auth": "none",
+    "contentType": "application/json"
+  }
+]
+```
+
+### Soporte para diferentes tipos de contenido
+
+El framework ahora puede servir diferentes tipos de contenido:
+- HTML para páginas web
+- CSS para estilos
+- JavaScript para scripts
+- JSON para APIs
+- Y cualquier otro tipo de contenido
+
+## Sistema de Sesiones
+
+### Configuración
+
+Para usar el sistema de sesiones, primero debes configurar el middleware en tu aplicación:
+
+```javascript
+const { APIServer, SessionManager, Cors } = require('@apisdkjs/apisdkjs');
+
+async function startServer() {
+  const server = new APIServer({
+    port: 3000,
+    host: 'localhost'
+  });
+
+  // Crear instancia del administrador de sesiones
+  const sessionManager = new SessionManager({
+    cookieName: 'myapp_session',
+    secret: 'my-super-secret-session-key',
+    timeout: 3600000 // 1 hora
+  });
+
+  // Aplicar middleware de sesión
+  server.use(sessionManager.middleware());
+
+  // Hacer que sessionManager esté disponible para el RouteLoader
+  server.sessionManager = sessionManager;
+
+  // Cargar rutas
+  const routeLoader = new RouteLoader();
+  await routeLoader.loadRoutes(server, './routes.json');
+
+  server.start();
+}
+```
+
+### Protección de rutas
+
+Puedes proteger rutas específicas usando `"auth": "session"` en tu archivo routes.json:
+
+```json
+[
+  {
+    "path": "/dashboard",
+    "method": "GET",
+    "controller": "./controllers/dashboardController.js",
+    "handler": "showDashboard",
+    "auth": "session",
+    "contentType": "text/html"
+  }
+]
+```
+
+### Uso en controladores
+
+En tus controladores, puedes acceder a la sesión a través de `req.session`:
+
+```javascript
+const authController = {
+  // Controlador para iniciar sesión
+  processLogin: async (req, res) => {
+    const { username, password } = req.body;
+    
+    // Validar credenciales (tu lógica aquí)
+    const user = await validateUser(username, password);
+    
+    if (user) {
+      // Crear sesión de usuario autenticado
+      req.session.create({
+        authenticated: true,
+        userId: user.id,
+        username: user.username
+      });
+      
+      res.writeHead(200, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({
+        success: true,
+        message: 'Inicio de sesión exitoso'
+      }));
+    } else {
+      res.writeHead(401, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({
+        success: false,
+        message: 'Credenciales inválidas'
+      }));
+    }
+  },
+
+  // Controlador para cerrar sesión
+  processLogout: (req, res) => {
+    if (req.session) {
+      req.session.destroy();
+    }
+    
+    res.writeHead(200, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify({
+      success: true,
+      message: 'Sesión cerrada exitosamente'
+    }));
+  }
+};
+```
+
+## Sistema de Hooks, Filters y Actions
+
+El sistema de sesiones está completamente integrado con el sistema de hooks, filters y actions del framework, lo que permite extender y personalizar su comportamiento.
+
+### Hooks Disponibles
+
+#### Sesion Creation Hooks
+- `session_create_data`: Filtra los datos antes de crear una sesión
+- `session_created`: Acción disparada después de crear una sesión
+- `session_create_user_data`: Filtra los datos de usuario antes de crear la sesión
+
+#### Sesion Retrieval Hooks
+- `session_get_id`: Filtra el ID de sesión antes de buscarla
+- `session_retrieved`: Acción disparada después de obtener una sesión
+- `session_not_found`: Acción disparada cuando no se encuentra una sesión
+- `session_expired`: Acción disparada cuando una sesión ha expirado
+
+#### Sesion Update Hooks
+- `session_update_data`: Filtra los nuevos datos antes de actualizar la sesión
+- `session_updated`: Acción disparada después de actualizar una sesión
+- `session_update_user_data`: Filtra los datos de usuario antes de actualizar
+
+#### Sesion Destruction Hooks
+- `session_destroy_before`: Acción disparada antes de destruir una sesión
+- `session_destroyed`: Acción disparada después de destruir una sesión
+- `session_destroy_failed`: Acción disparada cuando falla la destrucción
+
+#### Middleware Hooks
+- `session_middleware_before`: Acción disparada antes del middleware de sesión
+- `session_middleware_after`: Acción disparada después del middleware de sesión
+
+#### Authentication Hooks
+- `session_auth_check_before`: Acción disparada antes de verificar autenticación
+- `session_auth_success`: Acción disparada cuando la autenticación es exitosa
+- `session_auth_failed`: Acción disparada cuando la autenticación falla
+- `session_created_response`: Acción disparada después de crear sesión en respuesta
+- `session_updated_response`: Acción disparada después de actualizar sesión en respuesta
+- `session_destroyed_response`: Acción disparada después de destruir sesión en respuesta
+
+### Ejemplos de Uso de Hooks
+
+#### Registrar actividad de sesión
+
+```javascript
+const { hooks } = require('@apisdkjs/apisdkjs');
+
+// Registrar cuando se crea una sesión
+hooks.addAction('session_created', (sessionId, sessionData) => {
+  console.log(`Sesión creada: ${sessionId} para el usuario: ${sessionData.username}`);
+});
+
+// Registrar cuando se destruye una sesión
+hooks.addAction('session_destroyed', (sessionId, sessionData) => {
+  console.log(`Sesión destruida: ${sessionId} para el usuario: ${sessionData.username}`);
+});
+```
+
+#### Modificar datos de sesión antes de crearla
+
+```javascript
+const { hooks } = require('@apisdkjs/apisdkjs');
+
+// Añadir información de IP y fecha a los datos de sesión
+hooks.addFilter('session_create_data', (userData, req) => {
+  return {
+    ...userData,
+    ipAddress: req.headers['x-forwarded-for'] || req.connection.remoteAddress,
+    createdAt: new Date().toISOString()
+  };
+});
+```
+
+#### Personalizar el manejo de autenticación fallida
+
+```javascript
+const { hooks } = require('@apisdkjs/apisdkjs');
+
+// Registrar intentos de acceso no autorizado
+hooks.addAction('session_auth_failed', (req, res, redirectTo) => {
+  console.log(`Intento de acceso no autorizado a: ${req.url} desde IP: ${req.connection.remoteAddress}`);
+  
+  // Puedes personalizar la respuesta aquí
+  if (req.headers.accept && req.headers.accept.includes('application/json')) {
+    res.writeHead(401, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify({ error: 'No autorizado', code: 'AUTH_REQUIRED' }));
+  }
+});
+```
+
+#### Extender datos de sesión durante la actualización
+
+```javascript
+const { hooks } = require('@apisdkjs/apisdkjs');
+
+// Añadir marca de tiempo a cada actualización de sesión
+hooks.addFilter('session_update_data', (newData, req, sessionId) => {
+  return {
+    ...newData,
+    lastUpdated: new Date().toISOString(),
+    lastActivity: new Date().toISOString()
+  };
+});
+```
+
+## Ejemplo Completo
+
+Aquí tienes un ejemplo completo de una aplicación que combina frontend y sesiones:
+
+### app.js
+```javascript
+const {
+  APIServer,
+  RouteLoader,
+  Logger,
+  Cors,
+  SessionManager
+} = require('@apisdkjs/apisdkjs');
+
+async function startServer() {
+  const server = new APIServer({
+    port: 3000,
+    host: 'localhost'
+  });
+
+  const logger = new Logger({ level: 'info' });
+
+  try {
+    // Configurar sesiones
+    const sessionManager = new SessionManager({
+      cookieName: 'myapp_session',
+      secret: 'my-super-secret-session-key',
+      timeout: 3600000
+    });
+
+    server.use(sessionManager.middleware());
+    server.sessionManager = sessionManager;
+
+    // Configurar CORS
+    const cors = new Cors({
+      origin: '*',
+      methods: ['GET', 'POST', 'PUT', 'DELETE', 'OPTIONS'],
+      allowedHeaders: ['Content-Type', 'Authorization']
+    });
+
+    server.use(cors.middleware());
+
+    // Cargar rutas
+    const routeLoader = new RouteLoader();
+    await routeLoader.loadRoutes(server, './routes.json');
+
+    server.start();
+    logger.info('Servidor iniciado en http://localhost:3000');
+  } catch (error) {
+    logger.error('Error iniciando el servidor:', error.message);
+    process.exit(1);
+  }
+}
+
+startServer();
+```
+
+### routes.json
+```json
+[
+  {
+    "path": "/",
+    "method": "GET",
+    "controller": "./controllers/pageController.js",
+    "handler": "homePage",
+    "auth": "none",
+    "contentType": "text/html"
+  },
+  {
+    "path": "/login",
+    "method": "GET",
+    "controller": "./controllers/authController.js",
+    "handler": "showLoginPage",
+    "auth": "none",
+    "contentType": "text/html"
+  },
+  {
+    "path": "/dashboard",
+    "method": "GET",
+    "controller": "./controllers/dashboardController.js",
+    "handler": "showDashboard",
+    "auth": "session",
+    "contentType": "text/html"
+  },
+  {
+    "path": "/api/login",
+    "method": "POST",
+    "controller": "./controllers/authController.js",
+    "handler": "processLogin",
+    "auth": "none",
+    "contentType": "application/json"
+  },
+  {
+    "path": "/api/logout",
+    "method": "POST",
+    "controller": "./controllers/authController.js",
+    "handler": "processLogout",
+    "auth": "session",
+    "contentType": "application/json"
+  }
+]
+```
+
+Este ejemplo demuestra cómo crear una aplicación web completa con autenticación basada en sesiones, protección de rutas y soporte para frontend HTML.

package/docs/guia_inicio_rapido_jerkjs.md

@@ -0,0 +1,113 @@
+# Documentación de Aprendizajes con JERKJS
+
+## 1. Formato del archivo routes.json
+
+**Formato correcto:**
+```json
+[
+  {
+    "method": "GET",
+    "path": "/",
+    "controller": "./controllers/mainController.js",
+    "handler": "home",
+    "auth": "none"
+  }
+]
+```
+
+**Características importantes:**
+- Debe ser un array directo de rutas, **NO** un objeto con propiedad "routes"
+- Campos requeridos: `method`, `path`, `controller`, `handler`, `auth`
+- El campo `controller` debe especificar la ruta completa al archivo del controlador
+- El campo `handler` debe especificar el nombre exacto del método en el controlador
+- El campo `auth` puede ser "none", "required", etc.
+
+## 2. Estructura de controladores para usar con routes.json
+
+**Formato correcto:**
+```javascript
+const { ControllerBase } = require('jerkjs');
+
+class MainController extends ControllerBase {
+  constructor(options = {}) {
+    super(options);
+  }
+
+  home(req, res) {
+    // Lógica del controlador
+  }
+}
+
+// Exportar métodos directamente para que el RouteLoader pueda acceder a ellos
+const controllerInstance = new MainController({ viewsPath: './views' });
+
+module.exports = {
+  home: (req, res) => {
+    controllerInstance.setRequestResponse(req, res);
+    controllerInstance.home(req, res);
+  }
+};
+```
+
+**Características importantes:**
+- No se puede exportar directamente la instancia del controlador
+- Debe exportar un objeto con funciones que encapsulan la llamada al método del controlador
+- Se debe llamar a `setRequestResponse()` antes de ejecutar el método del controlador
+
+## 3. Uso del motor de plantillas de JERK
+
+**Características del motor de plantillas:**
+- Usa sintaxis `{{variable}}` para mostrar variables
+- Soporta condicionales: `{{if variable}}contenido{{endif}}`
+- Soporta bucles: `{{foreach:array}}contenido{{endforeach}}`
+- Se accede a los elementos del bucle con `{{item.property}}`
+
+## 4. Sistema de hooks
+
+**Tipos de hooks:**
+- `addAction(nombre_hook, callback)` - Para acciones que se ejecutan en puntos específicos
+- `addFilter(nombre_hook, callback)` - Para filtrar/modificar datos
+
+**Hooks útiles:**
+- `post_controller_load` - Se ejecuta después de cargar un controlador
+- `pre_route_load` - Se ejecuta antes de cargar rutas
+- `post_route_load` - Se ejecuta después de cargar rutas
+- `request_received` - Se ejecuta cuando se recibe una solicitud
+- `request_completed` - Se ejecuta cuando se completa una solicitud
+
+## 5. Puerto y configuración del servidor
+
+**Configuración del servidor:**
+```javascript
+const server = new APIServer({
+  port: 11000,  // Puerto específico
+  host: 'localhost'
+});
+```
+
+## 6. Controladores que extienden ControllerBase
+
+**Características:**
+- Deben extender `ControllerBase` del framework
+- Usan `this.set()` para establecer variables de vista
+- Usan `this.render()` para renderizar vistas
+- Requieren que se llame a `setRequestResponse()` antes de usar métodos del controlador
+
+## 7. Errores comunes y soluciones
+
+**Error común:** "this.set is not a function"
+**Solución:** Asegurarse de que se llama a `controllerInstance.setRequestResponse(req, res)` antes de ejecutar métodos del controlador
+
+**Error común:** "Error cargando rutas desde ./routes.json: El archivo de rutas debe contener un array de rutas"
+**Solución:** Asegurarse de que routes.json sea un array directo, no un objeto con propiedad "routes"
+
+**Error común:** "controllerLoader.loadControllers is not a function"
+**Solución:** El RouteLoader se encarga de cargar tanto rutas como controladores, no usar ControllerLoader por separado
+
+## 8. Recursos útiles
+
+- Directorio de ejemplos en `/node_modules/jerkjs/examples/`
+- Archivos routes.json de ejemplo en los directorios de ejemplos
+- Documentación en el README del paquete
+
+Esta documentación servirá para futuros desarrollos con JERKJS y evitará caer en los mismos errores o confusiones.

package/index.js

@@ -48,6 +48,11 @@ const ModelControllerExample = require('./lib/mvc/ModelControllerExample');
 // Componentes de manejo de errores
 const { ErrorHandler, ValidationError, AuthenticationError, DatabaseError } = require('./lib/utils/errorHandler');
 
+// Componentes del QueryBuilder (v2.3.0)
+const QueryBuilder = require('./lib/query/queryBuilder');
+const QueryBuilderMiddleware = require('./lib/query/queryBuilderMiddleware');
+const { initializeQueryBuilderHooks, extendQueryBuilderWithHooks } = require('./lib/query/queryBuilderHooks');
+
 // Exportar todos los componentes del framework
 module.exports = {
   // Componentes fundamentales (v1.0)
@@ -105,7 +110,13 @@ module.exports = {
   ErrorHandler,
   ValidationError,
   AuthenticationError,
-  DatabaseError
+  DatabaseError,
+
+  // Componentes del QueryBuilder (v2.3.0)
+  QueryBuilder,
+  QueryBuilderMiddleware,
+  initializeQueryBuilderHooks,
+  extendQueryBuilderWithHooks
 };
 
 // También exportar clases individuales por conveniencia

package/jerk-qbuilder/CHANGELOG.md

@@ -0,0 +1,71 @@
+# Changelog
+
+Todos los cambios importantes en este proyecto se documentarán en este archivo.
+
+El formato está basado en [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+y este proyecto adhiere al [Versionado Semántico](https://semver.org/spec/v2.0.0.html).
+
+## [Versión 1.0.0] - 2026-01-21
+
+### Cambios Importantes
+
+#### 🚀 Características Nuevas
+
+- **QueryBuilder principal**
+  - Implementación completa del QueryBuilder con API fluida
+  - Métodos para SELECT, INSERT, UPDATE, DELETE
+  - Soporte para condiciones WHERE, JOINs, GROUP BY, ORDER BY
+  - Paginación con LIMIT y OFFSET
+  - Funciones de agregación (COUNT, MAX, MIN, SUM, AVG)
+
+- **Método setAdapter()**
+  - Implementación del método `setAdapter(adapter)` para configurar dinámicamente cualquier adaptador
+  - Permite cambiar de base de datos en tiempo de ejecución
+  - Compatible con múltiples sistemas de base de datos
+
+- **Adaptador MariaDB**
+  - Implementación del adaptador para MariaDB/MySQL
+  - Conexión mediante pool de conexiones
+  - Ejecución segura de consultas SQL
+
+- **Adaptador de Consola**
+  - Adaptador de ejemplo para mostrar consultas SQL por consola
+  - Útil para pruebas y desarrollo
+  - Simula resultados de consultas
+
+- **Middleware de Integración**
+  - Sistema completo para inyectar QueryBuilder en solicitudes HTTP
+  - Middleware para configurar adaptadores
+  - Middleware para registrar QueryBuilder con hooks
+  - Middleware para habilitar registro de consultas
+  - Middleware para aplicar reglas de seguridad
+
+- **Sistema de Hooks**
+  - Integración completa con el sistema de hooks de JERK
+  - Acciones y filtros para eventos del QueryBuilder
+  - Sistema de auditoría de consultas
+  - Aplicación de reglas de seguridad
+
+#### 🔧 Cambios Técnicos
+
+- **Arquitectura modular**
+  - Estructura de archivos separados para cada componente
+  - Dependencias claras entre módulos
+  - Código organizado y mantenible
+
+- **Seguridad mejorada**
+  - Prevención de inyección SQL mediante el uso de parámetros
+  - Sistema de validación de consultas
+  - Reglas de seguridad configurables
+
+- **Documentación completa**
+  - README.md con descripción general
+  - HOWTO.md con instrucciones detalladas de uso
+  - Ejemplos prácticos de implementación
+
+#### 📝 Otros Cambios
+
+- **Ejemplos de uso**
+  - Aplicación de demostración completa
+  - Ejemplos de integración con JERK Framework
+  - Casos de uso prácticos con base de datos real