import { useWebSocket, 
type WebSocketResource
} from "@effection-contrib/websocket"

WebSocket

Use the WebSocket API as an Effection resource. Instead of a fragile, spring-loaded confederation of 'open', 'close', 'error', and 'message' event handlers, useWebSocket() organizes them for you so that you can consume all events from the server as a plain stream that has state-readiness and proper error handling baked in.

To use a websocket import the useWebSocket() operation which behaves just like the WebSocket constructor.

import { each, main } from "effection";
import { useWebSocket } from "@effection-contrib/websocket";

await main(function* () {
  let socket = yield* useWebSocket("ws://websocket.example.org");

  socket.send("Hello World");

  for (let message of yield* each(socket)) {
    console.log("Message from server", message);
    yield* each.next();
  }
});

The resource provides the following niceties:

When useWebSocket() returns, it will have already received the open event.
If the socket recieves an error event, that event's error will be thrown to the current error boundary.
The socket is a stream whose items are each MessageEvents, the CloseEvent of the websocket will be the close event of that stream.

You can also instantiate a websocket separately and pass it along to useWebSocket(). This is helpful for runtimes such as NodeJS prior to version 21 that do not have built in support for websocket.

import { createWebSocket } from "my-websocket-client";

await main(function* () {
  let socket = yield* useWebSocket(() =>
    createWebSocket("ws://websocket.example.org")
  );

  for (let message of yield* each(socket)) {
    console.log("Message from server", message);
    yield* each.next();
  }
});

API Reference

interface WebSocketResource<T> extends Stream<MessageEvent<T>, CloseEvent>

Handle to a WebSocket object that can be consumed as an Effection stream. It has all the same properties as the underlying WebSocket apart from the event handlers. Instead, the resource itself is a subscribale stream. When the socket is closed, the stream will complete with a CloseEvent

A WebSocketResource does not have an explicit close method. Rather, the underlying socket will be automatically closed when the resource passes out of scope.

Type Parameters

Properties

binaryType: BinaryType: the type of data that this websocket accepts
bufferedAmmount: number: No documentation available.
extensions: string: No documentation available.
protocol: string: No documentation available.
readyState: number: No documentation available.
url: string: No documentation available.

Methods

send(data: WebSocketData): void: No documentation available.

function useWebSocket<T>(url: string, protocols?: string): Operation<WebSocketResource<T>>

Create a WebSocket resource using the native WebSocket constructor available on the current platform.

The resource will not be returned until a connection has been succesffuly established with the server and the open has been received. Once initialized, it will crash if it receives an error event at any time.

Once created, the websocket resource can be use to consume events from the server:

let socket = yield* useWebSocket("ws://websocket.example.org");

for (let event of yield* each(socket)) {
  console.log('event data: ', event.data);
  yield* each.next();
}

Type Parameters

Parameters

url: string

The URL of the target WebSocket server to connect to. The URL must use one of the following schemes: ws, wss, http, or https, and cannot include a URL fragment. If a relative URL is provided, it is relative to the base URL of the calling script. For more detail, see https://developer.mozilla.org/en-US/docs/Web/API/WebSocket/WebSocket#url

protocolsoptional: string

A single string or an array of strings representing the sub-protocol(s) that the client would like to use, in order of preference. If it is omitted, an empty array is used by default, i.e. []. For more details, see

Return Type

Operation<WebSocketResource<T>>

an operation yielding a WebSocketResource

function useWebSocket<T>(create: () => WebSocket): Operation<WebSocketResource<T>>

Create a WebSocket resource, but delegate the creation of the underlying websocket to a function of your choice. This is necessary on platforms that do not have a global WebSocket constructor such as NodeJS <= 20.

Once created, the websocket resource can be use to consume events from the server:

import * as ws from 'ws';

function* example() {
  let socket = yield* useWebSocket(() => new ws.WebSocket("ws://websocket.example.org"));

  for (let event of yield* each(socket)) {
    console.log('event data: ', event.data);
    yield* each.next();
  }
}

Type Parameters

Parameters

create: () => WebSocket

a function that will construct the underlying WebSocket object that this resource wil use

Return Type

Operation<WebSocketResource<T>>

an operation yielding a WebSocketResource