🚀 Clean Node.js Sockets

Un SDK modular para comunicación en tiempo real con Socket.IO, diseñado para proyectos Node.js + Express. Abstrae la configuración base y proporciona una arquitectura extensible con handlers preconstruidos para chat y notificaciones.

🎯 Características

• ✅ Configuración automática de Socket.IO con CORS
• ✅ Handlers preconstruidos para chat y notificaciones
• ✅ Arquitectura modular con gestión de handlers y repositorios
• ✅ 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
• ✅ Listo para integrarse en cualquier backend con Express

🧩 Arquitectura

app-server.js ──┐
                ▼
        ┌───────────────┐
        │  SocketCore   │ ← Fachada principal
        └───────────────┘
                │
        ┌───────┼───────┐
        ▼       ▼       ▼
EventHandler  Repository  Handlers
Manager      Manager     Base
                        │
                ┌───────┼───────┐
                ▼       ▼       ▼
            Chat    Notification  [Custom]
            Handler   Handler     Handlers

📦 Instalación

npm install clean-nodejs-sockets

🚀 Uso Básico

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

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

// Inicialización simple
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');
});

📋 Eventos Disponibles

Chat Handler

• message:send → Envía mensaje a sala
• user:join → Usuario se une a sala
• user:leave → Usuario abandona sala
• user:typing → Usuario está escribiendo

Notification Handler

• notification:send → Envía notificación a usuario específico
• notification:bulk_send → Envía notificaciones masivas a múltiples usuarios
• notification:mark_read → Marca notificación como leída

🔧 Configuración Avanzada

const io = initSocketCore(server, {
  repositories: {
    messageRepository: new MongoMessageRepository(),
    notificationRepository: new MongoNotificationRepository(),
  },
  handlers: [new ChatHandler(), new NotificationHandler()], // o instancias
  cors: {
    origin: "http://localhost:3000",
    credentials: true
  }
});

🏗️ Extensibilidad

Crear Handler Personalizado

const { BaseHandler, SocketCore } = require('clean-nodejs-sockets');

class GameHandler extends BaseHandler {
  register(socket, repositories) {
    socket.on('game:join', (data) => {
      // Lógica del handler
      socket.join(`game_${data.gameId}`);
      socket.to(`game_${data.gameId}`).emit('player:joined', data);
    });

    socket.on('game:move', (data) => {
      socket.to(`game_${data.gameId}`).emit('game:move_made', data);
    });
  }
}

// Usar handler personalizado
const socketCore = new SocketCore({
  handlers: [new GameHandler()]
});
const io = socketCore.start(server);

Implementar Repositorio Personalizado

const { IMessageRepository, INotificationRepository } = require('clean-nodejs-sockets');

class MongoMessageRepository extends IMessageRepository {
  async save(message) {
    // Implementación con MongoDB
    return await MessageModel.create(message);
  }

  async findByRoom(roomId) {
    return await MessageModel.find({ roomId });
  }
}

class MongoNotificationRepository extends INotificationRepository {
  async save(notification) {
    // Implementación con MongoDB
    return await NotificationModel.create(notification);
  }

  async findByUser(userId) {
    return await NotificationModel.find({ targetUserId: userId });
  }
}

🧠 Patrones de Diseño Utilizados

| Patrón | Aplicación | |--------|------------| | Facade | SocketCore simplifica la inicialización | | Strategy | EventHandlerManager gestiona handlers dinámicamente | | Repository | Abstracción de persistencia con interfaces | | Template Method | BaseHandler define flujo base para handlers | | Dependency Injection | Inyección de repositorios y handlers | | Null Object | Repositorios nulos cuando no se especifican | | Factory | Creación automática de handlers por defecto |

📁 Estructura del Proyecto

src/
├── core/
│   ├── EventHandlerManager.ts # Gestión de handlers
│   ├── RepositoryManager.ts   # Gestión de repositorios
│   └── SocketCore.ts          # Fachada principal
├── handlers/
│   ├── ChatHandler.ts         # Handler de chat
│   └── NotificationHandler.ts # Handler de notificaciones
├── interfaces/
│   ├── Handlers.ts            # Interfaces de handlers
│   └── Repositories.ts        # Interfaces de repositorios
└── types/
    └── core.types.ts          # Tipos TypeScript

🤝 Contribuir

1. Fork el proyecto
2. Crea tu rama de feature (git checkout -b feature/AmazingFeature)
3. Commit tus cambios (git commit -m 'Add some AmazingFeature')
4. Push a la rama (git push origin feature/AmazingFeature)
5. Abre un Pull Request

📄 Licencia

Este proyecto está bajo la Licencia MIT - ver el archivo LICENSE para más detalles.

👨‍💻 Autor

Luisma Suarez - GitHub

🙏 Agradecimientos

• Socket.IO por la excelente librería de WebSockets
• Comunidad de Node.js por las mejores prácticas
• Todos los contribuidores del proyecto