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

package/src/lib/TLSocketRoom.ts

@@ -8,14 +8,95 @@ import { RoomSnapshot, RoomStoreMethods, TLSyncRoom } from './TLSyncRoom'
 import { JsonChunkAssembler } from './chunk'
 import { TLSocketServerSentEvent } from './protocol'
 
-// TODO: structured logging support
-/** @public */
+/**
+ * Logging interface for TLSocketRoom operations. Provides optional methods
+ * for warning and error logging during synchronization operations.
+ *
+ * @example
+ * ```ts
+ * const logger: TLSyncLog = {
+ *   warn: (...args) => console.warn('[SYNC]', ...args),
+ *   error: (...args) => console.error('[SYNC]', ...args)
+ * }
+ *
+ * const room = new TLSocketRoom({ log: logger })
+ * ```
+ *
+ * @public
+ */
 export interface TLSyncLog {
+	/**
+	 * Optional warning logger for non-fatal sync issues
+	 * @param args - Arguments to log
+	 */
 	warn?(...args: any[]): void
+	/**
+	 * Optional error logger for sync errors and failures
+	 * @param args - Arguments to log
+	 */
 	error?(...args: any[]): void
 }
 
-/** @public */
+/**
+ * A server-side room that manages WebSocket connections and synchronizes tldraw document state
+ * between multiple clients in real-time. Each room represents a collaborative document space
+ * where users can work together on drawings with automatic conflict resolution.
+ *
+ * TLSocketRoom handles:
+ * - WebSocket connection lifecycle management
+ * - Real-time synchronization of document changes
+ * - Session management and presence tracking
+ * - Message chunking for large payloads
+ * - Automatic client timeout and cleanup
+ *
+ * @example
+ * ```ts
+ * // Basic room setup
+ * const room = new TLSocketRoom({
+ *   onSessionRemoved: (room, { sessionId, numSessionsRemaining }) => {
+ *     console.log(`Client ${sessionId} disconnected, ${numSessionsRemaining} remaining`)
+ *     if (numSessionsRemaining === 0) {
+ *       room.close()
+ *     }
+ *   },
+ *   onDataChange: () => {
+ *     console.log('Document data changed, consider persisting')
+ *   }
+ * })
+ *
+ * // Handle new client connections
+ * room.handleSocketConnect({
+ *   sessionId: 'user-session-123',
+ *   socket: webSocket,
+ *   isReadonly: false
+ * })
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Room with initial snapshot and schema
+ * const room = new TLSocketRoom({
+ *   initialSnapshot: existingSnapshot,
+ *   schema: myCustomSchema,
+ *   clientTimeout: 30000,
+ *   log: {
+ *     warn: (...args) => logger.warn('SYNC:', ...args),
+ *     error: (...args) => logger.error('SYNC:', ...args)
+ *   }
+ * })
+ *
+ * // Update document programmatically
+ * await room.updateStore(store => {
+ *   const shape = store.get('shape:abc123')
+ *   if (shape) {
+ *     shape.x = 100
+ *     store.put(shape)
+ *   }
+ * })
+ * ```
+ *
+ * @public
+ */
 export class TLSocketRoom<R extends UnknownRecord = UnknownRecord, SessionMeta = void> {
 	private room: TLSyncRoom<R, SessionMeta>
 	private readonly sessions = new Map<
@@ -29,6 +110,20 @@ export class TLSocketRoom<R extends UnknownRecord = UnknownRecord, SessionMeta =
 		onPresenceChange?(): void
 	}
 
+	/**
+	 * Creates a new TLSocketRoom instance for managing collaborative document synchronization.
+	 *
+	 * opts - Configuration options for the room
+	 *   - initialSnapshot - Optional initial document state to load
+	 *   - schema - Store schema defining record types and validation
+	 *   - clientTimeout - Milliseconds to wait before disconnecting inactive clients
+	 *   - log - Optional logger for warnings and errors
+	 *   - onSessionRemoved - Called when a client session is removed
+	 *   - onBeforeSendMessage - Called before sending messages to clients
+	 *   - onAfterReceiveMessage - Called after receiving messages from clients
+	 *   - onDataChange - Called when document data changes
+	 *   - onPresenceChange - Called when presence data changes
+	 */
 	constructor(
 		public readonly opts: {
 			initialSnapshot?: RoomSnapshot | TLStoreSnapshot
@@ -104,14 +199,35 @@ export class TLSocketRoom<R extends UnknownRecord = UnknownRecord, SessionMeta =
 	}
 
 	/**
-	 * Call this when a client establishes a new socket connection.
+	 * Handles a new client WebSocket connection, creating a session within the room.
+	 * This should be called whenever a client establishes a WebSocket connection to join
+	 * the collaborative document.
+	 *
+	 * @param opts - Connection options
+	 *   - sessionId - Unique identifier for the client session (typically from browser tab)
+	 *   - socket - WebSocket-like object for client communication
+	 *   - isReadonly - Whether the client can modify the document (defaults to false)
+	 *   - meta - Additional session metadata (required if SessionMeta is not void)
 	 *
-	 * - `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.
-	 * - `isReadonly` is an optional boolean that can be set to true if the client should not be able to make changes to the document. They will still be able to send presence updates.
-	 * - `meta` is an optional object that can be used to store additional information about the session.
+	 * @example
+	 * ```ts
+	 * // Handle new WebSocket connection
+	 * room.handleSocketConnect({
+	 *   sessionId: 'user-session-abc123',
+	 *   socket: webSocketConnection,
+	 *   isReadonly: !userHasEditPermission
+	 * })
+	 * ```
 	 *
-	 * @param opts - The options object
+	 * @example
+	 * ```ts
+	 * // With session metadata
+	 * room.handleSocketConnect({
+	 *   sessionId: 'session-xyz',
+	 *   socket: ws,
+	 *   meta: { userId: 'user-123', name: 'Alice' }
+	 * })
+	 * ```
 	 */
 	handleSocketConnect(
 		opts: {
@@ -160,12 +276,30 @@ export class TLSocketRoom<R extends UnknownRecord = UnknownRecord, SessionMeta =
 	}
 
 	/**
-	 * 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.
+	 * Processes a message received from a client WebSocket. Use this method in server
+	 * environments where WebSocket event listeners cannot be attached directly to socket
+	 * instances (e.g., Bun.serve, Cloudflare Workers with WebSocket hibernation).
+	 *
+	 * The method handles message chunking/reassembly and forwards complete messages
+	 * to the underlying sync room for processing.
+	 *
+	 * @param sessionId - Session identifier matching the one used in handleSocketConnect
+	 * @param message - Raw message data from the client (string or binary)
 	 *
-	 * @param sessionId - The id of the session. (should match the one used when calling handleSocketConnect)
-	 * @param message - The message received from the client.
+	 * @example
+	 * ```ts
+	 * // In a Bun.serve handler
+	 * server.upgrade(req, {
+	 *   data: { sessionId, room },
+	 *   upgrade(res, req) {
+	 *     // Connection established
+	 *   },
+	 *   message(ws, message) {
+	 *     const { sessionId, room } = ws.data
+	 *     room.handleSocketMessage(sessionId, message)
+	 *   }
+	 * })
+	 * ```
 	 */
 	handleSocketMessage(sessionId: string, message: string | AllowSharedBufferSource) {
 		const assembler = this.sessions.get(sessionId)?.assembler
@@ -211,45 +345,104 @@ export class TLSocketRoom<R extends UnknownRecord = UnknownRecord, SessionMeta =
 	}
 
 	/**
-	 * If executing in a server environment where sockets do not have instance-level listeners,
-	 * call this when a socket error occurs.
-	 * @param sessionId - The id of the session. (should match the one used when calling handleSocketConnect)
+	 * Handles a WebSocket error for the specified session. Use this in server environments
+	 * where socket event listeners cannot be attached directly. This will initiate cleanup
+	 * and session removal for the affected client.
+	 *
+	 * @param sessionId - Session identifier matching the one used in handleSocketConnect
+	 *
+	 * @example
+	 * ```ts
+	 * // In a custom WebSocket handler
+	 * socket.addEventListener('error', () => {
+	 *   room.handleSocketError(sessionId)
+	 * })
+	 * ```
 	 */
 	handleSocketError(sessionId: string) {
 		this.room.handleClose(sessionId)
 	}
 
 	/**
-	 * If executing in a server environment where sockets do not have instance-level listeners,
-	 * call this when a socket is closed.
-	 * @param sessionId - The id of the session. (should match the one used when calling handleSocketConnect)
+	 * Handles a WebSocket close event for the specified session. Use this in server
+	 * environments where socket event listeners cannot be attached directly. This will
+	 * initiate cleanup and session removal for the disconnected client.
+	 *
+	 * @param sessionId - Session identifier matching the one used in handleSocketConnect
+	 *
+	 * @example
+	 * ```ts
+	 * // In a custom WebSocket handler
+	 * socket.addEventListener('close', () => {
+	 *   room.handleSocketClose(sessionId)
+	 * })
+	 * ```
 	 */
 	handleSocketClose(sessionId: string) {
 		this.room.handleClose(sessionId)
 	}
 
 	/**
-	 * 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.
+	 * Returns the current document clock value. The clock is a monotonically increasing
+	 * integer that increments with each document change, providing a consistent ordering
+	 * of changes across the distributed system.
+	 *
+	 * @returns The current document clock value
 	 *
-	 * @returns The clock
+	 * @example
+	 * ```ts
+	 * const clock = room.getCurrentDocumentClock()
+	 * console.log(`Document is at version ${clock}`)
+	 * ```
 	 */
 	getCurrentDocumentClock() {
 		return this.room.documentClock
 	}
 
 	/**
-	 * Returns a deeply cloned record from the store, if available.
-	 * @param id - The id of the record
-	 * @returns the cloned record
+	 * Retrieves a deeply cloned copy of a record from the document store.
+	 * Returns undefined if the record doesn't exist. The returned record is
+	 * safe to mutate without affecting the original store data.
+	 *
+	 * @param id - Unique identifier of the record to retrieve
+	 * @returns Deep clone of the record, or undefined if not found
+	 *
+	 * @example
+	 * ```ts
+	 * const shape = room.getRecord('shape:abc123')
+	 * if (shape) {
+	 *   console.log('Shape position:', shape.x, shape.y)
+	 *   // Safe to modify without affecting store
+	 *   shape.x = 100
+	 * }
+	 * ```
 	 */
 	getRecord(id: string) {
 		return structuredClone(this.room.documents.get(id)?.state)
 	}
 
 	/**
-	 * Returns a list of the sessions in the room.
+	 * Returns information about all active sessions in the room. Each session
+	 * represents a connected client with their current connection status and metadata.
+	 *
+	 * @returns Array of session information objects containing:
+	 *   - sessionId - Unique session identifier
+	 *   - isConnected - Whether the session has an active WebSocket connection
+	 *   - isReadonly - Whether the session can modify the document
+	 *   - meta - Custom session metadata
+	 *
+	 * @example
+	 * ```ts
+	 * const sessions = room.getSessions()
+	 * console.log(`Room has ${sessions.length} active sessions`)
+	 *
+	 * for (const session of sessions) {
+	 *   console.log(`${session.sessionId}: ${session.isConnected ? 'online' : 'offline'}`)
+	 *   if (session.isReadonly) {
+	 *     console.log('  (read-only access)')
+	 *   }
+	 * }
+	 * ```
 	 */
 	getSessions(): Array<{
 		sessionId: string
@@ -268,16 +461,32 @@ export class TLSocketRoom<R extends UnknownRecord = UnknownRecord, SessionMeta =
 	}
 
 	/**
-	 * 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 {@link TLSocketRoom#loadSnapshot} if you need to revert to a previous state.
-	 * @returns The snapshot
+	 * Creates a complete snapshot of the current document state, including all records
+	 * and synchronization metadata. This snapshot can be persisted to storage and used
+	 * to restore the room state later or revert to a previous version.
+	 *
+	 * @returns Complete room snapshot including documents, clock values, and tombstones
+	 *
+	 * @example
+	 * ```ts
+	 * // Capture current state for persistence
+	 * const snapshot = room.getCurrentSnapshot()
+	 * await saveToDatabase(roomId, JSON.stringify(snapshot))
+	 *
+	 * // Later, restore from snapshot
+	 * const savedSnapshot = JSON.parse(await loadFromDatabase(roomId))
+	 * const newRoom = new TLSocketRoom({ initialSnapshot: savedSnapshot })
+	 * ```
 	 */
 	getCurrentSnapshot() {
 		return this.room.getSnapshot()
 	}
 
 	/**
+	 * Retrieves all presence records from the document store. Presence records
+	 * contain ephemeral user state like cursor positions and selections.
+	 *
+	 * @returns Object mapping record IDs to presence record data
 	 * @internal
 	 */
 	getPresenceRecords() {
@@ -291,8 +500,10 @@ export class TLSocketRoom<R extends UnknownRecord = UnknownRecord, SessionMeta =
 	}
 
 	/**
-	 * Return a serialized snapshot of the document state, including clock-related bookkeeping.
-	 * @returns The serialized snapshot
+	 * Returns a JSON-serialized snapshot of the current document state. This is
+	 * equivalent to JSON.stringify(getCurrentSnapshot()) but provided as a convenience.
+	 *
+	 * @returns JSON string representation of the room snapshot
 	 * @internal
 	 */
 	getCurrentSerializedSnapshot() {
@@ -300,8 +511,22 @@ export class TLSocketRoom<R extends UnknownRecord = UnknownRecord, SessionMeta =
 	}
 
 	/**
-	 * Load a snapshot of the document state, overwriting the current state.
-	 * @param snapshot - The snapshot to load
+	 * Loads a document snapshot, completely replacing the current room state.
+	 * This will disconnect all current clients and update the document to match
+	 * the provided snapshot. Use this for restoring from backups or implementing
+	 * document versioning.
+	 *
+	 * @param snapshot - Room or store snapshot to load
+	 *
+	 * @example
+	 * ```ts
+	 * // Restore from a saved snapshot
+	 * const backup = JSON.parse(await loadBackup(roomId))
+	 * room.loadSnapshot(backup)
+	 *
+	 * // All clients will be disconnected and need to reconnect
+	 * // to see the restored document state
+	 * ```
 	 */
 	loadSnapshot(snapshot: RoomSnapshot | TLStoreSnapshot) {
 		if ('store' in snapshot) {
@@ -343,71 +568,163 @@ export class TLSocketRoom<R extends UnknownRecord = UnknownRecord, SessionMeta =
 	}
 
 	/**
-	 * Allow applying changes to the store inside of a transaction.
+	 * Executes a transaction to modify the document store. Changes made within the
+	 * transaction are atomic and will be synchronized to all connected clients.
+	 * The transaction provides isolation from concurrent changes until it commits.
 	 *
-	 * You can get values from the store by id with `store.get(id)`.
-	 * These values are safe to mutate, but to commit the changes you must call `store.put(...)` with the updated value.
-	 * You can get all values in the store with `store.getAll()`.
-	 * You can also delete values with `store.delete(id)`.
+	 * @param updater - Function that receives store methods to make changes
+	 *   - store.get(id) - Retrieve a record (safe to mutate, but must call put() to commit)
+	 *   - store.put(record) - Save a modified record
+	 *   - store.getAll() - Get all records in the store
+	 *   - store.delete(id) - Remove a record from the store
+	 * @returns Promise that resolves when the transaction completes
 	 *
 	 * @example
 	 * ```ts
-	 * room.updateStore(store => {
-	 *   const shape = store.get('shape:abc123')
-	 *   shape.meta.approved = true
-	 *   store.put(shape)
+	 * // Update multiple shapes in a single transaction
+	 * await room.updateStore(store => {
+	 *   const shape1 = store.get('shape:abc123')
+	 *   const shape2 = store.get('shape:def456')
+	 *
+	 *   if (shape1) {
+	 *     shape1.x = 100
+	 *     store.put(shape1)
+	 *   }
+	 *
+	 *   if (shape2) {
+	 *     shape2.meta.approved = true
+	 *     store.put(shape2)
+	 *   }
 	 * })
 	 * ```
 	 *
-	 * Changes to the store inside the callback are isolated from changes made by other clients until the transaction commits.
-	 *
-	 * @param updater - A function that will be called with a store object that can be used to make changes.
-	 * @returns A promise that resolves when the transaction is complete.
+	 * @example
+	 * ```ts
+	 * // Async transaction with external API call
+	 * await room.updateStore(async store => {
+	 *   const doc = store.get('document:main')
+	 *   if (doc) {
+	 *     doc.lastModified = await getCurrentTimestamp()
+	 *     store.put(doc)
+	 *   }
+	 * })
+	 * ```
 	 */
 	async updateStore(updater: (store: RoomStoreMethods<R>) => void | Promise<void>) {
 		return this.room.updateStore(updater)
 	}
 
 	/**
-	 * Send a custom message to a connected client.
+	 * Sends a custom message to a specific client session. This allows sending
+	 * application-specific data that doesn't modify the document state, such as
+	 * notifications, chat messages, or custom commands.
+	 *
+	 * @param sessionId - Target session identifier
+	 * @param data - Custom payload to send (will be JSON serialized)
+	 *
+	 * @example
+	 * ```ts
+	 * // Send a notification to a specific user
+	 * room.sendCustomMessage('session-123', {
+	 *   type: 'notification',
+	 *   message: 'Your changes have been saved'
+	 * })
 	 *
-	 * @param sessionId - The id of the session to send the message to.
-	 * @param data - The payload to send.
+	 * // Send a chat message
+	 * room.sendCustomMessage('session-456', {
+	 *   type: 'chat',
+	 *   from: 'Alice',
+	 *   text: 'Great work on this design!'
+	 * })
+	 * ```
 	 */
 	sendCustomMessage(sessionId: string, data: any) {
 		this.room.sendCustomMessage(sessionId, data)
 	}
 
 	/**
-	 * Immediately remove a session from the room, and close its socket if not already closed.
+	 * Immediately removes a session from the room and closes its WebSocket connection.
+	 * The client will attempt to reconnect automatically unless a fatal reason is provided.
+	 *
+	 * @param sessionId - Session identifier to remove
+	 * @param fatalReason - Optional fatal error reason that prevents reconnection
 	 *
-	 * The client will attempt to reconnect unless you provide a `fatalReason` parameter.
+	 * @example
+	 * ```ts
+	 * // Kick a user (they can reconnect)
+	 * room.closeSession('session-troublemaker')
 	 *
-	 * The `fatalReason` parameter will be available in the return value of the `useSync` hook as `useSync().error.reason`.
+	 * // Permanently ban a user
+	 * room.closeSession('session-banned', 'PERMISSION_DENIED')
 	 *
-	 * @param sessionId - The id of the session to remove
-	 * @param fatalReason - The reason message to use when calling .close on the underlying websocket
+	 * // Close session due to inactivity
+	 * room.closeSession('session-idle', 'TIMEOUT')
+	 * ```
 	 */
 	closeSession(sessionId: string, fatalReason?: TLSyncErrorCloseEventReason | string) {
 		this.room.rejectSession(sessionId, fatalReason)
 	}
 
 	/**
-	 * Close the room and disconnect all clients. Call this before discarding the room instance or shutting down the server.
+	 * Closes the room and disconnects all connected clients. This should be called
+	 * when shutting down the room permanently, such as during server shutdown or
+	 * when the room is no longer needed. Once closed, the room cannot be reopened.
+	 *
+	 * @example
+	 * ```ts
+	 * // Clean shutdown when no users remain
+	 * if (room.getNumActiveSessions() === 0) {
+	 *   await persistSnapshot(room.getCurrentSnapshot())
+	 *   room.close()
+	 * }
+	 *
+	 * // Server shutdown
+	 * process.on('SIGTERM', () => {
+	 *   for (const room of activeRooms.values()) {
+	 *     room.close()
+	 *   }
+	 * })
+	 * ```
 	 */
 	close() {
 		this.room.close()
 	}
 
 	/**
-	 * @returns true if the room is closed
+	 * Checks whether the room has been permanently closed. Closed rooms cannot
+	 * accept new connections or process further changes.
+	 *
+	 * @returns True if the room is closed, false if still active
+	 *
+	 * @example
+	 * ```ts
+	 * if (room.isClosed()) {
+	 *   console.log('Room has been shut down')
+	 *   // Create a new room or redirect users
+	 * } else {
+	 *   // Room is still accepting connections
+	 *   room.handleSocketConnect({ sessionId, socket })
+	 * }
+	 * ```
 	 */
 	isClosed() {
 		return this.room.isClosed()
 	}
 }
 
-/** @public */
+/**
+ * Utility type that removes properties with void values from an object type.
+ * This is used internally to conditionally require session metadata based on
+ * whether SessionMeta extends void.
+ *
+ * @example
+ * ```ts
+ * type Example = { a: string, b: void, c: number }
+ * type Result = OmitVoid<Example> // { a: string, c: number }
+ * ```
+ *
+ * @public
+ */
 export type OmitVoid<T, KS extends keyof T = keyof T> = {
 	[K in KS extends any ? (void extends T[KS] ? never : KS) : never]: T[K]
 }