jerkjs 2.0.1 → 2.0.2

package/examples/v2.1_hooks_demo/README.md

@@ -0,0 +1,85 @@
+# Ejemplo de Sistema de Hooks en Framework JERK
+
+Este ejemplo demuestra cómo usar el sistema de hooks como el core de WordPress para extender la funcionalidad del Framework JERK en diferentes puntos del ciclo de vida.
+
+## Características del Sistema de Hooks
+
+- **Acciones (Actions)**: Puntos de extensión donde se pueden ejecutar funciones
+- **Filtros (Filters)**: Puntos donde se pueden modificar datos antes de ser procesados
+- **Extensibilidad**: Capacidad para agregar funcionalidades en múltiples puntos del ciclo de vida
+- **Ciclo de Vida**: Hooks disponibles en diferentes etapas del proceso
+
+## Hooks Disponibles
+
+### Hooks de Servidor
+- `framework_init`: Se ejecuta cuando se inicializa el framework
+- `pre_server_start`: Antes de iniciar el servidor
+- `post_server_start`: Después de iniciar el servidor
+
+### Hooks de Carga de Rutas
+- `pre_route_load`: Antes de cargar rutas desde archivo
+- `post_route_load`: Después de cargar rutas desde archivo
+
+### Hooks de Carga de Controladores
+- `pre_controller_load`: Antes de cargar un controlador
+- `post_controller_load`: Después de cargar un controlador
+
+## Configuración
+
+No se requieren dependencias adicionales más allá del Framework JERK.
+
+## Uso
+
+1. Inicia el servidor:
+   ```bash
+   node app.js
+   ```
+
+2. El servidor escuchará en `http://localhost:8096`
+
+## Endpoints
+
+- `GET /` - Página de inicio con información del sistema de hooks
+- `GET /hooks-info` - Información sobre el sistema de hooks
+
+## Ejemplo de uso de Hooks
+
+```javascript
+const { hooks } = require('jerkjs');
+
+// Registrar una acción
+hooks.addAction('nombre_del_hook', (param1, param2) => {
+  console.log('Hook ejecutado con:', param1, param2);
+});
+
+// Registrar un filtro
+hooks.addFilter('nombre_del_filtro', (valor, parametroAdicional) => {
+  return valor + parametroAdicional;
+});
+
+// Ejecutar una acción
+hooks.doAction('nombre_del_hook', 'dato1', 'dato2');
+
+// Aplicar un filtro
+const resultado = hooks.applyFilters('nombre_del_filtro', 'valorInicial', 'datoAdicional');
+```
+
+## Estructura del proyecto
+
+```
+examples/v2.1_hooks_demo/
+├── app.js              # Punto de entrada de la aplicación con hooks
+├── routes.json         # Definición de rutas
+├── controllers/        # Controladores de las rutas
+│   ├── mainController.js
+│   └── hooksController.js
+└── README.md
+```
+
+## Beneficios del Sistema de Hooks
+
+1. **Extensibilidad**: Permite extender la funcionalidad sin modificar el código base
+2. **Modularidad**: Módulos pueden añadir funcionalidades sin interferir entre sí
+3. **Flexibilidad**: Hooks disponibles en múltiples puntos del ciclo de vida
+4. **Personalización**: Capacidad para modificar comportamientos predeterminados
+5. **Integración**: Fácil integración con sistemas de terceros

package/examples/v2.1_hooks_demo/app.js

@@ -0,0 +1,101 @@
+/**
+ * Ejemplo de uso del sistema de hooks en el Framework JERK
+ * Demostrando extensibilidad en diferentes puntos del ciclo de vida
+ */
+
+const jerk = require('../../index.js');
+const {
+  APIServer,
+  Logger
+} = jerk;
+const RouteLoader = require('../../lib/loader/routeLoader.js');
+const ControllerLoader = require('../../lib/loader/controllerLoader.js');
+const hooks = jerk.hooks;
+
+async function startServer() {
+  // Crear instancia del servidor
+  const server = new APIServer({
+    port: 8096,
+    host: 'localhost'
+  });
+
+  // Crear instancia del logger
+  const logger = new Logger({ level: 'info' });
+
+  try {
+    // Registrar hooks para diferentes eventos del ciclo de vida
+
+    // Hook que se ejecuta cuando se inicializa el framework
+    hooks.addAction('framework_init', () => {
+      logger.info('[[FRAMEWORK]] - El framework ha sido inicializado');
+    });
+
+    // Hook que se ejecuta antes de iniciar el servidor
+    hooks.addAction('pre_server_start', (serverInstance) => {
+      logger.info('[[HOOK]] - Antes de iniciar el servidor');
+      logger.info('[[HOOK]] - Puerto configurado:', serverInstance.port);
+    });
+
+    // Hook que se ejecuta después de iniciar el servidor
+    hooks.addAction('post_server_start', (serverInstance) => {
+      logger.info('[[HOOK]] - Servidor iniciado exitosamente');
+      logger.info('[[HOOK]] - Escuchando en:', `http://${serverInstance.host}:${serverInstance.port}`);
+    });
+
+    // Hook que se ejecuta antes de cargar rutas
+    hooks.addAction('pre_route_load', (filePath, serverInstance) => {
+      logger.info('[[HOOK]] - A punto de cargar rutas desde:', filePath);
+    });
+
+    // Hook que se ejecuta después de cargar rutas
+    hooks.addAction('post_route_load', (routes, serverInstance) => {
+      logger.info('[[HOOK]] - Rutas cargadas exitosamente:', routes.length, 'rutas');
+      routes.forEach((route, index) => {
+        logger.info(`[[HOOK]] - Ruta ${index + 1}: ${route.method} ${route.path}`);
+      });
+    });
+
+    // Hook que se ejecuta antes de cargar un controlador
+    hooks.addAction('pre_controller_load', (controllerPath) => {
+      logger.info('[[HOOK]] - A punto de cargar controlador:', controllerPath);
+    });
+
+    // Hook que se ejecuta después de cargar un controlador
+    hooks.addAction('post_controller_load', (controllerModule, absolutePath) => {
+      logger.info('[[HOOK]] - Controlador cargado exitosamente:', absolutePath);
+      // Podríamos inspeccionar las funciones disponibles en el módulo
+      const availableHandlers = Object.keys(controllerModule).filter(key => 
+        typeof controllerModule[key] === 'function'
+      );
+      logger.info('[[HOOK]] - Handlers disponibles en el controlador:', availableHandlers);
+    });
+
+    // Ejemplo de uso de filtros
+    hooks.addFilter('modify_response_data', (data, endpoint) => {
+      // Añadir información de auditoría a todas las respuestas
+      return {
+        ...data,
+        _hook_processed: true,
+        _timestamp: new Date().toISOString(),
+        _endpoint: endpoint
+      };
+    });
+
+    // Cargar rutas desde archivo JSON
+    const routeLoader = new RouteLoader();
+    await routeLoader.loadRoutes(server, './routes.json');
+
+    // Iniciar el servidor
+    server.start();
+
+    logger.info('Servidor iniciado con sistema de hooks activo');
+  } catch (error) {
+    logger.error('Error iniciando el servidor:', error.message);
+    process.exit(1);
+  }
+}
+
+// Iniciar el servidor
+startServer();
+
+module.exports = { startServer };

package/examples/v2.1_hooks_demo/controllers/hooksController.js

@@ -0,0 +1,29 @@
+const jerk = require('../../../index.js');
+const hooks = jerk.hooks;
+
+const hooksController = {
+  getHooksInfo: (req, res) => {
+    res.writeHead(200, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify({ 
+      message: 'Información sobre el sistema de hooks',
+      hooksSystem: {
+        'actionsRegistradas': hooks.actions ? hooks.actions.size : 0,
+        'filtersRegistrados': hooks.filters ? hooks.filters.size : 0,
+        'accionesDisponibles': [
+          'framework_init',
+          'pre_server_start',
+          'post_server_start',
+          'pre_route_load',
+          'post_route_load',
+          'pre_controller_load',
+          'post_controller_load'
+        ],
+        'ejemploUso': 'hooks.addAction(nombreHook, funcionCallback)',
+        'ejemploFiltro': 'hooks.addFilter(nombreFiltro, funcionCallback)'
+      },
+      timestamp: new Date().toISOString()
+    }));
+  }
+};
+
+module.exports = hooksController;

package/examples/v2.1_hooks_demo/controllers/mainController.js

@@ -0,0 +1,18 @@
+const mainController = {
+  home: (req, res) => {
+    res.writeHead(200, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify({ 
+      message: 'API con sistema de hooks activo',
+      features: [
+        'Pre/Post hooks para carga de rutas',
+        'Pre/Post hooks para carga de controladores',
+        'Pre/Post hooks para inicio de servidor',
+        'Filtros para modificar datos de respuesta',
+        'Extensibilidad en múltiples puntos del ciclo de vida'
+      ],
+      timestamp: new Date().toISOString()
+    }));
+  }
+};
+
+module.exports = mainController;

package/examples/v2.1_hooks_demo/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "jerk-hooks-demo",
+  "version": "1.0.0",
+  "description": "Ejemplo de API con sistema de hooks para extensibilidad usando el Framework JERK",
+  "main": "app.js",
+  "scripts": {
+    "start": "node app.js",
+    "dev": "nodemon app.js"
+  },
+  "keywords": [
+    "api",
+    "sdk",
+    "hooks",
+    "filters",
+    "extensibility",
+    "wordpress",
+    "framework"
+  ],
+  "author": "JERK Framework",
+  "license": "MIT",
+  "dependencies": {
+    "jsonwebtoken": "^9.0.0"
+  },
+  "devDependencies": {
+    "nodemon": "^3.0.0"
+  }
+}

package/examples/v2.1_hooks_demo/routes.json

@@ -0,0 +1,16 @@
+[
+  {
+    "path": "/",
+    "method": "GET",
+    "controller": "./controllers/mainController.js",
+    "handler": "home",
+    "auth": "none"
+  },
+  {
+    "path": "/hooks-info",
+    "method": "GET",
+    "controller": "./controllers/hooksController.js",
+    "handler": "getHooksInfo",
+    "auth": "none"
+  }
+]

package/examples/v2.1_openapi_demo/README.md

@@ -0,0 +1,82 @@
+# Ejemplo API con Funcionalidades OpenAPI (v2.1.0)
+
+Este ejemplo demuestra cómo crear una API con funcionalidades OpenAPI integradas utilizando el Framework JERK.
+
+## Características de OpenAPI
+
+- **Generación automática de documentación OpenAPI 3.0**
+- **Interfaz Swagger UI interactiva**
+- **Definición de esquemas de datos**
+- **Documentación de seguridad y autenticación**
+- **Especificación de endpoints, parámetros y respuestas**
+- **Soporte para diferentes formatos de contenido**
+- **Validación de peticiones y respuestas**
+
+## Configuración
+
+No se requieren dependencias adicionales más allá del Framework JERK.
+
+## Uso
+
+1. Inicia el servidor:
+   ```bash
+   node app.js
+   ```
+
+2. El servidor escuchará en `http://localhost:8096`
+
+## Endpoints
+
+- `GET /` - Página de inicio con información de OpenAPI
+- `POST /login` - Iniciar sesión y obtener token
+- `GET /users` - Lista de usuarios (requiere token)
+- `GET /products` - Lista de productos (requiere token)
+- `GET /docs` - Documentación interactiva OpenAPI/Swagger
+- `GET /openapi.json` - Especificación OpenAPI
+
+## Ejemplo de uso
+
+1. Iniciar sesión:
+   ```bash
+   curl -X POST http://localhost:8096/login \
+     -H "Content-Type: application/json" \
+     -d '{"username": "admin", "password": "password"}'
+   ```
+
+2. Acceder a usuarios con el token:
+   ```bash
+   curl -X GET http://localhost:8096/users \
+     -H "Authorization: Bearer TU_TOKEN_AQUI"
+   ```
+
+3. Ver documentación interactiva:
+   Visita `http://localhost:8096/docs` en tu navegador
+
+4. Obtener especificación OpenAPI:
+   ```bash
+   curl -X GET http://localhost:8096/openapi.json
+   ```
+
+## Estructura del proyecto
+
+```
+examples/v2.1_openapi_demo/
+├── app.js              # Punto de entrada de la aplicación
+├── controllers/        # Controladores de las rutas
+│   ├── mainController.js
+│   ├── authController.js
+│   ├── userController.js
+│   └── productController.js
+└── README.md
+```
+
+## Documentación OpenAPI
+
+El framework genera automáticamente:
+
+- Una especificación OpenAPI 3.0 en `/openapi.json`
+- Una interfaz Swagger UI interactiva en `/docs`
+- Esquemas de datos definidos para reutilización
+- Documentación detallada de endpoints, parámetros y respuestas
+- Soporte para diferentes códigos de respuesta HTTP
+- Definición de esquemas de seguridad

package/examples/v2.1_openapi_demo/app.js

@@ -0,0 +1,296 @@
+/**
+ * Ejemplo de API con funcionalidades OpenAPI (v2.1.0)
+ * Demostrando la generación automática de documentación OpenAPI
+ */
+
+const {
+  APIServer,
+  Authenticator,
+  Logger,
+  OpenApiGenerator
+} = require('../../index.js');
+
+async function startServer() {
+  // Crear instancia del servidor
+  const server = new APIServer({
+    port: 8096,
+    host: 'localhost'
+  });
+
+  // Crear instancia del logger
+  const logger = new Logger({ level: 'info' });
+
+  // Crear instancia del autenticador
+  const authenticator = new Authenticator({ logger });
+
+  // Registrar estrategia de autenticación JWT
+  authenticator.use('jwt-openapi', authenticator.jwtStrategy('super-secret-key-for-openapi-example'));
+
+  try {
+    // Crear instancia del generador de OpenAPI
+    const openApiGenerator = new OpenApiGenerator({
+      title: 'API de Ejemplo con OpenAPI',
+      description: 'API que demuestra la funcionalidad OpenAPI del Framework JERK',
+      version: '2.1.0',
+      servers: [
+        { url: 'http://localhost:8096', description: 'Servidor de desarrollo' }
+      ]
+    });
+
+    // Definir esquemas para la documentación
+    openApiGenerator.addSchema('User', {
+      type: 'object',
+      properties: {
+        id: { type: 'integer', example: 1 },
+        name: { type: 'string', example: 'John Doe' },
+        email: { type: 'string', example: 'john@example.com' },
+        role: { type: 'string', example: 'user' }
+      },
+      required: ['id', 'name', 'email']
+    });
+
+    openApiGenerator.addSchema('Product', {
+      type: 'object',
+      properties: {
+        id: { type: 'integer', example: 1 },
+        name: { type: 'string', example: 'Laptop' },
+        price: { type: 'number', example: 999.99 },
+        category: { type: 'string', example: 'Electronics' }
+      },
+      required: ['id', 'name', 'price']
+    });
+
+    openApiGenerator.addSchema('LoginRequest', {
+      type: 'object',
+      properties: {
+        username: { type: 'string', example: 'admin' },
+        password: { type: 'string', example: 'password' }
+      },
+      required: ['username', 'password']
+    });
+
+    openApiGenerator.addSchema('LoginResponse', {
+      type: 'object',
+      properties: {
+        message: { type: 'string', example: 'Inicio de sesión exitoso' },
+        token: { type: 'string', example: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...' },
+        user: { $ref: '#/components/schemas/User' }
+      }
+    });
+
+    // Agregar rutas a la documentación OpenAPI
+    openApiGenerator.addRoute({
+      path: '/',
+      method: 'GET',
+      config: {
+        summary: 'Página de inicio',
+        description: 'Devuelve información básica sobre la API y sus funcionalidades OpenAPI',
+        responses: {
+          '200': {
+            description: 'Información de la API',
+            content: {
+              'application/json': {
+                schema: {
+                  type: 'object',
+                  properties: {
+                    message: { type: 'string' },
+                    features: { type: 'array', items: { type: 'string' } },
+                    timestamp: { type: 'string', format: 'date-time' }
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    });
+
+    openApiGenerator.addRoute({
+      path: '/login',
+      method: 'POST',
+      config: {
+        summary: 'Iniciar sesión',
+        description: 'Autenticación de usuario y obtención de token JWT',
+        requestBody: {
+          content: {
+            'application/json': {
+              schema: { $ref: '#/components/schemas/LoginRequest' }
+            }
+          }
+        },
+        responses: {
+          '200': {
+            description: 'Inicio de sesión exitoso',
+            content: {
+              'application/json': {
+                schema: { $ref: '#/components/schemas/LoginResponse' }
+              }
+            }
+          },
+          '401': {
+            description: 'Credenciales inválidas'
+          }
+        }
+      }
+    });
+
+    openApiGenerator.addRoute({
+      path: '/users',
+      method: 'GET',
+      config: {
+        summary: 'Obtener usuarios',
+        description: 'Lista de usuarios registrados (requiere autenticación JWT)',
+        security: [{ bearerAuth: [] }],
+        responses: {
+          '200': {
+            description: 'Lista de usuarios',
+            content: {
+              'application/json': {
+                schema: {
+                  type: 'array',
+                  items: { $ref: '#/components/schemas/User' }
+                }
+              }
+            }
+          }
+        }
+      }
+    });
+
+    openApiGenerator.addRoute({
+      path: '/products',
+      method: 'GET',
+      config: {
+        summary: 'Obtener productos',
+        description: 'Lista de productos disponibles (requiere autenticación JWT)',
+        security: [{ bearerAuth: [] }],
+        responses: {
+          '200': {
+            description: 'Lista de productos',
+            content: {
+              'application/json': {
+                schema: {
+                  type: 'array',
+                  items: { $ref: '#/components/schemas/Product' }
+                }
+              }
+            }
+          }
+        }
+      }
+    });
+
+    // Agregar esquema de seguridad
+    openApiGenerator.addSecurityScheme('bearerAuth', {
+      type: 'http',
+      scheme: 'bearer',
+      bearerFormat: 'JWT',
+      description: 'Autenticación por token JWT'
+    });
+
+    // Agregar rutas de documentación al servidor
+    openApiGenerator.addDocumentationRoute(server);
+
+    // Ruta pública
+    server.addRoute('GET', '/', (req, res) => {
+      res.writeHead(200, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ 
+        message: 'API con funcionalidades OpenAPI (v2.1.0)',
+        features: [
+          'Generación automática de documentación OpenAPI 3.0',
+          'Interfaz Swagger UI interactiva',
+          'Esquemas de datos definidos',
+          'Documentación de seguridad',
+          'Especificación de endpoints, parámetros y respuestas'
+        ],
+        timestamp: new Date().toISOString()
+      }));
+    });
+
+    // Ruta de login
+    server.addRoute('POST', '/login', (req, res) => {
+      let body = req.body;
+      
+      // Si body es string, intentar parsear como JSON
+      if (typeof body === 'string') {
+        try {
+          body = JSON.parse(body);
+        } catch (parseError) {
+          res.writeHead(400, { 'Content-Type': 'application/json' });
+          res.end(JSON.stringify({ error: 'Formato de solicitud inválido' }));
+          return;
+        }
+      }
+      
+      const { username, password } = body;
+
+      // Simulación de autenticación
+      if (username === 'admin' && password === 'password') {
+        // Generar token JWT
+        const jwt = require('jsonwebtoken');
+        const token = jwt.sign(
+          { userId: 1, username: username, role: 'admin' },
+          'super-secret-key-for-openapi-example',
+          { expiresIn: '1h' }
+        );
+
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ 
+          message: 'Inicio de sesión exitoso',
+          token: token,
+          user: { userId: 1, username: username, role: 'admin' }
+        }));
+      } else {
+        res.writeHead(401, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ error: 'Credenciales inválidas' }));
+      }
+    });
+
+    // Ruta protegida - Usuarios
+    server.addRoute('GET', '/users', (req, res) => {
+      authenticator.authenticate('jwt-openapi')(req, res, () => {
+        if (req.user) {
+          const users = [
+            { id: 1, name: 'John Doe', email: 'john@example.com', role: 'admin' },
+            { id: 2, name: 'Jane Smith', email: 'jane@example.com', role: 'user' },
+            { id: 3, name: 'Robert Johnson', email: 'robert@example.com', role: 'user' }
+          ];
+
+          res.writeHead(200, { 'Content-Type': 'application/json' });
+          res.end(JSON.stringify(users));
+        }
+      });
+    });
+
+    // Ruta protegida - Productos
+    server.addRoute('GET', '/products', (req, res) => {
+      authenticator.authenticate('jwt-openapi')(req, res, () => {
+        if (req.user) {
+          const products = [
+            { id: 1, name: 'Laptop', price: 999.99, category: 'Electronics' },
+            { id: 2, name: 'Mouse', price: 29.99, category: 'Electronics' },
+            { id: 3, name: 'Keyboard', price: 79.99, category: 'Electronics' }
+          ];
+
+          res.writeHead(200, { 'Content-Type': 'application/json' });
+          res.end(JSON.stringify(products));
+        }
+      });
+    });
+
+    // Iniciar el servidor
+    server.start();
+
+    logger.info('Servidor OpenAPI iniciado en http://localhost:8096');
+    logger.info('Documentación OpenAPI disponible en http://localhost:8096/docs');
+    logger.info('Especificación OpenAPI disponible en http://localhost:8096/openapi.json');
+  } catch (error) {
+    logger.error('Error iniciando el servidor:', error.message);
+    process.exit(1);
+  }
+}
+
+// Iniciar el servidor
+startServer();
+
+module.exports = { startServer };

package/examples/v2.1_openapi_demo/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "jerk-openapi-demo",
+  "version": "1.0.0",
+  "description": "Ejemplo de API con funcionalidades OpenAPI usando el Framework JERK",
+  "main": "app.js",
+  "scripts": {
+    "start": "node app.js",
+    "dev": "nodemon app.js"
+  },
+  "keywords": [
+    "api",
+    "sdk",
+    "openapi",
+    "swagger",
+    "documentation",
+    "framework"
+  ],
+  "author": "JERK Framework",
+  "license": "MIT",
+  "dependencies": {
+    "jsonwebtoken": "^9.0.0"
+  },
+  "devDependencies": {
+    "nodemon": "^3.0.0"
+  }
+}