@endeavorance/socket

Lightweight reconnecting websocket interface

ManagedSocket

new ManagedSocket(url: string, handlers?: EventHandlers): ManagedSocket

Create a new ManagedSocket instance and connect to the provided URL via WebSocket.

The provided URL should use the ws:// or wss:// protocol.

import { ManagedSocket } from "@endeavorance/socket";

const mySocket = new ManagedSocket("wss://socket.my-server.web", {
  onConnected: () => {},
  onMessage: (data: unknown) => {},
  onError: (error: SocketError) => {},
  onDisconnected: ({wasClean, code, reason}) => {},
});

.send<T>(data: T)

Sends the provided data over the socket.

The data can be of any shape as long as it can be serialized (using JSON.stringify under the hood).

If send() is called on a ManagedSocket instance that is not currently connected, it will be enqueued to be sent once the connection is reestablished.

const mySocket = new ManagedSocket("...");
mySocket.send("hello!");
mySocket.send({
  command: "do-something",
  args: ["hello", "world"],
});

.onMessage: SocketDataHandler

A function to invoke whenever the socket receives a message meant to be handled by your application.

This handler will be passed the blob of data contained within the message, which is typed as unknown.

Your handler function should parse the incoming data to ensure it is of the shape you expect.

const handler = (data: unknown) => {
  console.log("Got some data: " + data);
}

const mySocket = new ManagedSocket("...");
mySocket.onMessage = handler;

.onError: SocketErrorHandler

Provide a function to invoke when the socket encounters a non-catastrophic error.

Not catastrophic errors may occur during the lifecycle of the WebSocket connection, but are different from Catastrophic errors which only occur if the connection was terminated with a non-reconnect code.

This function will be passed a ManagedSocketError. If no error handler is set, errors will instead be thrown.

const errorHandler = (error: ManagedSocketError) => {
  console.error(error);
}

const mySocket = new ManagedSocket("...");
mySocket.onError = errorHandler;

.onConnected: SocketOpenHandler

Provide a function to be invoked when the connection is opened.

No arguments are provided to this handler.

.onDisconnected: SocketCloseHandler

Provide a function to be invoked when the connection closes cleanly.

No arguments are provided to this handler.

.close()

Safely close the socket connection.

Utilities

wrap<T>(data: T): SocketDataMessage

Wraps the provided data in a shape to be serialized and sent over the socket.

unwrap(message: SocketDataMessage): T

Unwraps the provided SocketDataMessage to extract the data contained within.

deserialize(data: string): SocketMessage

Attempts to deserialize the provided string into a SocketMessage. Throws a ManagedSocketError if the deserialization fails or the deserialized shape is invalid.