[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:66](https://github.com/evoluhq/evolu/blob/e7144e2bbe9069362b62dec1b64a8aa922b8f1b0/packages/common/src/WebSocket.ts#L66)

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 the WebSocket closes the connection.

## 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")

### Example

```ts
const ws = await run(
  createWebSocket("wss://example.com", {
    onMessage: (data) => console.log("Received:", data),
    onOpen: () => console.log("Connected"),
    onClose: () => console.log("Disconnected"),
  }),
);
if (ws.ok) {
  ws.value.send("Hello");
  // Later: await ws.value[Symbol.asyncDispose]();
}
```

## 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/.bun/typescript@5.9.3/node_modules/typescript/lib/lib.esnext.disposable.d.ts:40

#### Inherited from

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

## Properties

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

### getReadyState

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

Defined in: [packages/common/src/WebSocket.ts:75](https://github.com/evoluhq/evolu/blob/e7144e2bbe9069362b62dec1b64a8aa922b8f1b0/packages/common/src/WebSocket.ts#L75)

### isOpen

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

Defined in: [packages/common/src/WebSocket.ts:78](https://github.com/evoluhq/evolu/blob/e7144e2bbe9069362b62dec1b64a8aa922b8f1b0/packages/common/src/WebSocket.ts#L78)

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

### send

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

Defined in: [packages/common/src/WebSocket.ts:71](https://github.com/evoluhq/evolu/blob/e7144e2bbe9069362b62dec1b64a8aa922b8f1b0/packages/common/src/WebSocket.ts#L71)

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.