🎉 Add WebSocket resource

[cowboyd]

Motivation

The WebSocket API is one of the most common ways to communicate with servers over a stateful connection that allows you to both send and receive events async.

However, it is one of the most annoying things to do as a programmer because you have to coordinate between 4 separate callbacks: open, close, message, and error. How do you handle these callbacks properly given that they could be received in any order? You can either maintain an ad-hoc state machine and consult it within every callback, or you can use this contrib module which properly sequences the lifecycle of events into a single, coherent computation that is always resumed at the right point.

Approach

Use the WebSocket:

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

Already at this point, you're a leg up because the actual useWebSocket() operation does not return until the socket has connected and successfully received the open event. Furthermore, it also has installed a handler for the error event that will crash the resource if a connection error is received at any point.

Then, you can send data to the WebSocket just as you would normally.

socket.send("Hello World");

And finally, you can receive data from the socket as a stream of MessageEvents that is closed with a CloseEvent:

let subscription = yield* socket;
let next = yield* subscription.next();
while (!next.done) {
  let event = next.value; //MessagEvent
  console.log('received message', event.data);
  next = yield* subscription.next()
}
let closeEvent = next.value
console.log("closed", closeEvent.code)

There is no close() method on the web socket resource because it will be closed automatically whenever it passes out of scope.

[taras]

👍