TLSocketRoom

class TLSocketRoom<
  R extends UnknownRecord = UnknownRecord,
  SessionMeta = void,
> {}

Constructs a new instance of the TLSocketRoom class

Parameters

{
  clientTimeout?: number
  initialSnapshot?: RoomSnapshot | TLStoreSnapshot
  log?: TLSyncLog
  onAfterReceiveMessage?: (args: {
    message: TLSocketServerSentEvent<R>
    meta: SessionMeta
    sessionId: string
    stringified: string
  }) => void
  onBeforeSendMessage?: (args: {
    message: TLSocketServerSentEvent<R>
    meta: SessionMeta
    sessionId: string
    stringified: string
  }) => void
  onDataChange?: () => void
  onSessionRemoved?: (
    room: TLSocketRoom<R, SessionMeta>,
    args: {
      meta: SessionMeta
      numSessionsRemaining: number
      sessionId: string
    }
  ) => void
  schema?: StoreSchema<R, any>
}

Properties

readonly log?: TLSyncLog

readonly opts: {
  clientTimeout?: number
  initialSnapshot?: RoomSnapshot | TLStoreSnapshot
  log?: TLSyncLog
  onAfterReceiveMessage?: (args: {
    message: TLSocketServerSentEvent<R>
    meta: SessionMeta
    sessionId: string
    stringified: string
  }) => void
  onBeforeSendMessage?: (args: {
    message: TLSocketServerSentEvent<R>
    meta: SessionMeta
    sessionId: string
    stringified: string
  }) => void
  onDataChange?: () => void
  onSessionRemoved?: (
    room: TLSocketRoom<R, SessionMeta>,
    args: {
      meta: SessionMeta
      numSessionsRemaining: number
      sessionId: string
    }
  ) => void
  schema?: StoreSchema<R, any>
}

Methods

Close the room and disconnect all clients. Call this before discarding the room instance or shutting down the server.

close(): void

Returns the current 'clock' of the document. The clock is an integer that increments every time the document changes. The clock is stored as part of the snapshot of the document for consistency purposes.

getCurrentDocumentClock(): number

Return a snapshot of the document state, including clock-related bookkeeping. You can store this and load it later on when initializing a TLSocketRoom. You can also pass a snapshot to if you need to revert to a previous state.

getCurrentSnapshot(): RoomSnapshot

Returns the number of active sessions. Note that this is not the same as the number of connected sockets! Sessions time out a few moments after sockets close, to smooth over network hiccups.

getNumActiveSessions(): number

If executing in a server environment where sockets do not have instance-level listeners, call this when a socket is closed.

handleSocketClose(sessionId: string): void

Parameters

string

Returns

void

Call this when a client establishes a new socket connection.

• sessionId is a unique ID for a browser tab. This is passed as a query param by the useSync hook.
• socket is a WebSocket-like object that the server uses to communicate with the client.
• meta is an optional object that can be used to store additional information about the session.

handleSocketConnect(
  opts: OmitVoid<{
    meta: SessionMeta
    sessionId: string
    socket: WebSocketMinimal
  }>
): void

Parameters

OmitVoid<{
  meta: SessionMeta
  sessionId: string
  socket: WebSocketMinimal
}>

Returns

void

If executing in a server environment where sockets do not have instance-level listeners, call this when a socket error occurs.

handleSocketError(sessionId: string): void

Parameters

string

Returns

void

If executing in a server environment where sockets do not have instance-level listeners (e.g. Bun.serve, Cloudflare Worker with WebSocket hibernation), you should call this method when messages are received. See our self-hosting example for Bun.serve for an example.

handleSocketMessage(
  sessionId: string,
  message: AllowSharedBufferSource | string
): void

Parameters

string

AllowSharedBufferSource | string

Returns

void

isClosed(): boolean

Load a snapshot of the document state, overwriting the current state.

loadSnapshot(snapshot: RoomSnapshot | TLStoreSnapshot): void

Parameters

RoomSnapshot | TLStoreSnapshot

Returns

void