TLPersistentClientSocket • tldraw Docs

Table of contents

connectionStatus
onReceiveMessage
onStatusChange
Properties
Methods

Interface for persistent WebSocket-like connections used by TLSyncClient. Handles automatic reconnection and provides event-based communication with the sync server. Implementations should maintain connection resilience and handle network interruptions gracefully.

interface TLPersistentClientSocket<
  ClientSentMessage extends object = object,
  ServerSentMessage extends object = object,
> {}

Example

class MySocketAdapter implements TLPersistentClientSocket {
  connectionStatus: 'offline' | 'online' | 'error' = 'offline'

  sendMessage(msg: TLSocketClientSentEvent) {
    if (this.ws && this.ws.readyState === WebSocket.OPEN) {
      this.ws.send(JSON.stringify(msg))
    }
  }

  onReceiveMessage = (callback) => {
    // Set up message listener and return cleanup function
  }

  restart() {
    this.disconnect()
    this.connect()
  }
}

Properties

connectionStatus

Current connection state - online means actively connected and ready

connectionStatus: 'error' | 'offline' | 'online'

onReceiveMessage

Subscribe to messages received from the server

onReceiveMessage: SubscribingFn<ServerSentMessage>

Parameters

Name	Description
`callback`	Function called for each received message

onStatusChange

Subscribe to connection status changes

onStatusChange: SubscribingFn<TLSocketStatusChangeEvent>

Parameters

Name	Description
`callback`	Function called when connection status changes

Methods

close

Close the connection

restart

Force a connection restart (disconnect then reconnect) Used for error recovery or when connection health checks fail

sendMessage

Send a protocol message to the sync server

Parameters

Name	Description
`msg`	`ClientSentMessage` Message to send (connect, push, ping, etc.)

Returns

void