🚀 Clean Node.js Utilities

Una librería modular de utilidades para aplicaciones Node.js, comenzando con comunicación en tiempo real vía Socket.IO. Arquitectura extensible preparada para módulos adicionales como autenticación, pagos y más.

🎯 Características

Módulos Disponibles

• ✅ Sockets Module: Comunicación en tiempo real con Socket.IO

  • Configuración automática con CORS
  • Handlers preconstruidos para chat y notificaciones
  • Arquitectura modular con gestión de handlers y repositorios

• ✅ Auth Module: Autenticación con JWT y refresh tokens

  • Arquitectura limpia con inyección de dependencias
  • Middlewares Express integrados
  • Control de roles y blacklist de tokens

• ✅ Server Module: Gestión de servidor Express con middlewares

  • MiddlewareServiceManager para gestión centralizada
  • Inicialización automática de middlewares
  • Soporte para middlewares personalizados

Características Generales

• ✅ Arquitectura modular preparada para múltiples utilidades
• ✅ Integración opcional de persistencia mediante Patrón Repository
• ✅ No acoplamiento a base de datos específica (Null Object Pattern)
• ✅ TypeScript con tipos completos y interfaces claras
• ✅ Utilidades compartidas entre módulos
• ✅ Tree shaking compatible para optimización de bundles
• ✅ Listo para integrarse en cualquier backend con Express

🧩 Arquitectura

Arquitectura General

clean-nodejs-utilities/
├── src/
│   ├── shared/           # Utilidades compartidas
│   │   ├── utils/        # Logger, helpers comunes
│   │   ├── core/         # Patrones base reutilizables
│   │   ├── types/        # Tipos compartidos
│   │   └── errors/       # Sistema de errores unificado
│   ├── sockets/          # Módulo de WebSockets
│   ├── auth/             # Módulo de autenticación
│   ├── server/           # Módulo de servidor Express
│   │   ├── core/         # Lógica core del servidor
│   │   ├── interfaces/   # Interfaces del módulo
│   │   ├── types/        # Tipos específicos
│   │   └── index.ts      # Exportaciones del módulo
│   ├── payments/         # Futuro: Módulo de pagos
│   └── index.ts          # Exportaciones principales

📦 Instalación

npm install clean-nodejs-utilities

🚀 Uso Básico

Módulo Sockets

const express = require('express');
const http = require('http');
const { initSocketCore } = require('clean-nodejs-utilities');

const app = express();
const server = http.createServer(app);

// Inicialización simple del módulo sockets
const io = initSocketCore(server, {
  cors: {
    origin: "http://localhost:3000",
    credentials: true
  }
});

app.get('/', (req, res) => {
  res.send('Servidor funcionando!');
});

server.listen(3000, () => {
  console.log('Servidor corriendo en puerto 3000');
});

Uso con ES Modules (Auth Module)

import express from 'express';
import http from 'http';
import { initSocketCore } from 'clean-nodejs-utilities';

const app = express();
const server = http.createServer(app);

// Inicialización simple del módulo sockets
const io = initSocketCore(server, {
  cors: {
    origin: "http://localhost:3000",
    credentials: true
  }
});

app.get('/', (req, res) => {
  res.send('Servidor funcionando!');
});

server.listen(3000, () => {
  console.log('Servidor corriendo en puerto 3000');
});

Módulo Auth

const express = require('express');
const { initAuthCore } = require('clean-nodejs-utilities');

const app = express();
app.use(express.json());

// Inicializar el módulo de autenticación
const authCore = initAuthCore({
  config: {
    jwtSecret: 'tu_jwt_secret',
    jwtExpiresIn: '15m',
    refreshSecret: 'tu_refresh_secret',
    refreshExpiresIn: '7d',
    bcryptRounds: 10,
  },
});

// Inicializar el módulo
authCore.initialize().then(() => {
  console.log('Auth module initialized');
});

// Rutas de autenticación
app.post('/auth/login', async (req, res) => {
  try {
    const tokens = await authCore.signIn(req.body);
    res.json(tokens);
  } catch (error) {
    res.status(401).json({ error: 'Credenciales inválidas' });
  }
});

// Ruta protegida
app.get('/protected', authCore.getAuthMiddleware(), (req, res) => {
  res.json({ message: 'Acceso autorizado', user: req.user });
});

Módulo Server

import express from 'express';
import { initServerCore } from 'clean-nodejs-utilities';
import helmet from 'helmet';
import cors from 'cors';

const app = express();

// Inicializar el servidor con middlewares
const serverCore = initServerCore({
  config: {
    port: 3000,
    env: 'production'
  },
  middlewares: {
    helmet: helmet(),
    cors: cors({
      origin: 'http://localhost:3000',
      credentials: true
    })
  }
});

// Iniciar servidor (middlewares se aplican automáticamente)
const httpServer = await serverCore.start();

// Acceder al manager de middlewares
const middlewareManager = serverCore.middlewareManager;

// Registrar middleware adicional en runtime
middlewareManager.registerMiddleware('custom', (req, res, next) => {
  console.log('Custom middleware');
  next();
});

// Aplicar cambios
await middlewareManager.initializeAll();

Uso con ES Modules (Sockets Module)

import express from 'express';
import { initAuthCore } from 'clean-nodejs-utilities';

const app = express();
app.use(express.json());

// Inicializar el módulo de autenticación
const authCore = initAuthCore({
  config: {
    jwtSecret: 'tu_jwt_secret',
    jwtExpiresIn: '15m',
    refreshSecret: 'tu_refresh_secret',
    refreshExpiresIn: '7d',
    bcryptRounds: 10,
  },
});

// Inicializar el módulo
await authCore.initialize();
console.log('Auth module initialized');

// Rutas de autenticación
app.post('/auth/login', async (req, res) => {
  try {
    const tokens = await authCore.signIn(req.body);
    res.json(tokens);
  } catch (error) {
    res.status(401).json({ error: 'Credenciales inválidas' });
  }
});

// Ruta protegida
app.get('/protected', authCore.getAuthMiddleware(), (req, res) => {
  res.json({ message: 'Acceso autorizado', user: req.user });
});

📁 Estructura del Proyecto

clean-nodejs-utilities/
├── src/
│   ├── shared/                # Utilidades compartidas
│   │   ├── utils/             # Logger y utilidades comunes
│   │   ├── errors/            # Sistema de errores unificado
│   │   └── index.ts           # Exportaciones compartidas
│   ├── sockets/               # Módulo de WebSockets
│   │   ├── core/              # Lógica core de sockets
│   │   ├── handlers/          # Handlers preconstruidos
│   │   ├── interfaces/        # Interfaces y contratos
│   │   ├── types/             # Tipos específicos
│   │   └── index.ts           # Exportaciones del módulo
│   ├── auth/                  # Módulo de autenticación
│   │   ├── core/              # Núcleo del módulo
│   │   ├── services/          # Servicios de negocio
│   │   ├── interfaces/        # Contratos y abstracciones
│   │   ├── types/             # Definiciones TypeScript
│   │   ├── utils/             # Utilidades
│   │   ├── middlewares/       # Middlewares Express
│   │   ├── examples/          # Ejemplos de uso
│   │   ├── tests/             # Tests del módulo
│   │   └── index.ts           # Punto de entrada
│   ├── server/                # Módulo de servidor Express
│   │   ├── core/              # Lógica core del servidor
│   │   ├── interfaces/        # Interfaces del módulo
│   │   ├── types/             # Tipos específicos
│   │   └── index.ts           # Exportaciones del módulo
│   └── index.ts               # Exportaciones principales
├── examples/                  # Ejemplos de uso
│   ├── basic-usage.js         # Uso básico de sockets
│   ├── custom-handler.js      # Handlers personalizados
│   ├── with-repositories.js   # Integración con repositorios
│   └── auth-integration/      # Ejemplos de autenticación
├── docs/                      # Documentación adicional
├── legacy/                    # Código legacy (v1.x)
└── dist/                      # Archivos compilados

Estado de los Módulos

• ✅ Sockets: Comunicación en tiempo real con Socket.IO
  • Handlers para chat y notificaciones
  • Arquitectura modular con repositorios
  • Integración opcional con persistencia
• ✅ Auth: Autenticación con JWT y refresh tokens
  • Middlewares Express integrados
  • Control de roles y permisos
  • Blacklist de tokens
  • Soporte para múltiples bases de datos
• ✅ Server: Gestión de servidor Express con middlewares
  • MiddlewareServiceManager para gestión centralizada
  • Inicialización automática de middlewares
  • Soporte para middlewares personalizados
• 🔄 Payments: Futuro - Integración con pasarelas de pago
• 🔄 Cache: Futuro - Sistema de cache distribuido

👨‍💻 Autor

Luisma Suarez - GitHub - LinkedIn

📋 Migración desde v1.x

Cambios Importantes en v2.0.0

Breaking Changes:

• 📦 Nombre del paquete: clean-nodejs-sockets → clean-nodejs-utilities
• 🏗️ Reestructuración interna: Código reorganizado en módulos
• 🔗 Rutas de importación: Cambios en rutas de módulos internos

Migración:

// Antes (v1.x)
const { initSocketCore } = require('clean-nodejs-sockets');

// Después (v2.0)
const { initSocketCore } = require('clean-nodejs-utilities');
// O para tree shaking:
const { initSocketCore } = require('clean-nodejs-utilities');

Backward Compatibility:

• ✅ API pública del módulo sockets se mantiene igual
• ✅ Funcionalidad existente funciona sin cambios
• ✅ Solo cambia el nombre del paquete

Cambios en v2.0.1

Correcciones:

• 📝 Documentación actualizada: Todas las referencias al nombre del paquete corregidas
• 🔧 Importaciones corregidas: Ejemplos de código ahora usan el nombre correcto del paquete
• 📦 Consistencia: Documentación sincronizada con la estructura actual del proyecto

Cambios en v2.0.3

Nuevas funcionalidades:

• 🏗️ Server Module: Nuevo módulo para gestión de servidor Express
  • MiddlewareServiceManager para gestión centralizada de middlewares
  • Inicialización automática de middlewares con initializeAll()
  • Soporte para registro de middlewares personalizados
  • Métodos getAll(), remove(), clearAll(), y disposeAll()
• 🔧 Mejoras en arquitectura: Mejor separación de responsabilidades
• 📚 Documentación actualizada: Incluye ejemplos del nuevo módulo Server