[API reference](https://evolu.dev/docs/api-reference) › [@evolu/common](https://evolu.dev/docs/api-reference/common) › [WebSocket](https://evolu.dev/docs/api-reference/common/WebSocket) › WebSocket

Defined in: [packages/common/src/WebSocket.ts:98](https://github.com/evoluhq/evolu/blob/037c390af081e9944d616ff298a729515c5c5ab7/packages/common/src/WebSocket.ts#L98)

WebSocket with auto-reconnect.

The API mirrors native
[WebSocket](https://developer.mozilla.org/en-US/docs/Web/API/WebSocket)
but retries connections indefinitely by default. This design accounts for the
fact that browser and React Native online/offline detection APIs are
unreliable — they may report online status incorrectly, so the only reliable
approach is to keep attempting reconnection.

Created via [createWebSocket](https://evolu.dev/docs/api-reference/common/WebSocket/variables/createWebSocket) which returns a [Task](https://evolu.dev/docs/api-reference/common/Task/type-aliases/Task).

Disposing starts closing the connection without waiting for the close event
so disposal stays immediate. This wrapper treats disposal as local teardown,
not as waiting for the full WebSocket close handshake to finish.

## How Binary Messages Work

The Server Chooses the Message Type:

- Text (0x1) → Sent as UTF-8 encoded text (always received as a string in the
  browser).
- Binary (0x2) → Sent as raw binary data (received as a Blob or ArrayBuffer,
  depending on binaryType).

The Client's binaryType Controls How Binary Data is Processed:

- If the server sends a text frame (0x1), the browser always delivers
  event.data as a string, regardless of binaryType.
- If the server sends a binary frame (0x2), the browser delivers event.data as:

  - A Blob (default: "blob")
  - An ArrayBuffer ("arraybuffer")

### Connecting and sending

```ts
import {
  assert,
  assertEqual,
  assertOk,
  assertTrue,
  createRun,
  createWebSocket,
  testCreateWebSocket,
  type CreateWebSocket,
  type Task,
  type WebSocketSendError,
} from "@evolu/common";

const connectAndSend =
  (
    createSocket: CreateWebSocket = createWebSocket,
  ): Task<void, WebSocketSendError> =>
  async (run) => {
    await using socket = await run.ok(
      createSocket("wss://example.com", {
        protocols: ["evolu"],
        binaryType: "arraybuffer",
      }),
    );
    return socket.send("Hello");
  };

const socketFactory = testCreateWebSocket();
await using run = createRun();

assertOk(await run(connectAndSend(socketFactory)), undefined);
assertTrue(socketFactory.sentMessages.length === 1);
const message = socketFactory.sentMessages[0];
assert(
  message !== undefined && typeof message.data === "string",
  "Expected a text message.",
);
assertEqual(
  { url: message.url, data: message.data },
  { url: "wss://example.com", data: "Hello" },
);
```

## Extends

- [`AsyncDisposable`](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-5-2.html#using-declarations-and-explicit-resource-management)

## Methods

<a id="asyncdispose"></a>

### \[asyncDispose\]()

```ts
asyncDispose: PromiseLike<void>;
```

Defined in: node\_modules/@typescript/old/lib/lib.esnext.disposable.d.ts:38

#### Inherited from

```ts
AsyncDisposable.[asyncDispose]
```

## Properties

<a id="getreadystate"></a>

### getReadyState

```ts
readonly getReadyState: () => WebSocketReadyState;
```

Defined in: [packages/common/src/WebSocket.ts:107](https://github.com/evoluhq/evolu/blob/037c390af081e9944d616ff298a729515c5c5ab7/packages/common/src/WebSocket.ts#L107)

### isOpen

```ts
readonly isOpen: () => boolean;
```

Defined in: [packages/common/src/WebSocket.ts:110](https://github.com/evoluhq/evolu/blob/037c390af081e9944d616ff298a729515c5c5ab7/packages/common/src/WebSocket.ts#L110)

Returns true if the WebSocket is open and ready to send data.

### send

```ts
send: (data: string | Uint8Array<ArrayBufferLike> | Blob | BufferSource) =>
  Result<void, WebSocketSendError>;
```

Defined in: [packages/common/src/WebSocket.ts:103](https://github.com/evoluhq/evolu/blob/037c390af081e9944d616ff298a729515c5c5ab7/packages/common/src/WebSocket.ts#L103)

Send data through the WebSocket connection. Returns [Result](https://evolu.dev/docs/api-reference/common/Result/type-aliases/Result) with an
error if the data couldn't be sent.