createSocketClient

createSocketClient abre un WebSocket a un canal Socket con una URL y un contrato explícitos. Valida cada evento que envía y cada uno que recibe con los schemas del contrato, se reconecta solo con retroceso exponencial y expone su estado como una señal. La entrega es como mucho una vez: emit rechaza si no hay conexión, sin cola ni reenvío.

No está ligado a ningún componente: hay que cerrarlo con close(). Dentro de un componente, usa useSocketClient, que lo cierra al desmontarse; en una aplicación, lo habitual es el autoimport useSocket("chat") o socket.chat, que ya conocen la URL y el contrato de cada canal.

Uso#

import { createSocketClient } from "@meekojs/meeko/framework";
import type { Schema } from "@meekojs/meeko/server";

const message: Schema<{ text: string }> = {
  "~standard": {
    version: 1,
    validate: (value) => typeof value === "object" && value !== null && typeof (value as { text?: unknown }).text === "string"
      ? { value: value as { text: string } }
      : { issues: [{ message: "Se esperaba { text }" }] },
  },
};
const chatContract = { clientToServer: { message }, serverToClient: { message } };

const chat = createSocketClient("wss://example.com/_meeko/socket/chat?room=general", chatContract, {
  onError: (error) => console.warn("socket", error),
});
const stop = chat.on("message", (data) => console.log(data.text));
// Más tarde, con el socket abierto:
await chat.emit("message", { text: "Hola" });
stop();
chat.close();

Tipo#

function createSocketClient<C extends SocketContract>(
  url: string,
  contract: C,
  options?: SocketClientOptions,
): SocketClient<C>

interface SocketClientOptions {
	readonly retryMs?: number
	readonly maxRetryMs?: number
	readonly maxMessageBytes?: number
	readonly webSocketFactory?: (url: string) => WebSocket
	readonly onError?: (error: unknown) => void
}

interface SocketClient<C extends SocketContract> {
  readonly state: ReadonlySignal<SocketClientState>;
  emit<K extends keyof C["clientToServer"] & string>(
    event: K,
    data: SchemaInput<C["clientToServer"][K]>,
  ): Promise<void>;
  on<K extends keyof C["serverToClient"] & string>(
    event: K,
    listener: (data: SchemaOutput<C["serverToClient"][K]>) => void,
  ): () => void;
  close(): void;
}

interface SocketContract<
  ClientToServer extends Events = Events,
  ServerToClient extends Events = Events,
> {
  readonly clientToServer: ClientToServer;
  readonly serverToClient: ServerToClient;
}

Parámetros#

Valor devuelto#

Un SocketClient tipado por el contrato:

La URL se pasa tal cual a new WebSocket(url): una URL que el WebSocket del runtime no acepta lanza su error al crear el cliente.

Ejemplos#

Esperar a que abra antes de enviar#

import { effect } from "@meekojs/meeko";

effect(() => {
  if (chat.state.value === "open") void chat.emit("message", { text: "conectado" });
  if (chat.state.value === "unauthorized") location.assign("/login");
});

state es una señal: un effect (o la plantilla de un componente) se actualiza con cada cambio.

Una prueba con un WebSocket falso#

import { createSocketClient } from "@meekojs/meeko/framework";
import type { Schema } from "@meekojs/meeko/server";

class FakeSocket extends EventTarget {
  readyState: number = WebSocket.CONNECTING;
  sent: string[] = [];
  send(value: string): void { this.sent.push(value); }
  close(): void { this.readyState = WebSocket.CLOSED; this.dispatchEvent(new Event("close")); }
  open(): void { this.readyState = WebSocket.OPEN; this.dispatchEvent(new Event("open")); }
}

const text: Schema<string> = { "~standard": { version: 1, validate: (value) => typeof value === "string" ? { value } : { issues: [{ message: "texto" }] } } };
const peer = new FakeSocket();
const client = createSocketClient("ws://localhost/chat", { clientToServer: { message: text }, serverToClient: { message: text } }, {
  webSocketFactory: () => peer as unknown as WebSocket,
});

await client.emit("message", "pronto").catch((error: Error) => console.log(error.message)); // Socket is disconnected
peer.open();
await client.emit("message", "hola");
console.log(peer.sent); // [ '{"event":"message","payload":"hola"}' ]
client.close();

Fuera de una aplicación Meeko#

// Un panel de administración que escucha los pedidos de la tienda
const orders = createSocketClient(`wss://tienda.example.com/_meeko/socket/orders?room=${storeId}`, ordersContract);
orders.on("created", (order) => addRow(order));
window.addEventListener("pagehide", () => orders.close());

El servidor comprueba Origin: un origen distinto del de la aplicación necesita estar en allowedOrigins del runtime.

Errores comunes#

Pasar el nombre del canal en lugar de su URL#

createSocketClient("chat", chatContract);

createSocketClient no conoce los canales de la aplicación: "chat" es una URL relativa. En Node, el WebSocket global lanza un DOMException con el mensaje TypeError: Invalid URL; con otro esquema, como ftp:, expected a ws: or wss: url.

createSocketClient(`${location.origin.replace(/^http/, "ws")}/_meeko/socket/chat`, chatContract);

Dentro de una aplicación, useSocket("chat") o socket.chat construyen la URL y conocen el contrato.

Enviar antes de que abra#

const chat = createSocketClient(url, chatContract);
await chat.emit("message", { text: "hola" });

Rechaza con Socket is disconnected: el socket todavía está en "connecting", y el cliente no encola mensajes.

const chat = createSocketClient(url, chatContract);
effect(() => { if (chat.state.value === "open") void chat.emit("message", { text: "hola" }); });

No cerrarlo#

function openChat() {
  const chat = createSocketClient(url, chatContract);
  chat.on("message", render);
}

Cada llamada deja un socket abierto que, además, se reconecta solo al caerse: las conexiones se acumulan hasta recargar la página.

function openChat() {
  const chat = createSocketClient(url, chatContract);
  chat.on("message", render);
  return () => chat.close();
}

Notas#

• Sólo en el navegador (o con webSocketFactory). En Node y en el SSR no hay WebSocket global que abrir.
• Seguridad. Los mensajes del servidor se validan con serverToClient antes de llegar a los listeners: un mensaje inválido se descarta y va a onError.
• Reconexión. Tras un corte, reintenta a los 500 ms, 1 s, 2 s… hasta 30 s. Los mensajes enviados mientras tanto se rechazan; reenvía tú lo que haga falta al volver a "open".
• Autorización. Un cierre 4401 o 4403 (o el 1008 de política del hub por la sesión) deja el estado en "unauthorized" para siempre: redirige al inicio de sesión y crea un cliente nuevo después.

Relacionado#

• useSocketClientCrea en un componente un cliente Socket con URL y contrato explícitos, que se cierra al desmontar el componente y usa su observador de errores.
• socketRegistro generado de los canales de server/socket, con on y emit tipados en el navegador y broadcast tipado en el servidor.
• useSocketConecta un componente a un canal de server/socket con sus eventos tipados y cierra la conexión al desmontarlo.
• defineSocketChannelDeclara un canal WebSocket de server/socket con los schemas de cada dirección, sus guardas por sala y evento y los handlers de los mensajes del cliente.
• createSocketUpgradeHandlerHandshake portable de Socket, que valida la ruta del canal, ejecuta las comprobaciones del hub y conecta al hub el WebSocket que abre el runtime.
• WebSocketMeeko como framework full-stack
• Clientes con URL y contrato explícitosMeeko como framework full-stack