jerkjs 2.5.6 → 2.5.8

package/doc-2.5/ADMIN_EXTENSION_INTEGRATION_MANUAL.md

@@ -0,0 +1,232 @@
+# Manual de Integración de la Extensión de Administración
+
+## Introducción
+
+Este manual explica cómo integrar la extensión de administración de JERK Framework en tus proyectos. La extensión proporciona un servidor TCP de administración que permite monitorear y gestionar tu aplicación en tiempo real.
+
+## Características
+
+- **Servidor TCP de administración**: Accesible solo desde localhost por seguridad
+- **Monitoreo en tiempo real**: Visualización de rutas registradas y activas
+- **Sistema de módulos extensible**: Arquitectura para añadir nuevas funcionalidades
+- **Integración con hooks**: Sistema de extensibilidad basado en el sistema de hooks del framework
+- **Puerto configurable**: Por defecto en el puerto 9999
+
+## Requisitos Previos
+
+- JERK Framework v2.5.8 o superior
+- Node.js 14.0.0 o superior
+- Acceso a la instancia del servidor APIServer
+
+## Instalación
+
+La extensión de administración ya viene incluida en JERK Framework v2.5.8+, por lo que no requiere instalación adicional.
+
+## Integración Básica
+
+### Método 1: Inicialización Directa
+
+```javascript
+const { APIServer } = require('jerkjs');
+
+const server = new APIServer({ port: 3000 });
+
+// Inicializar la extensión de administración
+server.initializeAdminExtension({
+  port: 9999,
+  host: '127.0.0.1'  // Solo localhost (recomendado)
+});
+
+server.start();
+```
+
+### Método 2: Con Opciones Personalizadas
+
+```javascript
+const { APIServer } = require('jerkjs');
+
+const server = new APIServer({ 
+  port: 3000,
+  host: 'localhost'
+});
+
+// Inicializar con opciones personalizadas
+server.initializeAdminExtension({
+  port: 9999,           // Puerto personalizado (por defecto: 9999)
+  host: '127.0.0.1'    // Host personalizado (por defecto: '127.0.0.1')
+});
+
+server.start();
+```
+
+## Integración con Carga de Rutas
+
+### Recomendado: Después de Cargar Rutas
+
+Para asegurar que la extensión capture todas las rutas registradas, es recomendable inicializarla después de cargar las rutas:
+
+```javascript
+const { 
+  APIServer, 
+  RouteDirectoryLoader,
+  ViewEngine,
+  ModelManager 
+} = require('jerkjs');
+
+const server = new APIServer({ port: 3000 });
+
+// Configurar otros componentes
+const viewEngine = new ViewEngine({ viewsDir: './views' });
+const modelManager = new ModelManager();
+server.viewEngine = viewEngine;
+server.modelManager = modelManager;
+
+// Cargar rutas desde directorio
+const routeDirectoryLoader = new RouteDirectoryLoader();
+routeDirectoryLoader.loadRoutesFromDirectory(server, './routes')
+    .then(routes => {
+        console.log(`${routes.length} rutas cargadas exitosamente`);
+
+        // Inicializar la extensión de administración DESPUÉS de cargar rutas
+        server.initializeAdminExtension({
+          port: 9999,
+          host: '127.0.0.1'
+        });
+
+        // Iniciar el servidor
+        server.start();
+    })
+    .catch(error => {
+        console.error('Error cargando rutas:', error.message);
+    });
+```
+
+## Integración en Diferentes Puntos del Ciclo de Vida
+
+### Durante la Configuración del Servidor
+
+```javascript
+const { APIServer, SessionManager } = require('jerkjs');
+
+const server = new APIServer({ port: 3000 });
+
+// Configurar sesión
+const sessionManager = new SessionManager();
+server.use(sessionManager.middleware());
+
+// Inicializar extensión de administración en cualquier punto
+server.initializeAdminExtension({
+  port: 9999,
+  host: '127.0.0.1'
+});
+
+server.start();
+```
+
+### Usando el Hook de Inicialización de Extensiones (Recomendado)
+
+Para garantizar que la extensión se inicialice después de que todas las rutas hayan sido completamente cargadas y el servidor esté operativo, puedes usar el hook `admin_extensions_initialize`:
+
+```javascript
+const { hooks } = require('jerkjs');
+
+// Registrar un listener para el hook de inicialización de extensiones
+hooks.addAction('admin_extensions_initialize', (server) => {
+  // Inicializar la extensión de administración después de que el servidor esté completamente iniciado
+  server.initializeAdminExtension({
+    port: 9999,
+    host: '127.0.0.1'
+  });
+});
+```
+
+Este enfoque garantiza que la extensión de administración se inicialice en el momento óptimo del ciclo de vida del servidor, después de que todas las rutas hayan sido cargadas y el servidor esté completamente operativo.
+
+### En Middleware o Controladores
+
+La extensión se puede inicializar en cualquier momento, incluso en middleware o controladores, aunque no es recomendable:
+
+```javascript
+// En un archivo de middleware
+function initializeAdminIfNotExists(req, res, next) {
+  if (!req.server.adminExtension) {
+    req.server.initializeAdminExtension({
+      port: 9999,
+      host: '127.0.0.1'
+    });
+  }
+  next();
+}
+```
+
+## Comandos Disponibles
+
+Una vez iniciada la extensión, puedes conectarte usando telnet o nc:
+
+```bash
+telnet localhost 9999
+# o
+nc localhost 9999
+```
+
+### Comandos del Módulo de Rutas:
+- `routes` - Muestra las rutas registradas
+- `active` - Muestra las rutas activas (solicitudes recientes)
+
+### Comandos del Módulo de Sistema:
+- `version` - Muestra la versión del framework
+- `status` - Muestra el estado del servidor
+- `help` - Muestra la ayuda
+
+### Comandos Generales:
+- `help` - Muestra la ayuda general
+- `quit` - Cierra la conexión
+
+## Seguridad
+
+- El servidor de administración solo escucha en localhost (127.0.0.1) por defecto
+- No es accesible desde fuera de la máquina local
+- Se recomienda mantener el puerto 9999 (o el puerto elegido) detrás del firewall
+- No enviar información sensible a través de la conexión de administración
+
+## Configuración Avanzada
+
+### Puerto Personalizado
+
+```javascript
+server.initializeAdminExtension({
+  port: 8888,  // Puerto personalizado
+  host: '127.0.0.1'
+});
+```
+
+### Múltiples Instancias (No Recomendado)
+
+Aunque técnicamente posible, no se recomienda inicializar múltiples extensiones de administración en el mismo servidor.
+
+## Troubleshooting
+
+### El comando `routes` no muestra rutas
+- Asegúrate de que la extensión se inicialice después de cargar las rutas
+- Verifica que las rutas se hayan registrado correctamente
+
+### No puedo conectarme al puerto
+- Verifica que el puerto esté disponible
+- Asegúrate de que el firewall no esté bloqueando la conexión
+- Confirma que la extensión se haya inicializado correctamente
+
+### Comandos no reconocidos
+- Asegúrate de estar usando la versión correcta de JERK Framework
+- Verifica que la extensión se haya inicializado correctamente
+
+## Buenas Prácticas
+
+1. **Inicializar después de cargar rutas**: Para capturar todas las rutas registradas
+2. **Usar localhost**: Siempre usar 127.0.0.1 como host para seguridad
+3. **Puerto dedicado**: Usar un puerto diferente al del servidor web principal
+4. **Entornos de desarrollo**: Adecuado para entornos de desarrollo y pruebas
+5. **No en producción**: No se recomienda usar en entornos de producción sin medidas de seguridad adicionales
+
+## Conclusión
+
+La extensión de administración se integra de forma transparente en JERK Framework y proporciona herramientas poderosas para monitorear y gestionar tu aplicación. La integración es simple y flexible, permitiendo inicializarla en cualquier punto del ciclo de vida del servidor.

package/doc-2.5/CACHE_SYSTEM_MAP.md

@@ -0,0 +1,206 @@
+# Mapa de Procesos de Caché del Framework JERK
+
+## Introducción
+
+Este documento describe los diferentes sistemas de caché implementados en el framework JERK y cómo se integran en los flujos del sistema.
+
+## Sistemas de Caché
+
+### 1. Caché de Expresiones Regulares para Rutas (RouteMatcher)
+
+**Ubicación**: `lib/router/RouteMatcher.js`
+**Tipo**: Mapa de caché (Map)
+**Propósito**: Almacenar expresiones regulares compiladas para rutas parametrizadas
+**Clave**: Ruta con parámetros (ej. `/users/:id`)
+**Valor**: Expresión regular compilada
+**Flujo de proceso**:
+1. Al procesar una ruta parametrizada, se convierte a expresión regular
+2. Antes de compilar, se verifica si ya existe en el cache
+3. Si existe, se devuelve la expresión regular cacheada
+4. Si no existe, se compila, se almacena en cache y se devuelve
+
+**Beneficios**:
+- Evita compilación repetida de expresiones regulares
+- Mejora el rendimiento de coincidencia de rutas parametrizadas
+- Reduce el uso de CPU en operaciones repetidas
+
+### 2. Caché de Vistas (ViewEngine)
+
+**Ubicación**: `lib/mvc/viewEngine.js`
+**Tipo**: Mapa de caché (Map)
+**Propósito**: Almacenar contenido de vistas ya procesadas (sin variables)
+**Clave**: Ruta completa del archivo de vista
+**Valor**: Contenido de la vista procesado (condiciones, bucles, etc. resueltos)
+**Flujo de proceso**:
+1. Al solicitar una vista, se verifica si está en cache
+2. Si está en cache, se procesa con las variables y se devuelve
+3. Si no está en cache, se lee el archivo, se procesa (condiciones, bucles, etc.)
+4. Si el cache está habilitado, se almacena la vista procesada (sin variables)
+5. Se procesan las variables y se devuelve el resultado
+
+**Beneficios**:
+- Evita lectura repetida de archivos de vistas
+- Evita procesamiento repetido de condiciones y bucles
+- Mejora el rendimiento de renderizado de vistas
+
+### 3. Caché de Controladores (ControllerLoader)
+
+**Ubicación**: `lib/loader/controllerLoader.js`
+**Tipo**: Sistema de caché de módulos de Node.js
+**Propósito**: Evitar recarga repetida de módulos de controladores
+**Clave**: Ruta del archivo del controlador
+**Valor**: Instancia del módulo del controlador
+**Flujo de proceso**:
+1. Al cargar un controlador, se verifica si ya está en el cache de require
+2. Si no está en cache, se carga y se mantiene en require.cache
+3. En subsiguientes solicitudes, se devuelve la instancia cacheada
+
+**Beneficios**:
+- Evita recarga repetida de módulos
+- Mejora el rendimiento de carga de controladores
+- Reduce el uso de memoria
+
+### 4. Índices de Rutas (RouteMatcher)
+
+**Ubicación**: `lib/router/RouteMatcher.js`
+**Tipo**: Mapas de índices y estructuras de datos
+**Propósito**: Optimizar la búsqueda de rutas mediante pre-filtrado
+**Componentes**:
+- `exactRoutes`: Mapa de rutas exactas por método y path
+- `routeBuckets`: Estructura jerárquica por método, número de segmentos y primer segmento
+- `indexesValid`: Bandera para validar si los índices están actualizados
+
+**Flujo de proceso**:
+1. Al registrar rutas, se actualizan los índices
+2. Al buscar una ruta, se usan los índices para pre-filtrar candidatos
+3. Se buscan coincidencias exactas primero (más rápido)
+4. Se buscan rutas parametrizadas solo entre candidatos filtrados
+5. Se buscan rutas estáticas por prefijo entre candidatos filtrados
+
+**Beneficios**:
+- Reduce drásticamente el número de rutas a evaluar
+- Mejora el rendimiento de coincidencia de rutas
+- Escala mejor con un gran número de rutas
+
+## Flujos de Integración de Caché
+
+### Flujo de Procesamiento de Solicitudes
+
+```
+Solicitud HTTP
+    ↓
+Middleware de seguridad
+    ↓
+Verificación de índices de rutas (RouteMatcher)
+    ↓
+→ Búsqueda por ruta exacta (más rápida)
+    ↓
+→ Pre-filtrado por número de segmentos y primer segmento
+    ↓
+→ Búsqueda en rutas candidatas
+    ↓
+→ Coincidencia con expresiones regulares (usando cache)
+    ↓
+Ejecución del handler de la ruta
+    ↓
+Renderizado de vista (usando cache de vistas)
+    ↓
+Respuesta HTTP
+```
+
+### Flujo de Caché de Expresiones Regulares
+
+```
+Solicitud de coincidencia de ruta parametrizada
+    ↓
+→ ¿Está la expresión regular en cache?
+    ↓
+┌─────────────┬─────────────┐
+│     SÍ      │     NO      │
+│             │             │
+│ Devolver    │ Compilar    │
+│ regex       │ expresión   │
+│ cacheada    │ regular     │
+│             │             │
+└─────────────┴─────────────┘
+    ↓
+Almacenar en cache
+    ↓
+Usar para coincidencia
+```
+
+### Flujo de Caché de Vistas
+
+```
+Solicitud de renderizado de vista
+    ↓
+→ ¿Está la vista en cache?
+    ↓
+┌─────────────┬─────────────┐
+│     SÍ      │     NO      │
+│             │             │
+│ Procesar    │ Leer archivo│
+│ con vars    │ de vista    │
+│             │             │
+│ Devolver    │ Procesar    │
+│ resultado   │ condiciónes,│
+│             │ bucles, etc.│
+│             │             │
+│             │ → ¿Cache    │
+│             │   habilitado?│
+│             │      ↓      │
+│             │   ┌─────────┼─┐
+│             │   │   SÍ    │ │
+│             │   │         │ │
+│             │   │ Almacenar││
+│             │   │ vista en ││
+│             │   │ cache    ││
+│             │   └─────────┼─┘
+│             │             │
+└─────────────┴─────────────┘
+    ↓
+Devolver HTML renderizado
+```
+
+## Estrategias de Invalidación de Caché
+
+### Caché de Expresiones Regulares
+- No requiere invalidación frecuente
+- Se actualiza automáticamente al cambiar las rutas
+
+### Caché de Vistas
+- Se puede limpiar manualmente con `viewEngine.clearCache()`
+- No se invalida automáticamente (diseñado para vistas estáticas)
+
+### Caché de Controladores
+- Se mantiene durante todo el ciclo de vida del proceso
+- Se puede limpiar manualmente eliminando del `require.cache`
+
+### Índices de Rutas
+- Se actualizan automáticamente al registrar nuevas rutas
+- Se invalidan si cambia el número total de rutas
+
+## Beneficios del Sistema de Caché
+
+1. **Mejora de Rendimiento**: Reducción significativa de operaciones repetidas
+2. **Eficiencia de CPU**: Menos compilación de expresiones regulares y procesamiento de vistas
+3. **Eficiencia de I/O**: Menos lecturas de disco para archivos de vistas
+4. **Escalabilidad**: Mejor manejo de alto volumen de solicitudes
+5. **Optimización de Memoria**: Reutilización de estructuras de datos ya procesadas
+
+## Consideraciones de Seguridad
+
+- Las cachés no almacenan datos sensibles de usuarios
+- Las expresiones regulares cacheadas no contienen información de entrada del usuario
+- Las vistas cacheadas no contienen datos de sesión o variables de usuario
+- El sistema de caché no expone información interna del sistema
+
+## Conclusión
+
+El framework JERK implementa múltiples niveles de caché para optimizar el rendimiento:
+- Caché de expresiones regulares para rutas parametrizadas
+- Caché de vistas procesadas
+- Índices optimizados para búsqueda de rutas
+- Caché de módulos de controladores
+
+Estos sistemas de caché trabajan juntos para proporcionar un rendimiento óptimo al minimizar operaciones repetidas y maximizar la eficiencia del procesamiento de solicitudes.

package/docs/CACHE_SYSTEM_MAP.md

@@ -0,0 +1,206 @@
+# Mapa de Procesos de Caché del Framework JERK
+
+## Introducción
+
+Este documento describe los diferentes sistemas de caché implementados en el framework JERK y cómo se integran en los flujos del sistema.
+
+## Sistemas de Caché
+
+### 1. Caché de Expresiones Regulares para Rutas (RouteMatcher)
+
+**Ubicación**: `lib/router/RouteMatcher.js`
+**Tipo**: Mapa de caché (Map)
+**Propósito**: Almacenar expresiones regulares compiladas para rutas parametrizadas
+**Clave**: Ruta con parámetros (ej. `/users/:id`)
+**Valor**: Expresión regular compilada
+**Flujo de proceso**:
+1. Al procesar una ruta parametrizada, se convierte a expresión regular
+2. Antes de compilar, se verifica si ya existe en el cache
+3. Si existe, se devuelve la expresión regular cacheada
+4. Si no existe, se compila, se almacena en cache y se devuelve
+
+**Beneficios**:
+- Evita compilación repetida de expresiones regulares
+- Mejora el rendimiento de coincidencia de rutas parametrizadas
+- Reduce el uso de CPU en operaciones repetidas
+
+### 2. Caché de Vistas (ViewEngine)
+
+**Ubicación**: `lib/mvc/viewEngine.js`
+**Tipo**: Mapa de caché (Map)
+**Propósito**: Almacenar contenido de vistas ya procesadas (sin variables)
+**Clave**: Ruta completa del archivo de vista
+**Valor**: Contenido de la vista procesado (condiciones, bucles, etc. resueltos)
+**Flujo de proceso**:
+1. Al solicitar una vista, se verifica si está en cache
+2. Si está en cache, se procesa con las variables y se devuelve
+3. Si no está en cache, se lee el archivo, se procesa (condiciones, bucles, etc.)
+4. Si el cache está habilitado, se almacena la vista procesada (sin variables)
+5. Se procesan las variables y se devuelve el resultado
+
+**Beneficios**:
+- Evita lectura repetida de archivos de vistas
+- Evita procesamiento repetido de condiciones y bucles
+- Mejora el rendimiento de renderizado de vistas
+
+### 3. Caché de Controladores (ControllerLoader)
+
+**Ubicación**: `lib/loader/controllerLoader.js`
+**Tipo**: Sistema de caché de módulos de Node.js
+**Propósito**: Evitar recarga repetida de módulos de controladores
+**Clave**: Ruta del archivo del controlador
+**Valor**: Instancia del módulo del controlador
+**Flujo de proceso**:
+1. Al cargar un controlador, se verifica si ya está en el cache de require
+2. Si no está en cache, se carga y se mantiene en require.cache
+3. En subsiguientes solicitudes, se devuelve la instancia cacheada
+
+**Beneficios**:
+- Evita recarga repetida de módulos
+- Mejora el rendimiento de carga de controladores
+- Reduce el uso de memoria
+
+### 4. Índices de Rutas (RouteMatcher)
+
+**Ubicación**: `lib/router/RouteMatcher.js`
+**Tipo**: Mapas de índices y estructuras de datos
+**Propósito**: Optimizar la búsqueda de rutas mediante pre-filtrado
+**Componentes**:
+- `exactRoutes`: Mapa de rutas exactas por método y path
+- `routeBuckets`: Estructura jerárquica por método, número de segmentos y primer segmento
+- `indexesValid`: Bandera para validar si los índices están actualizados
+
+**Flujo de proceso**:
+1. Al registrar rutas, se actualizan los índices
+2. Al buscar una ruta, se usan los índices para pre-filtrar candidatos
+3. Se buscan coincidencias exactas primero (más rápido)
+4. Se buscan rutas parametrizadas solo entre candidatos filtrados
+5. Se buscan rutas estáticas por prefijo entre candidatos filtrados
+
+**Beneficios**:
+- Reduce drásticamente el número de rutas a evaluar
+- Mejora el rendimiento de coincidencia de rutas
+- Escala mejor con un gran número de rutas
+
+## Flujos de Integración de Caché
+
+### Flujo de Procesamiento de Solicitudes
+
+```
+Solicitud HTTP
+    ↓
+Middleware de seguridad
+    ↓
+Verificación de índices de rutas (RouteMatcher)
+    ↓
+→ Búsqueda por ruta exacta (más rápida)
+    ↓
+→ Pre-filtrado por número de segmentos y primer segmento
+    ↓
+→ Búsqueda en rutas candidatas
+    ↓
+→ Coincidencia con expresiones regulares (usando cache)
+    ↓
+Ejecución del handler de la ruta
+    ↓
+Renderizado de vista (usando cache de vistas)
+    ↓
+Respuesta HTTP
+```
+
+### Flujo de Caché de Expresiones Regulares
+
+```
+Solicitud de coincidencia de ruta parametrizada
+    ↓
+→ ¿Está la expresión regular en cache?
+    ↓
+┌─────────────┬─────────────┐
+│     SÍ      │     NO      │
+│             │             │
+│ Devolver    │ Compilar    │
+│ regex       │ expresión   │
+│ cacheada    │ regular     │
+│             │             │
+└─────────────┴─────────────┘
+    ↓
+Almacenar en cache
+    ↓
+Usar para coincidencia
+```
+
+### Flujo de Caché de Vistas
+
+```
+Solicitud de renderizado de vista
+    ↓
+→ ¿Está la vista en cache?
+    ↓
+┌─────────────┬─────────────┐
+│     SÍ      │     NO      │
+│             │             │
+│ Procesar    │ Leer archivo│
+│ con vars    │ de vista    │
+│             │             │
+│ Devolver    │ Procesar    │
+│ resultado   │ condiciónes,│
+│             │ bucles, etc.│
+│             │             │
+│             │ → ¿Cache    │
+│             │   habilitado?│
+│             │      ↓      │
+│             │   ┌─────────┼─┐
+│             │   │   SÍ    │ │
+│             │   │         │ │
+│             │   │ Almacenar││
+│             │   │ vista en ││
+│             │   │ cache    ││
+│             │   └─────────┼─┘
+│             │             │
+└─────────────┴─────────────┘
+    ↓
+Devolver HTML renderizado
+```
+
+## Estrategias de Invalidación de Caché
+
+### Caché de Expresiones Regulares
+- No requiere invalidación frecuente
+- Se actualiza automáticamente al cambiar las rutas
+
+### Caché de Vistas
+- Se puede limpiar manualmente con `viewEngine.clearCache()`
+- No se invalida automáticamente (diseñado para vistas estáticas)
+
+### Caché de Controladores
+- Se mantiene durante todo el ciclo de vida del proceso
+- Se puede limpiar manualmente eliminando del `require.cache`
+
+### Índices de Rutas
+- Se actualizan automáticamente al registrar nuevas rutas
+- Se invalidan si cambia el número total de rutas
+
+## Beneficios del Sistema de Caché
+
+1. **Mejora de Rendimiento**: Reducción significativa de operaciones repetidas
+2. **Eficiencia de CPU**: Menos compilación de expresiones regulares y procesamiento de vistas
+3. **Eficiencia de I/O**: Menos lecturas de disco para archivos de vistas
+4. **Escalabilidad**: Mejor manejo de alto volumen de solicitudes
+5. **Optimización de Memoria**: Reutilización de estructuras de datos ya procesadas
+
+## Consideraciones de Seguridad
+
+- Las cachés no almacenan datos sensibles de usuarios
+- Las expresiones regulares cacheadas no contienen información de entrada del usuario
+- Las vistas cacheadas no contienen datos de sesión o variables de usuario
+- El sistema de caché no expone información interna del sistema
+
+## Conclusión
+
+El framework JERK implementa múltiples niveles de caché para optimizar el rendimiento:
+- Caché de expresiones regulares para rutas parametrizadas
+- Caché de vistas procesadas
+- Índices optimizados para búsqueda de rutas
+- Caché de módulos de controladores
+
+Estos sistemas de caché trabajan juntos para proporcionar un rendimiento óptimo al minimizar operaciones repetidas y maximizar la eficiencia del procesamiento de solicitudes.

package/index.js

@@ -48,6 +48,9 @@ const ModelControllerExample = require('./lib/mvc/ModelControllerExample');
 
 // Componentes de manejo de errores
 const { ErrorHandler, ValidationError, AuthenticationError, DatabaseError } = require('./lib/utils/errorHandler');
+
+// Componentes de caché
+const CacheHooks = require('./lib/cache/CacheHooks');
 // Componentes del QueryBuilder (v2.3.0) - MODIFICADO PARA USAR QBUILDERJS
 const QueryBuilder = require('qbuilderjs');
 // No hay middleware ni hooks ya que se eliminó la implementación interna
@@ -113,7 +116,10 @@ module.exports = {
   ErrorHandler,
   ValidationError,
   AuthenticationError,
-  DatabaseError
+  DatabaseError,
+
+  // Componentes de administración (v2.5.7)
+  AdminExtension: require('./lib/admin/AdminExtension')
 };
 
 // También exportar clases individuales por conveniencia