147 lines
4.8 KiB
Markdown
147 lines
4.8 KiB
Markdown
# @endeavorance/socket
|
|
|
|
Lightweight reconnecting websocket interface
|
|
|
|
## ManagedSocket
|
|
|
|
A self-reconnecting wrapped WebSocket with built-in heartbeats
|
|
|
|
### `new ManagedSocket(url: string): ManagedSocket`
|
|
|
|
Create a new `ManagedSocket` instance and connect to the provided URL via WebSocket.
|
|
|
|
The provided URL should use the `ws://` or `wss://` protocol.
|
|
|
|
```typescript
|
|
import { ManagedSocket } from "@endeavorance/socket";
|
|
|
|
const mySocket = new ManagedSocket("wss://socket.my-server.web");
|
|
```
|
|
|
|
|
|
### `.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.
|
|
|
|
```typescript
|
|
const mySocket = new ManagedSocket("...");
|
|
mySocket.send("hello!");
|
|
mySocket.send({
|
|
command: "do-something",
|
|
args: ["hello", "world"],
|
|
});
|
|
```
|
|
|
|
### `.onMessage(handler: SocketDataHandler)`
|
|
|
|
Provide 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.
|
|
|
|
```typescript
|
|
const handler = (data: unknown) => {
|
|
console.log("Got some data: " + data);
|
|
}
|
|
|
|
const mySocket = new ManagedSocket("...");
|
|
mySocket.onMessage(handler);
|
|
```
|
|
|
|
### `.onError(handler: 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.
|
|
|
|
```typescript
|
|
const errorHandler = (error: ManagedSocketError) => {
|
|
console.error(error);
|
|
}
|
|
|
|
const mySocket = new ManagedSocket("...");
|
|
mySocket.onError(handler);
|
|
```
|
|
|
|
### `.onCatastrophicError(handler: SocketCatastrophicErrorHandler)`
|
|
|
|
Provide a function to invoke when the socket is terminated with a non-reconnect code. When this handler is invoked, it means the socket connection is terminated and unable to be recovered automatically. Your handler will be passed the `SocketDisconnectCode` associated with the connection termination.
|
|
|
|
You may still attempt to manuall reconnect using the `.reconnect()` method, but it will not be automatic.
|
|
|
|
```typescript
|
|
const bigOops = (code) => {
|
|
console.error(`Welp, we're done here. Closed with code: ${code}`);
|
|
}
|
|
|
|
const mySocket = new ManagedSocket("...");
|
|
mySocket.onCatastrophicError(bigOops);
|
|
```
|
|
|
|
### `.onOpen(SocketOpenHandler)`
|
|
|
|
Provide a function to be invoked when the connection is opened.
|
|
|
|
No arguments are provided to this handler.
|
|
|
|
### `.onClose(SocketCloseHandler)`
|
|
|
|
Provide a function to be invoked when the connection closes cleanly.
|
|
|
|
No arguments are provided to this handler.
|
|
|
|
### `.reconnect()`
|
|
|
|
Attempts to reconnect the socket using an exponential backoff algorithm. Each failed connection attempt will wait a bit longer before the next try.
|
|
|
|
### `.close()`
|
|
|
|
Safely close the socket connection.
|
|
|
|
## `SocketSpeak`
|
|
|
|
`SocketSpeak` is a set of utilities for working with the `ManagedSocket` data interface. It is lower-level and meant primarily for writing servers.
|
|
|
|
All methods are defined on the `SocketSpeak` object, exported by the library.
|
|
|
|
```typescript
|
|
import { SocketSpeak } from "@endeavorance/socket"
|
|
```
|
|
|
|
### `createDataMessage<T>(data: T): SocketDataMessage`
|
|
|
|
Wraps the provided data in a well formatted message ready to serialize and send over the socket.
|
|
|
|
A `SocketDataMessage` is used for sending application data over the socket.
|
|
|
|
### `createHeartbeatMessage(): SocketHeartbeatMessage`
|
|
|
|
Creates a well formatted heartbeat message to serialize and send over the socket.
|
|
|
|
A `SocketHeartbeatMessage` is used internally to keep the connection alive and carries a data payload of the current timestamp as a string.
|
|
|
|
### `serialize(message: SocketMessage): SerializedSocketMessage`
|
|
|
|
Serialize any `SocketMessage`. Returns a `SerializedSocketMessage` which is a branded `string` type for type safety.
|
|
|
|
### `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.
|
|
|
|
Note: This is not to deserialize your application data messages. The managed socket handles wrapping and unwrapping messages before handing the payload to your application.
|
|
|
|
### `prepare<T>(data: T)`
|
|
|
|
Shorthand for `serialize(createDataMessage(data))
|
|
|
|
### `isCatastrophicCloseCode(code: SocketCloseCode)`
|
|
|
|
Returns `true` if the provided `SocketCloseCode` is a non-reconnect close code, or `false` otherwise.
|