expressed-core 1.0.0

package/hooked/README.md

@@ -0,0 +1,238 @@
+# Express-Hooked
+
+Express-Hooked is a powerful extension for Express.js that brings a comprehensive hooks and filters system to your applications. Inspired by WordPress hooks system, it allows developers to extend functionality at various points in the request lifecycle without modifying core code.
+
+## Why Choose Express-Hooked?
+
+- **Flexible Architecture**: Hook into request processing at multiple stages
+- **Non-Intrusive**: Extend functionality without modifying existing code
+- **Priority System**: Control execution order with priority levels
+- **Namespace Support**: Organize hooks with namespaces for better maintainability
+- **Easy Integration**: Simple setup with minimal configuration
+
+## Installation
+
+```bash
+npm install express-hooked
+```
+
+## Quick Start
+
+```javascript
+const express = require('express');
+const ExpressHooked = require('express-hooked');
+
+const app = express();
+const port = 3000;
+
+// Initialize ExpressHooked
+const expressHooks = new ExpressHooked(app);
+
+// Register an action hook
+expressHooks.addAction('request_started', (req, res, next) => {
+  console.log(`Request received: ${req.method} ${req.url}`);
+  next();
+});
+
+// Register a filter hook
+expressHooks.addFilter('modify_response_data', (data) => {
+  return {
+    ...data,
+    processedBy: 'ExpressHooked',
+    timestamp: new Date().toISOString()
+  };
+});
+
+// Example route using filters
+app.get('/', (req, res) => {
+  let responseData = { message: 'Hello World!' };
+  responseData = expressHooks.applyFilters('modify_response_data', responseData);
+  
+  res.json(responseData);
+});
+
+// Initialize hooks integration
+expressHooks.init();
+
+app.listen(port, () => {
+  console.log(`Server running at http://localhost:${port}`);
+});
+```
+
+## Key Features
+
+### Actions
+Actions allow you to execute code at specific points without modifying data:
+
+```javascript
+expressHooks.addAction('request_started', (req, res, next) => {
+  // Do something when request starts
+  next();
+});
+```
+
+### Filters
+Filters allow you to modify data flowing through your application:
+
+```javascript
+expressHooks.addFilter('modify_response_data', (data) => {
+  // Modify and return the data
+  return { ...data, customField: 'value' };
+});
+```
+
+### Priority System
+Control execution order with priority levels (lower numbers execute first):
+
+```javascript
+// This executes first (higher priority)
+expressHooks.addAction('request_started', callback, 5);
+
+// This executes later (lower priority)
+expressHooks.addAction('request_started', callback, 15);
+```
+
+### Namespaces
+Organize your hooks with namespaces:
+
+```javascript
+// Register hook with namespace
+expressHooks.addAction('myplugin::before_request', callback);
+
+// Execute namespaced hook
+expressHooks.doAction('myplugin::before_request', req, res);
+```
+
+### Advanced Methods
+
+#### Removing Hooks and Filters
+You can remove specific hooks or filters using the following methods:
+
+```javascript
+// Remove a specific action
+expressHooks.removeAction('request_started', callback);
+
+// Remove an action by identifier
+expressHooks.removeAction('request_started', 'my-action-id');
+
+// Remove all actions for a hook
+expressHooks.removeAllActions('request_started');
+
+// Remove a specific filter
+expressHooks.removeFilter('modify_response_data', callback);
+
+// Remove a filter by identifier
+expressHooks.removeFilter('modify_response_data', 'my-filter-id');
+
+// Remove all filters for a hook
+expressHooks.removeAllFilters('modify_response_data');
+```
+
+#### Checking for Hooks and Filters
+Check if hooks or filters exist for a specific hook name:
+
+```javascript
+// Check if an action exists
+const hasAction = expressHooks.hasAction('request_started');
+
+// Check if a filter exists
+const hasFilter = expressHooks.hasFilter('modify_response_data');
+```
+
+#### Counting Hooks and Filters
+Get the number of registered hooks or filters for a specific hook name:
+
+```javascript
+// Count actions for a hook
+const actionCount = expressHooks.actionsCount('request_started');
+
+// Count filters for a hook
+const filterCount = expressHooks.filtersCount('modify_response_data');
+```
+
+#### Asynchronous Hooks and Filters
+Execute hooks and filters asynchronously:
+
+```javascript
+// Execute actions asynchronously
+await expressHooks.doActionAsync('request_started', req, res, next);
+
+// Apply filters asynchronously
+const filteredData = await expressHooks.applyFiltersAsync('modify_response_data', data);
+```
+
+### Additional Parameters
+When registering hooks, you can specify additional parameters:
+
+```javascript
+// acceptedArgs: Number of arguments the callback accepts
+expressHooks.addAction('request_started', callback, priority, acceptedArgs);
+
+// identifier: Optional identifier for the callback (useful for removal)
+expressHooks.addAction('request_started', callback, priority, acceptedArgs, 'my-action-id');
+```
+
+### Error Handling
+Errors within hooks are caught and logged to prevent crashing the application:
+
+```javascript
+expressHooks.addAction('request_started', (req, res, next) => {
+  // If an error occurs here, it will be caught and logged
+  problematicFunction();
+  next();
+});
+```
+
+### Route-Specific Hooks
+Register hooks for specific routes:
+
+```javascript
+// Register a hook to run before a specific route
+expressHooks.addRouteHook('/api/users', 'before', (req, res, next) => {
+  console.log('Before /api/users route');
+  next();
+});
+
+// Register a hook to run after a specific route
+expressHooks.addRouteHook('/api/users', 'after', (req, res, data) => {
+  console.log('After /api/users route');
+});
+```
+
+### Extending Express Methods
+Extend Express methods with custom functionality:
+
+```javascript
+// Extend an Express method with custom functionality
+expressHooks.extendExpressMethod('use', (originalUse) => {
+  return function(path, ...middlewares) {
+    // Custom logic before calling the original method
+    console.log(`Registering middleware for path: ${path}`);
+    
+    // Call the original method
+    return originalUse.call(this, path, ...middlewares);
+  };
+});
+```
+
+### Version Compatibility
+The current version of Express-Hooked follows semantic versioning. Breaking changes will be documented in the changelog.
+
+## Use Cases
+
+- **Authentication & Authorization**: Hook into request processing to validate credentials
+- **Logging & Analytics**: Track requests, responses, and performance metrics
+- **Caching**: Implement caching strategies at different levels
+- **API Transformation**: Modify API responses before sending to clients
+- **Error Handling**: Centralized error handling with custom logic
+- **Rate Limiting**: Implement rate limiting based on custom criteria
+
+## Contributing
+
+We welcome contributions! Please see our contributing guidelines for more information.
+
+## License
+
+Apache 2.0
+
+Repository: https://gitlab.com/bytedogssyndicate1/express-hooked

package/hooked/advanced-example.js

@@ -0,0 +1,240 @@
+/**
+ * Ejemplo avanzado de uso del sistema de hooks para Express
+ *
+ * Este archivo demuestra cómo utilizar las características avanzadas del sistema de hooks,
+ * incluyendo namespaces, identificadores, métodos asíncronos y manejo de rutas específicas.
+ */
+
+// Importar Express
+const express = require('express');
+
+// Importar el sistema de hooks para Express
+const ExpressHooked = require('./express-hooked');
+
+// Crear una aplicación Express
+const app = express();
+const port = 3032;
+
+// Inicializar ExpressHooked con la aplicación
+const expressHooks = new ExpressHooked(app);
+
+// 1. USO DE NAMESPACES
+console.log('1. Registrando hooks con namespaces...');
+
+// Registrar hooks en diferentes namespaces
+// En lugar de registrarlos como middlewares, los registramos para ser llamados por doAction
+expressHooks.addAction('authentication::before_request', (req, res, next) => {
+  console.log('[NAMESPACE AUTH] Validando autenticación...');
+  req.user = { id: 1, name: 'John Doe' }; // Simulando un usuario autenticado
+  // No llamamos a next() aquí porque se llama desde doAction
+});
+
+expressHooks.addAction('logging::after_request', (req, res) => {
+  console.log(`[NAMESPACE LOGGING] Petición ${req.method} ${req.url} procesada por ${req.user?.name || 'Anónimo'}`);
+});
+
+expressHooks.addFilter('data::transform_response', (data) => {
+  console.log('[NAMESPACE DATA] Transformando respuesta...');
+  return {
+    ...data,
+    transformed: true,
+    timestamp: new Date().toISOString()
+  };
+});
+
+// 2. USO DE IDENTIFICADORES
+console.log('2. Registrando hooks con identificadores...');
+
+expressHooks.addAction('request_started', (req, res, next) => {
+  console.log('[IDENTIFIER EXAMPLE] Primer hook registrado con identificador');
+  next();
+}, 10, 3, 'first_hook');
+
+expressHooks.addAction('request_started', (req, res, next) => {
+  console.log('[IDENTIFIER EXAMPLE] Segundo hook registrado con identificador');
+  next();
+}, 15, 3, 'second_hook');
+
+// 3. MÉTODOS ASÍNCRONOS
+console.log('3. Registrando hooks y filtros asíncronos...');
+
+// Hook asíncrono para simular una operación que toma tiempo
+expressHooks.addAction('async_operation', async (req, res, next) => {
+  console.log('[ASYNC HOOK] Iniciando operación asíncrona...');
+  
+  // Simular operación asíncrona (por ejemplo, acceso a base de datos)
+  await new Promise(resolve => setTimeout(resolve, 1000));
+  
+  console.log('[ASYNC HOOK] Operación asíncrona completada');
+  req.asyncData = 'Datos obtenidos de operación asíncrona';
+  next();
+});
+
+// Filtro asíncrono para transformar datos
+expressHooks.addFilter('async_transform', async (data) => {
+  console.log('[ASYNC FILTER] Transformando datos de forma asíncrona...');
+  
+  // Simular operación asíncrona
+  await new Promise(resolve => setTimeout(resolve, 500));
+  
+  return {
+    ...data,
+    asyncProcessed: true,
+    extraInfo: 'Información adicional procesada asíncronamente'
+  };
+});
+
+// 4. MANEJO DE RUTAS ESPECÍFICAS
+console.log('4. Registrando hooks para rutas específicas...');
+
+// Hook antes de procesar la ruta /api/users
+expressHooks.addRouteHook('/api/users', 'before', (req, res, next) => {
+  console.log('[ROUTE HOOK] Antes de procesar /api/users');
+  req.routeStartTime = Date.now();
+  next();
+});
+
+// Hook después de procesar la ruta /api/users
+expressHooks.addRouteHook('/api/users', 'after', (req, res, data) => {
+  const duration = Date.now() - req.routeStartTime;
+  console.log(`[ROUTE HOOK] Después de procesar /api/users. Duración: ${duration}ms`);
+});
+
+// Agregar middleware específico para la ruta /api/users para disparar los hooks
+app.use('/api/users', (req, res, next) => {
+  expressHooks.doAction('before_route_api_users', req, res, next);
+  next(); // Asegurar que se continúa con el siguiente middleware
+});
+
+// 5. VERIFICACIÓN Y CONTABILIZACIÓN DE HOOKS
+console.log('5. Verificando y contabilizando hooks registrados...');
+
+console.log('¿Existe el hook authentication::before_request?', expressHooks.hasAction('authentication::before_request'));
+console.log('¿Existe el filtro data::transform_response?', expressHooks.hasFilter('data::transform_response'));
+console.log('Cantidad de acciones para request_started:', expressHooks.actionsCount('request_started'));
+
+// 6. USO DE MIDDLEWARE PARA DISPARAR HOOKS AVANZADOS
+app.use((req, res, next) => {
+  // Disparar el hook asíncrono
+  expressHooks.doActionAsync('async_operation', req, res, next).then(() => {
+    next();
+  }).catch(next);
+});
+
+// Middleware para disparar hooks de logging después de la respuesta
+app.use((req, res, next) => {
+  const originalSend = res.send;
+  
+  res.send = function(body) {
+    // Disparar el hook de logging después de la respuesta
+    expressHooks.doAction('logging::after_request', req, res);
+    
+    return originalSend.call(this, body);
+  };
+  
+  next();
+});
+
+// Agregamos un hook al sistema predeterminado para que se ejecute al inicio de cada solicitud
+expressHooks.addAction('request_started', (req, res, next) => {
+  // Disparar hooks de autenticación antes de la lógica de negocio
+  expressHooks.doAction('authentication::before_request', req, res, () => {});
+  next(); // Llamamos a next aquí para continuar con la cadena de Express
+}, 4); // Mayor prioridad que el hook predeterminado (que es 5)
+
+// Middleware para parsear JSON
+app.use(express.json());
+
+// Ruta de ejemplo que utiliza filtros y namespaces
+app.get('/', async (req, res) => {
+  // Aplicar filtro del namespace
+  let responseData = { message: 'Hola Mundo desde ejemplo avanzado!' };
+  responseData = expressHooks.applyFilters('data::transform_response', responseData);
+
+  // Aplicar filtro asíncrono
+  responseData = await expressHooks.applyFiltersAsync('async_transform', responseData);
+
+  res.json(responseData);
+});
+
+// Ruta que utiliza hooks específicos para la ruta
+app.get('/api/users', (req, res) => {
+  const users = [
+    { id: 1, name: 'John', email: 'john@example.com' },
+    { id: 2, name: 'Jane', email: 'jane@example.com' }
+  ];
+
+  // Aplicar filtro del namespace
+  const responseData = expressHooks.applyFilters('data::transform_response', { users });
+
+  // Disparar el hook 'after' antes de enviar la respuesta
+  expressHooks.doAction('after_route_api_users', req, res, responseData);
+
+  res.json(responseData);
+});
+
+// Ruta para demostrar remoción de hooks por identificador
+app.get('/remove-hooks', (req, res) => {
+  console.log('6. Removiendo hooks por identificador...');
+  
+  // Remover el primer hook por su identificador
+  const removed = expressHooks.removeAction('request_started', 'first_hook');
+  console.log('Hook con identificador "first_hook" removido:', removed);
+  
+  // Contar acciones nuevamente
+  console.log('Cantidad de acciones para request_started después de remover:', expressHooks.actionsCount('request_started'));
+  
+  res.json({ 
+    message: 'Hook removido', 
+    hooksRemaining: expressHooks.actionsCount('request_started'),
+    asyncData: req.asyncData 
+  });
+});
+
+// Ruta para probar la extensión de métodos de Express
+app.get('/extended-method', (req, res) => {
+  res.json({ message: 'Ruta con método extendido' });
+});
+
+// Extender un método de Express para registrar middleware automáticamente
+expressHooks.extendExpressMethod('get', (originalGet) => {
+  return function(path, ...handlers) {
+    console.log(`[EXTENDED METHOD] Registrando ruta GET: ${path}`);
+    // Agregar un middleware antes de la ruta
+    this.use(path, (req, res, next) => {
+      console.log(`[EXTENDED METHOD] Middleware ejecutado para ruta: ${path}`);
+      next();
+    });
+    
+    // Llamar al método original
+    return originalGet.call(this, path, ...handlers);
+  };
+});
+
+// Registrar hooks predeterminados para que se vean en los logs
+expressHooks.addAction('request_started', (req, res, next) => {
+  console.log('[DEFAULT HOOK] request_started ejecutado');
+  next();
+}, 5); // Alta prioridad
+
+expressHooks.addAction('request_processed', (req, res) => {
+  console.log('[DEFAULT HOOK] request_processed ejecutado');
+});
+
+expressHooks.addAction('response_sent', (req, res) => {
+  console.log('[DEFAULT HOOK] response_sent ejecutado');
+});
+
+// Iniciar la integración de hooks
+expressHooks.init();
+
+// Iniciar el servidor
+app.listen(port, () => {
+  console.log(`\nServidor Express avanzado corriendo en http://localhost:${port}`);
+  console.log('Características avanzadas del sistema de hooks integradas correctamente.');
+  console.log('\nPrueba las siguientes rutas:');
+  console.log('- GET http://localhost:' + port + '/');
+  console.log('- GET http://localhost:' + port + '/api/users');
+  console.log('- GET http://localhost:' + port + '/remove-hooks');
+  console.log('- GET http://localhost:' + port + '/extended-method');
+});

package/hooked/express-hooked.js

@@ -0,0 +1,206 @@
+/**
+ * Sistema de Hooks para Express
+ * Basado en el sistema de hooks independiente
+ * 
+ * @author Benjamin Sanchez Cardenas
+ * @license Apache 2.0
+ */
+
+// Importar el sistema de hooks independiente
+const HookSystem = require('./hooks');
+
+class ExpressHooked extends HookSystem {
+  constructor(app) {
+    super();
+    
+    // Almacenar la aplicación Express
+    this.app = app;
+    
+    // Registrar hooks predeterminados para eventos de Express
+    this._registerDefaultHooks();
+    
+    // Añadir el sistema de hooks a la aplicación Express
+    if (this.app) {
+      this.app.locals.hooks = this;
+    }
+  }
+
+  /**
+   * Registra hooks predeterminados para eventos de Express
+   * @private
+   */
+  _registerDefaultHooks() {
+    // Hooks para eventos de solicitud
+    this.addAction('request_started', (req, res, next) => {
+      // Este hook se ejecuta al inicio de cada solicitud
+      req.startTime = Date.now();
+      req.hookData = {}; // Objeto para almacenar datos entre hooks
+      next();
+    }, 5); // Alta prioridad para inicialización temprana
+    
+    this.addAction('request_processed', (req, res) => {
+      // Este hook se ejecuta después de procesar la solicitud
+      if (req.startTime) {
+        const duration = Date.now() - req.startTime;
+        req.duration = duration;
+        console.log(`Request ${req.method} ${req.url} took ${duration}ms`);
+      }
+    }, 15); // Baja prioridad para ejecución tardía
+    
+    this.addAction('response_sent', (req, res) => {
+      // Este hook se ejecuta después de enviar la respuesta
+      console.log(`Response sent for ${req.method} ${req.url}. Status: ${res.statusCode}`);
+    });
+  }
+
+  /**
+   * Middleware para disparar hooks al inicio de la solicitud
+   * @returns {Function} Middleware de Express
+   */
+  requestStartedMiddleware() {
+    return (req, res, next) => {
+      // Disparar hook al inicio de la solicitud
+      this.doAction('request_started', req, res, next);
+    };
+  }
+
+  /**
+   * Middleware para disparar hooks al finalizar la solicitud
+   * @returns {Function} Middleware de Express
+   */
+  requestProcessedMiddleware() {
+    return (req, res, next) => {
+      // Guardar la función original de res.end
+      const originalEnd = res.end;
+      
+      // Sobrescribir res.end para capturar cuando se envía la respuesta
+      res.end = function(chunk, encoding, callback) {
+        // Disparar hook antes de enviar la respuesta
+        this.doAction('request_processed', req, res);
+        
+        // Llamar a la función original
+        const result = originalEnd.call(res, chunk, encoding, callback);
+        
+        // Disparar hook después de enviar la respuesta
+        setImmediate(() => {
+          this.doAction('response_sent', req, res);
+        });
+        
+        return result;
+      }.bind(this);
+      
+      next();
+    };
+  }
+
+  /**
+   * Middleware para manejar errores y disparar hooks correspondientes
+   * @returns {Function} Middleware de Express
+   */
+  errorHandlerMiddleware() {
+    return (err, req, res, next) => {
+      // Disparar hook cuando ocurre un error
+      this.doAction('error_occurred', err, req, res, next);
+      
+      // Continuar con el manejo de errores de Express
+      next(err);
+    };
+  }
+
+  /**
+   * Middleware para disparar hooks antes de procesar la ruta
+   * @param {string} route - Ruta específica
+   * @returns {Function} Middleware de Express
+   */
+  routeProcessingMiddleware(route) {
+    return (req, res, next) => {
+      // Disparar hook antes de procesar la ruta específica
+      this.doAction(`before_route_${route}`, req, res, next);
+      next();
+    };
+  }
+
+  /**
+   * Middleware para disparar hooks después de procesar la ruta
+   * @param {string} route - Ruta específica
+   * @returns {Function} Middleware de Express
+   */
+  routeProcessedMiddleware(route) {
+    return (req, res, next) => {
+      // Guardar la función original de res.send
+      const originalSend = res.send;
+      
+      // Sobrescribir res.send para capturar cuando se envía la respuesta para una ruta específica
+      res.send = function(data) {
+        // Disparar hook antes de enviar la respuesta para la ruta específica
+        this.doAction(`after_route_${route}`, req, res, data);
+        
+        // Llamar a la función original
+        return originalSend.call(res, data);
+      }.bind(this);
+      
+      next();
+    };
+  }
+
+  /**
+   * Método para iniciar la integración con Express
+   */
+  init() {
+    // Añadir middleware para hooks al inicio de la solicitud
+    this.app.use(this.requestStartedMiddleware());
+    
+    // Añadir middleware para hooks al procesar la solicitud
+    this.app.use(this.requestProcessedMiddleware());
+    
+    // Añadir middleware para manejo de errores
+    this.app.use(this.errorHandlerMiddleware());
+  }
+
+  /**
+   * Método para registrar un hook específico para una ruta
+   * @param {string} route - Ruta específica
+   * @param {string} hookType - Tipo de hook ('before' o 'after')
+   * @param {Function} callback - Callback a ejecutar
+   * @param {number} priority - Prioridad del callback
+   * @param {number} acceptedArgs - Número de argumentos aceptados
+   * @param {string} [identifier] - Identificador opcional
+   */
+  addRouteHook(route, hookType, callback, priority = 10, acceptedArgs = 1, identifier = null) {
+    if (!['before', 'after'].includes(hookType)) {
+      throw new Error('hookType debe ser "before" o "after"');
+    }
+    
+    // Determinar el nombre del hook según el tipo
+    const hookName = hookType === 'before' 
+      ? `before_route_${route.replace(/\//g, '_')}` 
+      : `after_route_${route.replace(/\//g, '_')}`;
+      
+    this.addAction(hookName, callback, priority, acceptedArgs, identifier);
+  }
+
+  /**
+   * Método para registrar un middleware específico para una ruta
+   * @param {string} method - Método HTTP (GET, POST, etc.)
+   * @param {string} route - Ruta específica
+   * @param {...Function} middlewares - Middlewares a aplicar
+   */
+  addRouteMiddleware(method, route, ...middlewares) {
+    // Añadir middlewares antes de la ruta específica
+    this.app[method.toLowerCase()](route, ...middlewares);
+  }
+
+  /**
+   * Método para extender la funcionalidad de Express con hooks
+   * @param {string} methodName - Nombre del método a extender
+   * @param {Function} wrapperFn - Función que envuelve la funcionalidad original
+   */
+  extendExpressMethod(methodName, wrapperFn) {
+    if (this.app && typeof this.app[methodName] === 'function') {
+      const originalMethod = this.app[methodName];
+      this.app[methodName] = wrapperFn(originalMethod);
+    }
+  }
+}
+
+module.exports = ExpressHooked;