Y WebSocket

https://github.com/yjs/y-websocket
Admin
WebSocket Provider for Yjs that implements a classical client-server model for syncing collaborative...
Tokens:23,356
Snippets:150
Trust Score:8.1
License:MIT
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Start y-websocket server

Source: https://github.com/yjs/y-websocket/blob/master/README.md

Install and start the @y/websocket-server backend. The server listens on localhost:1234 by default.

```sh
npm install @y/websocket-server
HOST=localhost PORT=1234 npx y-websocket
```

--------------------------------

### connect(): void

Source: https://github.com/yjs/y-websocket/blob/master/_autodocs/api-reference/websocket-provider.md

Connects the provider, opening a socket and starting cross-tab communication if not already connected.

```APIDOC
## connect(): void

### Description
Sets `shouldConnect = true`; if the provider is neither connected nor currently connecting (`!wsconnected && ws === null`) it opens the socket via `setupWS()` and starts cross-tab communication via `connectBc()`. Safe to call from inside a `'closed'`-handler — the `'closed'` event is intentionally emitted *after* provider state has been reset so that the re-authenticate-and-reconnect idiom works synchronously.

### Method
`connect`

### Return Type
`void`

### Example
```js
// resume after a terminal close, once the cause is fixed
provider.on('closed', async ({ code, reason }) => {
  console.warn('server closed us:', code, reason)
  await refreshToken()
  provider.connect() // opens a socket synchronously
})
```
```

--------------------------------

### connect() - Open socket and start BroadcastChannel

Source: https://github.com/yjs/y-websocket/blob/master/_autodocs/api-reference/websocket-provider.md

Sets shouldConnect = true; if the provider is neither connected nor currently connecting (!wsconnected && ws === null) it opens the socket via setupWS() and starts cross-tab communication via connectBc(). Safe to call from inside a 'closed'-handler because the 'closed' event is emitted after provider state is reset.

```javascript
connect () {
    this.shouldConnect = true
    if (!this.wsconnected && this.ws === null) {
      setupWS(this)
      this.connectBc()
    }
  }
```

```javascript
// resume after a terminal close, once the cause is fixed
provider.on('closed', async ({ code, reason }) => {
  console.warn('server closed us:', code, reason)
  await refreshToken()
  provider.connect() // opens a socket synchronously
})
```

--------------------------------

### Install y-websocket dependencies

Source: https://github.com/yjs/y-websocket/blob/master/README.md

Install the stable release of y-websocket with `npm i y-websocket`, or the main branch/unstable release with `npm i @y/websocket`.

```sh
npm i y-websocket
```

```sh
npm i @y/websocket
```

--------------------------------

### Import and use messageSync in a backend

Source: https://github.com/yjs/y-websocket/blob/master/_autodocs/api-reference/constants.md

Example of importing messageSync and using it to peek at incoming WebSocket frames. It creates a decoder from the raw data and returns early if the first varUint is not messageSync.

```javascript
import { messageSync } from 'y-websocket'
// e.g. a minimal backend peeking at incoming frames
const decoder = decoding.createDecoder(new Uint8Array(data))
if (decoding.readVarUint(decoder) !== messageSync) return
```

--------------------------------

### Configure wsOpts for WebsocketProvider

Source: https://github.com/yjs/y-websocket/blob/master/README.md

Example of the wsOpts configuration object with default values. Set connect to false to manually connect, params to add URL parameters, WebsocketPolyfill for Node.js, awareness for shared awareness, maxBackoffTime for reconnect delay, and shouldReconnect to control reconnection behavior.

```javascript
wsOpts = {
  // Set this to `false` if you want to connect manually using wsProvider.connect()
  connect: true,
  // Specify a query-string / url parameters that will be url-encoded and attached to the `serverUrl`
  // I.e. params = { auth: "bearer" } will be transformed to "?auth=bearer"
  params: {}, // Object<string,string>
  // You may polyill the Websocket object (https://developer.mozilla.org/en-US/docs/Web/API/WebSocket).
  // E.g. In nodejs, you could specify WebsocketPolyfill = require('ws')
  WebsocketPolyfill: Websocket,
  // Specify an existing Awareness instance - see https://github.com/yjs/y-protocols
  awareness: new awarenessProtocol.Awareness(ydoc),
  // Specify the maximum amount to wait between reconnects (we use exponential backoff).
  maxBackoffTime: 2500,
  // Decide whether to reconnect after the *server* closed the connection. By default, close
  // codes in the 4400-4499 range are permanent: the provider stops reconnecting and fires the
  // `closed` event. See "Close codes & reconnecting" below.
  // This is never called when you close the connection yourself (e.g. wsProvider.disconnect()).
  shouldReconnect: (event, provider) => !(event.code >= 4400 && event.code < 4500)
}
```

--------------------------------

### get url(): string

Source: https://github.com/yjs/y-websocket/blob/master/_autodocs/api-reference/websocket-provider.md

Getter that returns the full connection URL for the provider.

```APIDOC
## GETTER `url`

### Description
Returns the full connection URL for the provider, including the server URL, room name, and any encoded query parameters.

### Return Type
`string`

### Return Value
The full connection URL, e.g. `http://localhost:1234/my-document-name?auth=bearer`. Reflects current `params`.

### Example
```js
console.log(provider.url)             // ws://localhost:1234/my-roomname
provider.params = { auth: 'new-token' }
console.log(provider.url)             // ws://localhost:1234/my-roomname?auth=new-token
```
```

--------------------------------

### Node.js usage with polyfill and deferred connect

Source: https://github.com/yjs/y-websocket/blob/master/_autodocs/api-reference/websocket-provider.md

Shows how to use WebsocketProvider in Node.js by providing a WebSocket polyfill (ws), sharing an awareness instance, setting URL params, deferring connection, and configuring backoff and resync intervals. Call provider.connect() to start the connection.

```javascript
// Node.js: polyfill WebSocket, defer connect, share awareness
import * as Y from '@y/y'
import { WebsocketProvider } from 'y-websocket'
import WS from 'ws'
import * as awarenessProtocol from 'y-protocols/awareness'

const doc = new Y.Doc()
const awareness = new awarenessProtocol.Awareness(doc)
const provider = new WebsocketProvider('ws://localhost:1234', 'room', doc, {
  WebSocketPolyfill: WS,
  awareness,
  params: { auth: 'token' },   // appended as ?auth=token
  connect: false,              // connect manually later
  maxBackoffTime: 10000,
  resyncInterval: 30000
})

provider.connect()
```

--------------------------------

### Get provider URL and update with params

Source: https://github.com/yjs/y-websocket/blob/master/_autodocs/api-reference/websocket-provider.md

The getter returns the full connection URL by combining serverUrl, roomname, and encoded query parameters from this.params. The second block shows that changing provider.params updates the URL, with example output showing the query string appended.

```javascript
get url () {
    const encodedParams = url.encodeQueryParams(this.params)
    return this.serverUrl + '/' + this.roomname +
      (encodedParams.length === 0 ? '' : '?' + encodedParams)
  }
```

```javascript
console.log(provider.url)             // ws://localhost:1234/my-roomname
provider.params = { auth: 'new-token' }
console.log(provider.url)             // ws://localhost:1234/my-roomname?auth=new-token
```

--------------------------------

### Subscribe to 'sync-status' event

Source: https://github.com/yjs/y-websocket/blob/master/_autodocs/types.md

Example of subscribing to the 'sync-status' event on a WebsocketProvider to receive the SyncStatus object.

```javascript
provider.on('sync-status', (status) => {
  // status: { connected, receivedInitialSync, localUpdatesSynced, localUpdatesAge, lastMessageAge, status }
})
```

--------------------------------

### get syncStatus(): SyncStatus

Source: https://github.com/yjs/y-websocket/blob/master/_autodocs/api-reference/websocket-provider.md

Getter that returns the current sync status of the provider.

```APIDOC
## GETTER `syncStatus`

### Description
Returns the current distilled sync state of the provider, including connection status, initial sync completion, local update age, and a computed status string.

### Return Type
`SyncStatus`

### Return Value
- `connected` (boolean) - Whether the WebSocket is connected.
- `receivedInitialSync` (boolean) - Whether the initial sync has been received.
- `localUpdatesSynced` (boolean) - Whether there are no unconfirmed local updates.
- `localUpdatesAge` (number) - Age in seconds of the oldest unconfirmed local update (0 if synced).
- `lastMessageAge` (number) - Seconds since the last WebSocket message was received.
- `status` (string) - `'green'` when connected + synced + no unconfirmed local updates; `'yellow'` when connected but the oldest unconfirmed local update is younger than `acceptableConnectionDelay` (8000 ms); `'red'` otherwise.

### Example
```js
// render a connection indicator
function renderStatus (provider) {
  const s = provider.syncStatus
  el.textContent = `status=${s.status} connected=${s.connected} localAge=${s.localUpdatesAge}`
}
```
```

--------------------------------

### Get syncStatus and render connection indicator

Source: https://github.com/yjs/y-websocket/blob/master/_autodocs/api-reference/websocket-provider.md

The getter returns a SyncStatus object with fields connected, receivedInitialSync, localUpdatesSynced, localUpdatesAge, lastMessageAge, and status. The status is 'green' when connected and synced with no unconfirmed local updates, 'yellow' when connected but the oldest unconfirmed update is younger than acceptableConnectionDelay (8000 ms), and 'red' otherwise. The second block shows a render function that reads provider.syncStatus to display the status.

```javascript
get syncStatus () {
    const {
      unconfirmedUpdates,
      wsconnected: connected,
      synced: receivedInitialSync,
      wsLastMessageReceived
    } = this
    const now = time.getUnixTime()
    const localUpdatesSynced = unconfirmedUpdates.length === 0
    const localUpdatesAge = localUpdatesSynced ? 0 : now - unconfirmedUpdates[0].created
    const status = (connected && receivedInitialSync && localUpdatesAge === 0) ? 'green' : (connected && localUpdatesAge < acceptableConnectionDelay ? 'yellow' : 'red')
    return {
      connected,
      receivedInitialSync,
      localUpdatesSynced,
      localUpdatesAge,
      lastMessageAge: now - wsLastMessageReceived,
      status
    }
  }
```

```javascript
// render a connection indicator
function renderStatus (provider) {
  const s = provider.syncStatus
  el.textContent = `status=${s.status} connected=${s.connected} localAge=${s.localUpdatesAge}`
}
```

--------------------------------

### get synced(): boolean / set synced(state: boolean)

Source: https://github.com/yjs/y-websocket/blob/master/_autodocs/api-reference/websocket-provider.md

Getter and setter for the synced state of the provider.

```APIDOC
## GETTER/SETTER `synced`

### Description
Gets or sets whether the provider has completed the initial sync. The setter fires the `'sync'` event (and an internal `'synced'` event) only when the value actually changes; setting it to `true` resets `wsUnsuccessfulReconnects`. The provider sets it when sync step 2 has been received — consumers normally only read it.

### Return Type
`boolean`

### Example
```js
if (provider.synced) {
  console.log('initial sync complete')
}
```
```

--------------------------------

### Get and set synced state with sync event

Source: https://github.com/yjs/y-websocket/blob/master/_autodocs/api-reference/websocket-provider.md

The getter returns the current synced state. The setter only emits 'sync' and 'synced' events when the value changes, and resets wsUnsuccessfulReconnects when set to true. The second block shows a consumer checking provider.synced to log when initial sync is complete.

```javascript
get synced () {
    return this._synced
  }

  set synced (state) {
    if (this._synced !== state) {
      this._synced = state
      if (state) {
        // a connection that synced did useful work - reset the reconnect backoff
        this.wsUnsuccessfulReconnects = 0
      }
      // @ts-ignore
      this.emit('synced', [state])
      this.emit('sync', [state])
    }
  }
```

```javascript
if (provider.synced) {
  console.log('initial sync complete')
}
```

--------------------------------

### destroy() - Teardown provider and doc

Source: https://github.com/yjs/y-websocket/blob/master/_autodocs/api-reference/websocket-provider.md

Tears down the provider: clears intervals, disconnects socket and BroadcastChannel, removes event listeners, and calls ObservableV2.destroy(). Does not destroy the doc; call doc.destroy() separately. The example shows an unmounting SPA view calling provider.destroy() and provider.doc.destroy().

```javascript
destroy () {
    if (this._resyncInterval !== 0) {
      clearInterval(this._resyncInterval)
    }
    clearInterval(this._checkInterval)
    this.disconnect()
    if (env.isNode && typeof process !== 'undefined') {
      process.off('exit', this._exitHandler)
    }
    this.awareness.off('update', this._awarenessUpdateHandler)
    this.doc.off('update', this._updateHandler)
    super.destroy()
  }
```

```javascript
// e.g. an unmounting SPA view
function onUnmount (provider) {
  provider.destroy()
  provider.doc.destroy()
}
```

--------------------------------

### Basic usage in browser

Source: https://github.com/yjs/y-websocket/blob/master/_autodocs/api-reference/websocket-provider.md

Creates a WebsocketProvider with a WebSocket URL and room name, and listens for status events. The status event provides 'connecting', 'connected', or 'disconnected'.

```javascript
// basic usage (browser)
import * as Y from '@y/y'
import { WebsocketProvider } from 'y-websocket'

const doc = new Y.Doc()
const provider = new WebsocketProvider('ws://localhost:1234', 'my-roomname', doc)

provider.on('status', event => {
  console.log('connection status:', event.status) // "connecting" | "connected" | "disconnected"
})
```

--------------------------------

### new WebsocketProvider(serverUrl, room, ydoc, wsOpts)

Source: https://github.com/yjs/y-websocket/blob/master/README.md

Create a new websocket-provider instance. As long as this provider, or the connected ydoc, is not destroyed, the changes will be synced to other clients via the connected server.

```APIDOC
## WebsocketProvider

### Description
Create a new websocket-provider instance. As long as this provider, or the connected ydoc, is not destroyed, the changes will be synced to other clients via the connected server.

### Constructor
`new WebsocketProvider(serverUrl: string, room: string, ydoc: Y.Doc [, wsOpts: WsOpts])`

### Parameters
- `serverUrl` (string) - Required - The URL of the websocket server.
- `room` (string) - Required - The room name to connect to.
- `ydoc` (Y.Doc) - Required - The Y.Doc instance to sync.
- `wsOpts` (WsOpts) - Optional - Configuration object with the following properties:
  - `connect` (boolean) - Set to `false` to connect manually using `wsProvider.connect()`.
  - `params` (Object<string,string>) - Query-string parameters to append to `serverUrl`.
  - `WebsocketPolyfill` (WebSocket) - Polyfill for the WebSocket object.
  - `awareness` (Awareness) - An existing Awareness instance.
  - `maxBackoffTime` (number) - Maximum wait time between reconnects (exponential backoff).
  - `shouldReconnect` (function) - Determines whether to reconnect after the server closes the connection. Not called when disconnecting manually.
```

--------------------------------

### JSDoc parameter types for constructor

Source: https://github.com/yjs/y-websocket/blob/master/_autodocs/api-reference/websocket-provider.md

Documents the types and descriptions of each constructor option, including serverUrl, roomname, doc, and all opts fields.

```javascript
/**
 * @param {string} serverUrl
 * @param {string} roomname
 * @param {Y.Doc} doc
 * @param {object} opts
 * @param {boolean} [opts.connect]
 * @param {awarenessProtocol.Awareness} [opts.awareness]
 * @param {Object<string,string>} [opts.params] specify url parameters
 * @param {Array<string>} [opts.protocols] specify websocket protocols
 * @param {typeof WebSocket} [opts.WebSocketPolyfill] Optionall provide a WebSocket polyfill
 * @param {number} [opts.resyncInterval] Request server state every `resyncInterval` milliseconds
 * @param {number} [opts.maxBackoffTime] Maximum amount of time to wait before trying to reconnect (we try to reconnect using exponential backoff)
 * @param {boolean} [opts.disableBc] Disable cross-tab BroadcastChannel communication
 * @param {number} [opts.socketTimeout] If no message is received for this amount of time, client will close the socket and reconnect
 * @param {(event: CloseEvent, provider: WebsocketProvider) => boolean} [opts.shouldReconnect] Decide whether to reconnect after the server closed the connection.
 */
```

--------------------------------

### Constructor signature with default options

Source: https://github.com/yjs/y-websocket/blob/master/_autodocs/api-reference/websocket-provider.md

Shows the constructor parameters and default values for WebsocketProvider, including connect, awareness, params, protocols, WebSocketPolyfill, resyncInterval, maxBackoffTime, disableBc, socketTimeout, and shouldReconnect.

```javascript
constructor (serverUrl, roomname, doc, {
    connect = true,
    awareness = new awarenessProtocol.Awareness(doc),
    params = {},
    protocols = [],
    WebSocketPolyfill = WebSocket,
    resyncInterval = -1,
    maxBackoffTime = 2500,
    disableBc = false,
    socketTimeout = math.round(awarenessProtocol.outdatedTimeout * 1.5),
    shouldReconnect = defaultShouldReconnect
  } = {})
```

--------------------------------

### SyncStatus typedef in y-websocket.js

Source: https://github.com/yjs/y-websocket/blob/master/_autodocs/types.md

JSDoc typedef for the SyncStatus object emitted by the 'sync-status' event and returned by the get syncStatus() getter. Only works on certain backends (e.g. yhub).

```javascript
/**
 * This sync status event only works on certain backends (e.g. yhub)
 * @typedef {object} SyncStatus
 * @property {boolean} SyncStatusEvent.connected
 * @property {boolean} SyncStatusEvent.receivedInitialSync
 * @property {boolean} SyncStatusEvent.localUpdatesSynced
 * @property {number} SyncStatusEvent.localUpdatesAge
 * @property {number} SyncStatusEvent.lastMessageAge
 * @property {'green' | 'yellow' | 'red'} SyncStatusEvent.status Distilled sync status: 'green' if synced, connected, there are no unsynced local updates. 'yellow' if last local message age is younger than 8 seconds. 'red' if unsynced or disconnected or if last local message is older than 8 seconds
 */
```

--------------------------------

### WebsocketProvider constructor options

Source: https://github.com/yjs/y-websocket/blob/master/_autodocs/configuration.md

Constructor options for WebsocketProvider. All runtime configuration is passed via this options object; no config files or environment variables are read. Defaults are shown for each option.

```javascript
new WebsocketProvider(serverUrl, roomname, doc, {
  connect = true,
  awareness = new awarenessProtocol.Awareness(doc),
  params = {},
  protocols = [],
  WebSocketPolyfill = WebSocket,
  resyncInterval = -1,
  maxBackoffTime = 2500,
  disableBc = false,
  socketTimeout = math.round(awarenessProtocol.outdatedTimeout * 1.5),
  shouldReconnect = defaultShouldReconnect
})
```

--------------------------------

### SyncStatus

Source: https://github.com/yjs/y-websocket/blob/master/_autodocs/types.md

The SyncStatus typedef describes the synchronization state of a WebsocketProvider. It is produced by the get syncStatus() method, emitted as the payload of the 'sync-status' event, and stored as provider.prevSyncStatus. Consumers can use it to render connection health.

```APIDOC
## SyncStatus

### Description
The SyncStatus typedef describes the synchronization state of a WebsocketProvider. It is produced by the get syncStatus() method, emitted as the payload of the 'sync-status' event, and stored as provider.prevSyncStatus. Consumers can use it to render connection health.

### Type
Object

### Properties
- **connected** (boolean) - Whether the provider is currently connected to the server
- **receivedInitialSync** (boolean) - Whether the initial sync with the server (sync step 2) has completed (mirrors provider.synced)
- **localUpdatesSynced** (boolean) - Whether all local updates have been confirmed by the server (unconfirmedUpdates.length === 0)
- **localUpdatesAge** (number) - Age in ms of the oldest unconfirmed local update; 0 when all are synced
- **lastMessageAge** (number) - Time in ms since the last message was received from the server (now - wsLastMessageReceived)
- **status** ('green' | 'yellow' | 'red') - Distilled status — 'green' when connected, synced, and no unconfirmed local updates; 'yellow' when connected but the oldest unconfirmed update is younger than acceptableConnectionDelay (8000 ms); 'red' otherwise

### Example Usage
```js
provider.on('sync-status', (status) => {
  // status: { connected, receivedInitialSync, localUpdatesSynced, localUpdatesAge, lastMessageAge, status }
})
```
```

--------------------------------

### new WebsocketProvider(serverUrl, roomname, doc, opts)

Source: https://github.com/yjs/y-websocket/blob/master/_autodocs/types.md

Creates a new WebsocketProvider instance. The opts object configures connection behavior, awareness, synchronization, and reconnection policies.

```APIDOC
## Constructor: new WebsocketProvider(serverUrl, roomname, doc, opts)

### Description
Creates a new WebsocketProvider instance that manages a WebSocket connection to a y-websocket server for shared document synchronization.

### Method
Constructor

### Endpoint
new WebsocketProvider(serverUrl, roomname, doc, opts)

### Parameters
#### Constructor Parameters
- **serverUrl** (string) - Required - The URL of the WebSocket server.
- **roomname** (string) - Required - The name of the room to join.
- **doc** (Y.Doc) - Required - The Y.Doc instance to synchronize.
- **opts** (WsOpts) - Optional - Configuration options object. All properties are optional.

#### Options Object (WsOpts)
- **connect** (boolean) - Optional - Default: `true` - Auto-connect on construction.
- **awareness** (awarenessProtocol.Awareness) - Optional - Default: `new awarenessProtocol.Awareness(doc)` - Shared awareness instance.
- **params** (Object<string,string>) - Optional - Default: `{}` - URL query parameters.
- **protocols** (Array<string>) - Optional - Default: `[]` - WebSocket sub-protocols.
- **WebSocketPolyfill** (typeof WebSocket) - Optional - Default: `WebSocket` - WebSocket constructor/polyfill.
- **resyncInterval** (number) - Optional - Default: `-1` - Periodic sync step 1 resend interval; `-1` or `<= 0` disables.
- **maxBackoffTime** (number) - Optional - Default: `2500` - Reconnect backoff cap in ms.
- **disableBc** (boolean) - Optional - Default: `false` - Disable BroadcastChannel cross-tab communication.
- **socketTimeout** (number) - Optional - Default: `math.round(awarenessProtocol.outdatedTimeout * 1.5)` - Watchdog threshold in ms (≈ 45 000 with the standard `@y/protocols` value of 30 000).
- **shouldReconnect** ((event: CloseEvent, provider: WebsocketProvider) => boolean) - Optional - Default: `defaultShouldReconnect` - Close-code reconnect policy.

### Request Example
```js
const provider = new WebsocketProvider(serverUrl, roomname, doc, {
  connect: true,
  awareness: new awarenessProtocol.Awareness(doc),
  params: {},
  protocols: [],
  WebSocketPolyfill: WebSocket,
  resyncInterval: -1,
  maxBackoffTime: 2500,
  disableBc: false,
  socketTimeout: math.round(awarenessProtocol.outdatedTimeout * 1.5),
  shouldReconnect: defaultShouldReconnect
});
```

### Response
#### Success Response
No return value (constructor).

#### Response Example
N/A
```

--------------------------------

### Import all message constants and log values

Source: https://github.com/yjs/y-websocket/blob/master/_autodocs/api-reference/constants.md

Shows importing all four message type constants and logging them as an object, producing { messageSync: 0, messageAwareness: 1, messageAuth: 2, messageQueryAwareness: 3 }.

```javascript
import { messageAwareness, messageQueryAwareness, messageSync, messageAuth } from 'y-websocket'
console.log({ messageSync, messageAwareness, messageAuth, messageQueryAwareness })
// { messageSync: 0, messageAwareness: 1, messageAuth: 2, messageQueryAwareness: 3 }
```

--------------------------------

### connectBc(): void

Source: https://github.com/yjs/y-websocket/blob/master/_autodocs/api-reference/websocket-provider.md

Subscribes to the BroadcastChannel and publishes sync and awareness messages. Public, but invoked automatically by connect().

```APIDOC
## connectBc(): void

### Description
Subscribes to the `BroadcastChannel` (unless `disableBc` or already connected) and publishes four messages: sync step 1, sync step 2 (full local state), a `messageQueryAwareness` query, and the local awareness state. Public, but invoked automatically by `connect()`.

### Method
`connectBc`

### Return Type
`void`

### Example
```js
connectBc () {
    if (this.disableBc) {
      return
    }
    if (!this.bcconnected) {
      bc.subscribe(this.bcChannel, this._bcSubscriber)
      this.bcconnected = true
    }
    // send sync step1 to bc
    // write sync step 1
    const encoderSync = encoding.createEncoder()
    encoding.writeVarUint(encoderSync, messageSync)
    syncProtocol.writeSyncStep1(encoderSync, this.doc)
    bc.publish(this.bcChannel, encoding.toUint8Array(encoderSync), this)
    // broadcast local state
    const encoderState = encoding.createEncoder()
    encoding.writeVarUint(encoderState, messageSync)
    syncProtocol.writeSyncStep2(encoderState, this.doc)
    bc.publish(this.bcChannel, encoding.toUint8Array(encoderState), this)
    // write queryAwareness
    const encoderAwarenessQuery = encoding.createEncoder()
    encoding.writeVarUint(encoderAwarenessQuery, messageQueryAwareness)
    bc.publish(
      this.bcChannel,
      encoding.toUint8Array(encoderAwarenessQuery),
      this
    )
    // broadcast local awareness state
    const encoderAwarenessState = encoding.createEncoder()
    encoding.writeVarUint(encoderAwarenessState, messageAwareness)
    encoding.writeVarUint8Array(
      encoderAwarenessState,
      awarenessProtocol.encodeAwarenessUpdate(this.awareness, [
        this.awareness.clientID
      ])
    )
    bc.publish(
      this.bcChannel,
      encoding.toUint8Array(encoderAwarenessState),
      this
    )
  }
```
```

--------------------------------

### connectBc() - BroadcastChannel sync and awareness

Source: https://github.com/yjs/y-websocket/blob/master/_autodocs/api-reference/websocket-provider.md

Subscribes to the BroadcastChannel (unless disableBc or already connected) and publishes sync step 1, sync step 2, a queryAwareness message, and the local awareness state. Invoked automatically by connect().

```javascript
connectBc () {
    if (this.disableBc) {
      return
    }
    if (!this.bcconnected) {
      bc.subscribe(this.bcChannel, this._bcSubscriber)
      this.bcconnected = true
    }
    // send sync step1 to bc
    // write sync step 1
    const encoderSync = encoding.createEncoder()
    encoding.writeVarUint(encoderSync, messageSync)
    syncProtocol.writeSyncStep1(encoderSync, this.doc)
    bc.publish(this.bcChannel, encoding.toUint8Array(encoderSync), this)
    // broadcast local state
    const encoderState = encoding.createEncoder()
    encoding.writeVarUint(encoderState, messageSync)
    syncProtocol.writeSyncStep2(encoderState, this.doc)
    bc.publish(this.bcChannel, encoding.toUint8Array(encoderState), this)
    // write queryAwareness
    const encoderAwarenessQuery = encoding.createEncoder()
    encoding.writeVarUint(encoderAwarenessQuery, messageQueryAwareness)
    bc.publish(
      this.bcChannel,
      encoding.toUint8Array(encoderAwarenessQuery),
      this
    )
    // broadcast local awareness state
    const encoderAwarenessState = encoding.createEncoder()
    encoding.writeVarUint(encoderAwarenessState, messageAwareness)
    encoding.writeVarUint8Array(
      encoderAwarenessState,
      awarenessProtocol.encodeAwarenessUpdate(this.awareness, [
        this.awareness.clientID
      ])
    )
    bc.publish(
      this.bcChannel,
      encoding.toUint8Array(encoderAwarenessState),
      this
    )
  }
```

--------------------------------

### wsOpts constructor options object

Source: https://github.com/yjs/y-websocket/blob/master/_autodocs/types.md

Shows the shape of the `wsOpts` object accepted by `new WebsocketProvider(serverUrl, roomname, doc, opts)`. Every property is optional; defaults are shown inline. `socketTimeout` defaults to about 45,000 ms with the standard `@y/protocols` value of 30,000.

```javascript
{
  connect = true,                                      // boolean
  awareness = new awarenessProtocol.Awareness(doc),    // awarenessProtocol.Awareness
  params = {},                                         // Object<string,string>
  protocols = [],                                      // Array<string>
  WebSocketPolyfill = WebSocket,                       // typeof WebSocket
  resyncInterval = -1,                                 // number
  maxBackoffTime = 2500,                               // number
  disableBc = false,                                   // boolean
  socketTimeout = math.round(awarenessProtocol.outdatedTimeout * 1.5),  // number
  shouldReconnect = defaultShouldReconnect             // (event: CloseEvent, provider: WebsocketProvider) => boolean
}
```

--------------------------------

### Client code in Node.js with WebSocketPolyfill

Source: https://github.com/yjs/y-websocket/blob/master/README.md

Client code in Node.js that polyfills WebSocket support using the `ws` package. The WebSocket provider requires a WebSocket object to connect to a server.

```js
const wsProvider = new WebsocketProvider('ws://localhost:1234', 'my-roomname', doc, { WebSocketPolyfill: require('ws') })
```

--------------------------------

### Client code with WebsocketProvider

Source: https://github.com/yjs/y-websocket/blob/master/README.md

Client code that creates a Y.Doc and connects to a y-websocket server using WebsocketProvider. The status event logs "connected" or "disconnected".

```js
import * as Y from '@y/y'
import { WebsocketProvider } from 'y-websocket'

const doc = new Y.Doc()
const wsProvider = new WebsocketProvider('ws://localhost:1234', 'my-roomname', doc)

wsProvider.on('status', event => {
  console.log(event.status) // logs "connected" or "disconnected"
})
```

--------------------------------

### destroy(): void

Source: https://github.com/yjs/y-websocket/blob/master/_autodocs/api-reference/websocket-provider.md

Tears down the provider, clearing intervals, disconnecting, and removing listeners. The doc and awareness are not destroyed.

```APIDOC
## destroy(): void

### Description
Tears the provider down: clears both intervals, disconnects (socket + bc), removes the `process.exit` hook and the doc/awareness listeners, then calls `ObservableV2.destroy()`. The doc and awareness themselves are *not* destroyed — call `doc.destroy()` separately.

### Method
`destroy`

### Return Type
`void`

### Example
```js
// e.g. an unmounting SPA view
function onUnmount (provider) {
  provider.destroy()
  provider.doc.destroy()
}
```
```

--------------------------------

### WebSocket Provider Events

Source: https://github.com/yjs/y-websocket/blob/master/_autodocs/api-reference/websocket-provider.md

Documentation for all events emitted by the Yjs WebSocket provider, including payloads and firing conditions.

```APIDOC
## Event: 'status'

### Description
Emitted when the socket opens, closes, or when `setupWS` schedules a connection attempt.

### Event Name
`'status'`

### Payload
- **status** (string) - `'connected'` | `'disconnected'` | `'connecting'`

### Fired When
- Socket opened (`'connected'`)
- Socket closed (`'disconnected'`)
- `setupWS` scheduled (`'connecting'`)

### Example
```js
provider.on('status', ({ status }) => {
  console.log('status:', status)
})
```

## Event: 'sync'

### Description
Emitted when the `synced` state transitions to true or false, indicating whether initial content has been received from the server.

### Event Name
`'sync'`

### Payload
- **boolean** - `true` when synced, `false` when not

### Fired When
- `synced` transitions true/false (initial content received from server)

### Example
```js
provider.on('sync', (isSynced) => {
  console.log('sync:', isSynced)
})
```

## Event: 'synced'

### Description
Internal companion of `'sync'` with the same trigger. Not part of the documented JSDoc event map.

### Event Name
`'synced'`

### Payload
- **boolean** - `true` when synced, `false` when not

### Fired When
- Same trigger as `'sync'`

### Example
```js
provider.on('synced', (isSynced) => {
  console.log('synced:', isSynced)
})
```

## Event: 'connection-close'

### Description
Emitted on every teardown of the socket, including local closes.

### Event Name
`'connection-close'`

### Payload
- **event** (CloseEvent | null) - The close event, or `null` for local closes (`disconnect()`, watchdog)
- **provider** (WebsocketProvider) - The provider instance

### Fired When
- Every teardown of the socket

### Example
```js
provider.on('connection-close', (event, provider) => {
  console.log('connection closed', event, provider)
})
```

## Event: 'connection-error'

### Description
Emitted when the socket fires an `onerror` event.

### Event Name
`'connection-error'`

### Payload
- **event** (Event) - The error event
- **provider** (WebsocketProvider) - The provider instance

### Fired When
- The socket fired `onerror`

### Example
```js
provider.on('connection-error', (event, provider) => {
  console.error('websocket error on', provider.url, event)
})
```

## Event: 'closed'

### Description
Emitted when the server closes the connection and `shouldReconnect` returns `false`. Emitted last, after state reset, so a handler may call `connect()` synchronously. The provider is idle (not destroyed); cross-tab communication keeps running.

### Event Name
`'closed'`

### Payload
- **code** (number) - The close code
- **reason** (string) - The close reason
- **provider** (WebsocketProvider) - The provider instance

### Fired When
- The server closed the connection and `shouldReconnect` returned `false`

### Example
```js
provider.on('closed', ({ code, reason }) => {
  // Idle, not destroyed — resume deliberately later
  console.log(`terminal close: ${code} ${reason}`)
})
```

## Event: 'sync-status'

### Description
Emitted when the sync status changes, diffed against `prevSyncStatus`. Also fired on state transitions and when local-update age crosses thresholds.

### Event Name
`'sync-status'`

### Payload
- **syncStatus** (SyncStatus) - The new sync status object

### Fired When
- Sync status changed (diffed against `prevSyncStatus`)
- State transitions
- Local-update age crosses thresholds

### Example
```js
provider.on('sync-status', syncStatus => {
  updateIndicator(syncStatus.status, syncStatus.localUpdatesAge)
})
```
```

--------------------------------

### Update provider.params and provider.shouldReconnect

Source: https://github.com/yjs/y-websocket/blob/master/_autodocs/configuration.md

Mutable runtime configuration: update provider.params and provider.shouldReconnect directly; changes take effect on the next connection. Useful for refreshing auth tokens or overriding reconnect behavior.

```javascript
provider.params = { auth: refreshedToken } // next reconnect uses the new token
provider.shouldReconnect = () => true      // never give up
```

--------------------------------

### acceptableConnectionDelay constant (value 8000)

Source: https://github.com/yjs/y-websocket/blob/master/_autodocs/api-reference/constants.md

Threshold in milliseconds used by the syncStatus computation: a connected provider whose oldest unconfirmed local update is younger than this reports 'yellow'; older or disconnection reports 'red'. Also halves the watchdog interval: _checkInterval ticks every acceptableConnectionDelay / 2 ms.

```javascript
export const acceptableConnectionDelay = 8000
```

--------------------------------

### Class declaration: WebsocketProvider extends ObservableV2

Source: https://github.com/yjs/y-websocket/blob/master/_autodocs/api-reference/websocket-provider.md

Declares the WebsocketProvider class as extending ObservableV2 from lib0/observable, providing on, off, emit, once, and destroy methods.

```javascript
export class WebsocketProvider extends ObservableV2
```

--------------------------------

### Registering event handlers for connection-error, closed, and sync-status

Source: https://github.com/yjs/y-websocket/blob/master/_autodocs/api-reference/websocket-provider.md

Register event handlers for the 'connection-error', 'closed', and 'sync-status' events. The 'connection-error' handler logs the error and provider URL. The 'closed' handler logs the terminal close code and reason, noting the provider is idle but not destroyed. The 'sync-status' handler updates an indicator with the sync status and local updates age.

```javascript
provider.on('connection-error', (event, provider) => {
  console.error('websocket error on', provider.url, event)
})

provider.on('closed', ({ code, reason }) => {
  // Idle, not destroyed — resume deliberately later
  console.log(`terminal close: ${code} ${reason}`)
})

provider.on('sync-status', syncStatus => {
  updateIndicator(syncStatus.status, syncStatus.localUpdatesAge)
})
```
Tokens:
Raw