Guía de WebSockets

Construye tiempo real con el plugin WebSocket oficial y los decoradores. Esta guía está alineada con las versiones actuales de veloce-ts (ver Registro de cambios).

Resumen

@WebSocket(path) — marca la clase como manejador para esa ruta.
@OnConnect / @OnMessage / @OnDisconnect — ciclo de vida.
WebSocketPlugin — registra rutas y hace el upgrade según el runtime (Bun / Deno).
WebSocketConnection — send, broadcast, join, leave, close, y acceso native al WebSocket.

Un solo @OnMessage por clase: los metadatos guardan un único manejador de mensajes (si declaras varios @OnMessage, gana el último). Modela distintos payloads del cliente con un esquema Zod (por ejemplo unión discriminada por un campo type).

Configuración

import 'reflect-metadata';
import {
  VeloceTS,
  WebSocketPlugin,
  WebSocket,
  OnConnect,
  OnMessage,
  OnDisconnect,
  WebSocketConnection,
} from 'veloce-ts';
import { z } from 'zod';

const ChatMessage = z.object({
  type: z.literal('chat'),
  text: z.string().min(1),
});

@WebSocket('/ws/chat')
class ChatSocket {
  @OnConnect()
  onOpen(client: WebSocketConnection) {
    client.join('lobby');
    client.send({ type: 'welcome', message: 'Conectado' });
  }

  @OnMessage(ChatMessage)
  onData(client: WebSocketConnection, msg: z.infer<typeof ChatMessage>) {
    client.broadcast({ type: 'chat', text: msg.text }, 'lobby');
  }

  @OnDisconnect()
  onClose(client: WebSocketConnection) {
    console.log('desconectado', client.id);
  }
}

const app = new VeloceTS({ title: 'Chat', version: '1.0.0' });
app.usePlugin(new WebSocketPlugin());
app.include(ChatSocket);
await app.compile();
app.listen(3000);

Notas de registro

Importa WebSocketPlugin desde veloce-ts (también en veloce-ts/plugins).
El constructor del plugin no acepta opciones; la ruta es siempre el argumento de @WebSocket('/ruta').
Llama a await app.compile() después de los include() para compilar metadatos.

`WebSocketConnection`

API	Uso
`id`	Identificador estable de la conexión
`send(data)`	Envía datos serializables a JSON a este cliente
`broadcast(data, room?)`	Envía a todas las conexiones de una sala, o a todas si omites `room`
`join(room)` / `leave(room)`	Entrar / salir de salas
`close(code?, reason?)`	Cierra el socket
`native`	Instancia `WebSocket` subyacente

Validación de mensajes

Un esquema Zod opcional en @OnMessage(Schema) valida cada mensaje JSON entrante. Si falla, el manager envía un objeto de error al cliente sin cerrar la conexión.

Ejemplos en el repositorio

El proyecto examples/chat-api (Bun) muestra REST + JWT + SQLite junto al flujo WebSocket, con notas sobre 426/501 cuando no hay upgrade (p. ej. pruebas con fetch).

Ver también

Limitaciones y hoja de ruta
Plugins
GraphQL — suscripciones experimentales; valida antes de producción.