@solid-primitives/websocket


Primitive to help establish, maintain and operate a websocket connection.

- makeWS - sets up a web socket connection with a buffered send
- createWS - sets up a web socket connection that disconnects on cleanup
- createWSState - creates a reactive signal containing the readyState of a websocket
- makeReconnectingWS - sets up a web socket connection that reconnects if involuntarily closed
- createReconnectingWS - sets up a reconnecting web socket connection that disconnects on cleanup
- makeHeartbeatWS - wraps a reconnecting web socket to send a heart beat and reconnect if the answer fails

All of them return a WebSocket instance extended with a message prop containing an accessor for the last received message for convenience and the ability to receive messages to send before the connection is opened.

How to use it

``ts
const ws = createWS("ws://localhost:5000");
const state = createWSState(ws);
const states = ["Connecting", "Connected", "Disconnecting", "Disconnected"];
ws.send("it works");
createEffect(on(ws.message, msg => console.log(msg), { defer: true }));
return

Connection: {states[state()]}

const socket = makeHeartbeatWS(
makeReconnectingWS(ws://${location.hostName}/api/ws, undefined, { timeout: 500 }),
{ message: "👍" },
);
// with the primitives starting with make..., one needs to manually clean up:
socket.send("this will reconnect if connection fails");
`

$3

`ts
/* Arguments of the primitives /
type WSProps = [url: string, protocols?: string | string[]];
type WSMessage = string | ArrayBufferLike | ArrayBufferView | Blob;
type WSReadyState = WebSocket.CONNECTING | WebSocket.OPEN | WebSocket.CLOSING | WebSocket.CLOSED;
type WSEventMap = {
close: CloseEvent;
error: Event;
message: MessageEvent;
open: Event;
};
type ReconnectingWebSocket = WebSocket & {
reconnect: () => void;
// ws.send.before is meant to be used by heartbeat
send: ((msg: WSMessage) => void) & { before: () => void };
};
type WSHeartbeatOptions = {
/**
* Heartbeat message being sent to the server in order to validate the connection
* @default "ping"
*/
message?: WSMessage;
/**
* The time between messages being sent in milliseconds
* @default 1000
*/
interval?: number;
/**
* The time after the heartbeat message being sent to wait for the next message in milliseconds
* @default 1500
*/
wait?: number;
};
`

If you want to use the messages as a signal, have a look at the event-listener package:

`ts
import { createWS } from "@solid-primitives/websocket";
import { createEventSignal } from "@solid-primitives/event-listener";

const ws = createWS("ws://localhost:5000");
const messageEvent = createEventSignal(ws, "message");
const message = () => messageEvent().data;
`

Otherwise, you can simply use the message event to get message.data:

`ts
import { createStore } from "solid-js/store";
import { createReconnectingWS, WSMessage } from "@solid-primitives/websocket";

const ws = createReconnectingWS("ws://localhost:5000");
const [messages, setMessages] = createStore();
ws.addEventListener("message", (ev) => setMessages(messages.length, ev.data));

messages}>
{(message) => ...}

`

Setting up a websocket server

While you can use this primitive with solid-start, it already provides a package for websockets that handles both the server and the client side:

`ts
import { createWebSocketServer } from "solid-start/websocket";
import server$ from "solid-start/server";

const pingPong = createWebSocketServer(
server$(function (webSocket) {
webSocket.addEventListener("message", async msg => {
try {
// Parse the incoming message
let incomingMessage = JSON.parse(msg.data);
console.log(incomingMessage);

switch (incomingMessage.type) {
case "ping":
webSocket.send(
JSON.stringify([
{
type: "pong",
data: {
id: incomingMessage.data.id,
time: Date.now(),
},
},
]),
);
break;
}
} catch (err: any) {
// Report any exceptions directly back to the client. As with our handleErrors() this
// probably isn't what you'd want to do in production, but it's convenient when testing.
webSocket.send(JSON.stringify({ error: err.stack }));
}
});
}),
);
`

Otherwise, in order to set up your own production-use websocket server, we recommend packages like

- nodejs: ws
- rust: websocket`

Demo

You may view a working example here:
https://primitives.solidjs.community/playground/websocket/

Changelog

See CHANGELOG.md