@tldraw/sync-core 4.1.0-next.b6dfe9bccde9 → 4.1.0-next.b9999db71010

package/src/lib/TLSyncClient.ts

@@ -24,90 +24,229 @@ import {
 	getTlsyncProtocolVersion,
 } from './protocol'
 
-/** @internal */
+/**
+ * Function type for subscribing to events with a callback.
+ * Returns an unsubscribe function to clean up the listener.
+ *
+ * @param cb - Callback function that receives the event value
+ * @returns Function to call when you want to unsubscribe from the events
+ *
+ * @internal
+ */
 export type SubscribingFn<T> = (cb: (val: T) => void) => () => void
 
 /**
- * This the close code that we use on the server to signal to a socket that
- * the connection is being closed because of a non-recoverable error.
- *
- * You should use this if you need to close a connection.
+ * WebSocket close code used by the server to signal a non-recoverable sync error.
+ * This close code indicates that the connection is being terminated due to an error
+ * that cannot be automatically recovered from, such as authentication failures,
+ * incompatible client versions, or invalid data.
  *
  * @example
  * ```ts
+ * // Server-side: Close connection with specific error reason
  * socket.close(TLSyncErrorCloseEventCode, TLSyncErrorCloseEventReason.NOT_FOUND)
- * ```
  *
- * The `reason` parameter that you pass to `socket.close()` will be made available at `useSync().error.reason`
+ * // Client-side: Handle the error in your sync error handler
+ * const syncClient = new TLSyncClient({
+ *   // ... other config
+ *   onSyncError: (reason) => {
+ *     console.error('Sync failed:', reason) // Will receive 'NOT_FOUND'
+ *   }
+ * })
+ * ```
  *
  * @public
  */
 export const TLSyncErrorCloseEventCode = 4099 as const
 
 /**
- * The set of reasons that a connection can be closed by the server
+ * Predefined reasons for server-initiated connection closures.
+ * These constants represent different error conditions that can cause
+ * the sync server to terminate a WebSocket connection.
+ *
+ * @example
+ * ```ts
+ * // Server usage
+ * if (!user.hasPermission(roomId)) {
+ *   socket.close(TLSyncErrorCloseEventCode, TLSyncErrorCloseEventReason.FORBIDDEN)
+ * }
+ *
+ * // Client error handling
+ * syncClient.onSyncError((reason) => {
+ *   switch (reason) {
+ *     case TLSyncErrorCloseEventReason.NOT_FOUND:
+ *       showError('Room does not exist')
+ *       break
+ *     case TLSyncErrorCloseEventReason.FORBIDDEN:
+ *       showError('Access denied')
+ *       break
+ *     case TLSyncErrorCloseEventReason.CLIENT_TOO_OLD:
+ *       showError('Please update your app')
+ *       break
+ *   }
+ * })
+ * ```
+ *
  * @public
  */
 export const TLSyncErrorCloseEventReason = {
+	/** Room or resource not found */
 	NOT_FOUND: 'NOT_FOUND',
+	/** User lacks permission to access the room */
 	FORBIDDEN: 'FORBIDDEN',
+	/** User authentication required or invalid */
 	NOT_AUTHENTICATED: 'NOT_AUTHENTICATED',
+	/** Unexpected server error occurred */
 	UNKNOWN_ERROR: 'UNKNOWN_ERROR',
+	/** Client protocol version too old */
 	CLIENT_TOO_OLD: 'CLIENT_TOO_OLD',
+	/** Server protocol version too old */
 	SERVER_TOO_OLD: 'SERVER_TOO_OLD',
+	/** Client sent invalid or corrupted record data */
 	INVALID_RECORD: 'INVALID_RECORD',
+	/** Client exceeded rate limits */
 	RATE_LIMITED: 'RATE_LIMITED',
+	/** Room has reached maximum capacity */
 	ROOM_FULL: 'ROOM_FULL',
 } as const
 /**
- * The set of reasons that a connection can be closed by the server
+ * Union type of all possible server connection close reasons.
+ * Represents the string values that can be passed when a server closes
+ * a sync connection due to an error condition.
+ *
  * @public
  */
 export type TLSyncErrorCloseEventReason =
 	(typeof TLSyncErrorCloseEventReason)[keyof typeof TLSyncErrorCloseEventReason]
 
 /**
- * Event handler for userland socket messages
+ * Handler function for custom application messages sent through the sync protocol.
+ * These are user-defined messages that can be sent between clients via the sync server,
+ * separate from the standard document synchronization messages.
+ *
+ * @param data - Custom message payload (application-defined structure)
+ *
+ * @example
+ * ```ts
+ * const customMessageHandler: TLCustomMessageHandler = (data) => {
+ *   if (data.type === 'user_joined') {
+ *     console.log(`${data.username} joined the session`)
+ *     showToast(`${data.username} is now collaborating`)
+ *   }
+ * }
+ *
+ * const syncClient = new TLSyncClient({
+ *   // ... other config
+ *   onCustomMessageReceived: customMessageHandler
+ * })
+ * ```
+ *
  * @public
  */
 export type TLCustomMessageHandler = (this: null, data: any) => void
 
 /**
+ * Event object describing changes in socket connection status.
+ * Contains either a basic status change or an error with details.
+ *
  * @internal
  */
 export type TlSocketStatusChangeEvent =
 	| {
+			/** Connection came online or went offline */
 			status: 'online' | 'offline'
 	  }
 	| {
+			/** Connection encountered an error */
 			status: 'error'
+			/** Description of the error that occurred */
 			reason: string
 	  }
-/** @internal */
+/**
+ * Callback function type for listening to socket status changes.
+ *
+ * @param params - Event object containing the new status and optional error details
+ *
+ * @internal
+ */
 export type TLSocketStatusListener = (params: TlSocketStatusChangeEvent) => void
 
-/** @internal */
+/**
+ * Possible connection states for a persistent client socket.
+ * Represents the current connectivity status between client and server.
+ *
+ * @internal
+ */
 export type TLPersistentClientSocketStatus = 'online' | 'offline' | 'error'
 
-/** @internal */
-export type TLPresenceMode = 'solo' | 'full'
 /**
- * A socket that can be used to send and receive messages to the server. It should handle staying
- * open and reconnecting when the connection is lost. In actual client code this will be a wrapper
- * around a websocket or socket.io or something similar.
+ * Mode for handling presence information in sync sessions.
+ * Controls whether presence data (cursors, selections) is shared with other clients.
+ *
+ * @internal
+ */
+export type TLPresenceMode =
+	/** No presence sharing - client operates independently */
+	| 'solo'
+	/** Full presence sharing - cursors and selections visible to others */
+	| 'full'
+/**
+ * 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.
+ *
+ * @example
+ * ```ts
+ * 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()
+ *   }
+ * }
+ * ```
  *
  * @internal
  */
 export interface TLPersistentClientSocket<R extends UnknownRecord = UnknownRecord> {
-	/** Whether there is currently an open connection to the server. */
+	/** Current connection state - online means actively connected and ready */
 	connectionStatus: 'online' | 'offline' | 'error'
-	/** Send a message to the server */
+
+	/**
+	 * Send a protocol message to the sync server
+	 * @param msg - Message to send (connect, push, ping, etc.)
+	 */
 	sendMessage(msg: TLSocketClientSentEvent<R>): void
-	/** Attach a listener for messages sent by the server */
+
+	/**
+	 * Subscribe to messages received from the server
+	 * @param callback - Function called for each received message
+	 * @returns Cleanup function to remove the listener
+	 */
 	onReceiveMessage: SubscribingFn<TLSocketServerSentEvent<R>>
-	/** Attach a listener for connection status changes */
+
+	/**
+	 * Subscribe to connection status changes
+	 * @param callback - Function called when connection status changes
+	 * @returns Cleanup function to remove the listener
+	 */
 	onStatusChange: SubscribingFn<TlSocketStatusChangeEvent>
-	/** Restart the connection */
+
+	/**
+	 * Force a connection restart (disconnect then reconnect)
+	 * Used for error recovery or when connection health checks fail
+	 */
 	restart(): void
 }
 
@@ -117,9 +256,61 @@ const MAX_TIME_TO_WAIT_FOR_SERVER_INTERACTION_BEFORE_RESETTING_CONNECTION = PING
 // Should connect support chunking the response to allow for large payloads?
 
 /**
- * TLSyncClient manages syncing data in a local Store with a remote server.
+ * Main client-side synchronization engine for collaborative tldraw applications.
  *
- * It uses a git-style push/pull/rebase model.
+ * TLSyncClient manages bidirectional synchronization between a local tldraw Store
+ * and a remote sync server. It uses an optimistic update model where local changes
+ * are immediately applied for responsive UI, then sent to the server for validation
+ * and distribution to other clients.
+ *
+ * The synchronization follows a git-like push/pull/rebase model:
+ * - **Push**: Local changes are sent to server as diff operations
+ * - **Pull**: Server changes are received and applied locally
+ * - **Rebase**: Conflicting changes are resolved by undoing local changes,
+ *   applying server changes, then re-applying local changes on top
+ *
+ * @example
+ * ```ts
+ * import { TLSyncClient, ClientWebSocketAdapter } from '@tldraw/sync-core'
+ * import { createTLStore } from '@tldraw/store'
+ *
+ * // Create store and socket
+ * const store = createTLStore({ schema: mySchema })
+ * const socket = new ClientWebSocketAdapter('ws://localhost:3000/sync')
+ *
+ * // Create sync client
+ * const syncClient = new TLSyncClient({
+ *   store,
+ *   socket,
+ *   presence: atom(null),
+ *   onLoad: () => console.log('Connected and loaded'),
+ *   onSyncError: (reason) => console.error('Sync failed:', reason)
+ * })
+ *
+ * // Changes to store are now automatically synchronized
+ * store.put([{ id: 'shape1', type: 'geo', x: 100, y: 100 }])
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Advanced usage with presence and custom messages
+ * const syncClient = new TLSyncClient({
+ *   store,
+ *   socket,
+ *   presence: atom({ cursor: { x: 0, y: 0 }, userName: 'Alice' }),
+ *   presenceMode: atom('full'),
+ *   onCustomMessageReceived: (data) => {
+ *     if (data.type === 'chat') {
+ *       showChatMessage(data.message, data.from)
+ *     }
+ *   },
+ *   onAfterConnect: (client, { isReadonly }) => {
+ *     if (isReadonly) {
+ *       showNotification('Connected in read-only mode')
+ *     }
+ *   }
+ * })
+ * ```
  *
  * @internal
  */
@@ -167,8 +358,13 @@ export class TLSyncClient<R extends UnknownRecord, S extends Store<R> = Store<R>
 	private clientClock = 0
 
 	/**
-	 * Called immediately after a connect acceptance has been received and processed Use this to make
-	 * any changes to the store that are required to keep it operational
+	 * Callback executed immediately after successful connection to sync room.
+	 * Use this to perform any post-connection setup required for your application,
+	 * such as initializing default content or updating UI state.
+	 *
+	 * @param self - The TLSyncClient instance that connected
+	 * @param details - Connection details
+	 *   - isReadonly - Whether the connection is in read-only mode
 	 */
 	public readonly onAfterConnect?: (self: this, details: { isReadonly: boolean }) => void
 
@@ -186,6 +382,22 @@ export class TLSyncClient<R extends UnknownRecord, S extends Store<R> = Store<R>
 
 	didCancel?: () => boolean
 
+	/**
+	 * Creates a new TLSyncClient instance to manage synchronization with a remote server.
+	 *
+	 * @param config - Configuration object for the sync client
+	 *   - store - The local tldraw store to synchronize
+	 *   - socket - WebSocket adapter for server communication
+	 *   - presence - Reactive signal containing current user's presence data
+	 *   - presenceMode - Optional signal controlling presence sharing (defaults to 'full')
+	 *   - onLoad - Callback fired when initial sync completes successfully
+	 *   - onSyncError - Callback fired when sync fails with error reason
+	 *   - onCustomMessageReceived - Optional handler for custom messages
+	 *   - onAfterConnect - Optional callback fired after successful connection
+	 *   - self - The TLSyncClient instance
+	 *   - details - Connection details including readonly status
+	 *   - didCancel - Optional function to check if sync should be cancelled
+	 */
 	constructor(config: {
 		store: S
 		socket: TLPersistentClientSocket<R>
@@ -469,6 +681,19 @@ export class TLSyncClient<R extends UnknownRecord, S extends Store<R> = Store<R>
 		}
 	}
 
+	/**
+	 * Closes the sync client and cleans up all resources.
+	 *
+	 * Call this method when you no longer need the sync client to prevent
+	 * memory leaks and close the WebSocket connection. After calling close(),
+	 * the client cannot be reused.
+	 *
+	 * @example
+	 * ```ts
+	 * // Clean shutdown
+	 * syncClient.close()
+	 * ```
+	 */
 	close() {
 		this.debug('closing')
 		this.disposables.forEach((dispose) => dispose())