stelar-time-real 1.0.0

package/README.md

@@ -0,0 +1,438 @@
+# stelar-time-real
+
+Tu propio sistema de tiempo real personalizado. Una librería ligera y sin dependencias para comunicación en tiempo real via WebSockets.
+
+![npm](https://img.shields.io/npm/v/stelar-time-real)
+![license](https://img.shields.io/npm/l/stelar-time-real)
+![size](https://img.shields.io/bundlephobia/min/stelar-time-real)
+
+## ¿Por qué stelar-time-real?
+
+- ⚡ **Ultra ligera** - Solo ~13MB de heap
+- 🚀 **Sin dependencias** - Usa solo `ws` (WebSocket nativo)
+- 🎯 **Personalizable** - Vos controlás todo, nada de código ajeno
+- 🔌 **Compatible** - Funciona con Express, Fastify, HTTP nativo, etc.
+- 💓 **Heartbeat incluido** - Detecta desconexiones automáticamente
+
+## Instalación
+
+```bash
+npm install stelar-time-real
+```
+
+## Inicio Rápido
+
+### Servidor
+
+```javascript
+import express from 'express';
+import StelarServer from 'stelar-time-real';
+
+const app = express();
+const server = app.listen(3000);
+
+const stelar = new StelarServer({ server });
+
+stelar.onConnection((client) => {
+  console.log('Nuevo cliente:', client.id);
+  client.emit('bienvenida', '¡Hola! Bienvenido a stelar-time-real');
+});
+
+stelar.on('mensaje', (ctx) => {
+  ctx.broadcast('mensaje', ctx.data);
+});
+
+stelar.start();
+```
+
+### Cliente
+
+```javascript
+import StelarClient from 'stelar-time-real/client';
+
+const client = new StelarClient('localhost:3000');
+
+client.on('connect', () => {
+  console.log('Conectado!');
+});
+
+client.on('bienvenida', (msg) => {
+  console.log(msg);
+});
+
+client.connect();
+```
+
+## API Completa
+
+### StelarServer (Lado del Servidor)
+
+#### Constructor
+
+```javascript
+new StelarServer({ server, port, heartbeatInterval })
+```
+
+| Opción | Tipo | Default | Descripción |
+|--------|------|---------|-------------|
+| server | http.Server | null | Tu server HTTP existente |
+| port | number | 3000 | Puerto si no pasás server |
+| heartbeatInterval | number | 30000 | Intervalo de ping en ms |
+
+#### Métodos
+
+**`.use(middleware)`**
+Agregar middleware para validar conexiones.
+
+```javascript
+stelar.use((ctx, next) => {
+  const token = ctx.req.headers['x-token'];
+  if (token === 'secreto') {
+    next();
+  } else {
+    ctx.socket.close();
+  }
+});
+```
+
+**`.on(event, handler)`**
+Escuchar eventos del cliente.
+
+```javascript
+stelar.on('chat', (ctx) => {
+  console.log('Mensaje:', ctx.data);
+  ctx.broadcast('chat', ctx.data);
+});
+```
+
+**`.onAll(handler)`**
+Escuchar todos los eventos (útil para debug).
+
+```javascript
+stelar.onAll(({ event, data }) => {
+  console.log(`Evento: ${event}`, data);
+});
+```
+
+**`.onConnection(handler)`**
+Ejecutar cuando un cliente se conecta.
+
+```javascript
+stelar.onConnection((client) => {
+  client.emit('bienvenida', 'Hola!');
+});
+```
+
+**`.broadcast(event, data)`**
+Enviar a todos los clientes.
+
+```javascript
+stelar.broadcast('chat', { mensaje: 'Hola a todos' });
+```
+
+**`.to(room, event, data)`**
+Enviar a una sala específica.
+
+```javascript
+stelar.to('sala-1', 'chat', { mensaje: 'Hola sala 1' });
+```
+
+**`.toId(id, event, data)`**
+Enviar a un cliente específico por ID.
+
+```javascript
+stelar.toId('abc123', 'privado', 'Solo para ti');
+```
+
+**`.getClients(room)`**
+Obtener lista de clientes.
+
+```javascript
+const todos = stelar.getClients();
+const sala = stelar.getClients('mi-sala');
+```
+
+**`.getPort()`**
+Obtener el puerto donde está corriendo.
+
+```javascript
+console.log('Puerto:', stelar.getPort());
+```
+
+**`.start(callback)`**
+Iniciar el servidor WebSocket.
+
+```javascript
+await stelar.start();
+console.log('Iniciado!');
+```
+
+**`.stop()`**
+Detener el servidor.
+
+```javascript
+stelar.stop();
+```
+
+#### Contexto (ctx) en handlers
+
+Cuando escuchás un evento, recibís un `ctx` con:
+
+```javascript
+stelar.on('mensaje', (ctx) => {
+  ctx.id          // ID único del cliente
+  ctx.socket      // WebSocket del cliente
+  ctx.req         // Request HTTP original
+  ctx.data        // Datos recibidos
+  
+  // Métodos disponibles:
+  ctx.emit('evento', data)     // Enviar solo a este cliente
+  ctx.broadcast('evento', data) // Enviar a todos
+  ctx.to('sala', 'evento', data) // Enviar a una sala
+  ctx.toId('id', 'evento', data) // Enviar a un cliente específico
+  ctx.getClients('sala')      // Ver clientes en sala
+  ctx.joinRoom('sala')        // Unir a sala
+  ctx.leaveRoom()             // Salir de sala
+});
+```
+
+---
+
+### StelarClient (Lado del Cliente)
+
+#### Constructor
+
+```javascript
+new StelarClient(urlOrPort, options)
+```
+
+| Param | Tipo | Default | Descripción |
+|-------|------|---------|-------------|
+| urlOrPort | string/number | localhost:3000 | URL o puerto del servidor |
+| options.reconnection | boolean | true | Reconectar automáticamente |
+| options.reconnectionAttempts | number | 5 | Intentos de reconexión |
+| options.reconnectionDelay | number | 1000 | Delay entre intentos (ms) |
+| options.heartbeatInterval | number | 30000 | Intervalo de ping |
+
+```javascript
+// Solo puerto
+const client = new StelarClient(3000);
+
+// URL completa
+const client = new StelarClient('ws://midominio.com/ws');
+
+// Con opciones
+const client = new StelarClient(3000, {
+  reconnection: true,
+  reconnectionAttempts: 10,
+  reconnectionDelay: 2000
+});
+```
+
+#### Métodos
+
+**`.on(event, handler)`**
+Escuchar eventos del servidor.
+
+```javascript
+client.on('bienvenida', (data) => {
+  console.log(data);
+});
+```
+
+**`.onAll(handler)`**
+Escuchar todos los eventos.
+
+```javascript
+client.onAll(({ event, data }) => {
+  console.log(`${event}:`, data);
+});
+```
+
+**`.emit(event, data)`**
+Enviar eventos al servidor.
+
+```javascript
+client.emit('chat', { mensaje: 'Hola!' });
+```
+
+**`.joinRoom(room)`**
+Unirse a una sala.
+
+```javascript
+client.joinRoom('sala-1');
+```
+
+**`.leaveRoom()`**
+Salir de la sala actual.
+
+```javascript
+client.leaveRoom();
+```
+
+**`.connect(callback)`**
+Conectar al servidor.
+
+```javascript
+client.connect(() => {
+  console.log('Conectado!');
+});
+```
+
+**`.disconnect()`**
+Desconectar manualmente.
+
+```javascript
+client.disconnect();
+```
+
+**`.isConnected()`**
+Verificar estado de conexión.
+
+```javascript
+if (client.isConnected()) {
+  console.log('Conectado');
+}
+```
+
+**`.getUrl()`**
+Obtener la URL de conexión.
+
+```javascript
+console.log(client.getUrl());
+```
+
+#### Eventos del Cliente
+
+```javascript
+client.on('connect', () => {});       // Cuando se conecta
+client.on('disconnect', () => {});     // Cuando se desconecta
+client.on('reconnecting', (attempt) => {}); // Cuando intenta reconectar
+client.on('error', (err) => {});      // Cuando hay error
+```
+
+---
+
+## Ejemplos
+
+### Chat Básico
+
+**server.js**
+```javascript
+import express from 'express';
+import StelarServer from 'stelar-time-real';
+
+const app = express();
+const server = app.listen(3000);
+
+const stelar = new StelarServer({ server });
+
+stelar.onConnection((client) => {
+  client.broadcast('system', 'Un usuario se unió');
+});
+
+stelar.on('chat', (ctx) => {
+  ctx.broadcast('chat', ctx.data);
+});
+
+stelar.start();
+console.log('Chat en http://localhost:3000');
+```
+
+**cliente.html**
+```html
+<script type="module">
+  import StelarClient from 'stelar-time-real/client.js';
+
+  const client = new StelarClient(3000);
+
+  client.on('connect', () => console.log('Conectado'));
+  client.on('chat', (msg) => console.log('Chat:', msg));
+  client.on('system', (msg) => console.log('Sistema:', msg));
+
+  client.connect();
+
+  // Enviar mensajes
+  function enviar(mensaje) {
+    client.emit('chat', mensaje);
+  }
+</script>
+```
+
+### Sistema de Rooms
+
+```javascript
+// Servidor
+stelar.on('unirse-sala', (ctx) => {
+  const sala = ctx.data.sala;
+  ctx.joinRoom(sala);
+  ctx.emit('bienvenida', `Te uniste a ${sala}`);
+});
+
+stelar.on('mensaje-sala', (ctx) => {
+  ctx.to(ctx.data.sala, 'mensaje-sala', ctx.data.mensaje);
+});
+
+// Cliente
+client.on('unirse-sala', (sala) => client.joinRoom(sala));
+```
+
+### Con Middleware de Auth
+
+```javascript
+stelar.use((ctx, next) => {
+  const token = ctx.req.headers['authorization'];
+  if (token && token.startsWith('Bearer ')) {
+    next(); // Permitir conexión
+  } else {
+    ctx.socket.close(); // Rechazar
+  }
+});
+```
+
+### Con Reconexión Automática
+
+```javascript
+const client = new StelarClient('localhost:3000', {
+  reconnection: true,
+  reconnectionAttempts: 5,
+  reconnectionDelay: 1000
+});
+
+client.on('connect', () => console.log('Conectado!'));
+client.on('disconnect', () => console.log('Desconectado'));
+client.on('reconnecting', (attempt) => console.log(`Reintentando ${attempt}/5`));
+
+client.connect();
+```
+
+---
+
+## Diferencia con Socket.io
+
+| Característica | stelar-time-real | Socket.io |
+|----------------|------------------|-----------|
+| Tamaño heap | ~13 MB | ~50-100 MB |
+| Dependencias | ws (1) | múltiples |
+| Configuración | mínima | compleja |
+| Flexibilidad | total | opinionada |
+| Ideal para | proyectos propios | producción rápida |
+
+## Changelog
+
+### v1.0.0
+- Lanzamiento inicial
+- WebSockets con ws
+- Heartbeat automático
+- Reconexión cliente
+- Middlewares
+- Rooms y broadcast
+- Soporte para servidor externo
+
+## Licencia
+
+MIT - Stelar
+
+## Autor
+
+Stelar

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "stelar-time-real",
+  "version": "1.0.0",
+  "description": "Tu propio sistema de tiempo real personalizado - WebSocket ligero sin dependencias",
+  "main": "src/index.js",
+  "type": "module",
+  "keywords": [
+    "websocket",
+    "real-time",
+    "socket",
+    " realtime",
+    "stelar",
+    "chat",
+    "webserver"
+  ],
+  "author": "Stelar",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/stelar-time-real/stelar-time-real"
+  },
+  "bugs": {
+    "url": "https://github.com/stelar-time-real/stelar-time-real/issues"
+  },
+  "homepage": "https://github.com/stelar-time-real/stelar-time-real#readme",
+  "exports": {
+    ".": "./src/index.js",
+    "./client": "./src/client.js"
+  },
+  "dependencies": {
+    "ws": "^8.14.0"
+  }
+}

package/src/client.js

@@ -0,0 +1,150 @@
+class StelarClient {
+  constructor(urlOrPort = 'localhost:3000', options = {}) {
+    if (typeof urlOrPort === 'number') {
+      this.url = `ws://localhost:${urlOrPort}`;
+    } else if (urlOrPort.includes('://')) {
+      this.url = urlOrPort.startsWith('http') ? 'ws' + urlOrPort.slice(4) : urlOrPort;
+    } else {
+      this.url = `ws://${urlOrPort}`;
+    }
+
+    this.options = {
+      reconnection: options.reconnection !== false,
+      reconnectionAttempts: options.reconnectionAttempts || 5,
+      reconnectionDelay: options.reconnectionDelay || 1000,
+      heartbeatInterval: options.heartbeatInterval || 30000
+    };
+
+    this.ws = null;
+    this.events = {};
+    this._wildcardHandler = null;
+    this.connected = false;
+    this.id = null;
+    this._reconnectAttempts = 0;
+    this._hbTimer = null;
+    this._isManualClose = false;
+  }
+
+  setUrl(url) {
+    this.url = url;
+    return this;
+  }
+
+  on(event, handler) {
+    this.events[event] = handler;
+    return this;
+  }
+
+  onAll(handler) {
+    this._wildcardHandler = handler;
+    return this;
+  }
+
+  emit(event, data) {
+    if (this.ws && this.ws.readyState === WebSocket.OPEN) {
+      this.ws.send(JSON.stringify({ event, data }));
+    }
+    return this;
+  }
+
+  joinRoom(room) {
+    this.emit('join-room', room);
+    return this;
+  }
+
+  leaveRoom() {
+    this.emit('leave-room', {});
+    return this;
+  }
+
+  _startHeartbeat() {
+    this._hbTimer = setInterval(() => {
+      if (this.ws && this.ws.readyState === WebSocket.OPEN) {
+        this.emit('pong', Date.now());
+      }
+    }, this.options.heartbeatInterval);
+  }
+
+  _stopHeartbeat() {
+    if (this._hbTimer) {
+      clearInterval(this._hbTimer);
+      this._hbTimer = null;
+    }
+  }
+
+  _connect() {
+    this._isManualClose = false;
+    this.ws = new WebSocket(this.url);
+
+    this.ws.onopen = () => {
+      this.connected = true;
+      this._reconnectAttempts = 0;
+      if (this.events['connect']) this.events['connect']();
+      this._startHeartbeat();
+    };
+
+    this.ws.onmessage = (e) => {
+      try {
+        const msg = JSON.parse(e.data);
+        const { event, data } = msg;
+
+        if (event === 'ping') return;
+
+        if (this.events[event]) this.events[event](data);
+
+        if (this._wildcardHandler) {
+          this._wildcardHandler({ event, data });
+        }
+      } catch (err) {}
+    };
+
+    this.ws.onclose = () => {
+      this.connected = false;
+      this._stopHeartbeat();
+      if (this.events['disconnect']) this.events['disconnect']();
+
+      if (!this._isManualClose && this.options.reconnection && this._reconnectAttempts < this.options.reconnectionAttempts) {
+        this._reconnectAttempts++;
+        if (this.events['reconnecting']) this.events['reconnecting'](this._reconnectAttempts);
+        setTimeout(() => this._connect(), this.options.reconnectionDelay * this._reconnectAttempts);
+      }
+    };
+
+    this.ws.onerror = (err) => {
+      if (this.events['error']) this.events['error'](err);
+    };
+
+    return this;
+  }
+
+  connect(callback) {
+    this._connect();
+    if (callback) {
+      const checkConnection = setInterval(() => {
+        if (this.connected) {
+          clearInterval(checkConnection);
+          callback();
+        }
+      }, 100);
+    }
+    return this;
+  }
+
+  disconnect() {
+    this._isManualClose = true;
+    this._stopHeartbeat();
+    if (this.ws) this.ws.close();
+    return this;
+  }
+
+  isConnected() {
+    return this.connected;
+  }
+
+  getUrl() {
+    return this.url;
+  }
+}
+
+if (typeof window !== 'undefined') window.StelarClient = StelarClient;
+export default StelarClient;

package/src/index.js

@@ -0,0 +1,219 @@
+import { createServer } from 'http';
+import { WebSocketServer } from 'ws';
+
+class StelarServer {
+  constructor(options = {}) {
+    this.port = options.port || 3000;
+    this.server = options.server || null;
+    this.wss = null;
+    this.clients = new Map();
+    this.events = {};
+    this.middlewares = [];
+    this.heartbeatInterval = options.heartbeatInterval || 30000;
+    this._hbTimer = null;
+    this._wildcardHandler = null;
+    this._connectionHandler = null;
+  }
+
+  use(middleware) {
+    this.middlewares.push(middleware);
+    return this;
+  }
+
+  on(event, handler) {
+    this.events[event] = handler;
+    return this;
+  }
+
+  onAll(handler) {
+    this._wildcardHandler = handler;
+    return this;
+  }
+
+  onConnection(handler) {
+    this._connectionHandler = handler;
+    return this;
+  }
+
+  broadcast(event, data) {
+    this.clients.forEach((info, client) => {
+      client.send(JSON.stringify({ event, data }));
+    });
+    return this;
+  }
+
+  to(room, event, data) {
+    this.clients.forEach((info, client) => {
+      if (info.room === room) {
+        client.send(JSON.stringify({ event, data }));
+      }
+    });
+    return this;
+  }
+
+  toId(id, event, data) {
+    this.clients.forEach((info, client) => {
+      if (info.id === id) {
+        client.send(JSON.stringify({ event, data }));
+      }
+    });
+    return this;
+  }
+
+  getClients(room) {
+    const list = [];
+    this.clients.forEach((info, client) => {
+      if (!room || info.room === room) list.push({ id: info.id, room: info.room });
+    });
+    return list;
+  }
+
+  getPort() {
+    const address = this.server?.address();
+    if (address && typeof address === 'object') {
+      return address.port;
+    }
+    return this.port;
+  }
+
+  _runMiddlewares(ctx, next) {
+    const run = (i) => {
+      if (i >= this.middlewares.length) return next();
+      this.middlewares[i](ctx, () => run(i + 1));
+    };
+    run(0);
+  }
+
+  _startHeartbeat() {
+    this._hbTimer = setInterval(() => {
+      this.clients.forEach((info, client) => {
+        if (info.lastPing && Date.now() - info.lastPing > this.heartbeatInterval * 2) {
+          client.close();
+          this.clients.delete(client);
+        } else {
+          client.send(JSON.stringify({ event: 'ping', data: Date.now() }));
+        }
+      });
+    }, this.heartbeatInterval);
+  }
+
+  _handleConnection(client, req) {
+    const clientId = Math.random().toString(36).substring(7);
+    const clientInfo = { id: clientId, room: null, lastPing: Date.now() };
+    this.clients.set(client, clientInfo);
+
+    const ctx = {
+      id: clientId,
+      socket: client,
+      req,
+      emit: (evt, d) => client.send(JSON.stringify({ event: evt, data: d })),
+      broadcast: (evt, d) => this.broadcast(evt, d),
+      to: (room, evt, d) => this.to(room, evt, d),
+      toId: (id, evt, d) => this.toId(id, evt, d),
+      getClients: (room) => this.getClients(room),
+      joinRoom: (room) => {
+        clientInfo.room = room;
+        client.send(JSON.stringify({ event: 'joined-room', data: room }));
+      },
+      leaveRoom: () => {
+        clientInfo.room = null;
+      }
+    };
+
+    this._runMiddlewares(ctx, () => {
+      if (this._connectionHandler) {
+        this._connectionHandler(ctx);
+      }
+    });
+
+    client.on('message', (raw) => {
+      try {
+        const msg = JSON.parse(raw);
+        const { event, data } = msg;
+
+        if (event === 'pong') {
+          clientInfo.lastPing = Date.now();
+          return;
+        }
+
+        if (event === 'join-room') {
+          clientInfo.room = data;
+          client.send(JSON.stringify({ event: 'joined-room', data }));
+        }
+
+        if (event === 'leave-room') {
+          clientInfo.room = null;
+          client.send(JSON.stringify({ event: 'left-room', data }));
+        }
+
+        const eventCtx = { ...ctx, data };
+
+        if (this.events[event]) {
+          this.events[event](eventCtx);
+        }
+
+        if (this._wildcardHandler) {
+          this._wildcardHandler({ event, data: eventCtx });
+        }
+      } catch (e) {}
+    });
+
+    client.on('close', () => {
+      this.clients.delete(client);
+    });
+
+    client.on('error', (err) => {
+      if (this.events['error']) {
+        this.events['error']({ id: clientId, error: err });
+      }
+    });
+  }
+
+  start(callback) {
+    return new Promise((resolve) => {
+      const startServer = (httpServer) => {
+        this.server = httpServer;
+        this.wss = new WebSocketServer({ server: httpServer });
+        this.wss.on('connection', (client, req) => this._handleConnection(client, req));
+        this._startHeartbeat();
+        
+        const finalPort = this.getPort();
+        if (callback) callback(finalPort);
+        resolve(finalPort);
+      };
+
+      if (this.server) {
+        startServer(this.server);
+      } else {
+        const tryListen = (port) => {
+          this.server = createServer((req, res) => {
+            res.writeHead(200, { 'Content-Type': 'text/plain' });
+            res.end('Stelar Time Real Server');
+          });
+
+          this.server.on('error', (err) => {
+            if (err.code === 'EADDRINUSE' && port < 65535) {
+              tryListen(port + 1);
+            }
+          });
+
+          this.server.listen(port, () => {
+            this.port = port;
+            startServer(this.server);
+          });
+        };
+        tryListen(this.port);
+      }
+    });
+  }
+
+  stop() {
+    if (this._hbTimer) clearInterval(this._hbTimer);
+    if (this.wss) this.wss.close();
+    if (this.server && !this._externalServer) this.server.close();
+    return this;
+  }
+}
+
+export default StelarServer;
+export { StelarServer };