stelar-time-real 1.0.2 → 1.1.0

package/README.md

@@ -13,6 +13,8 @@ Tu propio sistema de tiempo real personalizado. Una librería ligera y sin depen
 - 🎯 **Personalizable** - Vos controlás todo, nada de código ajeno
 - 🔌 **Compatible** - Funciona con Express, Fastify, HTTP nativo, etc.
 - 💓 **Heartbeat incluido** - Detecta desconexiones automáticamente
+- 🌐 **Namespaces** - Múltiples canales independientes (`/chat`, `/game`, etc.)
+- ⚡ **ACK ultra rápido** - Request-response con Promesas, sin overhead
 
 ## Instalación
 
@@ -22,11 +24,17 @@ npm install stelar-time-real
 
 ## Inicio Rápido
 
+### Un solo import para todo
+
+```javascript
+import StelarServer, { StelarClient } from 'stelar-time-real';
+```
+
 ### Servidor
 
 ```javascript
 import express from 'express';
-import StelarServer from 'stelar-time-real';
+import { StelarServer } from 'stelar-time-real';
 
 const app = express();
 const server = app.listen(3000);
@@ -48,7 +56,7 @@ stelar.start();
 ### Cliente
 
 ```javascript
-import StelarClient from 'stelar-time-real/client';
+import { StelarClient } from 'stelar-time-real';
 
 const client = new StelarClient('localhost:3000');
 
@@ -184,15 +192,78 @@ stelar.on('mensaje', (ctx) => {
   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.send('respuesta', data)  // Responder a un ACK
   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
+  ctx.ack('miAck', data)     // Responder a un ACK personalizado
+});
+```
+
+#### Namespaces
+
+Crear canales independientes:
+
+```javascript
+import { StelarServer } from 'stelar-time-real';
+
+// Namespace principal
+const main = new StelarServer({ server, namespace: '/' });
+
+// Namespace de chat
+const chat = StelarServer.of('/chat', { server });
+chat.on('message', (ctx) => {
+  ctx.broadcast('message', ctx.data);
+});
+
+// Namespace de game
+const game = StelarServer.of('/game', { server });
+game.on('move', (ctx) => {
+  ctx.to(ctx.data.room, 'move', ctx.data);
+});
+```
+
+#### ACK (Request-Response)
+
+Sistema ultra eficiente con Promesas:
+
+**Servidor:**
+
+```javascript
+// Registrar un ACK handler
+stelar.onAck('getUser', (ctx) => {
+  return { id: ctx.data.id, name: 'John' };
+});
+
+// O con lógica más compleja
+stelar.onAck('saveData', (ctx) => {
+  const result = saveToDatabase(ctx.data);
+  return { success: true, id: result.id };
+});
+```
+
+**Cliente:**
+
+```javascript
+// Usando request() - retorna Promise
+const user = await client.request('getUser', { id: 1 }, 'userData');
+console.log(user); // { id: 1, name: 'John' }
+
+// O emitiendo con callback
+client.emit('getUser', { id: 1 }, { ack: 'userData' });
+client.on('userData', (data) => {
+  console.log(data);
+});
+
+// ACK desde el servidor al cliente
+client.onAck('serverPush', (data) => {
+  console.log('El servidor envió:', data);
 });
 ```
 
@@ -249,11 +320,32 @@ client.onAll(({ event, data }) => {
 });
 ```
 
-**`.emit(event, data)`**
-Enviar eventos al servidor.
+**`.onAck(name, handler)`**
+Escuchar respuestas de ACK del servidor.
+
+```javascript
+client.onAck('userData', (data) => {
+  console.log('Datos recibidos:', data);
+});
+```
+
+**`.emit(event, data, opts)`**
+Enviar eventos al servidor. Soporta `opts.ack` para ACKs.
 
 ```javascript
 client.emit('chat', { mensaje: 'Hola!' });
+client.emit('getUser', { id: 1 }, { ack: 'userData' });
+```
+
+**`.request(event, data, ackName)`**
+Enviar y esperar respuesta como Promise.
+
+```javascript
+const result = await client.request('getUser', { id: 1 }, 'userData');
+console.log(result); // { id: 1, name: 'John' }
+
+// Con timeout opcional
+const client = new StelarClient(3000, { ackTimeout: 10000 });
 ```
 
 **`.joinRoom(room)`**
@@ -320,7 +412,7 @@ client.on('error', (err) => {});      // Cuando hay error
 **server.js**
 ```javascript
 import express from 'express';
-import StelarServer from 'stelar-time-real';
+import { StelarServer } from 'stelar-time-real';
 
 const app = express();
 const server = app.listen(3000);
@@ -342,7 +434,7 @@ console.log('Chat en http://localhost:3000');
 **cliente.html**
 ```html
 <script type="module">
-  import StelarClient from 'stelar-time-real/client.js';
+  import { StelarClient } from 'stelar-time-real';
 
   const client = new StelarClient(3000);
 
@@ -393,6 +485,8 @@ stelar.use((ctx, next) => {
 ### Con Reconexión Automática
 
 ```javascript
+import { StelarClient } from 'stelar-time-real';
+
 const client = new StelarClient('localhost:3000', {
   reconnection: true,
   reconnectionAttempts: 5,
@@ -420,6 +514,18 @@ client.connect();
 
 ## Changelog
 
+### v1.1.0
+- Namespaces: `StelarServer.of('/chat')` para múltiples canales
+- ACK personalizado: `ctx.ack('nombre', data)` y `client.request(event, data, 'ackName')`
+- Sistema de request-response con Promesas, ultra eficiente
+
+### v1.0.3
+- Exportación mejorada: un solo import para servidor y cliente
+- `import { StelarServer, StelarClient } from 'stelar-time-real'`
+
+### v1.0.2
+- Exportación mejorada: un solo import para servidor y cliente
+
 ### v1.0.0
 - Lanzamiento inicial
 - WebSockets con ws

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stelar-time-real",
-  "version": "1.0.2",
+  "version": "1.1.0",
   "description": "Tu propio sistema de tiempo real personalizado - WebSocket ligero sin dependencias",
   "main": "src/index.js",
   "type": "module",

package/src/client.js

@@ -12,7 +12,8 @@ class StelarClient {
       reconnection: options.reconnection !== false,
       reconnectionAttempts: options.reconnectionAttempts || 5,
       reconnectionDelay: options.reconnectionDelay || 1000,
-      heartbeatInterval: options.heartbeatInterval || 30000
+      heartbeatInterval: options.heartbeatInterval || 30000,
+      ackTimeout: options.ackTimeout || 5000
     };
 
     this.ws = null;
@@ -23,6 +24,65 @@ class StelarClient {
     this._reconnectAttempts = 0;
     this._hbTimer = null;
     this._isManualClose = false;
+    this._acks = {};
+  }
+
+  setUrl(url) {
+    this.url = url;
+    return this;
+  }
+
+  on(event, handler) {
+    this.events[event] = handler;
+    return this;
+  }
+
+  onAll(handler) {
+    this._wildcardHandler = handler;
+    return this;
+  }
+
+  onAck(name, handler) {
+    this._acks[name] = handler;
+    return this;
+  }
+
+  emit(event, data, opts = {}) {
+    if (this.ws && this.ws.readyState === WebSocket.OPEN) {
+      const payload = { event, data };
+      if (opts.ack) {
+        payload._ackName = opts.ack;
+      }
+      this.ws.send(JSON.stringify(payload));
+    }
+    return this;
+  }
+
+  request(event, data, ackName) {
+    return new Promise((resolve, reject) => {
+      const timeout = setTimeout(() => {
+        reject(new Error(`ACK '${ackName}' timeout`));
+      }, this.options.ackTimeout);
+
+      const handler = (responseData) => {
+        clearTimeout(timeout);
+        this.off(ackName, handler);
+        resolve(responseData);
+      };
+
+      this.on(ackName, handler);
+      this.emit(event, data, { ack: ackName });
+    });
+  }
+
+  joinRoom(room) {
+    this.emit('join-room', room);
+    return this;
+  }
+
+  leaveRoom() {
+    this.emit('leave-room', {});
+    return this;
   }
 
   setUrl(url) {
@@ -86,10 +146,15 @@ class StelarClient {
     this.ws.onmessage = (e) => {
       try {
         const msg = JSON.parse(e.data);
-        const { event, data } = msg;
+        const { event, data, _isAck } = msg;
 
         if (event === 'ping') return;
 
+        if (_isAck && this._acks[event]) {
+          this._acks[event](data);
+          return;
+        }
+
         if (this.events[event]) this.events[event](data);
 
         if (this._wildcardHandler) {

package/src/index.js

@@ -5,6 +5,7 @@ class StelarServer {
   constructor(options = {}) {
     this.port = options.port || 3000;
     this.server = options.server || null;
+    this.namespace = options.namespace || '/';
     this.wss = null;
     this.clients = new Map();
     this.events = {};
@@ -13,6 +14,15 @@ class StelarServer {
     this._hbTimer = null;
     this._wildcardHandler = null;
     this._connectionHandler = null;
+    this._acks = {};
+    this._parent = null;
+    this._children = new Map();
+  }
+
+  static of(path, options = {}) {
+    const ns = new StelarServer({ ...options, namespace: path });
+    ns._parent = this;
+    return ns;
   }
 
   use(middleware) {
@@ -35,6 +45,11 @@ class StelarServer {
     return this;
   }
 
+  onAck(name, handler) {
+    this._acks[name] = handler;
+    return this;
+  }
+
   broadcast(event, data) {
     this.clients.forEach((info, client) => {
       client.send(JSON.stringify({ event, data }));
@@ -98,6 +113,14 @@ class StelarServer {
   }
 
   _handleConnection(client, req) {
+    const urlPath = new URL(req.url, `http://localhost`).pathname;
+    const nsPath = this.namespace === '/' ? '/' : this.namespace;
+
+    if (nsPath !== '/' && urlPath !== nsPath) {
+      client.close();
+      return;
+    }
+
     const clientId = Math.random().toString(36).substring(7);
     const clientInfo = { id: clientId, room: null, lastPing: Date.now() };
     this.clients.set(client, clientInfo);
@@ -107,6 +130,7 @@ class StelarServer {
       socket: client,
       req,
       emit: (evt, d) => client.send(JSON.stringify({ event: evt, data: d })),
+      send: (respId, d) => client.send(JSON.stringify({ event: respId, data: d, _isAck: true })),
       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),
@@ -117,6 +141,15 @@ class StelarServer {
       },
       leaveRoom: () => {
         clientInfo.room = null;
+      },
+      ack: (ackName, data) => {
+        const ackHandler = this._acks[ackName];
+        if (ackHandler) {
+          const result = ackHandler({ ...ctx, data });
+          if (result !== undefined) {
+            client.send(JSON.stringify({ event: ackName, data: result, _isAck: true }));
+          }
+        }
       }
     };
 
@@ -146,6 +179,15 @@ class StelarServer {
           client.send(JSON.stringify({ event: 'left-room', data }));
         }
 
+        if (msg._ackName && this._acks[msg._ackName]) {
+          const ackHandler = this._acks[msg._ackName];
+          const result = ackHandler({ ...ctx, data });
+          if (result !== undefined) {
+            client.send(JSON.stringify({ event: msg._ackName, data: result, _isAck: true }));
+          }
+          return;
+        }
+
         const eventCtx = { ...ctx, data };
 
         if (this.events[event]) {