@effectionx/websocket

WebSocket

A streamlined WebSocket client for Effection programs that transforms the event-based WebSocket API into a clean, resource-oriented stream.

Why Use this API?

Traditional WebSocket API require managing multiple event handlers (open, close, error, message) which can become complex and error-prone.

This package simplifies WebSocket usage by:

• Providing a clean stream-based interface
• Handling connection state management automatically
• Implementing proper error handling
• Ensuring resource cleanup

Basic Usage

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

await main(function* () {
  // Connection is guaranteed to be open when this returns
  let socket = yield* useWebSocket("ws://websocket.example.org");

  // Send messages to the server
  socket.send("Hello World");

  // Receive messages using a simple iterator
  for (let message of yield* each(socket)) {
    console.log("Message from server", message);
    yield* each.next();
  }
});

Features

• Ready-to-use Connections: useWebSocket() returns only after the connection is established
• Automatic Error Handling: Socket errors are properly propagated to your error boundary
• Stream-based API: Messages are delivered through a simple stream interface
• Clean Resource Management: Connections are properly cleaned up when the operation completes

Advanced Usage

Custom WebSocket Implementations

For environments without native WebSocket support (like Node.js < 21), you can provide your own WebSocket implementation:

import { createWebSocket } from "my-websocket-client";
import { each, main } from "effection";
import { useWebSocket } from "@effectionx/websocket";

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();
  }
});