# Express-Hooked

Express-Hooked es una potente extensión para Express.js que incorpora un sistema completo de hooks y filtros a tus aplicaciones. Inspirado en el sistema de hooks de WordPress, permite a los desarrolladores extender la funcionalidad en varios puntos del ciclo de vida de las solicitudes sin modificar el código central.

## ¿Por qué elegir Express-Hooked?

- **Arquitectura Flexible**: Integra hooks en múltiples etapas del procesamiento de solicitudes
- **No Intrusivo**: Extiende funcionalidad sin modificar código existente
- **Sistema de Prioridades**: Controla el orden de ejecución con niveles de prioridad
- **Soporte de Espacios de Nombres**: Organiza hooks con espacios de nombres para mejor mantenibilidad
- **Fácil Integración**: Configuración simple con mínima configuración

## Instalación

```bash
npm install express-hooked
```

## Inicio Rápido

```javascript
const express = require('express');
const ExpressHooked = require('express-hooked');

const app = express();
const port = 3000;

// Inicializar ExpressHooked
const expressHooks = new ExpressHooked(app);

// Registrar un hook de acción
expressHooks.addAction('request_started', (req, res, next) => {
  console.log(`Solicitud recibida: ${req.method} ${req.url}`);
  next();
});

// Registrar un hook de filtro
expressHooks.addFilter('modify_response_data', (data) => {
  return {
    ...data,
    processedBy: 'ExpressHooked',
    timestamp: new Date().toISOString()
  };
});

// Ruta de ejemplo usando filtros
app.get('/', (req, res) => {
  let responseData = { message: '¡Hola Mundo!' };
  responseData = expressHooks.applyFilters('modify_response_data', responseData);
  
  res.json(responseData);
});

// Inicializar integración de hooks
expressHooks.init();

app.listen(port, () => {
  console.log(`Servidor corriendo en http://localhost:${port}`);
});
```

## Características Clave

### Acciones
Las acciones permiten ejecutar código en puntos específicos sin modificar datos:

```javascript
expressHooks.addAction('request_started', (req, res, next) => {
  // Haz algo cuando comienza la solicitud
  next();
});
```

### Filtros
Los filtros permiten modificar los datos que fluyen a través de tu aplicación:

```javascript
expressHooks.addFilter('modify_response_data', (data) => {
  // Modifica y devuelve los datos
  return { ...data, campoPersonalizado: 'valor' };
});
```

### Sistema de Prioridades
Controla el orden de ejecución con niveles de prioridad (números más bajos se ejecutan primero):

```javascript
// Esto se ejecuta primero (prioridad más alta)
expressHooks.addAction('request_started', callback, 5);

// Esto se ejecuta después (prioridad más baja)
expressHooks.addAction('request_started', callback, 15);
```

### Espacios de Nombres
Organiza tus hooks con espacios de nombres:

```javascript
// Registrar hook con espacio de nombres
expressHooks.addAction('miplugin::before_request', callback);

// Ejecutar hook con espacio de nombres
expressHooks.doAction('miplugin::before_request', req, res);
```

### Métodos Avanzados

#### Remover Hooks y Filtros
Puedes remover hooks o filtros específicos usando los siguientes métodos:

```javascript
// Remover una acción específica
expressHooks.removeAction('request_started', callback);

// Remover una acción por identificador
expressHooks.removeAction('request_started', 'my-action-id');

// Remover todas las acciones para un hook
expressHooks.removeAllActions('request_started');

// Remover un filtro específico
expressHooks.removeFilter('modify_response_data', callback);

// Remover un filtro por identificador
expressHooks.removeFilter('modify_response_data', 'my-filter-id');

// Remover todos los filtros para un hook
expressHooks.removeAllFilters('modify_response_data');
```

#### Verificar la Existencia de Hooks y Filtros
Comprueba si existen hooks o filtros para un nombre específico:

```javascript
// Verificar si existe una acción
const hasAction = expressHooks.hasAction('request_started');

// Verificar si existe un filtro
const hasFilter = expressHooks.hasFilter('modify_response_data');
```

#### Contar Hooks y Filtros
Obtén el número de hooks o filtros registrados para un nombre específico:

```javascript
// Contar acciones para un hook
const actionCount = expressHooks.actionsCount('request_started');

// Contar filtros para un hook
const filterCount = expressHooks.filtersCount('modify_response_data');
```

#### Hooks y Filtros Asíncronos
Ejecuta hooks y filtros de forma asíncrona:

```javascript
// Ejecutar acciones de forma asíncrona
await expressHooks.doActionAsync('request_started', req, res, next);

// Aplicar filtros de forma asíncrona
const filteredData = await expressHooks.applyFiltersAsync('modify_response_data', data);
```

### Parámetros Adicionales
Al registrar hooks, puedes especificar parámetros adicionales:

```javascript
// acceptedArgs: Número de argumentos que acepta el callback
expressHooks.addAction('request_started', callback, priority, acceptedArgs);

// identifier: Identificador opcional para el callback (útil para removerlo)
expressHooks.addAction('request_started', callback, priority, acceptedArgs, 'my-action-id');
```

### Manejo de Errores
Los errores dentro de los hooks se capturan y registran para evitar que la aplicación se bloquee:

```javascript
expressHooks.addAction('request_started', (req, res, next) => {
  // Si ocurre un error aquí, se capturará y registrará
  problematicFunction();
  next();
});
```

### Hooks Específicos para Rutas
Registra hooks para rutas específicas:

```javascript
// Registrar un hook para ejecutar antes de una ruta específica
expressHooks.addRouteHook('/api/users', 'before', (req, res, next) => {
  console.log('Antes de la ruta /api/users');
  next();
});

// Registrar un hook para ejecutar después de una ruta específica
expressHooks.addRouteHook('/api/users', 'after', (req, res, data) => {
  console.log('Después de la ruta /api/users');
});
```

### Extensión de Métodos de Express
Extiende métodos de Express con funcionalidad personalizada:

```javascript
// Extiende un método de Express con funcionalidad personalizada
expressHooks.extendExpressMethod('use', (originalUse) => {
  return function(path, ...middlewares) {
    // Lógica personalizada antes de llamar al método original
    console.log(`Registrando middleware para la ruta: ${path}`);
    
    // Llama al método original
    return originalUse.call(this, path, ...middlewares);
  };
});
```

### Compatibilidad de Versiones
La versión actual de Express-Hooked sigue la semántica de versionado. Los cambios importantes se documentarán en el registro de cambios.

## Casos de Uso

- **Autenticación y Autorización**: Integra hooks en el procesamiento de solicitudes para validar credenciales
- **Registro y Análisis**: Realiza seguimiento de solicitudes, respuestas y métricas de rendimiento
- **Caché**: Implementa estrategias de caché en diferentes niveles
- **Transformación de API**: Modifica respuestas de API antes de enviarlas a los clientes
- **Manejo de Errores**: Manejo centralizado de errores con lógica personalizada
- **Límites de Velocidad**: Implementa límites de velocidad basados en criterios personalizados

## Contribuciones

¡Agradecemos las contribuciones! Por favor, consulta nuestras pautas de contribución para obtener más información.

## Licencia

Apache 2.0

Repositorio: https://gitlab.com/bytedogssyndicate1/express-hooked