jerkjs 2.2.0 → 2.3.0

package/docs/JERK_MODELOS_HOWTO.md

@@ -0,0 +1,566 @@
+# Guía de Uso de Modelos en JERK Framework
+
+## Tabla de Contenidos
+1. [Introducción](#introducción)
+2. [Conceptos Básicos](#conceptos-básicos)
+3. [Creación de Modelos](#creación-de-modelos)
+4. [Operaciones CRUD](#operaciones-crud)
+5. [Validación de Datos](#validación-de-datos)
+6. [Comunicación con Controladores](#comunicación-con-controladores)
+7. [Uso de Adaptadores](#uso-de-adaptadores)
+8. [Hooks en Modelos](#hooks-en-modelos)
+9. [Ejemplos Prácticos](#ejemplos-prácticos)
+
+## Introducción
+
+Los modelos en JERK Framework representan la capa de datos de tu aplicación y forman parte integral del patrón MVC (Modelo-Vista-Controlador). Proporcionan una interfaz para interactuar con diferentes fuentes de datos, ya sea memoria, bases de datos SQL o NoSQL.
+
+## Conceptos Básicos
+
+### Componentes Principales
+
+- **ModelBase**: Clase base para todos los modelos
+- **ModelManager**: Gestor centralizado para administrar instancias de modelos
+- **Adaptadores**: Interfaces para diferentes tipos de almacenamiento
+- **Hooks**: Sistema de extensibilidad para modelos
+
+### Características
+
+- Comunicación bidireccional con controladores
+- Soporte para múltiples adaptadores de almacenamiento
+- Validación de datos integrada
+- Sistema de hooks para extensibilidad
+- Integración con el sistema de autenticación y autorización
+
+## Creación de Modelos
+
+### Extender ModelBase
+
+Para crear un modelo personalizado, extiende la clase `ModelBase`:
+
+```javascript
+const ModelBase = require('jerkjs').ModelBase;
+
+class ProductoModel extends ModelBase {
+  constructor(options = {}) {
+    super({
+      ...options,
+      tableName: options.tableName || 'productos'
+    });
+    
+    // Definir campos del modelo
+    this.fields = {
+      id: { type: 'integer', primaryKey: true, autoIncrement: true },
+      nombre: { type: 'string', required: true },
+      descripcion: { type: 'text' },
+      precio: { type: 'decimal', required: true },
+      categoria: { type: 'string' },
+      createdAt: { type: 'datetime', default: 'CURRENT_TIMESTAMP' },
+      updatedAt: { type: 'datetime', default: 'CURRENT_TIMESTAMP' }
+    };
+  }
+  
+  // Métodos personalizados
+  async getProductosPorCategoria(categoria) {
+    return await this.find({ categoria });
+  }
+  
+  async getProductosConPrecioMayor(precioMinimo) {
+    // Implementación personalizada según el adaptador
+    return await this.find({ precio: { $gte: precioMinimo } });
+  }
+}
+```
+
+### Uso de ModelManager
+
+El `ModelManager` te permite administrar tus modelos y sus adaptadores:
+
+```javascript
+const { ModelManager, MemoryAdapter } = require('jerkjs');
+
+// Crear instancia del gestor de modelos
+const modelManager = new ModelManager();
+
+// Registrar un adaptador
+const memoryAdapter = new MemoryAdapter();
+modelManager.registerAdapter('memory', memoryAdapter);
+
+// Crear instancia de modelo
+const productoModel = modelManager.createModel('Producto', {
+  adapterName: 'memory',
+  modelOptions: { tableName: 'productos' }
+});
+```
+
+## Operaciones CRUD
+
+Los modelos proporcionan métodos estándar para operaciones CRUD:
+
+### Crear Registros
+
+```javascript
+// Crear un nuevo registro
+const nuevoProducto = await productoModel.create({
+  nombre: 'Laptop',
+  descripcion: 'Laptop de alta gama',
+  precio: 1200.00,
+  categoria: 'Electrónica'
+});
+```
+
+### Leer Registros
+
+```javascript
+// Encontrar todos los registros
+const productos = await productoModel.find({});
+
+// Encontrar un registro específico
+const producto = await productoModel.findOne({ id: 1 });
+
+// Encontrar con condiciones
+const electronicos = await productoModel.find({ categoria: 'Electrónica' });
+
+// Encontrar con opciones (orden, límites)
+const productosOrdenados = await productoModel.find(
+  { categoria: 'Electrónica' },
+  { orderBy: 'precio DESC', limit: 10 }
+);
+```
+
+### Actualizar Registros
+
+```javascript
+// Actualizar un registro
+const filasAfectadas = await productoModel.update(
+  { id: 1 }, // condiciones
+  { precio: 1100.00 } // datos a actualizar
+);
+
+// Actualizar con validación personalizada
+const resultado = await productoModel.updateUser(
+  { id: 1 },
+  { nombre: 'Laptop Actualizada' }
+);
+```
+
+### Eliminar Registros
+
+```javascript
+// Eliminar registros que coincidan con condiciones
+const filasEliminadas = await productoModel.delete({ categoria: 'Obsoleto' });
+
+// Eliminar un registro específico
+const filasEliminadas = await productoModel.delete({ id: 1 });
+```
+
+## Validación de Datos
+
+Los modelos incluyen un sistema de validación flexible:
+
+### Validación Personalizada
+
+```javascript
+class ProductoModel extends ModelBase {
+  validate(operation, data) {
+    const result = { isValid: true, errors: [] };
+    
+    // Validaciones específicas para creación
+    if (operation === 'create') {
+      if (!data.nombre) {
+        result.isValid = false;
+        result.errors.push('Nombre es requerido');
+      }
+      
+      if (!data.precio || data.precio <= 0) {
+        result.isValid = false;
+        result.errors.push('Precio debe ser positivo');
+      }
+    }
+    
+    // Validaciones para actualización
+    if (operation === 'update') {
+      if (data.hasOwnProperty('nombre') && !data.nombre) {
+        result.isValid = false;
+        result.errors.push('Nombre no puede estar vacío si se proporciona');
+      }
+      
+      if (data.hasOwnProperty('precio') && (data.precio <= 0)) {
+        result.isValid = false;
+        result.errors.push('Precio debe ser positivo');
+      }
+    }
+    
+    return result;
+  }
+}
+```
+
+### Validación Automática
+
+Los modelos realizan validaciones automáticas según las reglas definidas en el método `validate`.
+
+## Comunicación con Controladores
+
+### Registro de Controladores
+
+Los modelos pueden comunicarse con controladores registrándolos:
+
+```javascript
+// En el modelo
+class ProductoModel extends ModelBase {
+  // ...
+  
+  async notifyControllerOnCreate(producto) {
+    // Notificar a todos los controladores registrados
+    for (const controller of this.getControllers()) {
+      if (typeof controller.onProductoCreated === 'function') {
+        controller.onProductoCreated(producto);
+      }
+    }
+  }
+}
+
+// En el controlador
+class ProductoController extends ControllerBase {
+  constructor() {
+    super();
+    
+    // Registrar este controlador con el modelo
+    productoModel.registerController(this);
+  }
+  
+  onProductoCreated(producto) {
+    console.log('Nuevo producto creado:', producto);
+    // Lógica adicional cuando se crea un producto
+  }
+  
+  async crearProducto(req, res) {
+    try {
+      const producto = await productoModel.create(req.body);
+      res.status(201).json({ success: true, data: producto });
+    } catch (error) {
+      res.status(500).json({ success: false, error: error.message });
+    }
+  }
+}
+```
+
+### Comunicación Bidireccional
+
+La comunicación es bidireccional, permitiendo que tanto modelos como controladores se comuniquen entre sí.
+
+## Uso de Adaptadores
+
+### Adaptador de Memoria
+
+Útil para pruebas o aplicaciones pequeñas:
+
+```javascript
+const { MemoryAdapter } = require('jerkjs');
+
+const memoryAdapter = new MemoryAdapter();
+productoModel.setAdapter(memoryAdapter);
+```
+
+### Adaptadores Personalizados
+
+Puedes crear adaptadores personalizados extendiendo `GenericAdapter`:
+
+```javascript
+const { GenericAdapter } = require('jerkjs');
+
+class MiAdaptadorPersonalizado extends GenericAdapter {
+  constructor(options = {}) {
+    super({ ...options, type: 'mi_adaptador' });
+    // Inicializar conexión
+  }
+  
+  async create(tableName, data) {
+    // Implementar lógica de creación
+    return { id: 1, ...data }; // Ejemplo
+  }
+  
+  async find(tableName, conditions, options) {
+    // Implementar lógica de búsqueda
+    return []; // Ejemplo
+  }
+  
+  // Implementar otros métodos...
+}
+```
+
+## Hooks en Modelos
+
+Los modelos pueden participar en el sistema de hooks del framework:
+
+### Hooks Disponibles
+
+- `model_before_create`: Antes de crear un registro
+- `model_after_create`: Después de crear un registro
+- `model_before_find`: Antes de buscar registros
+- `model_after_find`: Después de buscar registros
+- `model_before_update`: Antes de actualizar registros
+- `model_after_update`: Después de actualizar registros
+- `model_before_delete`: Antes de eliminar registros
+- `model_after_delete`: Después de eliminar registros
+
+### Uso de Hooks
+
+```javascript
+// Registrar un hook
+hooks.addAction('model_after_create', (result, modelName) => {
+  console.log(`Registro creado en modelo ${modelName}:`, result);
+});
+
+// Filtrar datos antes de crear
+hooks.addFilter('model_before_create', (data, modelName) => {
+  // Agregar marca de tiempo
+  return {
+    ...data,
+    createdAt: new Date(),
+    updatedAt: new Date()
+  };
+});
+```
+
+## Ejemplos Prácticos
+
+### Ejemplo Completo de Modelo de Usuario
+
+```javascript
+const { ModelBase } = require('jerkjs');
+
+class UsuarioModel extends ModelBase {
+  constructor(options = {}) {
+    super({
+      ...options,
+      tableName: options.tableName || 'usuarios'
+    });
+    
+    this.fields = {
+      id: { type: 'integer', primaryKey: true, autoIncrement: true },
+      username: { type: 'string', required: true, unique: true },
+      email: { type: 'string', required: true, unique: true },
+      password: { type: 'string', required: true },
+      rol: { type: 'string', default: 'usuario' },
+      activo: { type: 'boolean', default: true },
+      createdAt: { type: 'datetime', default: 'CURRENT_TIMESTAMP' },
+      updatedAt: { type: 'datetime', default: 'CURRENT_TIMESTAMP' }
+    };
+  }
+  
+  validate(operation, data) {
+    const result = { isValid: true, errors: [] };
+    
+    if (operation === 'create' || operation === 'update') {
+      if (operation === 'create' && !data.username) {
+        result.isValid = false;
+        result.errors.push('Username es requerido');
+      }
+      
+      if (operation === 'create' && !data.email) {
+        result.isValid = false;
+        result.errors.push('Email es requerido');
+      }
+      
+      if (operation === 'create' && !data.password) {
+        result.isValid = false;
+        result.errors.push('Password es requerido');
+      }
+      
+      // Validar formato de email
+      if (data.email && !this.isValidEmail(data.email)) {
+        result.isValid = false;
+        result.errors.push('Formato de email inválido');
+      }
+    }
+    
+    return result;
+  }
+  
+  isValidEmail(email) {
+    const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+    return emailRegex.test(email);
+  }
+  
+  async findByUsername(username) {
+    return await this.findOne({ username });
+  }
+  
+  async findByEmail(email) {
+    return await this.findOne({ email });
+  }
+  
+  async crearUsuario(datos) {
+    // Validar datos
+    const validacion = this.validate('create', datos);
+    if (!validacion.isValid) {
+      throw new Error(`Validación fallida: ${validacion.errors.join(', ')}`);
+    }
+    
+    // Encriptar contraseña
+    if (datos.password) {
+      datos.password = await this.encriptarPassword(datos.password);
+    }
+    
+    return await this.create(datos);
+  }
+  
+  async encriptarPassword(password) {
+    const bcrypt = require('bcrypt');
+    const saltRounds = 10;
+    return await bcrypt.hash(password, saltRounds);
+  }
+  
+  async verificarPassword(password, hashedPassword) {
+    const bcrypt = require('bcrypt');
+    return await bcrypt.compare(password, hashedPassword);
+  }
+}
+```
+
+### Uso en un Controlador
+
+```javascript
+const ControllerBase = require('jerkjs').ControllerBase;
+const UsuarioModel = require('./models/UsuarioModel');
+const { ModelManager, MemoryAdapter } = require('jerkjs');
+
+class UsuarioController extends ControllerBase {
+  constructor() {
+    super();
+    
+    // Configurar modelo de usuario
+    this.modelManager = new ModelManager();
+    const memoryAdapter = new MemoryAdapter();
+    this.modelManager.registerAdapter('memory', memoryAdapter);
+    
+    this.usuarioModel = new UsuarioModel({
+      adapter: memoryAdapter,
+      tableName: 'usuarios'
+    });
+    
+    // Registrar este controlador con el modelo
+    this.usuarioModel.registerController(this);
+  }
+  
+  async crearUsuario(req, res) {
+    try {
+      const usuario = await this.usuarioModel.crearUsuario(req.body);
+      res.status(201).json({ success: true, data: usuario });
+    } catch (error) {
+      res.status(400).json({ success: false, error: error.message });
+    }
+  }
+  
+  async obtenerUsuarioPorUsername(req, res) {
+    try {
+      const username = req.params.username;
+      const usuario = await this.usuarioModel.findByUsername(username);
+      
+      if (!usuario) {
+        res.status(404).json({ success: false, error: 'Usuario no encontrado' });
+        return;
+      }
+      
+      res.status(200).json({ success: true, data: usuario });
+    } catch (error) {
+      res.status(500).json({ success: false, error: error.message });
+    }
+  }
+  
+  async listarUsuarios(req, res) {
+    try {
+      const usuarios = await this.usuarioModel.find({});
+      res.status(200).json({ 
+        success: true, 
+        data: usuarios,
+        count: usuarios.length
+      });
+    } catch (error) {
+      res.status(500).json({ success: false, error: error.message });
+    }
+  }
+}
+```
+
+## Uso de Modelos en Controladores con loadModel
+
+JERK Framework proporciona un helper `loadModel` en el ControllerBase para facilitar la carga y uso de modelos en los controladores:
+
+```javascript
+const ControllerBase = require('jerkjs').ControllerBase;
+
+class ProductoController extends ControllerBase {
+  constructor() {
+    super();
+
+    // Cargar el modelo de producto
+    this.productoModel = this.loadModel('ProductoModel', {
+      // Opciones del modelo
+    });
+  }
+
+  async listarProductos(req, res) {
+    try {
+      // Usar el modelo para obtener productos
+      const productos = await this.productoModel.find({});
+
+      res.status(200).json({ success: true, data: productos });
+    } catch (error) {
+      res.status(500).json({ success: false, error: error.message });
+    }
+  }
+
+  async obtenerProductoPorId(req, res) {
+    try {
+      const productId = req.params.id;
+
+      // Usar el modelo para encontrar un producto específico
+      const producto = await this.productoModel.findOne({ id: productId });
+
+      if (!producto) {
+        res.status(404).json({ success: false, error: 'Producto no encontrado' });
+        return;
+      }
+
+      res.status(200).json({ success: true, data: producto });
+    } catch (error) {
+      res.status(500).json({ success: false, error: error.message });
+    }
+  }
+
+  async crearProducto(req, res) {
+    try {
+      // Usar el modelo para crear un nuevo producto
+      const nuevoProducto = await this.productoModel.create(req.body);
+
+      res.status(201).json({ success: true, data: nuevoProducto });
+    } catch (error) {
+      res.status(400).json({ success: false, error: error.message });
+    }
+  }
+}
+
+module.exports = new ProductoController();
+```
+
+### Métodos Disponibles
+
+- `loadModel(modelName, options)`: Carga un modelo para su uso en el controlador
+- `getModel(modelName)`: Obtiene un modelo previamente cargado
+
+### Rutas de Carga de Modelos
+
+El helper `loadModel` busca modelos en las siguientes ubicaciones (en orden):
+
+1. `../../../models/${modelName}` (relativo a la carpeta actual)
+2. `../models/${modelName}` (relativo al controlador)
+3. `../../models/${modelName}` (relativo a la raíz del proyecto)
+
+## Conclusión
+
+Los modelos en JERK Framework proporcionan una capa de abstracción potente y flexible para interactuar con datos. Con soporte para múltiples adaptadores, validación integrada, comunicación bidireccional con controladores y hooks para extensibilidad, los modelos permiten construir aplicaciones robustas y escalables.
+
+La arquitectura modular permite adaptar los modelos a diferentes necesidades de almacenamiento y lógica de negocio, manteniendo al mismo tiempo una interfaz consistente y fácil de usar.