phoenix-websocket

!NPM

> A custom implementation of the Channels API for communicating with an Elixir/Phoenix backend via WebSockets.

Full Documentation: https://inkarnaterpg.github.io/phoenix-websocket/

How this differs from the phoenix package

- Built with async/await.
- Allows defining multiple message handler functions that are called depending on the content of received messages.
- Opinionated in assuming the server will send pre-defined messages with variable payloads.
- Only supports the WebSocket protocol, does not have a LongPoll fallback.
- Does not include built in Presence support.
- Configurable timeout which can help avoid flooding the dev console with connection errors.
- Built with TypeScript and includes definitions without a second dependency.

Install

``
npm install phoenix-websocket
`

Usage

$3


First create a PhoenixWebsocket instance, normally you should only need one instance per backend endpoint, which can then be shared throughout your application.
`typescript
const socket = new PhoenixWebsocket("wss://example.io/channel-endpoint")
`

You can optionally pass in a params object to be included with the connection request.
`typescript
const socket = new PhoenixWebsocket("wss://example.io/channel-endpoint", { token: "auth-token" })
`

You can also optionally pass in a timeout value (in milliseconds), which can be helpful if you need a more or less aggressive connection retry, or if you want to avoid having connection errors flooding your development console while testing locally.
`typescript
const socket = new PhoenixWebsocket(
"wss://example.io/channel-endpoint",
{ token: "auth-token" },
process.env.NODE_ENV === 'development' ? (10006015) : (1000*30)
)
`

You may also wish to add callbacks for connected/disconnected events.
`typescript
socket.onConnectedCallback = () => {
// Do something when connected, such as updating the UI
}

socket.onDisconnectedCallback = () => {
// Do something when disconnected, such as updating the UI
}
`

$3

You can initiate the connection to the server by calling .connect() on your PhoenixWebsocket instance.

`typescript
socket.connect().then(() => {
//Connected!
})
`
Once .connect() is called, this library will continue attempting to keep the connection alive, and will automatically try to reconnect after any disconnections, until .disconnect() is called.

Note: Awaiting the .connect() promise and setting a .onConnectedCallback listener are both ways to learn when the connection is successfully opened. The difference is that .onConnectedCallback will also be called anytime a reconnection happens, and so it is recommended to use this callback for any UI updates.

$3

To send or receive messages, you'll first need to subscribe to a topic. The simplest way to do this is:
`typescript
socket.subscribeToTopic("exampleTopic")
`

To include a payload object with the request, pass it in as the second parameter:
`typescript
socket.subscribeToTopic("exampleTopic", {userId: "1"})
`

Calling .subscribeToTopic with one or two parameters will connect to the topic but will not include any way to handle messages or broadcasts received from the server. As such this method is only recommended when you intend to interact with the server purely in the Client -> Server direction. See the following section for instructions on handling server messages.

Note: Attempting to subscribe to the same topic twice will result in a warning being logged to the console, but otherwise no action will be taken and the original topic subscription will remain active. This differs from the behavior of the phoenix package which will rejoin a channel on subsequent subscription attempts. To rejoin a channel with this library, you must first explicitly leave it with .unsubscribeToTopic() before re-joining.

$3

To handle messages broadcast from the server, you can pass in callbacks to the .subscribeToTopic() function which are called when a message is received whose content matches one of the callbacks. This library currently makes the opinionated assumption that the messages you receive are predefined by the server, and any dynamic content is only included in the payload. In otherwords, messages are treated as event names while the payload can include any additional data for that event.

Callbacks are passed in as a single object containing key/value entries mapping a message to a callback. For example:
`typescript
socket.subscribeToTopic("exampleTopic", {userId: "1"},
{
user_joined: (payload) => { /* User joined! /},
user_left: (payload) => { /* User left! /},
}
)
`

$3

If the server responds to a join request with an 'error' status, the topic will not be added to your PhoenixWebsocket instance and the promise will be rejected with a PhoenixRespondedWithError error object. An example of handling a join error conditionally based on the message payload is:

`typescript
socket.subscribeToTopic("exampleTopic", {userId: "1"}).catch((error) => {
if (error instanceof PhoenixRespondedWithError) {
if (error.reply.response.reason === "Invalid User") {
// Do something
}
}
else {
console.error(error)
}
}
)
`

If you would like to also handle errors on rejoin attempts (rejoining happens automatically when the network connection is lost and restored, for example), you can pass a reconnectHandler to subscribeToTopic(). This handler function will be called with the connection promise of any rejoin attempt, and errors can be handled in the same way as the originally subscription promise by handling the promise's rejection.
`typescript
await socket.subscribeToTopic("exampleTopic", {userId: "1"}, undefined, (reconnectPromise) => {
// Will be called on any rejoin attempt, but NOT the initial join attempt, as that promise is already accessible by the return value of subscribeToTopic()
reconnectPromise.catch((error) => {
if (error instanceof PhoenixRespondedWithError) {
if (error.reply.response.reason === "Invalid User") {
// Do something
}
}
else {
console.error(error)
}
})
})
`

$3

To send a message to a subscribed topic, you can call .sendMessage() and optionally include a payload. To wait for and handle the server's response, you can await the promise returned from .sendMessage().

To send a message without a payload:
`typescript
socket.sendMessage("exampleTopic", "notify_server")
`

To send a message with a payload:
`typescript
socket.sendMessage("exampleTopic", "send_message", {message: "Hello!", attachments: []})
`

To handle a message response:
`typescript
socket.sendMessage("exampleTopic", "query_users").then((reply) => {
this.userList = [...reply.response.users]
})
`

$3

The promise returned by .sendMessage() will only resolve if the server responds with a successful ("ok") response. If the server returns an error response, then the promise will be rejected with a PhoenixRespondedWithError error. This error type contains the response body in case you need to implement further logic on error.

The .sendMessage() function may also throw either a PhoenixInvalidTopicError or a PhoenixInvalidStateError if you try to send a message to a topic you aren't subscribed to, or if the websocket is not currently connected. These types are exported and can be used to catch these library-specific errors and handle them. For ex:
`typescript
try {
socket.sendMessage("topicImNotSubscribedTo", "test")
}
catch (error) {
if (error instanceof PhoenixInvalidTopicError || error instanceof PhoenixInvalidStateError) {
// Do something
}
else {
throw error
}
}
`

$3


Once you are done with a PhoenixWebsocket instance, you can call .disconnect() to permanently close the connection and cleanup event listeners.

Using in a Node Context

This library was primarily intended for use within a browser, so it relies on the browser WebSocket API. If you want to use this library in a node context, you will need to expose a node implementation of the WebSocket API, which can be done with the wspackage.

After installing ws, add the following to the top of your entrypoint:
`typescript
import WebSocket from "ws"
(global as any).WebSocket ??= WebSocket
``

Maintainer

This library is maintained by Inkarnate.

In addition, this library is currently in use by us in a high-traffic, production environment. While we strive to keep this library up-to-date and bug free, there may be use cases we have not encountered with unknown bugs. As such, Issue reports and PRs are most welcome.