expressed-core 1.0.0

package/queued/README.es.md

@@ -0,0 +1,335 @@
+# Express-Queued
+
+Express-Queued es un sistema de colas independiente para Express.js que permite la ejecución asíncrona de tareas en múltiples colas concurrentes. Este sistema es ideal para operaciones que consumen tiempo como procesamiento de imágenes, envío de correos electrónicos, procesamiento de pagos, y otras operaciones que no deben bloquear la respuesta inmediata a las solicitudes del usuario.
+
+## Características
+
+- **Soporte para N colas**: Puedes crear tantas colas como necesites, cada una con su propia configuración.
+- **Concurrencia configurable**: Controla cuántas tareas se ejecutan simultáneamente por cola.
+- **Hooks personalizados**: Personaliza la lógica de procesamiento y fallback para cada cola usando el sistema de hooks de [express-hooked](https://www.npmjs.com/package/express-hooked).
+- **Sistema de reintentos**: Manejo automático de fallos con reintentos configurables.
+- **Gestión de prioridades**: Asigna prioridades a las tareas para determinar su orden de ejecución.
+- **Sistema de fallback**: Manejo de tareas que fallan definitivamente.
+- **Totalmente asíncrono**: No bloquea el hilo principal de ejecución.
+- **Integración con Express**: Middleware para inyectar el sistema de colas en las solicitudes de Express.
+
+## Instalación
+
+```bash
+npm install express-queued express-hooked
+```
+
+## Uso Básico
+
+### 1. Importar e inicializar
+
+```javascript
+const express = require('express');
+const ExpressQueueIntegration = require('express-queued');
+
+const app = express();
+const expressQueue = new ExpressQueueIntegration();
+```
+
+### 2. Crear una cola
+
+```javascript
+// Crear una cola con configuración por defecto
+expressQueue.createQueue('procesamiento-general', {
+  concurrency: 2,      // Máximo 2 tareas ejecutándose simultáneamente
+  retryAttempts: 3,    // Reintentar hasta 3 veces si falla
+  retryDelay: 1000     // Esperar 1 segundo entre reintentos
+});
+```
+
+### 3. Definir una tarea
+
+```javascript
+// Función que representa una tarea
+function procesarImagen(datos, taskObj) {
+  return new Promise((resolve, reject) => {
+    // Simular procesamiento
+    setTimeout(() => {
+      console.log(`Procesando imagen:`, datos);
+      resolve('Procesamiento de imagen completado');
+    }, 2000);
+  });
+}
+```
+
+### 4. Agregar tareas a la cola
+
+```javascript
+// Agregar una tarea a la cola
+const taskId = expressQueue.addTask(
+  'procesamiento-general',  // Nombre de la cola
+  procesarImagen,           // Función de la tarea
+  { id: 1, nombre: 'imagen1.jpg' }, // Datos para la tarea
+  0                        // Prioridad (0 es la más alta)
+);
+```
+
+### 5. Iniciar el sistema de colas
+
+```javascript
+// Iniciar la ejecución de tareas
+expressQueue.start();
+```
+
+## Uso con Express
+
+### 1. Agregar el middleware
+
+```javascript
+// Middleware para inyectar el sistema de colas en las solicitudes
+app.use(expressQueue.queueMiddleware());
+```
+
+### 2. Usar el sistema de colas en las rutas
+
+```javascript
+// Ruta para agregar una tarea
+app.post('/procesar-imagen', (req, res) => {
+  const { nombre, tamaño } = req.body;
+
+  const taskId = req.addTask('procesamiento-general', procesarImagen, {
+    nombre,
+    tamaño
+  });
+
+  res.json({ 
+    message: 'Tarea de procesamiento de imagen agregada a la cola',
+    taskId 
+  });
+});
+
+// Ruta para obtener el estado del sistema de colas
+app.get('/estado-colas', (req, res) => {
+  const status = req.getQueueStatus();
+  res.json(status);
+});
+```
+
+## Hooks Personalizados
+
+El sistema de colas se integra con el sistema de hooks de [express-hooked](https://www.npmjs.com/package/express-hooked), lo que permite personalizar el comportamiento del sistema a través de puntos de extensión.
+
+### Hooks Disponibles
+
+- `queue_execute_task`: Se ejecuta antes de procesar una tarea. Permite modificar la lógica de la tarea.
+- `queue_task_completed`: Se ejecuta cuando una tarea se completa exitosamente.
+- `queue_task_failed`: Se ejecuta cuando una tarea falla.
+- `queue_task_retry`: Se ejecuta cuando una tarea se reintenta.
+- `queue_task_fallback`: Se ejecuta cuando una tarea falla definitivamente después de todos los reintentos.
+- `queue_task_added`: Se ejecuta cuando se agrega una tarea a la cola.
+- `queue_system_started`: Se ejecuta cuando se inicia el sistema de colas.
+- `queue_system_stopped`: Se ejecuta cuando se detiene el sistema de colas.
+
+### Ejemplo de hook personalizado
+
+```javascript
+const { HookSystem } = require('express-hooked');
+
+// Crear un sistema de hooks específico para una cola
+const imagenHooks = new HookSystem();
+
+// Hook para personalizar la lógica de procesamiento
+imagenHooks.addAction('queue_execute_task', (task, queueName, taskObj) => {
+  console.log(`Preparando para procesar imagen: ${taskObj.id}`);
+
+  // Envolver la tarea original con lógica adicional
+  const wrappedTask = async (datos, taskObj) => {
+    console.log(`Iniciando procesamiento de imagen: ${taskObj.id}`);
+    try {
+      const result = await task(datos, taskObj);
+      console.log(`Imagen procesada exitosamente: ${taskObj.id}`);
+      return result;
+    } catch (error) {
+      console.log(`Error procesando imagen: ${taskObj.id} - ${error.message}`);
+      throw error;
+    }
+  };
+
+  return wrappedTask;
+});
+
+// Crear la cola con hooks personalizados
+expressQueue.createQueue('imagenes', {
+  concurrency: 3,
+  retryAttempts: 2,
+  retryDelay: 1000
+}, imagenHooks);
+```
+
+## Manejo de Errores y Reintentos
+
+El sistema de colas incluye un mecanismo robusto para manejar errores:
+
+### Configuración de reintentos
+
+```javascript
+expressQueue.createQueue('procesamiento-confiable', {
+  retryAttempts: 5,    // Número máximo de reintentos
+  retryDelay: 2000     // Milisegundos de espera entre reintentos
+});
+```
+
+### Lógica de fallback
+
+Cuando una tarea falla después de todos los reintentos, se ejecuta la lógica de fallback:
+
+```javascript
+const hooks = new HookSystem();
+
+hooks.addAction('queue_task_fallback', (queueName, task, error) => {
+  // Aquí puedes implementar lógica personalizada para manejar tareas fallidas
+  console.log(`Tarea fallida definitivamente:`, task.id);
+  console.log(`Error:`, error.message);
+
+  // Por ejemplo, guardar en una base de datos para procesamiento manual
+  // o enviar una alerta al equipo de soporte
+});
+```
+
+## Uso Avanzado
+
+### Múltiples colas con diferentes configuraciones
+
+```javascript
+// Cola de procesamiento de imágenes
+expressQueue.createQueue('procesamiento-imagenes', {
+  concurrency: 3,
+  retryAttempts: 2,
+  retryDelay: 1000
+});
+
+// Cola de envío de correos
+expressQueue.createQueue('envio-correos', {
+  concurrency: 2,
+  retryAttempts: 3,
+  retryDelay: 2000
+});
+
+// Cola de procesamiento de pagos
+expressQueue.createQueue('procesamiento-pagos', {
+  concurrency: 1,
+  retryAttempts: 5,
+  retryDelay: 3000
+});
+```
+
+### Prioridades de tareas
+
+Las tareas pueden asignarse con diferentes niveles de prioridad:
+
+```javascript
+// Tarea de alta prioridad (prioridad 0)
+expressQueue.addTask('procesamiento-imagenes', procesarImagen, { nombre: 'urgente.jpg' }, 0);
+
+// Tarea de prioridad media (prioridad 5)
+expressQueue.addTask('procesamiento-imagenes', procesarImagen, { nombre: 'normal.jpg' }, 5);
+
+// Tarea de baja prioridad (prioridad 10)
+expressQueue.addTask('procesamiento-imagenes', procesarImagen, { nombre: 'opcional.jpg' }, 10);
+```
+
+### Gestión de colas mediante API
+
+```javascript
+// Pausar una cola
+app.post('/pausar-cola/:queueName', (req, res) => {
+  const { queueName } = req.params;
+  expressQueue.pauseQueue(queueName);
+  res.json({ message: `Cola ${queueName} pausada` });
+});
+
+// Reanudar una cola
+app.post('/reanudar-cola/:queueName', (req, res) => {
+  const { queueName } = req.params;
+  expressQueue.resumeQueue(queueName);
+  res.json({ message: `Cola ${queueName} reanudada` });
+});
+
+// Limpiar una cola
+app.post('/limpiar-cola/:queueName', (req, res) => {
+  const { queueName } = req.params;
+  expressQueue.clearQueue(queueName);
+  res.json({ message: `Cola ${queueName} limpiada` });
+});
+
+// Reintentar tareas fallidas
+app.post('/reintentar-fallidas/:queueName', (req, res) => {
+  const { queueName } = req.params;
+  expressQueue.retryFailedTasks(queueName);
+  res.json({ message: `Reintentando tareas fallidas en cola ${queueName}` });
+});
+```
+
+## API
+
+### ExpressQueueIntegration
+
+#### constructor(options = {})
+
+- `options.concurrency`: Número de trabajadores concurrentes por defecto (por defecto: 1)
+- `options.retryAttempts`: Número de reintentos por defecto (por defecto: 3)
+- `options.retryDelay`: Retraso entre reintentos en ms por defecto (por defecto: 1000)
+
+#### createQueue(queueName, options = {}, hooks = null)
+
+Crea una cola con la configuración especificada.
+
+- `queueName`: Nombre de la cola
+- `options.concurrency`: Número de trabajadores concurrentes
+- `options.retryAttempts`: Número de reintentos
+- `options.retryDelay`: Retraso entre reintentos en ms
+- `hooks`: Sistema de hooks para esta cola
+
+#### addTask(queueName, task, data = {}, priority = 0)
+
+Agrega una tarea a la cola especificada.
+
+- `queueName`: Nombre de la cola
+- `task`: Función que representa la tarea
+- `data`: Datos para la tarea
+- `priority`: Prioridad de la tarea (menor número = mayor prioridad)
+
+#### start()
+
+Inicia la ejecución de tareas en todas las colas.
+
+#### stop()
+
+Detiene la ejecución de tareas en todas las colas.
+
+#### getStatus()
+
+Obtiene el estado actual del sistema de colas.
+
+#### retryFailedTasks(queueName)
+
+Reintenta todas las tareas fallidas en la cola especificada.
+
+#### queueMiddleware()
+
+Middleware para inyectar el sistema de colas en las solicitudes de Express.
+
+#### pauseQueue(queueName)
+
+Pausa la cola especificada.
+
+#### resumeQueue(queueName)
+
+Reanuda la cola especificada.
+
+#### clearQueue(queueName)
+
+Limpia las tareas pendientes de la cola especificada.
+
+## Repositorio
+
+Código fuente disponible en: https://gitlab.com/bytedogssyndicate1/express-queued
+
+## Licencia
+
+Apache 2.0

package/queued/README.md

@@ -0,0 +1,335 @@
+# Express-Queued
+
+Express-Queued is an independent queue system for Express.js that enables asynchronous execution of tasks in multiple concurrent queues. This system is ideal for time-consuming operations such as image processing, email sending, payment processing, and other operations that shouldn't block the immediate response to user requests.
+
+## Features
+
+- **Support for N queues**: Create as many queues as needed, each with its own configuration.
+- **Configurable concurrency**: Control how many tasks execute simultaneously per queue.
+- **Custom hooks**: Customize processing and fallback logic for each queue using the hooks system from [express-hooked](https://www.npmjs.com/package/express-hooked).
+- **Retry system**: Automatic failure handling with configurable retries.
+- **Priority management**: Assign priorities to tasks to determine their execution order.
+- **Fallback system**: Handle tasks that definitively fail.
+- **Fully asynchronous**: Does not block the main execution thread.
+- **Express integration**: Middleware to inject the queue system into Express requests.
+
+## Installation
+
+```bash
+npm install express-queued express-hooked
+```
+
+## Basic Usage
+
+### 1. Import and initialize
+
+```javascript
+const express = require('express');
+const ExpressQueueIntegration = require('express-queued');
+
+const app = express();
+const expressQueue = new ExpressQueueIntegration();
+```
+
+### 2. Create a queue
+
+```javascript
+// Create a queue with default configuration
+expressQueue.createQueue('general-processing', {
+  concurrency: 2,      // Maximum 2 tasks running simultaneously
+  retryAttempts: 3,    // Retry up to 3 times if it fails
+  retryDelay: 1000     // Wait 1 second between retries
+});
+```
+
+### 3. Define a task
+
+```javascript
+// Function representing a task
+function processImage(data, taskObj) {
+  return new Promise((resolve, reject) => {
+    // Simulate processing
+    setTimeout(() => {
+      console.log(`Processing image:`, data);
+      resolve('Image processing completed');
+    }, 2000);
+  });
+}
+```
+
+### 4. Add tasks to the queue
+
+```javascript
+// Add a task to the queue
+const taskId = expressQueue.addTask(
+  'general-processing',  // Queue name
+  processImage,          // Task function
+  { id: 1, filename: 'image1.jpg' }, // Data for the task
+  0                      // Priority (0 is highest)
+);
+```
+
+### 5. Start the queue system
+
+```javascript
+// Start task execution
+expressQueue.start();
+```
+
+## Express Usage
+
+### 1. Add the middleware
+
+```javascript
+// Middleware to inject the queue system into requests
+app.use(expressQueue.queueMiddleware());
+```
+
+### 2. Use the queue system in routes
+
+```javascript
+// Route to add a task
+app.post('/process-image', (req, res) => {
+  const { filename, size } = req.body;
+
+  const taskId = req.addTask('general-processing', processImage, {
+    filename,
+    size
+  });
+
+  res.json({ 
+    message: 'Image processing task added to queue',
+    taskId 
+  });
+});
+
+// Route to get queue system status
+app.get('/queue-status', (req, res) => {
+  const status = req.getQueueStatus();
+  res.json(status);
+});
+```
+
+## Custom Hooks
+
+The queue system integrates with the hooks system from [express-hooked](https://www.npmjs.com/package/express-hooked), allowing customization of system behavior through extension points.
+
+### Available Hooks
+
+- `queue_execute_task`: Executes before processing a task. Allows modifying task logic.
+- `queue_task_completed`: Executes when a task completes successfully.
+- `queue_task_failed`: Executes when a task fails.
+- `queue_task_retry`: Executes when a task is retried.
+- `queue_task_fallback`: Executes when a task definitively fails after all retries.
+- `queue_task_added`: Executes when a task is added to the queue.
+- `queue_system_started`: Executes when the queue system starts.
+- `queue_system_stopped`: Executes when the queue system stops.
+
+### Custom Hook Example
+
+```javascript
+const { HookSystem } = require('express-hooked');
+
+// Create a specific hook system for a queue
+const imageHooks = new HookSystem();
+
+// Hook to customize processing logic
+imageHooks.addAction('queue_execute_task', (task, queueName, taskObj) => {
+  console.log(`Preparing to process image: ${taskObj.id}`);
+
+  // Wrap the original task with additional logic
+  const wrappedTask = async (data, taskObj) => {
+    console.log(`Starting image processing: ${taskObj.id}`);
+    try {
+      const result = await task(data, taskObj);
+      console.log(`Image processed successfully: ${taskObj.id}`);
+      return result;
+    } catch (error) {
+      console.log(`Error processing image: ${taskObj.id} - ${error.message}`);
+      throw error;
+    }
+  };
+
+  return wrappedTask;
+});
+
+// Create the queue with custom hooks
+expressQueue.createQueue('images', {
+  concurrency: 3,
+  retryAttempts: 2,
+  retryDelay: 1000
+}, imageHooks);
+```
+
+## Error Handling and Retries
+
+The queue system includes a robust mechanism for handling errors:
+
+### Retry Configuration
+
+```javascript
+expressQueue.createQueue('reliable-processing', {
+  retryAttempts: 5,    // Maximum number of retries
+  retryDelay: 2000     // Milliseconds to wait between retries
+});
+```
+
+### Fallback Logic
+
+When a task fails after all retries, the fallback logic executes:
+
+```javascript
+const hooks = new HookSystem();
+
+hooks.addAction('queue_task_fallback', (queueName, task, error) => {
+  // Implement custom logic to handle failed tasks
+  console.log(`Definitively failed task:`, task.id);
+  console.log(`Error:`, error.message);
+
+  // For example, save to a database for manual processing
+  // or send an alert to the support team
+});
+```
+
+## Advanced Usage
+
+### Multiple Queues with Different Configurations
+
+```javascript
+// Image processing queue
+expressQueue.createQueue('image-processing', {
+  concurrency: 3,
+  retryAttempts: 2,
+  retryDelay: 1000
+});
+
+// Email sending queue
+expressQueue.createQueue('email-sending', {
+  concurrency: 2,
+  retryAttempts: 3,
+  retryDelay: 2000
+});
+
+// Payment processing queue
+expressQueue.createQueue('payment-processing', {
+  concurrency: 1,
+  retryAttempts: 5,
+  retryDelay: 3000
+});
+```
+
+### Task Priorities
+
+Tasks can be assigned different priority levels:
+
+```javascript
+// High priority task (priority 0)
+expressQueue.addTask('image-processing', processImage, { filename: 'urgent.jpg' }, 0);
+
+// Medium priority task (priority 5)
+expressQueue.addTask('image-processing', processImage, { filename: 'normal.jpg' }, 5);
+
+// Low priority task (priority 10)
+expressQueue.addTask('image-processing', processImage, { filename: 'optional.jpg' }, 10);
+```
+
+### Queue Management via API
+
+```javascript
+// Pause a queue
+app.post('/pause-queue/:queueName', (req, res) => {
+  const { queueName } = req.params;
+  expressQueue.pauseQueue(queueName);
+  res.json({ message: `Queue ${queueName} paused` });
+});
+
+// Resume a queue
+app.post('/resume-queue/:queueName', (req, res) => {
+  const { queueName } = req.params;
+  expressQueue.resumeQueue(queueName);
+  res.json({ message: `Queue ${queueName} resumed` });
+});
+
+// Clear a queue
+app.post('/clear-queue/:queueName', (req, res) => {
+  const { queueName } = req.params;
+  expressQueue.clearQueue(queueName);
+  res.json({ message: `Queue ${queueName} cleared` });
+});
+
+// Retry failed tasks
+app.post('/retry-failed/:queueName', (req, res) => {
+  const { queueName } = req.params;
+  expressQueue.retryFailedTasks(queueName);
+  res.json({ message: `Retrying failed tasks in queue ${queueName}` });
+});
+```
+
+## API
+
+### ExpressQueueIntegration
+
+#### constructor(options = {})
+
+- `options.concurrency`: Default number of concurrent workers (default: 1)
+- `options.retryAttempts`: Default number of retries (default: 3)
+- `options.retryDelay`: Default delay between retries in ms (default: 1000)
+
+#### createQueue(queueName, options = {}, hooks = null)
+
+Creates a queue with the specified configuration.
+
+- `queueName`: Name of the queue
+- `options.concurrency`: Number of concurrent workers
+- `options.retryAttempts`: Number of retries
+- `options.retryDelay`: Delay between retries in ms
+- `hooks`: Hook system for this queue
+
+#### addTask(queueName, task, data = {}, priority = 0)
+
+Adds a task to the specified queue.
+
+- `queueName`: Name of the queue
+- `task`: Function representing the task
+- `data`: Data for the task
+- `priority`: Task priority (lower number = higher priority)
+
+#### start()
+
+Starts task execution in all queues.
+
+#### stop()
+
+Stops task execution in all queues.
+
+#### getStatus()
+
+Gets the current status of the queue system.
+
+#### retryFailedTasks(queueName)
+
+Retries all failed tasks in the specified queue.
+
+#### queueMiddleware()
+
+Middleware to inject the queue system into Express requests.
+
+#### pauseQueue(queueName)
+
+Pauses the specified queue.
+
+#### resumeQueue(queueName)
+
+Resumes the specified queue.
+
+#### clearQueue(queueName)
+
+Clears pending tasks from the specified queue.
+
+## Repository
+
+Source code available at: https://gitlab.com/bytedogssyndicate1/express-queued
+
+## License
+
+Apache 2.0