stelar-time-real 1.0.3 → 1.2.0

package/README.md

@@ -13,6 +13,9 @@ 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
+- 📦 **Binarios** - Envía imágenes, archivos, audio, video sin overhead de base64
 
 ## Instalación
 
@@ -190,15 +193,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);
 });
 ```
 
@@ -255,11 +321,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)`**
@@ -414,6 +501,49 @@ client.on('reconnecting', (attempt) => console.log(`Reintentando ${attempt}/5`))
 client.connect();
 ```
 
+### Enviar Archivos Binarios
+
+```javascript
+// Servidor - recibir imagen
+stelar.on('image', (ctx) => {
+  // ctx.buffer es un Uint8Array
+  console.log('Recibido:', ctx.buffer.byteLength, 'bytes');
+  // Guardar o procesar la imagen
+  saveImage(ctx.buffer);
+
+  // Responder al cliente
+  ctx.emit('imageSaved', { success: true });
+});
+
+// Cliente - enviar imagen
+const input = document.querySelector('input[type="file"]');
+input.addEventListener('change', async (e) => {
+  const file = e.target.files[0];
+  const buffer = await file.arrayBuffer();
+  client.emitBinary('image', buffer);
+});
+
+// Cliente - recibir imagen
+client.on('image', (buffer) => {
+  const blob = new Blob([buffer], { type: 'image/png' });
+  const url = URL.createObjectURL(blob);
+  document.getElementById('img').src = url;
+});
+```
+
+### Broadcast de Binarios
+
+```javascript
+// Servidor - compartir archivo con todos
+stelar.on('upload', (ctx) => {
+  ctx.broadcastBinary('file', ctx.buffer);
+});
+
+// Cliente - enviar archivo
+const fileData = await file.arrayBuffer();
+client.emitBinary('upload', fileData);
+```
+
 ---
 
 ## Diferencia con Socket.io
@@ -428,6 +558,17 @@ client.connect();
 
 ## Changelog
 
+### v1.2.0
+- Soporte binarios: envía imágenes, archivos, audio, video sin base64
+- `ctx.emitBinary('event', buffer)` y `client.emitBinary('event', buffer)`
+- `client.sendFile(file)` y `client.sendImage(blob)`
+- Eficiente: usa WebSocket binary diretamente, sin overhead
+
+### 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'`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stelar-time-real",
-  "version": "1.0.3",
+  "version": "1.2.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,86 @@ 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;
+  }
+
+  emitBinary(event, data) {
+    if (this.ws && this.ws.readyState === WebSocket.OPEN) {
+      const header = JSON.stringify({ event });
+      const headerBytes = new TextEncoder().encode(header);
+      const combined = new Uint8Array(headerBytes.length + 1 + data.byteLength);
+      combined.set(headerBytes, 0);
+      combined[headerBytes.length] = 0;
+      combined.set(new Uint8Array(data), headerBytes.length + 1);
+      this.ws.send(combined);
+    }
+    return this;
+  }
+
+  sendFile(file) {
+    return this.emitBinary('file', file);
+  }
+
+  sendImage(blob) {
+    return this.emitBinary('image', blob);
+  }
+
+  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) {
@@ -83,13 +164,44 @@ class StelarClient {
       this._startHeartbeat();
     };
 
+    this.ws.binaryType = 'arraybuffer';
+
     this.ws.onmessage = (e) => {
       try {
+        if (e.data instanceof ArrayBuffer) {
+          const view = new Uint8Array(e.data);
+          let headerEnd = -1;
+          for (let i = 0; i < view.length; i++) {
+            if (view[i] === 0) {
+              headerEnd = i;
+              break;
+            }
+          }
+          if (headerEnd === -1) return;
+
+          const headerStr = new TextDecoder().decode(view.slice(0, headerEnd));
+          const header = JSON.parse(headerStr);
+          const buffer = view.slice(headerEnd + 1);
+
+          if (this.events[header.event]) {
+            this.events[header.event](buffer);
+          }
+          if (this._wildcardHandler) {
+            this._wildcardHandler({ event: header.event, data: buffer, buffer, isBinary: true });
+          }
+          return;
+        }
+
         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 }));
@@ -42,6 +57,20 @@ class StelarServer {
     return this;
   }
 
+  broadcastBinary(event, buffer) {
+    const header = JSON.stringify({ event, _binary: true });
+    const headerBytes = new TextEncoder().encode(header);
+    const combined = new Uint8Array(headerBytes.length + 1 + buffer.byteLength);
+    combined.set(headerBytes, 0);
+    combined[headerBytes.length] = 0;
+    combined.set(new Uint8Array(buffer), headerBytes.length + 1);
+
+    this.clients.forEach((info, client) => {
+      client.send(combined);
+    });
+    return this;
+  }
+
   to(room, event, data) {
     this.clients.forEach((info, client) => {
       if (info.room === room) {
@@ -98,6 +127,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,7 +144,10 @@ 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 })),
+      emitBinary: (evt, buffer) => client.send(buffer),
       broadcast: (evt, d) => this.broadcast(evt, d),
+      broadcastBinary: (evt, buffer) => this.broadcastBinary(evt, buffer),
       to: (room, evt, d) => this.to(room, evt, d),
       toId: (id, evt, d) => this.toId(id, evt, d),
       getClients: (room) => this.getClients(room),
@@ -117,6 +157,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 }));
+          }
+        }
       }
     };
 
@@ -126,7 +175,35 @@ class StelarServer {
       }
     });
 
-    client.on('message', (raw) => {
+    client.on('message', (raw, isBinary) => {
+      if (isBinary) {
+        try {
+          const view = new Uint8Array(raw);
+          let headerEnd = -1;
+          for (let i = 0; i < view.length; i++) {
+            if (view[i] === 0) {
+              headerEnd = i;
+              break;
+            }
+          }
+          if (headerEnd === -1) return;
+
+          const headerStr = new TextDecoder().decode(view.slice(0, headerEnd));
+          const header = JSON.parse(headerStr);
+          const data = view.slice(headerEnd + 1);
+
+          const eventCtx = { ...ctx, data, buffer: data, isBinary: true };
+
+          if (this.events[header.event]) {
+            this.events[header.event](eventCtx);
+          }
+          if (this._wildcardHandler) {
+            this._wildcardHandler({ event: header.event, data: eventCtx });
+          }
+        } catch (e) {}
+        return;
+      }
+
       try {
         const msg = JSON.parse(raw);
         const { event, data } = msg;
@@ -146,6 +223,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]) {