expressed-example-app 1.0.0 → 2.1.0

package/README.md

@@ -0,0 +1,136 @@
+# Express-Router-BDS Example Application
+
+This is a sample Express.js application demonstrating the usage of the `express-router-bds` routing system with custom hooks, advanced features, and integrated queue system.
+
+## Overview
+
+This example application showcases:
+
+- High-performance routing with `express-router-bds`
+- JSON-based route configuration
+- Custom hook system implementation
+- Parameterized route handling
+- Directory-based route loading
+- Integrated queue system with `express-queued`
+- Declarative route definitions in separate JSON files
+
+## Features
+
+- **Modular Route Configuration**: Routes defined in JSON files for easy maintenance
+- **Custom Hooks**: Comprehensive hook system with `pre_route_load`, `post_route_load`, `before_route_handler`, `after_route_handler`, `route_handler_error`, and more
+- **Parameterized Routes**: Support for dynamic routes like `/users/:id` and `/products/:category/:id`
+- **Integrated Queue System**: Background task processing with `express-queued`
+- **Declarative Routes**: Separate route files for different functionalities
+- **Extensible Architecture**: Easy to extend with custom middleware and hooks
+
+## Project Structure
+
+```
+express-app/
+├── app.js                 # Main application entry point
+├── queue-system.js        # Queue system integration
+├── hooks-config.js        # Base hook configurations
+├── hooks-personalizados.js # Custom hook implementations
+├── controllers/
+│   ├── mainController.js  # Home, init and queue route handlers
+│   ├── productController.js # Product route handlers
+│   └── userController.js  # User route handlers
+├── routes/
+│   ├── main-routes.json   # Main route definitions in JSON format
+│   └── queue-routes.json  # Queue-related route definitions
+└── node_modules/
+    ├── express-router-bds/ # Custom routing system
+    └── express-queued/    # Queue system
+```
+
+## Available Endpoints
+
+### Main Endpoints
+- `GET /` - Home page with welcome message
+- `GET /init` - Initialization endpoint
+- `GET /users/:id` - Get user by ID
+- `GET /products/:category/:id` - Get product by category and ID
+- `GET /test-hook` - Test endpoint for hook demonstration
+
+### Queue System Endpoints
+- `GET /queue-status` - Get the status of the queue system
+- `GET /start-queues` - Start the queue system
+- `GET /stop-queues` - Stop the queue system
+- `POST /process-user` - Add a user processing task to the queue
+- `POST /process-product` - Add a product processing task to the queue
+- `POST /send-email` - Add an email sending task to the queue
+
+## Queue System
+
+The application integrates `express-queued` for background task processing:
+
+- **Multiple Queues**: Dedicated queues for different types of tasks
+- **Configurable Concurrency**: Control how many tasks execute simultaneously per queue
+- **Retry System**: Automatic failure handling with configurable retries
+- **Priority Management**: Assign priorities to tasks
+- **Hooks Integration**: Customize processing with hooks
+
+### Queue Types
+- `procesamiento-general` - General processing tasks
+- `envio-correos` - Email sending tasks
+- `procesamiento-usuarios` - User processing tasks
+- `procesamiento-productos` - Product processing tasks
+
+## Hook System
+
+The application demonstrates several types of hooks:
+
+- `pre_route_load` - Executes before loading routes from a file
+- `post_route_load` - Executes after loading routes from a file
+- `before_route_processing` - Executes before processing any route
+- `route_matched` - Executes when a matching route is found
+- `before_route_handler` - Executes before executing a route handler
+- `after_route_handler` - Executes after executing a route handler
+- `route_handler_error` - Executes when a route handler error occurs
+
+## Installation
+
+```bash
+npm install
+```
+
+## Usage
+
+Start the server:
+
+```bash
+npm start
+```
+
+The application will be available at `http://localhost:3000`
+
+## Testing
+
+Test the main endpoints:
+
+```bash
+curl http://localhost:3000
+curl http://localhost:3000/users/123
+curl http://localhost:3000/products/electronics/456
+```
+
+Test the queue system:
+
+```bash
+# Check queue status
+curl http://localhost:3000/queue-status
+
+# Add a user processing task
+curl -X POST http://localhost:3000/process-user \
+  -H "Content-Type: application/json" \
+  -d '{"userId": "123", "name": "John Doe", "email": "john@example.com"}'
+
+# Add an email sending task
+curl -X POST http://localhost:3000/send-email \
+  -H "Content-Type: application/json" \
+  -d '{"to": "test@example.com", "subject": "Test", "content": "Test content"}'
+```
+
+## License
+
+This project is part of the `express-router-bds` ecosystem and follows the same licensing terms.

package/app.js

@@ -1,115 +1,167 @@
-/**
- * Aplicación principal
- * Integración de @hooked, @router y @queued con una arquitectura limpia
- */
-
 const express = require('express');
-const fs = require('fs');
-const path = require('path');
-const ExpressHooked = require('express-hooked');
 const ExpressRouterIntegration = require('express-router-bds');
-const ExpressQueueIntegration = require('express-queued');
-const AppHooks = require('./hooks/AppHooks');
-const { captureBodyMiddleware } = require('./middleware/bodyCapture');
+const RouteDirectoryLoader = require('express-router-bds/RouteDirectoryLoader');
+const AppHooks = require('./hooks-config');
+const HooksPersonalizados = require('./hooks-personalizados');
+const QueueSystem = require('./queue-system');
 
-// Crear la aplicación Express
 const app = express();
-const port = 3001;
+const PORT = process.env.PORT || 3000;
 
-// Leer la configuración de rutas desde el archivo JSON
-const routesConfig = JSON.parse(fs.readFileSync(path.join(__dirname, 'config/routes.json'), 'utf8'));
+// Crear instancia del router
+const routerIntegration = new ExpressRouterIntegration();
 
-// Inicializar el sistema de hooks
-const hooked = new ExpressHooked(app);
+// Crear instancia del sistema de colas
+const queueSystem = new QueueSystem();
 
-// Inicializar el sistema de enrutamiento
-const router = new ExpressRouterIntegration();
+// Inicializar hooks y filtros
+const appHooks = new AppHooks(app, routerIntegration.getHooks());
 
-// Inicializar el sistema de colas
-const queueSystem = new ExpressQueueIntegration();
+// Inicializar hooks personalizados
+const hooksPersonalizados = new HooksPersonalizados(routerIntegration);
 
-// Registrar los hooks de la aplicación
-AppHooks.registerHooks(hooked);
+// Cargar rutas desde directorio
+const routeDirectoryLoader = new RouteDirectoryLoader();
 
-// Middleware para capturar el body
-app.use(captureBodyMiddleware);
+// Middleware para parsear JSON
+app.use(express.json());
 
-// Middleware para servir archivos estáticos
-app.use(express.static(path.join(__dirname, 'public')));
+// Middleware para inyectar el sistema de colas en las solicitudes
+app.use(queueSystem.getInstance().queueMiddleware());
 
-// Cargar dinámicamente los controladores y registrar las rutas
-for (const route of routesConfig.routes) {
-  // Extraer el nombre del controlador y la acción
-  const [controllerName, actionName] = route.controller.split('.');
-  
-  // Construir la ruta del archivo del controlador
-  const controllerPath = path.join(__dirname, 'controllers', `${controllerName}.js`);
-  
-  // Verificar si el archivo del controlador existe
-  if (fs.existsSync(controllerPath)) {
-    // Importar el controlador
-    const Controller = require(controllerPath);
-    
-    // Verificar si la acción existe en el controlador
-    if (Controller[actionName]) {
-      // Registrar la ruta con el método HTTP, la ruta y el controlador
-      router.addRoute(route.method, route.path, (req, res) => {
-        // Disparar hook antes de ejecutar la acción
-        hooked.doAction('before_controller_action', req, res, route);
-        
-        // Disparar hook para mostrar información detallada de la solicitud
-        // Usar el body capturado en lugar del body original que puede estar vacío
-        if (req.capturedBody) {
-          req.body = req.capturedBody;
-        }
-        hooked.doAction('request_details_log', req, res, route);
-        
-        // Ejecutar la acción del controlador
-        Controller[actionName](req, res);
-        
-        // Disparar hook después de ejecutar la acción
-        hooked.doAction('after_controller_action', req, res, route);
-      });
-    } else {
-      console.error(`La acción "${actionName}" no existe en el controlador "${controllerName}"`);
-    }
-  } else {
-    console.error(`El archivo del controlador "${controllerPath}" no existe`);
+// Middleware para inyectar el sistema de rutas en las solicitudes
+app.use((req, res, next) => {
+  req.routerIntegration = routerIntegration;
+  next();
+});
+
+routerIntegration.addHook('route_matched', (matchedRoute, req, res) => {
+  console.log(`Ruta encontrada: ${matchedRoute.route.path}`);
+  if (matchedRoute.params && Object.keys(matchedRoute.params).length > 0) {
+    console.log(`Parámetros:`, matchedRoute.params);
   }
-}
+});
+
+// Cargar rutas desde el directorio
+routeDirectoryLoader.loadRoutesFromDirectory(routerIntegration, './routes')
+  .then(routes => {
+    console.log(`${routes.length} rutas cargadas desde directorio`);
+    // Mostrar las rutas que se han cargado
+    routes.forEach(route => {
+      console.log(`Ruta cargada: ${route.method} ${route.path}`);
+    });
+  })
+  .catch(error => {
+    console.error('Error cargando rutas desde directorio:', error.message);
+  });
+
+// Cargar rutas específicas de colas
+const RouteLoader = require('express-router-bds/RouteLoader');
+const queueRouteLoader = new RouteLoader();
+queueRouteLoader.loadRoutes(routerIntegration, './routes/queue-routes.json')
+  .then(queueRoutes => {
+    console.log(`${queueRoutes.length} rutas de colas cargadas`);
+    queueRoutes.forEach(route => {
+      console.log(`Ruta de cola cargada: ${route.method} ${route.path}`);
+    });
+  })
+  .catch(error => {
+    console.error('Error cargando rutas de colas:', error.message);
+  });
 
-// Aplicar el middleware de colas para inyectar el sistema en las solicitudes
-app.use(queueSystem.queueMiddleware());
+// Aplicar el router a la aplicación Express
+routerIntegration.applyToApp(app);
 
-// Aplicar el router a la aplicación
-router.applyToApp(app);
+// Middleware para manejar errores 404
+app.use((req, res) => {
+  res.status(404).json({ error: 'Ruta no encontrada' });
+});
 
-// Iniciar el sistema de colas
-queueSystem.start();
+// Ruta para obtener el estado del sistema de colas
+app.get('/queue-status', (req, res) => {
+  const status = req.getQueueStatus();
+  res.json(status);
+});
+
+// Ruta para iniciar el sistema de colas
+app.get('/start-queues', (req, res) => {
+  queueSystem.start();
+  res.json({ message: 'Sistema de colas iniciado' });
+});
+
+// Ruta para detener el sistema de colas
+app.get('/stop-queues', (req, res) => {
+  queueSystem.stop();
+  res.json({ message: 'Sistema de colas detenido' });
+});
+
+// Ruta para procesar un usuario en cola
+app.post('/process-user', (req, res) => {
+  const { userId, name, email } = req.body;
+  
+  if (!userId) {
+    return res.status(400).json({ error: 'userId es requerido' });
+  }
+  
+  const taskId = queueSystem.addUserProcessingTask({ userId, name, email });
+  
+  res.json({
+    message: 'Tarea de procesamiento de usuario agregada a la cola',
+    taskId
+  });
+});
 
-// Iniciar el sistema de hooks
-hooked.init();
+// Ruta para procesar un producto en cola
+app.post('/process-product', (req, res) => {
+  const { productId, name, price } = req.body;
+  
+  if (!productId) {
+    return res.status(400).json({ error: 'productId es requerido' });
+  }
+  
+  const taskId = queueSystem.addProductProcessingTask({ productId, name, price });
+  
+  res.json({
+    message: 'Tarea de procesamiento de producto agregada a la cola',
+    taskId
+  });
+});
 
-// Middleware para manejo de errores
-app.use((err, req, res, next) => {
-  console.error('Error:', err);
-  res.status(500).json({
-    error: 'Ocurrió un error en el servidor',
-    message: err.message
+// Ruta para enviar un correo en cola
+app.post('/send-email', (req, res) => {
+  const { to, subject, content } = req.body;
+  
+  if (!to) {
+    return res.status(400).json({ error: 'to es requerido' });
+  }
+  
+  const taskId = queueSystem.addEmailSendingTask({ to, subject, content });
+  
+  res.json({
+    message: 'Tarea de envío de correo agregada a la cola',
+    taskId
   });
 });
 
 // Iniciar el servidor
-app.listen(port, () => {
-  console.log(`Servidor corriendo en http://localhost:${port}`);
-  console.log('Módulos integrados:');
-  console.log('- @hooked: Sistema de hooks activo');
-  console.log('- @router: Sistema de enrutamiento activo');
-  console.log('- @queued: Sistema de colas activo');
+app.listen(PORT, () => {
+  console.log(`Servidor corriendo en el puerto ${PORT}`);
+  console.log('Endpoints disponibles:');
+  console.log('- GET /');
+  console.log('- GET /init');
+  console.log('- GET /users/:id');
+  console.log('- GET /products/:category/:id');
+  console.log('- GET /test-hook');
+  console.log('- GET /queue-status');
+  console.log('- GET /start-queues');
+  console.log('- GET /stop-queues');
+  console.log('- POST /process-user');
+  console.log('- POST /process-product');
+  console.log('- POST /send-email');
   
-  // Mostrar rutas registradas
-  console.log('\nRutas disponibles:');
-  routesConfig.routes.forEach(route => {
-    console.log(`${route.method} ${route.path} -> ${route.controller}.${route.action}`);
-  });
-});
+  // Iniciar el sistema de colas
+  queueSystem.start();
+  console.log('Sistema de colas iniciado');
+});
+
+module.exports = app;

package/changelog-core-enrutador.md

@@ -0,0 +1,177 @@
+# Changelog Detallado: Modificaciones al Core de Express-Router-BDS
+
+## Archivo: `/node_modules/express-router-bds/ExpressRouter.js`
+
+### Cambio 1: Llamada al hook `before_route_processing`
+- **Fecha**: 15 de febrero de 2026
+- **Línea(s)**: 154
+- **Antes**:
+  ```javascript
+  this.hooks.doAction('before_route_processing', req, res, next);
+  ```
+- **Después**:
+  ```javascript
+  this.hooks.doAction('before_route_processing', req, res);
+  ```
+- **Motivo**: Evitar que el hook reciba el parámetro `next` para prevenir conflictos con el flujo normal de Express
+
+### Cambio 2: Manejo de headers en ejecución del handler
+- **Fecha**: 15 de febrero de 2026
+- **Líneas**: 185-187
+- **Antes**:
+  ```javascript
+  if (!res.headersSent) {
+    matchedRoute.route.handler(req, res, next);
+  } else {
+    console.warn('Headers ya fueron enviados, no se puede ejecutar el handler');
+  }
+  ```
+- **Después**:
+  ```javascript
+  if (!res.headersSent) {
+    // Añadir logging para depuración
+    console.log(`Ejecutando handler para ruta: ${req.method} ${req.url}`);
+    matchedRoute.route.handler(req, res, next);
+  } else {
+    console.warn('Headers ya fueron enviados, no se puede ejecutar el handler');
+    next();
+  }
+  ```
+- **Motivo**: Añadir logging para depuración y asegurar que se llame a `next()` si los headers ya han sido enviados
+
+### Cambio 3: Llamada a hooks de handler
+- **Fecha**: 15 de febrero de 2026
+- **Línea(s)**: 180
+- **Antes**:
+  ```javascript
+  this.hooks.doAction('before_route_handler', req, res, next);
+  ```
+- **Después**:
+  ```javascript
+  this.hooks.doAction('before_route_handler', req, res);
+  ```
+- **Motivo**: Consistencia con el manejo de hooks para evitar conflictos con `next()`
+
+### Cambio 4: Manejo de errores en handler
+- **Fecha**: 15 de febrero de 2026
+- **Línea(s)**: 193
+- **Antes**:
+  ```javascript
+  this.hooks.doAction('route_handler_error', error, req, res, next);
+  ```
+- **Después**:
+  ```javascript
+  this.hooks.doAction('route_handler_error', error, req, res);
+  ```
+- **Motivo**: Consistencia con el manejo de hooks para evitar conflictos con `next()`
+
+## Archivo: `/node_modules/express-router-bds/RouteLoader.js`
+
+### Cambio 1: Manejo seguro de headers en handlers con contentType
+- **Fecha**: 15 de febrero de 2026
+- **Líneas**: 178-195
+- **Antes**:
+  ```javascript
+  // Ejecutar el handler original
+  try {
+    if (handler.constructor.name === 'AsyncFunction') {
+      await handler(req, res, next);
+    } else {
+      handler(req, res, next);
+    }
+  } catch (error) {
+    // Si ocurre un error, asegurarse de no intentar enviar headers otra vez
+    if (!res.headersSent) {
+      next(error);
+    } else {
+      console.error('Error en el handler:', error);
+    }
+  }
+  ```
+- **Después**:
+  ```javascript
+  // Ejecutar el handler original solo si no se han enviado headers aún
+  if (!res.headersSent) {
+    try {
+      if (handler.constructor.name === 'AsyncFunction') {
+        await handler(req, res, next);
+      } else {
+        handler(req, res, next);
+      }
+    } catch (error) {
+      // Si ocurre un error, asegurarse de no intentar enviar headers otra vez
+      if (!res.headersSent) {
+        next(error);
+      } else {
+        console.error('Error en el handler:', error);
+      }
+    }
+  }
+  ```
+- **Motivo**: Asegurar que los handlers no se ejecuten si los headers ya han sido enviados
+
+### Cambio 2: Eliminación de wrapper adicional
+- **Fecha**: 15 de febrero de 2026
+- **Líneas**: 197-217
+- **Antes**:
+  ```javascript
+  // Crear un handler que envuelva completamente la lógica para prevenir doble ejecución
+  const wrappedHandler = async (req, res, next) => {
+    // Verificar que no se hayan enviado headers aún
+    if (res.headersSent) {
+      return;
+    }
+
+    // Ejecutar el handler final
+    try {
+      await finalHandler(req, res, next);
+    } catch (error) {
+      if (!res.headersSent) {
+        next(error);
+      } else {
+        console.error('Error en el handler:', error);
+      }
+    }
+  };
+
+  // Agregar la ruta con el handler envuelto
+  routerIntegration.addRoute(route.method, route.path, wrappedHandler);
+  ```
+- **Después**:
+  ```javascript
+  // Agregar la ruta con el handler final (sin doble wrapper)
+  // Asegurarse de que el handler es correcto
+  routerIntegration.addRoute(route.method, route.path, finalHandler);
+  ```
+- **Motivo**: Eliminar wrapper redundante que podría causar problemas de ejecución doble
+
+## Archivo: `/node_modules/express-router-bds/RouteMatcher.js`
+
+### Cambio 1: Mejora en la conversión de rutas a expresiones regulares
+- **Fecha**: 15 de febrero de 2026
+- **Líneas**: 213-225
+- **Antes**:
+  ```javascript
+  // Lógica de escape de caracteres especiales
+  let escapedPath = '';
+  for (let i = 0; i < path.length; i++) {
+    const char = path[i];
+    if (char.match(/[.+?^${}()|[\]\\-]/) && !(i > 0 && path[i-1] === ':')) {
+      escapedPath += '\\' + char;
+    } else {
+      escapedPath += char;
+    }
+  }
+  ```
+- **Después**: (Sin cambios, ya que no se modificó este archivo directamente)
+
+## Resumen de Impacto
+
+Los cambios realizados al core de `express-router-bds` se enfocaron principalmente en:
+
+1. **Evitar conflictos con el parámetro `next`** en las llamadas a hooks
+2. **Mejorar la seguridad en el manejo de headers** para prevenir el error `ERR_HTTP_HEADERS_SENT`
+3. **Eliminar wrappers redundantes** que podían causar ejecuciones dobles de handlers
+4. **Agregar verificaciones adicionales** para asegurar que los handlers solo se ejecuten cuando sea seguro hacerlo
+
+Estos cambios resolvieron el problema fundamental donde las rutas se identificaban pero los handlers no se ejecutaban, permitiendo que la aplicación funcione correctamente.

package/controllers/mainController.js

@@ -0,0 +1,96 @@
+// controllers/mainController.js
+// Controlador principal de la aplicación
+
+class MainController {
+  /**
+   * Maneja la ruta raíz
+   * @param {Object} req - Objeto de solicitud
+   * @param {Object} res - Objeto de respuesta
+   */
+  home(req, res) {
+    if (!res.headersSent) {
+      res.json({
+        message: '¡Bienvenido a la aplicación Express con Router-BDS!',
+        timestamp: new Date().toISOString()
+      });
+    } else {
+      console.log('Headers ya fueron enviados en home handler');
+    }
+  }
+
+  /**
+   * Maneja la ruta de inicialización
+   * @param {Object} req - Objeto de solicitud
+   * @param {Object} res - Objeto de respuesta
+   */
+  init(req, res) {
+    res.json({
+      message: 'Aplicación inicializada correctamente con Router-BDS',
+      status: 'success'
+    });
+  }
+
+  /**
+   * Obtiene el estado del sistema de colas
+   * @param {Object} req - Objeto de solicitud
+   * @param {Object} res - Objeto de respuesta
+   */
+  getQueueStatus(req, res) {
+    const status = req.getQueueStatus();
+    res.json(status);
+  }
+
+  /**
+   * Inicia el sistema de colas
+   * @param {Object} req - Objeto de solicitud
+   * @param {Object} res - Objeto de respuesta
+   */
+  startQueues(req, res) {
+    req.queueSystem.start();
+    res.json({ message: 'Sistema de colas iniciado' });
+  }
+
+  /**
+   * Detiene el sistema de colas
+   * @param {Object} req - Objeto de solicitud
+   * @param {Object} res - Objeto de respuesta
+   */
+  stopQueues(req, res) {
+    req.queueSystem.stop();
+    res.json({ message: 'Sistema de colas detenido' });
+  }
+
+  /**
+   * Agrega una tarea de envío de correo a la cola
+   * @param {Object} req - Objeto de solicitud
+   * @param {Object} res - Objeto de respuesta
+   */
+  sendEmailInQueue(req, res) {
+    const { to, subject, content } = req.body;
+
+    if (!to) {
+      return res.status(400).json({ error: 'to es requerido' });
+    }
+
+    const taskId = req.addTask('envio-correos', async (data, taskObj) => {
+      console.log(`[ENVIO-CORREO] Enviando correo a: ${data.to}`);
+      
+      // Simular envío de correo (con 10% de probabilidad de fallo)
+      await new Promise(resolve => setTimeout(resolve, 1000));
+      
+      if (Math.random() < 0.1) {
+        throw new Error(`Fallo al enviar correo a: ${data.to}`);
+      }
+      
+      console.log(`[ENVIO-CORREO] Correo enviado exitosamente a: ${data.to}`);
+      return `Correo enviado a ${data.to} exitosamente`;
+    }, { to, subject, content });
+
+    res.json({
+      message: 'Tarea de envío de correo agregada a la cola',
+      taskId
+    });
+  }
+}
+
+module.exports = new MainController();