trucostars-core-module

v0.0.6

Published

3 days ago

Truco Stars core API module for NestJS.

0High
0Medium
0Low

trucostars

TrucoStars API

📑 Índice

📋 Descripción

TrucoStars API es una aplicación backend moderna construida con NestJS, que proporciona funcionalidades completas para:

Gestión de Productos: CRUD de productos con almacenamiento en MongoDB
Autenticación y Autorización: Integración con Firebase para autenticación segura
Caché en Tiempo Real: Uso de Redis para optimizar el rendimiento
Comunicación WebSocket: Soporte para comunicación bidireccional en tiempo real
Persistencia de Datos: MongoDB como base de datos principal

🏗️ Estructura del Proyecto

src/
├── app.controller.ts          # Controlador principal
├── app.service.ts             # Servicio principal
├── app.module.ts              # Módulo raíz
├── main.ts                    # Punto de entrada
├── firebase/                  # Módulo de autenticación Firebase
│   ├── firebase.config.ts     # Configuración de Firebase
│   ├── firebase.controller.ts # Endpoints de autenticación
│   ├── firebase.service.ts    # Lógica de autenticación
│   └── firebase.module.ts     # Módulo Firebase
├── products/                  # Módulo de productos
│   ├── products.controller.ts # Endpoints de productos
│   ├── products.service.ts    # Lógica de negocio de productos
│   ├── products.module.ts     # Módulo de productos
│   └── entities/
│       └── product.entity.ts  # Esquema/entidad de producto
├── redis/                     # Módulo de caché Redis
│   ├── redis.service.ts       # Servicio de Redis
│   └── redis.module.ts        # Módulo Redis
└── websocket/                 # Módulo de WebSocket
    ├── websocket.gateway.ts   # Gateway de WebSocket
    ├── websocket.service.ts   # Lógica de WebSocket
    └── websocket.module.ts    # Módulo WebSocket

🛠️ Stack Tecnológico

Core Framework

NestJS v11: Framework progresivo para aplicaciones Node.js
TypeScript: Tipado seguro y desarrollo escalable

Bases de Datos

MongoDB: Base de datos NoSQL con Mongoose ODM
Redis: Sistema de caché en memoria

Funcionalidades

Firebase Admin SDK: Autenticación y gestión de usuarios
Socket.io: Comunicación WebSocket en tiempo real
Swagger: Documentación API automática

Testing & Quality

Jest: Framework de testing
ESLint: Linting de código
Prettier: Formateo de código

Dependencias Principales

"@nestjs/core": "^11.0.1"
"@nestjs/mongoose": "^11.0.4"
"@nestjs/websockets": "^11.1.11"
"@nestjs/swagger": "^11.2.4"
"firebase-admin": "^13.6.0"
"mongoose": "^9.1.3"
"ioredis": "^5.9.2"

🚀 Módulos Principales

📦 Productos Module

Gestión completa de productos con operaciones CRUD, validaciones y caché.

ProductsController: Endpoints para CRUD de productos
ProductsService: Lógica de negocio
ProductEntity: Esquema MongoDB

🔐 Firebase Module

Autenticación y autorización segura mediante Firebase.

FirebaseService: Gestión de tokens y autenticación
FirebaseController: Endpoints de login y verificación

⚡ Redis Module

Se implementa un sistema de caché distribuido para optimizar el rendimiento de la aplicación, utilizando Redis como backend de almacenamiento, a través del Cache Manager de NestJS y reutilizando el cliente que provee RedisService.

Esto permite:

Cacheo automático de respuestas HTTP mediante CacheInterceptor
Compatibilidad total con interceptores y decoradores estándar de NestJS.
Reducción de consultas repetidas a MongoDB
Expiración de datos configurable (TTL)

Adicionalmente, se implementa Rate Limiting mediante el paquete @nestjs/throttler, que provee un ThrottlerGuard que limita la cantidad de solicitudes permitidas por cliente en un período de tiempo configurable, aplicándose a todos los endpoints de la aplicación y reutilizando el mismo cliente Redis expuesto por RedisService.

Este enfoque desacopla la lógica de caché de la lógica de negocio, siguiendo las mejores prácticas recomendadas por NestJS.

🔌 WebSocket Module

Comunicación en tiempo real bidireccional.

WebSocketGateway: Gestor de conexiones WebSocket
WebSocketService: Lógica de mensajería

⚙️ Configuración e Instalación

Requisitos Previos

Node.js: v18+ recomendado
npm: v9+
MongoDB: Instancia local o conexión remota
Redis: Instancia local o conexión remota

Instalación

# Instalar dependencias
$ npm install

Variables de Entorno

Crear un archivo .env en la raíz del proyecto:

# MongoDB
MONGODB_URI=mongodb+srv://user:[email protected]/?appName=Develop

# Redis
# GENERAL
REDIS_URL=redis://[usuario]:[password]@[host]:[port]/[db]
# LOCAL
REDIS_URL=redis://localhost:6379

# Firebase
FIREBASE_PROJECT_ID=your-project-id
FIREBASE_PRIVATE_KEY=your-private-key
FIREBASE_CLIENT_EMAIL=your-client-email

# API
PORT=3000
NODE_ENV=development

# Logging Configuration
LOG_LEVEL=debug                  # Nivel de logging: debug | log | warn | error
ENABLE_HTTP_LOGGING=true         # Logs del middleware HTTP (request/response)
ENABLE_API_LOGGING=true          # Logs del interceptor API (controllers/handlers)

Control de Logs

La aplicación incluye un sistema de logging profesional que puede controlarse mediante variables de entorno:

LOG_LEVEL: Define el nivel de detalle de los logs
- debug: Todos los logs (desarrollo)
- log: Información general
- warn: Solo advertencias y errores
- error: Solo errores críticos
ENABLE_HTTP_LOGGING: Controla los logs del middleware HTTP
- true: Muestra logs detallados de requests/responses con formato visual mejorado
- false: Desactiva completamente los logs HTTP
ENABLE_API_LOGGING: Controla los logs del interceptor API
- true: Muestra logs de controllers, handlers y timing de ejecución
- false: Desactiva los logs de API

Ejemplo para producción (logs mínimos):

NODE_ENV=production
LOG_LEVEL=error
ENABLE_HTTP_LOGGING=false
ENABLE_API_LOGGING=false

Ejemplo para desarrollo (logs completos):

NODE_ENV=development
LOG_LEVEL=debug
ENABLE_HTTP_LOGGING=true
ENABLE_API_LOGGING=true

🚀 Ejecución

# Modo desarrollo (con reinicio automático)
$ npm run start:dev

# Modo desarrollo con depuración
$ npm run start:debug

# Modo producción
$ npm run start:prod

# Compilar proyecto
$ npm run build

🧪 Testing

Comandos Disponibles

# Ejecutar todas las pruebas unitarias
$ npm run test

# Ejecutar tests de módulos comunes (Database, Redis, Firebase, WebSocket)
$ npm run test:common

# Ejecutar solo tests de conexiones e inicialización
$ npm run test:connections

# Modo watch (re-ejecuta al cambiar archivos)
$ npm run test:watch

# Cobertura de pruebas
$ npm run test:cov

# Pruebas end-to-end
$ npm run test:e2e

📋 Tests de Conexiones e Inicialización

El proyecto incluye un conjunto completo de unit tests para verificar que las conexiones e inicialización de los módulos funcionen correctamente:

Tests Implementados

| Módulo | Archivo | Tests | Descripción | |--------|---------|-------|-------------| | DatabaseService | database.service.spec.ts | 10 tests | Verificación de conexión MongoDB, estados, health checks | | RedisService | redis.service.spec.ts | 7 tests | Configuración de Redis, ciclo de vida, gestión de conexión | | FirebaseService | firebase.service.spec.ts | 6 tests | Inicialización Firebase, notificaciones push, manejo de errores | | WebSocketService | websocket.service.spec.ts | 9 tests | Broadcasting, gestión de conexiones, manejo de errores | | SqsProducer | sqs.producer.spec.ts | 11 tests | Configuración AWS, inicialización cliente SQS, métodos de envío | | SqsConsumer | sqs.consumer.spec.ts | 15 tests | Polling, procesamiento de mensajes, RxJS Subjects, lifecycle | | SqsModule | sqs.module.spec.ts | 9 tests | Compilación módulo, providers, exports, integración | | CommonModule | common.module.spec.ts | 8 tests | Compilación del módulo, configuración global, providers |

✅ Qué Verifican los Tests

✅ Inicialización correcta de servicios y conexiones
✅ Estados de conexión (conectado, desconectado, conectando)
✅ Configuración de variables de entorno
✅ Health checks de conexiones a bases de datos y servicios externos
✅ Manejo de errores durante la inicialización
✅ Inyección de dependencias correcta en todos los módulos

📊 Cobertura de Tests

# Ejecutar solo tests de conexiones
$ npm run test:8 passed, 8 total
# Tests:       74 passed, 74
# Resultado esperado:
# Test Suites: 4 passed, 4 total
# Tests:       32 passed, 32 total

🔍 Ejemplo de Test: DatabaseService

describe('DatabaseService - Connection Initialization', () => {
  it('should initialize with a connected state', () => {
    expect(mockConnection.readyState).toBe(1); // 1 = conectado
  });

  it('should perform health check successfully', async () => {
    const healthStatus = await service.checkHealth();
    expect(healthStatus.status).toBe('healthy');
  });
});

📝 Documentación Completa

Para más detalles sobre los tests y cómo implementarlos, consulta:

TESTING.md - Guía completa de testing
Incluye ejemplos de mocks, mejores prácticas y troubleshooting

🎯 Beneficios

Detección Temprana: Identifica problemas de configuración antes del despliegue
Documentación Viva: Los tests sirven como documentación del comportamiento esperado
Confianza en Refactoring: Permite cambiar código con seguridad
CI/CD Ready: Tests automatizables para pipelines de integración continua

📝 Herramientas de Desarrollo

# Linting y formateo
$ npm run lint              # Ejecutar ESLint
$ npm run format            # Formatear código con Prettier

# Gestión de puertos
$ npm run kill              # Cerrar proceso en puerto 3000
$ npm run stop-force        # Forzar cierre del puerto 3000

📚 Características Principales

✅ CRUD de Productos

Crear nuevos productos
Listar y buscar productos
Actualizar información de productos
Eliminar productos
Caché automático con Redis

🔐 Autenticación con Firebase

Registro de usuarios
Login seguro
Verificación de tokens JWT
Control de acceso basado en roles

💬 WebSocket en Tiempo Real

Conexiones persistentes
Notificaciones en tiempo real
Mensajería bidireccional
Manejo de desconexiones automático

⚡ Optimización con Redis

Caché de productos frecuentes
Reducción de consultas a MongoDB
Sincronización automática de datos
Expiración configurable de datos

🔗 Endpoints Principales

La API expone todos sus recursos bajo el prefijo global /api.

Si estás ejecutando el proyecto en entorno local, la URL base será: http://localhost:3000/api

A partir de esta URL base, se describen a continuación los endpoints disponibles, organizados por módulo.

Documentación de la API

GET /docs - Devuelve la documentación interactiva de todos los endpoints disponibles en la API.

Productos

GET /products - Listar todos los productos
GET /products/:id - Obtener un producto
POST /products - Crear nuevo producto
PATCH /products/:id - Actualizar producto
DELETE /products/:id - Eliminar producto

Firebase (Autenticación)

POST /auth/register - Registrar usuario
POST /auth/login - Iniciar sesión
POST /auth/verify - Verificar token

WebSocket

Evento: message - Enviar mensaje en tiempo real
Evento: connect - Conexión establecida
Evento: disconnect - Conexión cerrada

📦 Dependencias Importantes

| Paquete | Versión | Propósito | |---------|---------|----------| | @nestjs/core | ^11.0.1 | Core framework | | @nestjs/mongoose | ^11.0.4 | ODM para MongoDB | | @nestjs/websockets | ^11.1.11 | Soporte WebSocket | | @nestjs/swagger | ^11.2.4 | Documentación API | | firebase-admin | ^13.6.0 | Autenticación Firebase | | mongoose | ^9.1.3 | MongoDB driver | | ioredis | ^5.9.2 | Cliente Redis |

🛠️ Herramientas de Desarrollo

| Herramienta | Propósito | |------------|----------| | Jest | Testing unitario y e2e | | ESLint | Linting de código | | Prettier | Formateo de código | | Swagger | Documentación de API | | TypeScript | Tipado estático |

📄 Archivos de Configuración

tsconfig.json - Configuración TypeScript
nest-cli.json - Configuración NestJS
eslint.config.mjs - Reglas ESLint
package.json - Dependencias y scripts

🤝 Autor

Fractured Mesh Studios

📜 Licencia

Este proyecto está bajo licencia UNLICENSED.