WebSocket

WebSocketClient is an Effect service that wraps Convex’s ConvexClient. It provides the same query, mutation, and action methods as HttpClient, plus a reactiveQuery method that returns a Stream of live results. It works in any JavaScript environment that supports WebSocket. The WebSocket connection is managed as a scoped resource—it is opened when the layer is provided and closed automatically when the scope ends.

Setup

Create the WebSocketClient layer by passing your Convex deployment URL.

import { WebSocketClient } from "@confect/js";

const WebSocketClientLive = WebSocketClient.layer(
  "https://example-123.convex.cloud",
);

The layer can then be provided to any Effect that uses the WebSocketClient service. The underlying WebSocket connection is closed automatically when the layer’s scope ends—there is no need to close it manually.

Calling functions

Use the WebSocketClient service inside Effect.gen to call your functions with refs, the same way you would with HttpClient, @confect/react hooks, or @confect/test.

import { WebSocketClient } from "@confect/js";
import * as Effect from "effect/Effect";

import refs from "./confect/_generated/refs";

const program = Effect.gen(function* () {
  const client = yield* WebSocketClient.WebSocketClient;

  const notes = yield* client.query(refs.public.notes.list);

  const noteId = yield* client.mutation(refs.public.notes.insert, {
    text: "Hello from the server",
  });

  const result = yield* client.action(refs.public.random.getNumber);
});

Each method returns an Effect that can fail with WebSocketClientError (wrapping transport-level errors) or ParseResult.ParseError (if schema encoding or decoding fails).

Reactive queries

reactiveQuery subscribes to a query over the WebSocket connection and returns a Stream that emits a new value whenever the query result changes on the server.

import { WebSocketClient } from "@confect/js";
import * as Console from "effect/Console";
import * as Effect from "effect/Effect";
import * as Stream from "effect/Stream";

import refs from "./confect/_generated/refs";

const program = Effect.gen(function* () {
  const client = yield* WebSocketClient.WebSocketClient;

  yield* client
    .reactiveQuery(refs.public.notes.list)
    .pipe(Stream.runForEach((notes) => Console.log(notes)));
});

The underlying WebSocket subscription is cleaned up automatically when the stream’s scope ends (for example, when the consuming Effect is interrupted or when an operator like Stream.take completes).

Typed errors

When a ref’s spec declares an error schema, the decoded error is added to the error channel of query, mutation, action, and reactiveQuery alongside WebSocketClientError and ParseError. See Error Handling for how to declare error schemas.

import { WebSocketClient } from "@confect/js";
import * as Effect from "effect/Effect";

import refs from "./confect/_generated/refs";

const lookup = Effect.gen(function* () {
  const client = yield* WebSocketClient.WebSocketClient;

  return yield* client.query(refs.public.notes.getOrFail, { noteId });
});
// Effect.Effect<Note, NoteNotFound | WebSocketClientError | ParseError, WebSocketClient.WebSocketClient>

For reactiveQuery, a typed failure terminates the Stream with the decoded value in its error channel—the subscription does not stay open across failures. Recover with Stream.catchTag (or any other Stream error combinator) to keep the stream alive across typed failures.

import { WebSocketClient } from "@confect/js";
import * as Effect from "effect/Effect";
import * as Stream from "effect/Stream";

import refs from "./confect/_generated/refs";

const lookups = Effect.gen(function* () {
  const client = yield* WebSocketClient.WebSocketClient;

  return client
    .reactiveQuery(refs.public.notes.getOrFail, { noteId })
    .pipe(
      Stream.catchTag("NoteNotFound", (error) =>
        Stream.succeed(`Note ${error.noteId} not found.`),
      ),
    );
});

Authentication

Set the authentication token provider before making authenticated requests. setAuth accepts an Effect-returning function that is called whenever a token is needed or expires.

Effect.gen(function* () {
  const client = yield* WebSocketClient.WebSocketClient;

  yield* client.setAuth(
    ({ forceRefreshToken }) =>
      Effect.promise(() => getToken({ forceRefreshToken })),
    (isAuthenticated) => Console.log(`Auth state changed: ${isAuthenticated}`),
  );

  const identity = yield* client.query(refs.public.auth.getIdentity);
});

The optional second argument is a function that receives the current isAuthenticated status and returns an Effect to run whenever the authentication state changes.

Running programs

Provide the WebSocketClient layer when running your program.

import { WebSocketClient } from "@confect/js";
import * as Console from "effect/Console";
import * as Effect from "effect/Effect";
import * as Stream from "effect/Stream";

const WebSocketClientLive = WebSocketClient.layer(
  "https://example-123.convex.cloud",
);

const program = Effect.gen(function* () {
  const client = yield* WebSocketClient.WebSocketClient;

  yield* client.reactiveQuery(refs.public.notes.list).pipe(
    Stream.take(10),
    Stream.runForEach((notes) => Console.log(notes)),
  );
});

Effect.runPromise(program.pipe(Effect.provide(WebSocketClientLive)));

Differences from `ConvexClient`

`ConvexClient`	`WebSocketClient`
Functions referenced via `api.module.fn`	Functions referenced via `refs`
Args passed directly to Convex as-is	Args are schema-encoded from `Type` to `Encoded` before sending
Return values received directly as-is	Return values are schema-decoded from `Encoded` to `Type`
`query`/`mutation`/`action` return `Promise`	`query`/`mutation`/`action` return `Effect` with typed errors
`onUpdate` uses callbacks and returns an unsubscribe function	`reactiveQuery` returns a `Stream` with automatic cleanup
Must call `close()` manually	Connection closed automatically when the layer’s scope ends
`setAuth` takes a `Promise`-returning callback	`setAuth` takes an `Effect`-returning function

Getting Started

Concepts

Server

Clients

Guides

Setup

Calling functions

Reactive queries

Typed errors

Authentication

Running programs

Differences from `ConvexClient`

​Setup

​Calling functions

​Reactive queries

​Typed errors

​Authentication

​Running programs

​Differences from ConvexClient

Setup

Calling functions

Reactive queries

Typed errors

Authentication

Running programs

Differences from `ConvexClient`