jerkjs 2.5.6 → 2.6.1

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/doc-2.5/MANUAL_MODULOS_ADMIN.md

@@ -0,0 +1,287 @@
+# Manual de Uso: Módulos de Administración de JERK Framework
+
+## Descripción General
+
+Este manual describe el uso de los módulos de administración interactivos para crear controladores y gestionar rutas en JERK Framework.
+
+## Módulo de Generación de Controladores
+
+### Descripción
+El módulo de generación de controladores permite crear nuevos controladores de manera interactiva con una interfaz paso a paso.
+
+### Comandos Disponibles
+- `generate-controller`
+- `gen-ctrl`
+- `new-ctrl`
+
+### Cómo Usar el Módulo
+
+1. **Iniciar el proceso**
+   ```
+   > generate-controller
+   ```
+
+2. **Nombre del controlador**
+   - Ingresa el nombre base del controlador (sin la palabra "Controller")
+   - Ejemplo: "User", "Product", "Home"
+
+3. **Selección de métodos**
+   - Selecciona los métodos que deseas incluir:
+     - 1. index - Método para mostrar lista de elementos
+     - 2. show - Método para mostrar un elemento específico
+     - 3. create - Método para crear un nuevo elemento
+     - 4. update - Método para actualizar un elemento
+     - 5. delete - Método para eliminar un elemento
+     - 6. All - Todos los métodos anteriores
+   - Opciones de entrada:
+     - Números separados por comas: "1,2,3"
+     - Nombres de métodos: "index,show,create"
+     - "All" para todos los métodos
+
+4. **Ruta del archivo**
+   - Indica la ruta donde crear el archivo del controlador
+   - Deja vacío para usar "./controllers/" por defecto
+   - Ejemplo: "./controllers/", "./src/controllers/"
+
+5. **Confirmación**
+   - Se mostrará una vista previa del código generado
+   - Confirma con "sí" para crear el archivo o "no" para cancelar
+
+### Ejemplo Completo
+```
+> generate-controller
+=== Generador de Controladores ===
+Por favor, introduce el nombre del controlador (sin la palabra "Controller"):
+> User
+
+Selecciona los métodos que deseas incluir (separados por comas):
+> 1,2,3
+
+Indica la ruta donde deseas crear el archivo del controlador:
+> 
+
+=== Vista Previa del Controlador ===
+[... código del controlador ...]
+¿Deseas crear este controlador? (sí/no):
+> sí
+
+✅ Controlador "UserController" creado exitosamente en: ./controllers/UserController.js
+```
+
+## Módulo de Gestión de Rutas
+
+### Descripción
+El módulo de gestión de rutas permite crear nuevas rutas, deshabilitar rutas existentes y ver rutas registradas o activas.
+
+### Comandos Disponibles
+- `manage-routes`
+- `route-manager`
+- `route-mgmt`
+
+## Módulo de Cache de Rutas
+
+### Descripción
+El módulo de cache de rutas permite monitorear y gestionar el cache de rutas del sistema, incluyendo visualización de estadísticas, contenido del cache, y limpieza del cache.
+
+### Comandos Disponibles
+- `route-cache`
+- `cache-stats`
+- `cache-view`
+- `cache-dynamic`
+- `cache-static`
+- `cache-clear`
+
+### Cómo Usar el Módulo
+
+1. **Ver estadísticas del cache**
+   ```
+   > route-cache
+   ```
+
+2. **Ver contenido completo del cache**
+   ```
+   > cache-view
+   ```
+
+3. **Ver solo rutas dinámicas (parametrizadas)**
+   ```
+   > cache-dynamic
+   ```
+
+4. **Ver solo rutas estáticas (exactas)**
+   ```
+   > cache-static
+   ```
+
+5. **Limpiar el cache de rutas**
+   ```
+   > cache-clear
+   ```
+
+### Ejemplo de Uso
+```
+> route-cache
+=== Estadísticas del Cache de Rutas ===
+Rutas dinámicas (parametrizadas) en cache: 5
+Rutas estáticas exactas en cache: 10
+Tamaño total de índices: 15
+Índices válidos: Sí
+
+> cache-dynamic
+=== Cache de Rutas Dinámicas (Parametrizadas) ===
+1. Ruta: /users/:id
+   Regex: /^\/users\/([^\/]+?)$/
+
+Total: 1 rutas dinámicas en cache.
+
+> cache-clear
+=== Limpieza del Cache de Rutas ===
+Rutas dinámicas eliminadas: 5
+Rutas estáticas eliminadas: 10
+Cache de rutas limpiado exitosamente.
+```
+
+### Cómo Usar el Módulo
+
+1. **Iniciar el proceso**
+   ```
+   > route-mgmt
+   ```
+
+2. **Menú Principal**
+   El sistema mostrará las opciones disponibles:
+   - 1. Crear nueva ruta
+   - 2. Deshabilitar ruta existente
+   - 3. Ver rutas registradas
+   - 4. Ver rutas activas
+
+### Opción 1: Crear Nueva Ruta
+
+1. **Selecciona el método HTTP**
+   - 1. GET
+   - 2. POST
+   - 3. PUT
+   - 4. DELETE
+   - 5. PATCH
+   - 6. Otro
+   - O ingresa el método directamente (GET, POST, etc.)
+
+2. **Introduce la ruta**
+   - Ejemplo: "/api/users", "/users/:id"
+
+3. **Ruta al archivo del controlador**
+   - Ejemplo: "./controllers/UserController.js"
+
+4. **Nombre del handler**
+   - Nombre del método en el controlador
+   - Ejemplo: "index", "show", "create"
+
+5. **Confirmación**
+   - Se mostrará una vista previa de la entrada para routes.json
+   - Confirma con "sí" para crear la ruta o "no" para cancelar
+
+### Opción 2: Deshabilitar Ruta Existente
+
+1. **Selecciona la ruta**
+   - El sistema mostrará una lista numerada de rutas registradas
+   - Ingresa el número de la ruta que deseas deshabilitar
+
+2. **Confirmación**
+   - Se mostrará la ruta seleccionada
+   - Confirma con "sí" para deshabilitar la ruta o "no" para cancelar
+
+### Opción 3: Ver Rutas Registradas
+
+- Muestra todas las rutas registradas en el sistema
+- Formato: Número. Método HTTP Ruta
+
+### Opción 4: Ver Rutas Activas
+
+- Muestra las rutas que han recibido solicitudes recientemente
+- Formato: Método HTTP Ruta - Fecha y hora de la última solicitud
+
+### Ejemplo de Creación de Ruta
+```
+> route-mgmt
+=== Gestión de Rutas ===
+¿Qué deseas hacer?
+1. Crear nueva ruta
+2. Deshabilitar ruta existente
+3. Ver rutas registradas
+4. Ver rutas activas
+> 1
+
+=== Crear Nueva Ruta ===
+Selecciona el método HTTP:
+1. GET
+2. POST
+3. PUT
+4. DELETE
+5. PATCH
+6. Otro
+> GET
+
+Método seleccionado: GET
+Introduce la ruta (ej: /api/users, /users/:id):
+> /api/demo
+
+Ruta: /api/demo
+Introduce la ruta al archivo del controlador (ej: ./controllers/UserController.js):
+> ./controllers/DemoController.js
+
+Introduce el nombre del handler (método del controlador):
+> index
+
+=== Vista Previa de la Ruta ===
+Método: GET
+Ruta: /api/demo
+Controlador: ./controllers/DemoController.js
+Handler: index
+
+Entrada para routes.json:
+{
+  "path": "/api/demo",
+  "method": "GET",
+  "controller": "./controllers/DemoController.js",
+  "handler": "index",
+  "contentType": "application/json"
+}
+
+¿Deseas crear esta ruta? (sí/no):
+> sí
+
+✅ Ruta "GET /api/demo" creada exitosamente.
+```
+
+## Consejos de Uso
+
+### Para Controladores
+- Usa nombres descriptivos para tus controladores
+- Considera qué métodos necesitas antes de crear el controlador
+- Elige rutas de archivo que sigan la estructura de tu proyecto
+
+### Para Rutas
+- Asegúrate de que el controlador y el handler existan antes de crear la ruta
+- Usa rutas RESTful cuando sea posible
+- Considera el método HTTP adecuado para cada operación
+
+## Errores Comunes y Soluciones
+
+### Controlador
+- **Nombre inválido**: Asegúrate de usar solo letras, números y guiones bajos
+- **Ruta de archivo no encontrada**: Verifica que la ruta sea correcta
+
+### Rutas
+- **Ruta duplicada**: El sistema no impide rutas duplicadas
+- **Controlador o handler no encontrado**: Verifica que existan antes de crear la ruta
+- **Método HTTP inválido**: Usa métodos estándar (GET, POST, PUT, DELETE, PATCH)
+
+## Comandos Generales
+
+- `help`: Muestra la ayuda general
+- `quit` o `exit`: Cierra la conexión
+- `cancel`: Cancela el proceso interactivo actual
+
+## Soporte
+
+Para soporte adicional, consulta la documentación del framework o contacta al equipo de desarrollo.